Accessibilité
Ressources pour les développeurs

Création de rapports avec ColdFusion MX 7

Ben Forta

www.forta.com*

La création de fonctions de reporting est sans doute la tâche la plus commune pour les développeurs, et ce depuis les débuts de la révolution créée par l'informatique. Les développeurs Macromedia ColdFusion n'avaient auparavant pas beaucoup de choix quant aux possibilités de création de rapports et d'intégration à leurs applications. Ils devaient quitter le « confort » de ColdFusion et utiliser une autre application ou rédiger du code CFML pour créer des mises en page HTML, une solution qui demandait une grande quantité de code CFML pour lire des données d'une base de données, traiter les données et produire le résultat HTML.

Ce type de travail peut être fastidieux, répétitif et simplement ennuyant. Même après tout ce travail, un résultat optimal n'est pas garanti. Le format HTML n'ayant rien de prévu pour les sauts de page, les en-têtes ou les pieds de page, le résultat imprimé à partir du navigateur n'a généralement pas bonne apparence.

L'équipe ColdFusion a réussi à créer, pour ColdFusion 7, une fonction de reporting qui simplifie grandement cette tâche. Vous pouvez désormais vous concentrer sur le développement d'applications dynamiques sans vous inquiéter du résultat à l'impression.

Configuration requise

Le suivi de ce didacticiel requiert les éléments suivants :

ColdFusion MX 7

Didacticiels et fichiers fournis en exemple :

Remarque – Ce fichier ZIP contient les exemples utilisés pour votre premier rapport. Si vous avez installé ColdFusion MX 7 sans les applications fournies en exemple, vous devrez exécuter le programme d'installation et sélectionner l'option des exemples d'application au cours du processus d'installation.

Connaissances prérequises :

La connaissance des fonctions de ColdFusion est utile mais pas nécessaire.

Syntaxe de la nouvelle balise cfreport

La balise cfreport a fait l'objet de quelques révisions. La nouvelle syntaxe (qui ne change pas la prise en charge de l'intégration avec Crystal Reports) est la suivante :

<cfreport
     template = "nom du fichier de définition"
     format = "PDF or FlashPaper" ou "excel"
     name = "variable cf"
     filename = "nom du fichier de résultat"
     query = "variable de requête"
     overwrite = "yes" ou "no"
     encryption = "128-bit" ou "40-bit" ou "none"
     ownerpassword = "mot de passe"
     userpassword = "mot de passe"
     permissions = "liste de permissions"
>
     balises cfreportparam [facultatif]
</cfreport>

La solution de reporting ColdFusion MX 7

La solution de reporting ColdFusion est composée de deux éléments : un moteur de reporting et un « créateur de rapport ».

Le moteur de reporting fournit les fonctions suivantes : représentation graphique des données, mise en page par colonnes, prise en charge des paramètres d'exécution des rapports, production de résultat en trois formats (Adobe PDF, Macromedia FlashPaper ou Microsoft Excel). Les résultats peuvent être envoyés directement dans un navigateur, enregistrés sur disque ou envoyés par courrier électronique.

La fonction de reporting présente plusieurs avantage pour les développeurs ColdFusion :

Le créateur de rapport contient les assistants suivants :

Examinons le créateur de rapport d'un peu plus près.

Créateur de rapport de ColdFusion

Le créateur de rapport de ColdFusion est l'outil utilisé pour créer les fichiers de rapports ColdFusion (fichiers CFR) consommés par le moteur de reporting. Le créateur de rapport n'est disponible que dans la version Windows, même si les rapports peuvent être exécutés sur la plupart des plates-formes sur lesquelles ColdFusion peut être déployé (Windows, Linux, Solaris, Mac OS X, HPUX et AIX – HPUX et AIX ne sont pris en charge que pour les déploiements Java).

L'assistant de configuration de serveur est affiché à la première exécution du créateur de rapport pour vous aider à configurer le fonctionnement de ce dernier avec le serveur ColdFusion. Il vous permet de modifier tous les paramètres, dans l'écran des préférences, paramètres que vous pouvez également modifier par la suite en exécutant à nouveau cet assistant.

