Personnalisation des rapports d'information BIRT à partir de JMap 7 Istanbul / Customizing BIRT information reports from JMap 7 Istanbul

Owned by Gabriela Orzanco
Sept 16, 2019

Produit concerné / Related product

JMap

Versions

7 Istanbul

Jump to English version

Birt est un moteur de rapports intégré à JMap depuis JMap 4.0.2b. Pour plus d'informations, reportez-vous à l'aide en ligne JMap. Ce document met l'accent sur  la personnalisation de ces rapports. Pour modifier un rapport Birt, l'éditeur de Birt doit être téléchargé et installé. Les instructions pour installer et télécharger Birt sont disponibles sur le site d’Eclipse: http://eclipse.org/birt.  La version exacte de Birt est très importante.  Pour les version JMap 6.0a et plus, la version Birt 4.4.0 est requise.  Pour les versions inférieures à JMap 6.0a, la version Birt 3.7.0 est requise.  

Il ya deux notions importantes aux rapports Birt dans JMap. La première est un modèle et la seconde est un rapport généré.

Modèles

Les modèles se trouvent dans le répertoire d'installation JMap: \applications\templates\reports. Il y a actuellement quatre modèles de rapports fournis avec JMap:

  • inforequest.rpttemplate : Simple rapport d’information.

  • inforequestMap.rpttemplate : Simple rapport d’information avec carte.

  • selectionreport.rpttemplate : Rapport de selection

  • selectionreportMap.rpttemplate: Rapport de sélection avec carte.

Ces rapports ne contiennent aucune information relative aux informations de la couche. Ils sont essentiellement des rapports vierges qui sont utilisés comme modèles par JMap lorsque de nouveaux rapports d'information Birt sont créés. Ces rapports peuvent être modifiés par un administrateur, mais ce n'est pas recommandé parce que ces modèles pourraient être écrasées lors de la mise à jour la version du serveur JMap. Si les administrateurs veulent modifier ces modèles pour ajouter leur propre logo, changer les styles, structure, etc., alors ils devraient copier et renommer chacun dans les répertoires correspondant:    jmap\applications\templates\reports\single pour le rapport d’information et jmap\applications\templates\reports\multiple pour le rapport de sélection. Ces nouveaux modèles apparaîtront dans la liste des modèles lors de la création du rapport de l'information. 

Par exemple, après avoir copié inforequest.rpttemplate dans \applications\templates\reports\single et renommé en myCustomReport.rpttemplate, lorsque vous créerez un nouveau rapport d’information, le modèle de rapport sera disponible dans la liste des modèles:



Les noms des nouveaux modèles doit être différents des noms des modèles par défaut fourni par JMap. Une fois qu'un rapport a été créé à partir d'un modèle, il n'est pas actuellement possible de régénérer le rapport à partir du modèle à moins d’effacer le rapport généré. (Voir la prochaine section) 

Rapports générés

Une fois qu'un administrateur a créé un rapport d'information sur une couche, JMap va générer des rapports Birt en utilisant les modèles spécifiés et ajouter les informations relatives à la couche tels que les attributs, les liens hypertexte, etc. Ces rapports générés apparaîtront maintenant dans jmap\applications\reports\#projectId#\#layerId#\. Donc par exemple, si on avait un projet The World (project id ‘0’) et une couche Cities (layer id ‘4’), le répertoire serait : jmap\applications\reports\0\4\. Ces rapports sont donc peuplés par JMap et prêt à être utilisés.

Chaque fois qu’un rapport d’information est généré, il y aura deux rapports Birt. Le premier; single_#infoIndex#.rptdesign et le second; multiple_#infoIndex#.rptdesign. Single réfère au rapport d’information et multiple réfère au rapport de sélection. Le #inforeIndex# fait référence à l’index du rapport d’information qui peut être affiché en déplaçant le curseur sur un rapport d’information dans la page de configuration de la couche. (single_0.rptdesign, single_1.rptdesign, etc) Une fois le curseur sur le titre d’un rapport, l’information apparaitra dans la barre de statut, avec aussi l’identifiant du projet et de la couche.



