docgen: mise à jour des principes et utilisation dans Libre office

admin/generation-documents.md

@@ -13,6 +13,16 @@ Seuls les documents suivants peuvent être utilisés:
 
 ## Rappel du parcours des utilisateurs
 
+Les utilisateurs peuvent générer un document depuis plusieurs contextes du logiciel:
+
+- les documents du dossier d'usager;
+- les documents du parcours;
+- les documents dans les évaluations;
+- les activités / échanges;
+- les rendez-vous.
+
+Chaque contexte peut être dédiée à un usage précis. Par exemple, l'utilisateur peut générer une invitation à un rendez-vous depuis la page "rendez-vous". Depuis les évaluations, un formulaire officiel pourrait être pré-rempli. Et un document récapitulatif du parcours peut être généré dans ses documents.
+
 Lors de la génération de document, les utilisateurs parcourrent trois étapes, dont l'un est optionnelle:
 
 1. Étape optionnelle: un formulaire demande des précisions à l'utilisateur.
@@ -21,7 +31,7 @@ Lors de la génération de document, les utilisateurs parcourrent trois étapes,
 
     Ce formulaire est soit:
 
-    * natif au nœud. Dans ce cas, il apparait systématiquement ou dans certaines conditions;
+    * natif au contexte. Dans ce cas, il apparait systématiquement ou dans certaines conditions;
     * configuré par l'admnistrateur fonctionnel parmi des options disponibles;
 
 2. le document est effectivement généré en arrière-plan. Cela peut nécessiter éventuellement quelques secondes;
@@ -29,11 +39,21 @@ Lors de la génération de document, les utilisateurs parcourrent trois étapes,
 
     Notez que, pour que la redirection soit effective, l'utilisateur doit fermer **dans l'interface de l'éditeur**: fermer la fenêtre ou l'onglet fait perdre les informations de redirection - cependant, le document est normalement enregistré.
 
-## Syntaxe de génération d'un document
+## Préparation des documents
 
-Les documents sont préparés par l'administrateur fonctionnel.
+Les documents sont préparés par l'administrateur fonctionnel. Il s'agit d'un document "traitement de texte" (ou tableur, ou présentation).
 
-## Indiquer un champ dans un document
+Le document est préparé de manière habituelle: le texte y est écrit, le logo de l'association inséré, etc. Ensuite, l'administrateur définit certaines zones qui seront remplacées par des informations qui sont collectées dans le logiciel.
+
+Le travail de préparation consiste à préciser les endroits où ces informations doivent être insérées: des champs spécifiques.
+
+::: .note
+
+Le fonctionnement de la génération de document est assez semblable au "publi-postage": des champs sont définis dans le document, et le logiciel de traitement de texte vient les remplacer par ceux provenant d'une base de donnée.
+
+:::
+
+## Indiquer un champ dans un document en utilisant Libre Office
 
 Aux endroits où cela est nécessaire, l'administrateur indique un "champ substituant".
 
@@ -41,53 +61,84 @@ Cela est accessible via le menu "Insertion > Renvoi...", puis choisir l'onglet "
 
 La valeur à indiquer dans le champ "substituant" est à déduire des informations ci-dessous.
 
-## Principes liés au variables
+![Menu Insertion > Renvoi dans LibreOffice](./img/generation-document/libre-office-insert-renvoi.png)
 
-### Nommage de variables
+![Insérer un substituant. Ici, le substituant est la date de génération du document au format long: `v.createdAtDate.long`](./img/generation-document/libre-office-insert-renvoi.png)
-
-TODO
-
-#### Exemple: application aux objets "date"
-
-Les dates sont disponibles dans deux formats:
-
-* le format "court", ou dd/mm/yyyy (par exemple, 15/06/1980, 18/08/2021, …). Ce format est accessible par le champ `short`;
-* le format "long": 15 juin 1980, 18 août 2021, … Ce format est accessible par le champ `long`;
-
-lorsqu'une date est disponible, il est donc possible d'avoir accès à son format en précisant sa chaine de caractère. Exemple avec la date de naissance de la personne:
-
-```
-person.Birthdate.Short=15/06/1980
-person.Birthdate.Long=15 juin 1980
-```
 
 
-### Cas où une variable est optionnelle
+## Nature (type) des variables
 