La fonction de reporting de ColdFusion est basée sur un mode de création de rapports à bandes. En d'autres termes, chaque section du rapport est séparée en bandes distinctes, chaque section (ou bande) est une région imprimable du rapport. Chaque bande a ses propres règles spécifiant les paramètres d'impression. Le créateur de rapport affiche chacune de ces bandes dans l'espace de travail, de haut en bas, dans l'ordre suivant :

Une bande spéciale, la bande de filigrane, est imprimée sur chaque page. Le système d'aide, accessible à partir du menu Aide, contient de plus amples informations sur les différentes bandes.

Le créateur de rapport est composé de quatre régions principales (voir Figure 1) :

Disposition du créateur de rapport

Figure 1. Disposition du créateur de rapport

L'espace de travail affiché au milieu de l'écran est utilisé pour placer les images, les étiquettes, le texte ou tout autre élément que vous souhaitez imprimer. Le panneau des propriétés, dans l'angle supérieur droit, affiche les propriétés de l'objet ou du texte sélectionné dans l'espace de travail. Les panneaux des champs et des paramètres, sous le panneau des propriétés, affichent les champs (de la base de données ou calculés pour le rapport) et les paramètres disponibles pour le rapport. Enfin, le panneau des styles de texte permet de définir les attributs du texte du rapport.

Création d'un exemple de rapport

Ce didacticiel a été conçu pour vous permettre de créer un exemple de rapport à l'aide du créateur de rapport de ColdFusion, pour vous aider à découvrir les fonctions suivantes des rapports ColdFusion MX 7 :

La section suivante va vous permettre de créer un rapport comprenant plusieurs éléments : en-tête de rapport, en-tête de page, page de détails et requêtes.

  1. Ouvrez le créateur de rapport.
  2. Créez un nouveau document de rapport, à l'aide de l'option As a Blank Report.
  3. Enregistrez votre rapport dans la racine de votre serveur ColdFusion, avec le nom FirstReport.cfr.

Par défaut, le créateur de rapport affiche un certain nombre de bandes : en-tête de rapport, en-tête de colonne, détails, pied de colonne, pied de page de rapport. Le créateur de rapport n'affiche pas, par défaut, les éléments suivants : en-tête de page, pied de page, filigrane, et bandes créés à partir de l'option de gestion de groupe (une explication est donnée un peu plus loin).

Les bandes affichées représentent tout ce que votre rapport peut contenir. Certaines bandes, telles que l'en-tête de rapport, n'apparaissent qu'une seule fois, en haut de chaque première page du rapport dans le cas présent. Les autres bandes, surtout la bande des détails, sont répétées à plusieurs reprises en fonction des données des requêtes, du regroupement et du nombre de pages.

Création d'une requête pour votre rapport dans le créateur de requête

Pour ouvrir le créateur de requête, choisissez Report > Report Query dans la barre des menus ou cliquez sur le bouton Report Query dans la barre des menus. Le créateur de requête apparaît.

Pour sélectionner une source de données :

  1. Vérifiez que vous avez sélectionné le bon serveur RDS en choisissant un serveur RDS dans la liste placée au-dessus de l'arborescence. Le créateur de requête affiche une liste des sources de données définies pour le serveur ColdFusion associé.
  2. Sélectionnez une source de données en cliquant dessus ou en cliquant sur le signe (+) en regard de la source de données pour développer la liste.

  3. Développez l'arborescence de la source de données :

    • Cliquez sur le signe (+) en regard de Tables pour afficher le schéma de la base de données.
    • Cliquez sur le signe (+) en regard du nom de table pour afficher les définitions de colonne.

Créez une requête SQL dans le panneau Table et le panneau Properties :

  1. Sélectionnez un serveur RDS.
  2. Développez une source de données.
  3. Faites glisser une ou plusieurs tables du panneau Table vers le panneau Data Source. Vous pouvez obtenir le même résultat en cliquant sur une table avec le bouton droit et en sélectionnant Add to Work Area. Vous pouvez également sélectionner une table en double-cliquant dessus ou en cliquant sur le panneau Table avec le bouton droit.
  4. Pour supprimer une table du panneau Table, cliquez sur la table à retirer avec le bouton droit et sélectionnez Remove Table.
  5. (Facultatif) Si vous sélectionnez plus d'une table, vous devez spécifier la colonne ou les colonnes utilisées pour les joindre en faisant glisser une colonne d'une table vers la colonne associée dans la seconde table.
  6. Double-cliquez sur les colonnes pour la requête SELECT.