Ces rapports générés peuvent être modifiés avec l'éditeur Birt et toute modification de leur style ou leur structure n'affectera que le rapport d'information particulier. Si vous modifiez ce rapport par exemple en changeant son titre ou ses attributs sélectionnés à l'aide de JMap Admin, JMap ira modifier en conséquence le présent rapport. Il parcourra les divers éléments du rapport, modifiera le titre du rapport (si c'est un nom d'élément Birt n'a pas été modifié) et aussi modifier le tableau pour ajouter ou supprimer ses attribut.

JMap s'appuie sur le nom des éléments Birt pour modifier le rapport donc ceux-ci ne doivent pas être changés. Les éléments important dans le rapport BIRT pour JMap sont les suivants. Si ils sont modifiés, le rapport ne sera pas bien mis à jour:

  • Étiquette de titre Birt: jmapLableReportTitle

  • Source de données Birt (datasource): jmapInfoDatasource

  • Nom du jeu de données (dataset): jmapInfoDataset

  • Table d’information Birt: jmapDataTable


Ajout de cartes

Il est possible d'ajouter des images représentant des cartes qui seront générées par le client lors de la génération de rapports. Deux modèles de rapports Birt avec une carte sont fournis avec JMap. Un rapport peut contenir un nombre multiple d'images. Les administrateurs peuvent également ajouter des paramètres à chaque image, ce qui va dicter la façon dont les images seront générées.





Pour ajouter une carte à un rapport, l’administrateur doit suivre les étapes suivantes:

  1. Créer une image incorporée (embedded) dans le rapport. L'image source intégrée est sans importance et sera automatiquement remplacée par l'image de carte lors de la génération du rapport, mais chaque image doit correspondre à des images intégrées séparées:



      2.  L’administrateur doit spécifier des propriétés définies par l’usager dans les propriétés de l’image. (User defined properties). Une seule propriété est obligatoire; JMAP_IMAGE dont la valeur doit être à vrai. Les autres propriétés sont optionnelles.



JMAP_IMAGE (boolean) requise: Indique que cette image doit être gérée par JMap.

JMAP_IMAGE_ZOOM (String) optionnel (valeur par défaut ‘scale’): Ce paramètre spécifie si la carte devrait essayer de préserver soit l’échelle de la carte ou si elle devrait afficher la région entière de la vue dans l'image. Deux valeurs possibles: 1) "scale", ce qui indique l'échelle doivent être conservée ou 2) «region» qui indique que la région de la vue entière doit être affiché dans l'image.

JMAP_IMAGE_DRAW_STATIC (Boolean) optionnel (défaut vrai): Indique si les éléments statiques doivent être dessinés sur la carte. Les éléments statiques sont par exemple l’échelle, la flèche du nord, logos, etc. Valeur par défaut vrai.

JMAP_IMAGE_X et JMAP_IMAGE_Y (Float) optionnel. Le centre X et Y de la carte dans l’unité du projet. Par défaut, le centre de la carte du client est utilisé.

JMAP_IMAGE_SCALE (Float) optionnel. Spécifie l’échelle de la carte. Si la propriété JMAP_IMAGE_ZOOM est ‘region’, cette propriété est ignorée.

       

         3.  Spécifier les valeurs des propriétés définies par l’administrateur. Ces valeurs apparaissent dans les propriétés avancées de l’image.

       

4.  Ajouter le “Birt Report Event Handler” JMapServerBirtReportAdapter au rapport:


Pour ce faire, il faudra ajouter jmap_server.jar aux librairies du projet Eclipse. Le chemin est :    com.kheops.jmap.server.JMapServerBirtReportAdapter  


5.  Aller dans JMap Admin, rendez-vous à la page de configuration du rapport d'information correspondant et appuyez sur Enregistrer. Cela permettra JMap de balayer le rapport et de détecter toute nouvelle information des images que vous avez ajoutées. Cette étape est cruciale. Si ce n’est pas fait, les propriétés changées ne seront pas tenues en compte par JMap.

Note

Lorsque la configuration d'un rapport d'information est modifiée dans JMap Admin, il est nécessaire de redémarrer les applications JMap pouvant utiliser ce rapport pour que les modifications soient effectives.

Pour les modifications apportées directement à un rapport Birt, il n'est pas nécessaire de relancer l’application ou même de relancer un rapport d'information à partir de l’application.  Par exemple, si un rapport d'information a été généré en affichant les valeurs de 5 éléments, il faut simplement rafraichir la page du navigateur web après une modification pour voir les modifications apportées au rapport.

English version

Birt is a reporting engine integrated in JMap since JMap 4.0.2b. For more information, refer to the JMap online help. This document focuses on customizing these reports. Birt instructions and download available on the Eclipse website: http://eclipse.org/birt. There are two important notions to Birt JMap reports. The first is a template and the second is a generated report. To modify a Birt report, the Birt editor must be downloaded and installed.  It is important to download and use the exact Birt version.  For JMap 6.0a and up, the Birt version to use is 4.4.0.  For JMap 6.0 and below, the Birt version to use is 3.7.0

JMap Birt Templates

The templates are located in the JMap installation directory: \applications\templates\reports