-Lorsqu'une variable est optionnelle, si sa valeur est inconnue ou vide, alors tout ses champs apparaissent avec une chaine de caractère vide.
+Pour chaque contexte où un document est généré, les variables disponibles sont listées [dans la section suivante](#sec:gendoc-champs-documents). 
 
-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.
+Chaque variable comporte un type: il peut s'agir de:
 
-## Variables disponibles par document
+- un nombre;
+- un texte;
+- un bouléen (`vrai` ou `faux`)
+- un objet;
+- ou une liste d'objets, de nombres, ou de textes.
 
-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é.
+Les variables et leur type sont décrites [dans la section suivante](#sec:gendoc-champs-objets). Le type est indiqué entre parenthèse:
 
-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 est un object. Il comporte des sous-champs, et il faut se reporter à la description de l'objet correspondant;
-
-* 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 }
+### Cas où le contenu d'une variable est vide
 
-#### Paramètres pour l'administrateur fonctionnel
+Si une variable est vide, alors tout ses champs apparaissent avec une chaine de caractère vide.
 
-Les administrateurs fonctionnels peuvent activer les paramètres suivants:
+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.
 
-* un champ "lieu", qui permettra de choisir parmi les lieux pré-enregistrés. Le lieu pré-sélectionné sera celui choisi par l'utilisateur;
+### Exemple: la date de naissance d'une personne
+
+Dans le contexte "personne", les informations de la personne sont disponibles sous le champ `v.person`. Il s'agit d'un objet de type `Person` qui comporte une sous-variable appelée `birthdate`, qui est lui-même disponible dans un objet de type `Date`. 
+
+Les objets `Date` proposent deux sous-champs, qui correspondent au format de la date:
+
+* le format "court", ou dd/mm/yyyy (par exemple, 15/06/1980, 18/08/2021, …). Ce format est accessible par le champ `short`;
+* le format "long": 15 juin 1980, 18 août 2021, … Ce format est accessible par le champ `long`;
+
+Donc, pour insérer la date de naissance, on utilisera les substituants suivants:
+
+```
+v.person.birthdate.short
+
+v.person.birthdate.long
+```
+
+Ce qui donnera (pour une personne née le 15 décembre 1980):
+
+```
+15/12/1980
+
+15 décembre 1980
+```
+
+Si, par contre, la date de naissance de la personne n'est pas renseignée, deux lignes vides s'afficheront dans le document:
+
+```
+
+
+```
+
+## Paramètres pour l'administrateur fonctionnel
+
+Pour chaque gabarit, l'administrateur peut activer certaines options. Par exemple:
+
+* permettre de sélectionner une personne parmi les usagers du parcours;
+* configurer le libellé qui s'affichera pour l'utilisateur devant l'usager.
+
+Les options disponibles dépendent du contexte.
+
+Par exemple, pour un courrier généré dans un contexte "parcours", l'utilisateur pourra choisir un usager du parcours pour un courrier; l'administrateur indiquera qu'il s'agira du "destinataire" du courrier. Tandis que pour un formulaire officiel, l'administrateur configurera un "demandeur" et "co-demandeur", et ce sont ces libellés qui s'afficheront.
+
+## Variables par contexte
+
+### Pour tous les contextes { #sec:gendoc:champs-documents }
 
 #### Variables
 
@@ -104,7 +155,7 @@ Les administrateurs fonctionnels peuvent activer les paramètres suivants:
 
 * un champ "usager 1", qui permet ensuite à l'utilisateur de choisir un usager parmi ceux concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
 * un champ "usager 2", qui permet aux utilisateurs de choisir un deuxième usager parmis ceux concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
-* un champ "usager principal du parcours", qui permet, cette fois, de choisir parmi les usagers concernés par le parcours,, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
+* un champ "usager principal du parcours", qui permet, cette fois, de choisir parmi les usagers concernés par le parcours, les interlocuteurs privilégiés qui sont des usagers (à l'exclusion des tiers), et les personnes ressources associées à un usager concerné du parcours (à l'exclusion des ressources tiers et "texte libre");
 
 #### Variables
 
@@ -163,20 +214,18 @@ Les variables disponibles sont les suivantes:
 * une variable `person`, de type `Person`, avec les variants `relations`, `household` (ménage) et `budget`.
 * une variable `thirdParty`, de type `ThirdParty`;
 
+### Document générés dans un contexte "rendez-vous"
+
+Les champs suivant sont disponibles:
+
+* une variable `calendar` (Calendar), qui contient les données du rendez-vous;
+* une variable `mainPerson` (Person), la personne principale parmi les personnes participant au rendez-vous. Cette variable n'est présente que si l'administrateur fonctionnel l'a configurée.
+* une variable `thirdParty` (ThirdParty): un tiers participant au rendez-vous. Cette variable n'est présente que si l'administrateur fonctionnel l'a configurée.
+
+## Principes liés au variables
+
 ## Champs par objet { #sec:gendoc-champs-objets }
 
-Les champs ci-dessous étendent les variables disponibles dans les documents.
-
-Par exemple, le document généré à partir d'un parcours présente la variable `startDate` qui contient la date de début du parcours. Ce champ peut être exploité de la manière suivante:
-
-```
-${courseStartDateLong} // 15 janvier 2021
-
-ou dans la forme courte:
-
-${courseStartDateShort} // 15/01/2021
-```
-
 ### AccompanyingPeriod
 
 * `id` (texte): l'identifiant du parcours
@@ -308,6 +357,12 @@ Présence à l'échange
 * `short` (texte): la date au format dd/mm/yyyy, vide si la date est absente;
 * `long` (texte): la date au format jour mois années: 15 août 1980, vide si al date est absente;
 
+### NiveauEtude
+
+* `id` (int): identifiant (utile pour des comparaisons);
+* `active` (bool): si le niveau d'étude est encore utilisé;
+* `name` (texte): titre
+
 ### Person
 
 * `id` (texte): Identifiant du dossier usager;
@@ -570,11 +625,6 @@ Pour rappel, les ressources peuvent être:
 * `active` (bool): si le statut est encore utilisé;
 * `name` (texte): titre
 
-### NiveauEtude
-
-* `id` (int): identifiant (utile pour des comparaisons);
-* `active` (bool): si le niveau d'étude est encore utilisé;
-* `name` (texte): titre
 
 ### SituationProfessionelle