Lorsque vous sélectionnez des colonnes, le créateur de requête crée la requête SELECT dans la moitié inférieure du panneau :

  1. (Facultatif) Spécifiez l'ordre de tri et les critères de sélection.
  2. Examinez la requête SELECT affichée dans le panneau SQL, puis utilisez les panneaux Table et Properties pour effectuer toute correction nécessaire.
  3. (Facultatif) Cliquez sur Test Query.
  4. Cliquez sur Save.

Le créateur de requête enregistre l'instruction SQL comme partie du rapport et définit les champs de requête pour les colonnes renvoyées par le jeu de résultats. La documentation LiveDocs de ColdFusion contient de plus amples informations.

Le créateur de requête devrait avoir l'aspect présenté dans la figure 2 dans le cas de notre exemple.

Créateur de requête de ce didacticiel

Figure 2. Créateur de requête de ce didacticiel

Les exemples de rapport utilisent des « styles de texte » pour formater les éléments qui affichent des polices. Les « styles de texte » sont semblables aux styles de police de Microsoft Word. Les éléments de texte sont associés à un style au lieu d'être associés de façon explicite à des spécifications de police. La section Using Text Styles de la documentation LiveDocs de ColdFusion contient de plus amples informations.

Mise en forme du rapport

La boîte à outils du créateur de rapport contient tout ce dont vous avez besoin pour tracer, saisir du texte ou placer tous les éléments nécessaires dans le rapport.

Mise en forme de l'en-tête du rapport

Pour créer un en-tête de rapport à l'aide de la boîte à outils du créateur de rapport :

  1. Cliquez sur le bouton représentant un éclair. Il s'agit du contrôle de champ, qui permet d'afficher les expressions texte devant apparaître dans votre rapport. Les expressions, comme vous allez le voir, peuvent contenir les éléments suivants : texte statique, texte dynamique, texte calculé et texte concaténé.

  2. Utilisez votre curseur pour redimensionner l'en-tête de rapport. Une boîte de dialogue apparaît pour vous demander de sélectionner une des options suivantes : valeurs existantes du rapport (telles que des données d'une requête créée dans le créateur de requête) ou expression saisie manuellement. Sélectionnez une expression saisie manuellement et saisissez les éléments suivants :

    "Format du rapport : " & param.outputFormatLabel

    Cette expression regroupe du texte statique et un paramètre prédéfini, outputFormatLabel, spécifié dans la balise cfreportparam, incorporée dans la balise cfreport, qui est celle qui invoque votre rapport (voir ci-après pour des informations supplémentaires). Comme nous l'avons déjà expliqué, le contenu de l'en-tête de rapport apparaît une fois sur la première page de votre rapport. Dans cet exemple, c'est « Format du rapport : FlashPaper » qui pourrait apparaître.

  3. Le texte doit apparaître dans le coin supérieur gauche de l'en-tête du rapport. Le champ de texte étant sélectionné (ce qui est indiqué par l'apparition de poignées sur le rectangle), cliquez sur le bouton Align to Band dans la palette Align, sur le bouton Align Left Edges, puis sur le bouton Align Top Edges. Le texte est alors déplacé vers la bande supérieure gauche, tout en respectant les limites extérieures de la bande.
  4. Pour redimensionner ou déplacer la bande sélectionnée, cliquez sur l'élément pour le déplacer, utilisez les touches fléchées du clavier, cliquez sur les poignées de l'élément pour les faire glisser, ou changez les valeurs de cet élément dans le panneau Properties sous Layout (valeurs telles que Height, Width, Left, Top, etc.). Prenez note des propriétés associées à chaque nouveau type d'élément utilisé dans votre rapport dans le panneau Properties pour mieux identifier chaque propriété que vous pouvez configurer.

  5. Indiquez un titre de rapport en texte statique. Dans la boîte à outils, cliquez sur le bouton abc (la mention « Label » apparaît au survol du pointeur). Tracez un rectangle de la largeur de la bande d'en-tête de rapport. Vous remarquerez que le créateur de rapport ne vous invite pas à indiquer d'expression lorsque vous relâchez le pointeur, mais vous invite plutôt à entrer du texte. Saisissez la ligne suivante :

    Works of Art on Consignment (grouped by Artist)

    Vous pouvez aligner le cadre autour du texte, mais aussi le texte, en choisissant Properties Panel > Format > Alignment ou en utilisant la barre d'outils Text and Styles. Les champs dynamiques et statiques apparaissent de façon différente dans le rapport. Les champs sont encadrés d'une ligne pleine. Les étiquettes ne sont entourées que de crochets.

  6. L'en-tête du rapport est presque terminé, à l'exception de l'inclusion de couleurs. Cliquez sur le bouton Rectangle de la boîte à outils et faites-le glisser, comme n'importe quel autre contrôle de texte. Réglez les points du contrôle de façon à ce que le rectangle occupe toute la largeur et toute la hauteur de la bande d'en-tête. Le rectangle étant sélectionné, donnez à la couleur d'arrière-plan la valeur de votre choix en sélectionnant Properties Panel > Colors & Style > Background Color ou à l'aide du pot de peinture Background Color du panneau Text Styles.
  7. Vous remarquerez que le rectangle du rapport couvre les deux éléments placés dans l'en-tête, ce que l'on appelle « ordre z ». En gros, vous avez empilé votre rectangle sur les autres éléments. Cliquez sur le rectangle avec le bouton droit et sélectionnez Send to Back. Comme pour pratiquement chaque commande du créateur de rapport, un même résultat peut être obtenu de plusieurs façons (raccourcis clavier, panneaux, boîtes à outils, clic avec le bouton droit).