There are currently four report templates provided with JMap:

  • inforequest.rpttemplate : Simple information report

  • inforequestMap.rpttemplate : Simple information report including a map image

  • selectionreport.rpttemplate : Report for a selection of elements

  • selectionreportMap.rpttemplate: Report for a selection of elements with map image

These reports do not contain any information pertaining to any report. They are basically blank reports which are used as templates by JMap when new Birt information reports are created. These reports could be modified by an administrator but this is not recommended because these templates could be overwritten when updating the JMap server version.

If administrators wish to modify these templates to add their own logo, change the styles, etc., then they should copy any of those templates in either single for inforequest or multiple for selection reports directories, and rename the reports. Then, these new reports will appear in the list of templates during Information report creation. Once a report has been created from a template, it is not currently possible to regenerate the report from a template. For example, after copying inforequest.rpttemplate to \applications\templates\reports\single and renaming it to myCustomReport.rpttemplate, when creating a new JMap Information report, the report template will be available in the template list:



The new report templates name must be different to the default JMap templates.


Generated Birt reports

Once an administrator has created an information report on a layer, JMap will generate a Birt report using the specified templates, adding information pertaining to the layer such as the attributes, hyperlink, etc. This generated report will now appear jmap\applications\reports\#projectId#\#layerID#\. So for example, if we have created an inforeport in the project The World (project id ‘0’) on layer Cities (layer id ‘4’), the directory would be: jmap\applications\reports\0\4\. Each time an information report is generated; there will be two Birt reports single_#infoIndex#.rptdesign and multiple_#infoIndex#.rptdesign. Single referring to the information report template and multiple to the selection report template.

The #inforeIndex# refers to the index of the information report. To find the report index, simply go to the information report page and move your cursor over one of the report and the status bar will indicate the information report index as well as the project and layer Id.



These generated reports can be modified with the Birt editor and any changes to their style or design will only affect the report for this particular information report. If you edit this report by for example changing its title or its selected attributes using the JMap admin, JMap will accordingly modify this report. It will scan through the report elements, modify the report title (if it’s Birt element name hasn’t been modified) and also modify the table to add or remove any attribute.


JMap relies on the name of the Birt elements to modify the report so these should not be changed, the improtant Birt elements to JMap are, if any of these are changed, the report might not be updated correctly:

  • Birt title lable: jmapLableReportTitle

  • Birt datasource name: jmapInfoDatasource

  • Birt dataset name: jmapInfoDataset

  • Birt data table: jmapDataTable


Adding embedded JMap images

It is possible to add an image which will generated by the client during the report generation. Two templates provided with JMap include such an image. A report can contain a multiple number of images. Administrators can also add parameters to each image which will dictate how the images are generated.


For a map image to be displayed on the Birt report, one has to follow the following steps:

  1. Create an embedded image in the report. The source embedded image is unimportant and will be automatically replaced by the map image during report generation, but each image must correspond to separate embedded images:



2. The administrator must specify a set of user defined properties. Most are optional, but one, JMAP_IMAGE is required and indicated to JMap that JMap should provide the data for this image:



JMAP_IMAGE (boolean) required: Indicates that this image element corresponds to a Map image to be handled by JMap

JMAP_IMAGE_ZOOM (String) optional (default scale): This parameter specifies if the map image should try to either preserve the map scale or if it should draw the entire view region in the image. So it has two possible values: 1) “scale”, which indicates scale must be preserved or 2) “region” which indicates that the entire view region must be displayed in the image.

JMAP_IMAGE_DRAW_STATIC (Boolean) optional (default true): This Boolean indicates if static elements must be drawn on the map image. Static elements are for example the scale bar, north arrow, logos, etc. The value is true by default.

JMAP_IMAGE_X and JMAP_IMAGE_Y (Float) optional. The center X and Y coordinate of the Map image corresponding to the Map’s unit. By default, the map image will represent the region of the map when the client launched the information report.

JMAP_IMAGE_SCALE (Float) optional. A specific scale to display the map. If the JMAP_IMAGE_ZOOM is set to region, this parameter is ignored.  


3.  Set the values of the user defined properties. This can be done under the advanced section of the image’s properties.  

4. Set the Birt Report Event Handler to JMapServerBirtReportAdapter :


To do this, you will have to include jmap_server.jar to your project’s library, the complete classpath is:   com.kheops.jmap.server.JMapServerBirtReportAdapter  


5.  Go to the JMap admin, go to the corresponding information report you just modified configuration’s page and hit ‘save’. This will allow JMap to scan the report and detect any new image information you have added. This step is crucial. If you then modify your report, to change for example one of the image user properties values, for the changes to be applied in JMap, you must go to the information report configuration page and hit ‘save’.