Tony CHEMIT pushed to branch develop at ultreiaio / ird-observe Commits: b5ef9ebc by Tony Chemit at 2024-03-15T14:38:31+01:00 Update reports documentation - - - - - 2 changed files: - src/site/markdown/report/index.md.vm - src/site/markdown/report/syntax.md Changes: ===================================== src/site/markdown/report/index.md.vm ===================================== @@ -118,7 +118,7 @@ version applicative, à savoir dans Dans la configuration de l'assistant, par défaut on utilise ce fichier. -Il est envisagé en *v10* de faire évoluer cela pour que chaque rapport puisse être décrit dans un fichier séparé. +Depuis la version **9.3.0**, chaque rapport est décrit dans un fichier séparé. Cela aura pour avantage : @@ -126,6 +126,54 @@ Cela aura pour avantage : * de simplifier l'écriture de ceux-ci (on pourra alors supprimer tous les préfixes actuellement utilisés pour identifier un rapport). * de pouvoir organiser ces rapports par modèle métier, ou par type d'organisation +Tous les rapports sont regroupés dans un répertoire des resources de la version applicative, à savoir dans + +```.observe/resources-${project.version}/report/default``` + +dont voici le contenu (en 9.3.0) + +``` +resources-9.3.0-RC-5/report/ +└── default + ├── ll + │ ├── llCommonTripGearUseFeatures.report + │ ├── llLanding.report + │ ├── llLogbookActivities.report + │ ├── llLogbookCatches.report + │ ├── llLogbookSamplesOnActivity.report + │ ├── llLogbookSamplesOnBoth.report + │ └── llLogbookSamplesOnTrip.report + └── ps + ├── psCommonTripGearUseFeatures.report + ├── psLocalmarketBatch.report + ├── psLocalmarketSample.report + ├── psLocalmarketSurvey.report + ├── psLogbookActivity.report + ├── psLogbookSampleMeasures.report + ├── psLogbookSampleSet.report + ├── psLogbookSampleSpeciesMeasuresCount.report + ├── psLogbookSampleSpeciesMeasures.report + ├── psLogbookTrip.report + ├── psLogbookWellPlanCheck.report + ├── psLogbookWellPlan.report + ├── psObservationActivitiesByZone.report + ├── psObservationActivityWithComment.report + ├── psObservationAllActivities.report + ├── psObservationCatch.report + ├── psObservationCatchTotalCountByGroupAndSpeciesFateDiscardPerAssociation.report + ├── psObservationCatchTotalCountByGroupPerReasonForDiscard.report + ├── psObservationCatchTotalCountByGroupPerSpeciesFate.report + ├── psObservationCatchWeightByGroupAndSpeciesFateDiscardPerAssociation.report + ├── psObservationCatchWeightByGroupPerReasonForDiscard.report + ├── psObservationCatchWeightByGroupPerSpeciesFate.report + ├── psObservationDailySetAndCatch.report + ├── psObservationFobUsageExtended.report + ├── psObservationFobUsageMinimal.report + ├── psObservationLengthsDistribution.report + ├── psObservationRepartionCaleeParCuve.report + └── psObservationSetByAssociation.report +``` + ## Description du fonctionnement général d'un rapport ### Prération des variables ===================================== src/site/markdown/report/syntax.md ===================================== @@ -6,78 +6,110 @@ Ce document décrit comment écrire un rapport. Comme écrit dans la page de présentation des rapports, ceux-ci sont décrits dans un fichier de type *properties*. -La syntaxe a été uniformisée en version 9. +La syntaxe a été uniformisée en version 9 et depuis la 9.3.0 chaque rapport est décrit dans un fichier séparé. ### Identifiant d'un rapport -Chaque rapport possède un identifiant unique; celui-ci est utilisé pour identifier toute sa description dans le fichier -global. +Chaque rapport possède un identifiant unique; le nom du fichier correspondant est **id.report**. Voici un premier exemple de rapport pour mieux comprendre comment cela s'organise : ```properties -report.llCommonTripGearUseFeatures.modelType=LL -report.llCommonTripGearUseFeatures.name=Liste des équipements -report.llCommonTripGearUseFeatures.description=Afficher les équipements -report.llCommonTripGearUseFeatures.columns=Equipement,Nombre,Utilisé dans la marée,Mesures -report.llCommonTripGearUseFeatures.repeatVariable.1.name=gearUseFeaturesId -report.llCommonTripGearUseFeatures.repeatVariable.1.type=java.lang.String -report.llCommonTripGearUseFeatures.repeatVariable.1.request=Select g.id \ +modelType=LL +name=Liste des équipements +name.en=Gears uses features +name.es= +description=Afficher les équipements +description.en=Display gear uses features +description.es= +columns=Equipement,Nombre,Utilisé dans la marée,Mesures +columns.en=Gear,Number,Used in trip?,Measures +columns.es= +repeatVariable.1.name=gearUseFeaturesId +repeatVariable.1.type=java.lang.String +repeatVariable.1.request=Select g.id \ From fr.ird.observe.entities.data.ll.common.TripImpl m \ Join m.gearUseFeatures g \ Where \ m.id In :tripId \ and g in elements (m.gearUseFeatures) \ -Order By g.gear.label2 -report.llCommonTripGearUseFeatures.request.1.location=0,0 -report.llCommonTripGearUseFeatures.request.1.layout=row -report.llCommonTripGearUseFeatures.request.1.request=Select \ -concat(CASE When g.gear.code IS NULL Then 'Aucun code' Else g.gear.code End, ' - ', g.gear.label2), \ +Order By g.gear.@i18nColumnName@ +request.1.location=0,0 +request.1.layout=row +request.1.request=Select \ +concat(CASE When g.gear.code IS NULL Then '@noCode@' Else g.gear.code End, ' - ', g.gear.@i18nColumnName@), \ g.number, \ -( CASE g.usedInTrip When true Then 'Oui' Else Case g.usedInTrip When false Then 'Non' Else 'Indéterminé' End End )\ +( CASE g.usedInTrip When true Then '@yes@' Else Case g.usedInTrip When false Then '@no@' Else '@Null@' End End )\ From fr.ird.observe.entities.data.ll.common.GearUseFeaturesImpl g \ Where g.id = :gearUseFeaturesId -report.llCommonTripGearUseFeatures.request.1.repeat.name=gearUseFeaturesId -report.llCommonTripGearUseFeatures.request.1.repeat.layout=column -report.llCommonTripGearUseFeatures.operations.1.type=ComputeMeasurementsLongline +request.1.repeat.name=gearUseFeaturesId +request.1.repeat.layout=column +operations.1.type=ComputeMeasurementsLongline +i18n.Null=Indéterminé +i18n.Null.en=Undefined +i18n.Null.es=Indeterminado +i18n.noCode=Aucun code +i18n.noCode.en=No code +i18n.noCode.es= ``` Ici l'identifiant du rapport est ```llCommonTripGearUseFeatures```. Par convention, on utilise le domaine métier **ll**, suivi du sous-domaine métier **Common**, puis enfin un suffixe qui exprime ce que le rapport doit produire **TripGearUseFeatures**. - -Dans le fichier global, toutes les entrées commençants par **report.llCommonTripGearUseFeatures** permettent alors de -décrire le rapport. - + ### Méta-données d'un rapport Il existe cinq méta-données pour un rapport (dont trois sont obligatoires) : ```properties -report.xxx.modelType=PS ou LL -report.xxx.name=Nom du rapport -report.xxx.description=Description du rapport -report.xxx.columns=En-têtes des colonnes du rapport (séparées par des virgules) [Optionnel] -report.xxx.rows=En-têtes des lignes du rapport (séparées par des virgules) [Optionnel] +modelType=PS ou LL +name=Nom du rapport +name.en=Nom du rapport (Anglais) +name.es=Nom du rapport (Espagnol) +description=Description du rapport +description.en=Description du rapport (Anglais) +description.es=Description du rapport (Espagnol) +columns=En-têtes des colonnes du rapport (séparées par des virgules) [Optionnel] +columns.en=En-têtes des colonnes du rapport (séparées par des virgules) (Anglais) [Optionnel] +columns.es=En-têtes des colonnes du rapport (séparées par des virgules) (Espagnol) [Optionnel] +rows=En-têtes des lignes du rapport (séparées par des virgules) [Optionnel] +rows.en=En-têtes des lignes du rapport (séparées par des virgules) (Anglais) [Optionnel] +rows.es=En-têtes des lignes du rapport (séparées par des virgules) (Espagnol) [Optionnel] ``` -```report.xxx.modelType``` permet de définir le domaine métier sur lequel porte le rapport, valeurs possibles : +```modelType``` permet de définir le domaine métier sur lequel porte le rapport, valeurs possibles : * **PS** pour le domaine *Senne* * **LL** pour le domaine *Palangre*. En *V10*, on ajoutera certainement **COMMON** pour le domaine métier des marées agnostiques. -```report.xxx.name``` permet de définir le nom du rapport, ce texte est celui affiché dans la liste déroulante des +```name``` permet de définir le nom du rapport en français, ce texte est celui affiché dans la liste déroulante des rapports à sélectionner dans l'assistant. -```report.xxx.description``` permet de définir une description longue d'un rapport, ce texte est celui affiché +```name.en``` permet de définir le nom du rapport en anglais, si vide le texte français est utilisé. + +```name.es``` permet de définir le nom du rapport en espagnol, si vide le texte français est utilisé. + +```description``` permet de définir une description longue d'un rapport, ce texte est celui affiché comme description lorsqu'un rapport est sélectionné dans l'assistant. -```report.xxx.colomns``` **[Optionnel]** permet de définir les en-têtes de colonnes de manière fixe. +```description.en``` version anglaise, si vide le texte français est utilisé. + +```description.es``` version espagnole, si vide le texte français est utilisé. -```report.xxx.rows``` **[Optionnel]** permet de définir les en-têtes de lignes de manière fixe. +```colomns``` **[Optionnel]** permet de définir les en-têtes de colonnes de manière fixe. + +```colomns.en``` version anglaise, si vide le texte français est utilisé. + +```colomns.es``` version espagnole, si vide le texte français est utilisé. + +```rows``` **[Optionnel]** permet de définir les en-têtes de lignes de manière fixe. + +```rows.en``` version anglaise, si vide le texte français est utilisé. + +```rows.es``` version espagnole, si vide le texte français est utilisé. Il est possible de ne pas les indiquer si le rapport n'a pas d'en-têtes de colonnes ou de lignes fixes; Ces en-têtes seront alors définies via les requêtes du rapport. @@ -100,9 +132,9 @@ variable attend que la seconde soit remplie...** Pour décrire une variable trois lignes sont nécessaires, comme on peut le voir dans l'exemple suivant : ```properties -report.xxx.variable.1.name=speciesGroup -report.xxx.variable.1.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference -report.xxx.variable.1.request=Select distinct sg \ +variable.1.name=speciesGroup +variable.1.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference +variable.1.request=Select distinct sg \ From TripImpl t \ Join t.routeObs r \ Join r.activity a \ @@ -114,11 +146,11 @@ Where t.id In :tripId \ Order By sg.code ``` -```report.xxx.variable.1.name``` définit l'*alias* de la variable que l'on pourra ensuite utiliser dans le +```variable.1.name``` définit l'*alias* de la variable que l'on pourra ensuite utiliser dans le reste de la définition du rapport (par exemple dans d'autres variables, variables de répétition, requêtes ou opérations). -```report.xxx.variable.1.type``` définit le type de la variable. Ce type doit être un type de *dto* ou une +```variable.1.type``` définit le type de la variable. Ce type doit être un type de *dto* ou une *référence de dto*. On ne peut pas ici utiliser un type d'*entité*, puisque l'interface graphique (selon le principe de séparation des couches) n'a pas connaissance du modèle des entités. @@ -133,13 +165,13 @@ l'arbre de navigation; la notion de *dto* étant utilisée au niveau d'un formul * comment décorer la donnée * comment transformer l'entité -```report.xxx.variable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de +```variable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de la variable. Il est possible de documenter cette variable en utilise une quatrième ligne optionnelle : ```properties -report.xxx.variable.1.comment=Un commentaire optionnel pour documenter la variable +variable.1.comment=Un commentaire optionnel pour documenter la variable ``` **À noter que l'utilisation d'une variable dans le reste du rapport se fait toujours via son identifiant technique @@ -151,9 +183,9 @@ sélection des marées sur lequel on veut appliquer le rapport**. Voici un second exemple de deux variables dont la seconde utilise la première : ```properties -report.xxx.variable.1.name=discardMode -report.xxx.variable.1.type=fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto -report.xxx.variable.1.request=Select distinct new fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto(sf.discard) \ +variable.1.name=discardMode +variable.1.type=fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto +variable.1.request=Select distinct new fr.ird.observe.dto.data.ps.observation.SpeciesFateDiscardModeDto(sf.discard) \ From TripImpl t \ Join t.routeObs r \ Join r.activity a \ @@ -162,9 +194,9 @@ Join c.catches ca with ca.totalCount Is Not Null \ Join ca.speciesFate sf \ Where t.id In :tripId \ Order By sf.discard -report.xxx.variable.2.name=speciesGroup -report.xxx.variable.2.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference -report.xxx.variable.2.request=Select distinct sg \ +variable.2.name=speciesGroup +variable.2.type=fr.ird.observe.dto.referential.common.SpeciesGroupReference +variable.2.request=Select distinct sg \ From TripImpl t \ Join t.routeObs r \ Join r.activity a \ @@ -194,9 +226,9 @@ Comme indiqué plus haut, la syntaxe d'une variable de répétition est identiqu Pour décrire une variable de répétition, trois lignes sont nécessaires, comme on peut le voir dans l'exemple suivant : ```properties -report.xxx.repeatVariable.1.name=gearUseFeaturesId -report.xxx.repeatVariable.1.type=java.lang.String -report.xxx.repeatVariable.1.request=Select g.id \ +repeatVariable.1.name=gearUseFeaturesId +repeatVariable.1.type=java.lang.String +repeatVariable.1.request=Select g.id \ From fr.ird.observe.entities.data.ll.common.TripImpl m \ Join m.gearUseFeatures g \ Where \ @@ -205,10 +237,10 @@ and g in elements (m.gearUseFeatures) \ Order By g.gear.label2 ``` -```report.xxx.repeatVariable.1.name``` définit l'*alias* de la variable de répétition à utiliser dans une requête, autre +```repeatVariable.1.name``` définit l'*alias* de la variable de répétition à utiliser dans une requête, autre variable de répétition ou opération -```report.xxx.repeatVariable.1.type``` définit le type de la variable de répétition. Contrairement aux variables, les +```repeatVariable.1.type``` définit le type de la variable de répétition. Contrairement aux variables, les variables de répétition sont utilisées en interne pour exécuter le rapport, on peut donc utiliser directement des types d'*entité*, ou bien des types *simples* qui correspondent aux types d'une colonne en base (**java.lang.String**, **java.lang.Float @@ -219,7 +251,7 @@ requêtes : si on définit une variable de type *entité*, c'est bien l'entité qui sera injectée dans la requête *hql*, et non pas juste son identifiant technique.** -```report.xxx.repeatVariable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de la variable +```repeatVariable.1.request``` définit la requête **hql** pour récupérer l'univers des valeurs de la variable de répétition Il est possible d'utiliser dans une requête de variable de répétition, un alias sur toute variable du rapport (dont la @@ -235,13 +267,13 @@ l'univers de cette variable de répétion, ce qui peut etre utilise (et nous nou pas décrire via la requete *hql. ```properties -report.xxx.repeatVariable.1.addNull=true +repeatVariable.1.addNull=true ``` Il est possible de documenter cette variable de répétition en utilisant une ligne optionnelle : ```properties -report.xxx.repeatVariable.1.comment=Un commentaire optionnel pour documenter la variable de répétition +repeatVariable.1.comment=Un commentaire optionnel pour documenter la variable de répétition ``` ### requêtes d'un rapport @@ -255,9 +287,9 @@ On distingue deux types de requêtes : Les deux types de requêtes nécessitent les trois lignes, comme décrit dans l'exemple suivant : ```properties -report.xxx.request.1.location=0,0 -report.xxx.request.1.layout=row -report.xxx.request.1.request=Select \ +request.1.location=0,0 +request.1.layout=row +request.1.request=Select \ concat(CASE When g.gear.code IS NULL Then 'Aucun code' Else g.gear.code End, ' - ', g.gear.label2), \ g.number, \ ( CASE g.usedInTrip When true Then 'Oui' Else Case g.usedInTrip When false Then 'Non' Else 'Indéterminé' End End )\ @@ -265,10 +297,10 @@ From fr.ird.observe.entities.data.ll.common.GearUseFeaturesImpl g \ Where g.id = :gearUseFeaturesId ``` -```report.xxx.request.1.location``` définit la position dans le résultat final où positionner le résultat de cette +```request.1.location``` définit la position dans le résultat final où positionner le résultat de cette requête. -```report.xxx.request.1.layout``` définit la disposition à utiliser pour placer le résultat de cette requête dans le +```request.1.layout``` définit la disposition à utiliser pour placer le résultat de cette requête dans le résultat final. Deux valeurs sont possibles : * **row** pour signifier que le résultat de la requête sera positionné en ligne à partir de la position précedemment @@ -277,24 +309,24 @@ résultat final. Deux valeurs sont possibles : précedemment définie. Ce mode est une transposition du résultat de la requête : une ligne du résultat de la requête sera une colonne dans le résultat final -```report.xxx.request.1.request``` définit le code **hql** qui permet de construire le résultat à placer ensuite dans le +```request.1.request``` définit le code **hql** qui permet de construire le résultat à placer ensuite dans le résultat final du rapport Pour une requête avec variable de répétition, il faut alors ajouter les deux lignes suivantes : ```properties -report.xxx.request.1.repeat.name=gearUseFeaturesId -report.xxx.request.1.repeat.layout=column +request.1.repeat.name=gearUseFeaturesId +request.1.repeat.layout=column ``` -```report.xxx.request.1.repeat.name``` définit l'*alias* de la variable de répétition à utiliser. La requête sera +```request.1.repeat.name``` définit l'*alias* de la variable de répétition à utiliser. La requête sera exécutée autant de fois qu'il y a de valeurs dans l'univers calculé de la variable de répétition. **À noter qu'il faut alors que le corps de cette requête doit utiliser l'alias de cette variable de répétition, même si dans les faits, rien ne l'oblige, mais le résultat sera alors toujours le même...** -```report.xxx.request.1.repeat.layout``` définit la disposition à utiliser pour constuire le résultat final de la +```request.1.repeat.layout``` définit la disposition à utiliser pour constuire le résultat final de la requête appliqué à chaque valeur de la variable de répétition. Deux valeurs sont possibles : * **row** pour signifier que pour chaque valeur de l'univers de la variable de répétition, le résultat de la requête @@ -309,7 +341,7 @@ sont pas compatibles.** Il est possible de documenter cette requête en utilisant une ligne optionnelle : ```properties -report.xxx.request.1.comment=Un commentaire optionnel pour documenter la requête +request.1.comment=Un commentaire optionnel pour documenter la requête ``` ### Opérations d'un rapport @@ -323,23 +355,23 @@ Les deux types d'opération nécessitent une première ligne pour déclarer le t dans l'exemple suivant : ```properties -report.xxx.operations.1.type=SumIntRow +operations.1.type=SumIntRow ``` -```report.xxx.operations.1.type``` définit le type d'opération à réaliser. +```operations.1.type``` définit le type d'opération à réaliser. Dans le cas où l'opération est paramétrable, on doit alors ajouter une autre ligne avec le paramétrage de l'opération : ```properties -report.xxx.operations.1.parameters=0|1 +operations.1.parameters=0|1 ``` -```report.xxx.operations.1.parameters``` définit le paramétrage à utiliser pour exécuter l'opération. +```operations.1.parameters``` définit le paramétrage à utiliser pour exécuter l'opération. Il est possible de documenter cette opération en utilisant une ligne optionnelle : ```properties -report.xxx.operations.1.comment=Un commentaire optionnel pour documenter l'opération +operations.1.comment=Un commentaire optionnel pour documenter l'opération ``` Les opérations disponibles et leur documentation sont décrites dans le document [suivant](./embedded-operations.html). @@ -355,14 +387,18 @@ Un rendu est défini par deux lignes : 2. Une pour paramétrer ce rendu ```properties -report.xxx.columnRenderers.1.type=HighlightIfAbsoluteDeltaIsPositive -report.ccc.columnRenderers.1.parameters=10|11|0.0001|0.5 +columnRenderers.1.type=HighlightIfAbsoluteDeltaIsPositive +columnRenderers.1.parameters=10|11|0.0001|0.5 ``` Il est possible d'ajouter plusieurs rendus sur un même rapport. Les rendus disponibles et leur documentation sont décrits dans le document [suivant](./embedded-column-renderers.html). +### Traductions + +**TODO** + ## Pour aller plus loin Vous pouvez aussi consulter la [documentation des rapports embarqués par l'application](./embedded-reports.html). View it on GitLab: https://gitlab.com/ultreiaio/ird-observe/-/commit/b5ef9ebc78e3cab2442d0bb8f0... -- View it on GitLab: https://gitlab.com/ultreiaio/ird-observe/-/commit/b5ef9ebc78e3cab2442d0bb8f0... You're receiving this email because of your account on gitlab.com.