Voilà, c'est tout pour l'en-tête !

Mise en forme de l'en-tête de page

Saisissez la date d'aujourd'hui dans l'en-tête de page. Ce rapport ColdFusion est traité comme une page ColdFusion et peut accéder à toutes les variables auxquelles la page contenant la balise cfreport et invoquant le rapport (à moins qu'un utilisateur accède directement à la définition du rapport) peut accéder. Il a également accès à toutes les fonctions ColdFusion.

Vous pouvez explorer les fonctionnalités disponibles pour votre rapport en faisant glisser un champ de texte (dynamique, identifié par un éclair) sur l'en-tête de page et en saisissant l'expression suivante :

DateFormat(Now (), "d mmmm yyyy")

Vous venez d'utiliser la fonction ColdFusion Now(), que vous avez mise en forme à l'aide d'une autre fonction, DateFormat(). Vous aurez remarqué que le créateur d'expression vous a indiqué différentes options de saisie automatique du code. Vous pouvez profiter de cette fonction ou simplement continuer à taper.

Mise en forme de la bande de détails

Passons maintenant au coeur du rapport, la bande de détails. Cette bande est imprimée dans votre rapport pour chaque ligne de données renvoyée par votre requête (la requête spécifiée dans votre rapport à l'aide de la balise cfreport ou que vous avez intégrée au rapport à l'aide du créateur de requête).

Voyez si vous pouvez répliquer la mise en page décrite ci-dessous dans la bande des détails, avec ce que vous savez concernant les champs, les étiquettes, la mise en page et les expressions. Si vous ne connaissez pas encore bien le langage CFML, ne vous attaquez pas à cette étape avant de vous familiariser avec ces fonctions. Remarquez que les éléments entre parenthèses sont fournis pour information seulement et ne doivent pas être inclus dans le rapport. Essayez vous-même :

------ Detail Band Start ------
(Label) Artist Contact Info
(Label) Name: (Field) query.FIRSTNAME & " " & query.LASTNAME
(Label) Address: (Field) report.FormatAddress("", query.ADDRESS, "", query.CITY, query.STATE, query.POSTALCODE)
(Label) Email: (Field) query.EMAIL
(Label) Phone: (Field) report.FormatPhone(query.PHONE, "", "")
(Label) Fax: (Field) report.FormatPhone(query.FAX, "", "")

(Label) "See all artwork by " & query.FIRSTNAME
------ Detail Band End ------

