Créer un rapport

Un rapport est un document imprimé à partir des données de l'app : une liste, une facture, un état de clôture du mois. Il sort en PDF — paginé, avec des en-têtes qui se répètent et des totaux à la fin — ou en Excel, et il peut être généré à la main, par un bouton d'un écran, par un script, par un workflow, ou par une planification qui l'envoie par e-mail.

Le modèle est celui des bandes : un rapport n'est pas un écran qui s'allonge vers le bas, c'est une suite de bandes que le moteur répète selon la règle de chacune — une fois, par page, par ligne, par groupe. C'est cela qui rend la pagination possible.

L'unité est le millimètre, partout. C'est l'unité du papier et elle survit au passage du A4 au Letter.

Dans cette page, nous concevons le rapport Oportunidades por conta de l'app Gestion des Clients : le pipeline commercial regroupé par compte, avec les contacts de chacun, le total par compte et un graphique à la fin.

#Où vivent les rapports

Les rapports se trouvent dans le minitab Données de l'arborescence de l'app, sous les sources de données. Cliquer sur le nom ouvre la conception dans un onglet.

Une app sans rapports affiche « Aucun rapport pour l'instant — créez-en un pour le concevoir. »

#Créer un rapport

1. Passez la souris sur la ligne du groupe Rapports et cliquez sur Nouveau rapport.
2. Saisissez le Nom — par exemple Factures du mois.
3. Cliquez sur Créer.

« Crée un rapport à la racine. Vous pourrez le déplacer dans un dossier ensuite. » Le rapport naît en A4 portrait, avec les cinq bandes fixes et sans données connectées, et la conception s'ouvre aussitôt.

#La conception

L'onglet a trois colonnes et une barre en haut :

Zone	Ce que c'est
Barre du haut	Le nom, l'identifiant du rapport (rpt_…, celui que le code utilise pour l'appeler), l'état de l'enregistrement, annuler/rétablir, les mesures du papier et les boutons Excel et Prévisualiser.
Colonne de gauche	La palette Éléments, les Données, les Regroupements, les Paramètres et les Planifications.
Centre	La surface de conception : une règle en millimètres et les bandes, les unes au-dessus des autres dans l'ordre où elles sortent sur le papier.
Droite	Les propriétés — du rapport, de la bande sélectionnée ou de l'élément sélectionné.

Comme dans le reste de la plateforme, il n'y a pas de bouton d'enregistrement : la conception s'enregistre toute seule.

#Les bandes

Les bandes forment un ensemble fixe — on n'ajoute pas des bandes à volonté, parce que chacune a sa propre règle de répétition, que le moteur connaît par son nom.

Bande	Quand elle sort
En-tête du rapport	« Sort une seule fois, au début de la première page. » Logo, titre, date d'émission.
En-tête de page	« Se répète en haut de toutes les pages — logo, titres de colonne. »
Détail	« Sort une fois par ligne de données. C'est cette bande qui remplit le rapport. »
Pied de page	« Se répète en bas de toutes les pages — numéro de page, date. »
Pied du rapport	« Sort une seule fois, à la fin — totaux généraux. » Il naît désactivé.

À celles-ci s'ajoutent, quand il y a des regroupements, un en-tête et un pied par niveau — voir Graphiques et sous-rapports.

Cliquer sur le titre d'une bande la sélectionne ; le panneau de droite montre alors ses propriétés.

Propriété	Ce qu'elle fait
Hauteur (mm)	La hauteur de la bande. On fait aussi glisser la ligne de séparation, sur la surface de conception.
Active	« Désactivée, la bande ne sort pas dans le rapport et n'occupe pas d'espace. »
Règles de la bande	Supprimer la bande selon les données.

À propos des règles : « supprimer la bande selon les données. Supprimée, elle ne sort pas et n'occupe pas d'espace — c'est ce qui remplace le fait d'avoir plusieurs bandes de détail ». Au lieu de trois bandes de détail avec des conditions différentes, une seule bande et des règles qui la masquent quand ce n'est pas le cas.

#Le papier

Quand rien n'est sélectionné, le panneau de droite montre les propriétés du rapport et de la page :

Champ	Options
Nom / Description	L'identification, pour la personne qui construit le rapport.
Format	A4, A3, A5, Letter, Legal ou Personnalisé (largeur et hauteur en mm).
Orientation	Portrait ou Paysage.
Marges (mm)	Haut, Bas, Gauche, Droite.

« L'espace entre le papier et le contenu. La largeur utile qui reste est celle de la surface de conception » — changer les marges change la largeur dans laquelle vous dessinez, et la règle suit.

La section Vue, en bas du panneau, contient le Zoom de la surface de conception. Il n'affecte pas le document ; c'est seulement la loupe de la personne qui conçoit.

#Les données

Un rapport sans données connectées n'a aucun champ à faire glisser. Ouvrez Jeux de données par le + de la section Données :

Chaque jeu de données a :

Champ	Notes
Nom du jeu de données	Le nom que les éléments utilisent pour l'appeler (oportunidades, contactos).
Rôle	principal, lié ou autonome — voir le tableau ci-dessous.
API de table	L'API de l'app d'où viennent les lignes.
Filtres (where)	La même grammaire de filtres que dans le reste de la plateforme. Peut comparer avec les paramètres du rapport.
Chargement / Par page	Comment les lignes sont lues.

Les trois rôles :

