docgen: more explanations

This commit is contained in:
Julien Fastré 2022-01-05 13:43:41 +01:00
parent b2a4aa3b17
commit 36a0b34d5b

View File

@ -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]: <https://fr.wikipedia.org/wiki/Camel_case>
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