From 36a0b34d5b5d202da8398abd44a0ed02799c88d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Julien=20Fastr=C3=A9?= Date: Wed, 5 Jan 2022 13:43:41 +0100 Subject: [PATCH] docgen: more explanations --- admin/generation-documents.md | 61 ++++++++--------------------------- 1 file changed, 14 insertions(+), 47 deletions(-) diff --git a/admin/generation-documents.md b/admin/generation-documents.md index 34befc4..66ad9f3 100644 --- a/admin/generation-documents.md +++ b/admin/generation-documents.md @@ -45,26 +45,7 @@ La valeur à indiquer dans le champ "substituant" est à déduire des informatio ### Nommage de variables -Les variables contiennent des informations importées d'objets présents dans le logiciel. Par objet, nous entendons, par exemple, un utilisateur (User), un usager (Person), etc… - -Ces objets comportent plusieurs champs. On accède à ces champs en concaténant les noms de la variable qui contient un objet, et le nom des champs de ces objets. - -Par exemple: le créateur d'un document est disponible sous la variable `creator`. Cette variable est un objet de type `User`. Cet objet contient ces trois champs ([la liste complète est disponible ci-dessous](#sec:gendoc-var-user)): - -* `username`; -* `service`; -* `email`; - -Alors, pour indiquer le nom du créateur, son email et son service, on préfixe la variable par `creator`, et on ajoute les noms des champs de l'objet `User`, en commençant par une majuscule pour ces champs. Exemple: - -``` -Pour joindre ${creatorUsername} (service: ${creatorService}), -vous pouvez envoyer un courriel à l'adresse ${creatorEmail}. -``` - -Pour nommer les variables et les concaténer, nous utilisons la syntaxe camelcase [^camelcase], avec la première lettre en bas de casse (en minuscule). - -[^camelcase]: +TODO #### Exemple: application aux objets "date" @@ -80,41 +61,27 @@ personBirthdateShort=15/06/1980 personBirthdateLong=15 juin 1980 ``` -### Cas où une variable peut être de deux natures différentes - -Certaines variables peuvent être de deux natures différentes, par exemple, soit une personne, soit un tiers. Dans ce cas, les variables qui sont de noms différents sont à l'état "vide". Par exemple, le champ "date de naissance" n'est pas disponible pour un tiers, dans ce cas, il est vide. - -Exemple, une liste des interlocuteurs principaux. Le premier est une personne: - -``` -text=Maxime Berger -firstName=Maxime -lastName=Berger -birthDate=19/01/1996 -type= -job= -``` - -Le second est un tiers: - -``` -text=Jean Couteau -firstName=Jean -lastName=Couteau -birthDate= -type=Médecin -job=Assistant social -``` ### Cas où une variable est optionnelle Lorsqu'une variable est optionnelle, si sa valeur est inconnue ou vide, alors tout ses champs apparaissent avec une chaine de caractère vide. +L'arbre des variables est toujours identique, sur toute la profondeur de celles-ci. L'administrateur est garanti qu'un champ existera, même si sa valeur n'est pas présente dans la base de donnée. + ## Variables disponibles par document -Lorsqu'une variable n'est pas de type "texte", ses champs sont complétés par ceux décrits [dans la section suivante](#sec:gendoc-champs-objets). +Pour chaque contexte où un document est généré, les variables disponibles sont listées [dans la section suivante](#sec:gendoc-champs-documents). Le type des variables est indiqué. -### Pour chaque document +Les variables pour chaque type sont décrites [dans la section suivante](#sec:gendoc-champs-objets): + +* si le type commence par une majuscule, alors cette variable comporte des sous-champs, et il faut se reporter à la description des variables pour ce type; +* si le type commence par une minuscule, alors cette variable peut être utilisée directement dans le document: + + * s'il s'agit d'un booléen (`bool`), le champ peut être utilisé dans des tests; + * les champs `text` et `int` peuvent faire l'objet de test sur l'égalité; + * les champs de type `int` peuvent faire l'objet de comparaison sur l'ordre de grandeur (par exemple, le champs `age` des objets de type `Person` peut être filtré `> 18` ou `< 18` pour distinguer les adultes des enfants). + +### Pour chaque document { #sec:gendoc:champs-documents } #### Paramètres pour l'administrateur fonctionnel