Rôle	Ce que cela veut dire
principal	« La bande de détail le parcourt, une ligne imprimée par ligne de celui-ci. » Il n'y en a qu'un.
lié	« Il appartient à une ligne d'un autre jeu de données par le champ que vous indiquez — la facture et ses lignes. »
autonome	« Ni parcouru ni lié, il alimente l'en-tête ou un total général. »

Un jeu de données lié demande trois champs de plus : le Jeu de données parent, le Champ dans le parent (« le champ qui identifie la ligne du parent — normalement la clé ») et le Champ dans ce jeu de données (« le champ qui pointe vers le parent »).

Dans la colonne de gauche, chaque jeu de données apparaît avec son nombre de champs et se déplie avec la flèche. Faire glisser un champ sur une bande crée un élément Champ déjà relié — c'est la façon la plus rapide de remplir la bande de détail.

#Les paramètres

Les paramètres sont des « valeurs que le rapport reçoit de la personne qui le lance » — le mois, la phase, le client. On les utilise dans les filtres des jeux de données.

Champ	Notes
Nom	Le nom que le filtre et le code utilisent.
Libellé	Ce qu'on lit quand la valeur est demandée.
Type	Texte, Nombre, Date ou Oui/Non.
Obligatoire	Sans valeur, le rapport refuse de s'exécuter.
Valeur par défaut	Utilisée quand la personne qui l'appelle n'en donne aucune.

#Les éléments

La palette Éléments contient tout ce qui se pose sur une bande. On le fait glisser vers la bande ; on le lâche là où il doit rester.

Élément	À quoi il sert
Texte	Texte fixe — titres, libellés, pieds de page.
Champ	La valeur d'un champ du jeu de données. C'est ce qui sort quand on fait glisser un champ.
Agrégat	Un calcul sur un jeu de données : Somme, Moyenne, Comptage, Minimum, Maximum.
Champ système	Numéro de la page, Total de pages, Page X sur Y, Date d'émission, Nom du rapport.
Ligne	Séparateurs et encadrements.
Rectangle	Fonds et cadres, avec remplissage, contour et coins.
Image	Un fichier de l'app, une adresse, ou le contenu d'un champ.
Graphique	Neuf types, avec les mêmes données que les écrans.
Sous-rapport	Un autre rapport dessiné à l'intérieur de celui-ci.
Code-barres	Code 128, EAN-13 ou QR.

Les trois derniers ont leur propre page : Graphiques et sous-rapports.

#Les propriétés d'un élément

Cliquez sur un élément de la surface de conception :

Section	Ce qu'elle contient
Position et taille	X (mm), Y (mm), Largeur (mm), Hauteur (mm). Le y compte à partir du haut de la bande.
Apparence	Police, Corps (pt), gras/italique/souligné, alignement, Alignement vertical, couleur, Remplissage, Contour (mm) et Couleur du contour, Retour à la ligne.
Format (champs et agrégats)	Masque d'affichage, avec la même grammaire que les colonnes de la table.
Exportation	Nom de la colonne dans Excel. « Vide utilise le nom du champ. Sur le papier, il n'apparaît pas — là, l'en-tête est un texte que vous placez où vous voulez. »
Règles de formatage	Voir ci-dessous.

À propos de Retour à la ligne : « désactivé, le texte qui ne tient pas est coupé au lieu de passer à la ligne suivante » — c'est ce qu'on veut dans une colonne de table, pour qu'une ligne longue ne pousse pas toute la page.

En sélectionnant plusieurs éléments (avec le rectangle de sélection ou avec Shift), le panneau dit combien ils sont et les déplace ensemble, à la souris ou avec les flèches.

#Règles de formatage

Chaque élément peut avoir des règles qui « changent l'apparence selon les données de la ligne : colorer une valeur en retard, masquer un libellé, mettre un total en gras quand il est négatif ». C'est le même moteur et le même éditeur que les règles des widgets.

La dernière règle qui correspond l'emporte — classez-les de la plus générale à la plus spécifique.

#Voir le résultat

Deux boutons, dans le coin supérieur droit :

• Prévisualiser génère le PDF avec les données réelles de l'app et l'ouvre sur place, paginé. C'est ainsi qu'on vérifie la conception : ce qui tient sur la surface de conception ne tient pas toujours sur la page.
• Excel génère la feuille de calcul et la télécharge. Ici, il n'y a ni bandes ni pages : il en sort une table, avec une colonne par élément de la bande de détail, et les en-têtes viennent du Nom de la colonne de chacun.

Si le rapport a des paramètres obligatoires, ils sont demandés avant la génération.

#Questions fréquentes

La bande de détail sort vide. Il n'y a pas de jeu de données principal, ou son filtre ne renvoie aucune ligne. Ouvrez Jeux de données et vérifiez qu'il y en a un avec le rôle principal, et que les paramètres utilisés par le filtre ont une valeur.

Un champ dans une bande d'en-tête sort vide. C'est attendu en dehors des bandes de groupe. Dans l'En-tête du rapport et dans le Pied du rapport, il n'y a pas de « ligne courante » — montrer la première de toutes reviendrait à inventer une valeur. Dans un en-tête de groupe, le champ lit la première ligne du groupe, ce qui est bien ce qu'on veut.

Le rapport est lent ou tronqué. Chaque jeu de données a un plafond de lignes par lecture. Filtrez davantage — par date, par état — au lieu d'imprimer la table entière. Un rapport de 4 000 pages n'est lu par personne.

J'ai besoin de plus que ce qu'une planification sait faire. Écrivez un script Python et appelez reports.render(...) — voir Planifier et envoyer.