Remarque – L'affichage d'images dans les rapports requiert l'inclusion du chemin des fichiers correspondants. Ici, j'ai utilisé Application.cfm pour définir une variable d'application appelée application.sImageLocation. Dans le rapport que vous avez appelé works-of-art-by-artist.cfr, l'élément de champ sous l'étiquette d'image a l'expression suivante : application.sImageLocation & "/" & query.LARGEIMAGE. Le nom du fichier étant enregistré dans la table, la concaténation du chemin de l'image permet d'associer les fichiers de façon dynamique dans le rapport.

Ajout d'un sous-rapport

Il vous reste un élément à ajouter à la bande des détails : un autre rapport, qui sert de sous-rapport du rapport principal. Ce concept est semblable à la façon dont un développeur ColdFusion regroupe les données de requêtes, c'est-à-dire à l'aide de balises cfoutput.

Les sous-rapports sont utilisés pour imbriquer un rapport au sein d'un autre rapport. Les données affichées dans un sous-rapport sont généralement liées aux données du rapport principal. Les sous-rapports sont invoqués en transmettant un ou plusieurs paramètres de sous-rapport du rapport principal au sous-rapport. Cependant, les données affichées dans un sous-rapport peuvent également ne pas être liées aux données du rapport principal. Une telle relation entre rapports est également appelée « principal/détail » ou « parent/enfant ».

  1. Dans la barre d'outils, sélectionnez l'outil Subreport et tracez un cadre dans la bande des détails.
  2. A l'invite de l'assistant de sous-rapport, sélectionnez l'option From an Existing Report.
  3. Sélectionnez le fichier consignment-report.cfr.
  4. L'assistant de sous-rapport vous invite à spécifier les paramètres de liaison entre le rapport principal et le sous-rapport. Pour cet exemple, sélectionnez #query.ARTISTID#.
  5. Cliquez sur Finished.

La documentation LiveDocs de ColdFusion contient de plus amples informations.

Ajout d'un pied de page

Placez un contrôle de champ dans le pied de page à l'aide de la variable suivante : 

calc.PAGE_NUMBER

La variable calc.PAGE_NUMBER est une des quelques variables disponibles pour les rapports. Les autres variables sont :

La documentation LiveDocs de ColdFusion contient de plus amples informations, tout particulièrement dans la section Built-in Calculated Fields and Input Parameters.

Consultation du rapport

La quantité de code ColdFusion nécessaire à l'affichage de ce rapport est très réduite étant donné que vous avez déjà incorporé votre requête dans la définition du rapport. Enregistrez ce code ColdFusion dans votre racine web (là où se trouve votre fichier CFR). Enregistrez-le sous le nom FirstReport.cfm :

<cfreport template="FirstReport.cfr" format="flashpaper">
     <cfreportparam name="outputFormatLabel" value="flashpaper">
     <cfreportparam name="reportTemplateName" value="FirstReport">
</cfreport>

Sélectionnez FirstReport.cfm : la version FlashPaper de votre rapport apparaît. Vous pouvez changer la valeur de l'attribut de format de la balise cfreport de flashpaper à pdf ou excel.

Félicitations ! Vous venez de créer votre premier rapport ColdFusion MX 7.

Et après ?

Cet article vous a parmi de découvrir les nouveaux assistants de ColdFusion MX 7. Nous vous recommandons également de consulter les rubriques suivantes de la documentation de ColdFusion et le centre des développeurs ColdFusion pour encore plus d'informations sur la personnalisation des rapports :

A propos de l'auteur

Ben Forta est l'vangliste senior de Macromedia et l'auteur de plusieurs ouvrages, tels que ColdFusion Web Application Construction Kit* et sa suite, Advanced ColdFusion Application Development*, de mme que d'ouvrages sur SQL, JavaServer Pages, WAP, le dveloppement Windows, etc. Ben a galement particip la rdaction des supports de formation de Macromedia ColdFusion, des tests de certification et des guides de prparation Macromedia Press* correspondants, et passe la plus grande partie de son temps discuter du dveloppement d'applications, par le biais de confrences ou d'articles. Son blog, forta.com/blog*, regroupe ses ides les plus rcentes concernant ColdFusion et d'autres technologies.