manuals/admin/docs/generation-documents/index.md

Génération de documents

L'administrateur fonctionnel prépare la génération des documents.

Cela consiste à configurer le gabarit et ses éventuelles options via l'interface d'administration. Pour chaque gabarit, un document est joint et contient des "zones substituantes", qui permettent d'insérer des informations issues de Chill.

Seuls les documents suivants peuvent être utilisés:

• .odt (LibreOffice Writer);
• .ods
• .odp

Des exemples sont disponibles en ligne.

Rappel de "l'expérience utilisateur": comment les utilisateurs génèrent un document ?

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.

   Il peut s'agir, par exemple, de préciser les destinataires du document, de choisir un signataire, etc.

   Ce formulaire est soit:

   • 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;

3. le document est ouvert pour édition dans un éditeur en ligne. L'enregistrement est automatique. Lorsqu'ils ferment l'éditeur depuis l'interface de l'éditeur, l'utilisateur est redirigé vers l'interface de Chill, généralement la page de génération du document.

   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é.

Préparation des documents

Les documents sont préparés par l'administrateur fonctionnel. Il s'agit d'un document "traitement de texte" (ou tableur, ou présentation).

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".

Cela est accessible via le menu "Insertion > Renvoi...", puis choisir l'onglet "Fonction", "Substituant", "Texte", et indiquer la valeur du champ.

La valeur à indiquer dans le champ "substituant" est à déduire des informations ci-dessous.

Nature (type) des variables

Pour chaque contexte où un document est généré, les variables disponibles sont listées dans la section suivante.

Chaque variable comporte un type: il peut s'agir de:

• un nombre;
• un texte;
• un bouléen (vrai ou faux)
• un objet;
• ou une liste d'objets, de nombres, ou de textes.

Les variables et leur type sont décrites dans la section suivante. Le type est indiqué entre parenthèse:

• 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 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).

Cas où le contenu d'une variable est vide

Si une variable est 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.

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

Variables

• creator: (User) le créateur;
• createdAt (Date): la date et l'heure de création;
• createdAtDate (Date): la date de la création (sans l'heure). Utilisable pour indiquer la date d'un courrier, par exemple;
• location (Location): le lieu sélectionné par le créateur, au moment de la génération ou celui choisi par l'étape 1.

Document générés pour un parcours

Paramètres pour l'administrateur fonctionnel

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 "tiers", qui permet de choisir un tiers parmi les tiers "personnes ressources" du parcours, ou le demandeur du parcours (s'il s'agit d'un tiers);

Variables

Le document présente:

• une variable course, de type AccompanyingPeriod;
• si usager principal du parcours est coché, une variable mainPerson, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 1 est coché, une variable person1, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 2 est coché, une variable person2, de type Person, avec les variants relations, household (ménage) et budget;
• une variable thirdParty, de type ThirdParty, uniquement si l'administrateur fonctionnel l'a configuré.

Document générés pour un parcours, contexte "liste des activités"

Le contexte présente les mêmes variables et paramètre que les documents générés par un parcours.

La variable suivante est ajoutée:

• activities (liste de Activity): Liste d'activités, variant "light". Aucun filtre n'est appliqué sur les échanges récupérés.

Document générés pour une évaluation

Le document présente:

• une variable evaluation de type AccompanyingPeriodWorkEvaluation: l'évaluation concernée;
• une variable work de type AccompanyingPeriodWork: l'action d'accompagnement au sein de laquelle l'évaluation est générée;
• une variable course, de type AccompanyingPeriod: le parcours au sein duquel l'évaluation est générée;
• si usager principal du parcours est coché, une variable mainPerson, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 1 est coché, une variable person1, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 2 est coché, une variable person2, de type Person, avec les variants relations, household (ménage) et budget;
• une variable thirdParty, de type ThirdParty, uniquement si l'administrateur fonctionnel l'a configuré.

Document générés pour un échange

Le document présente:

• une variable activity, de type Activity: l'évaluation concernée
• une variable course, de type AccompanyingPeriod: le parcours concerné, à condition que l'échange ait été créé dans un contexte parcours
• une variable person, de type Person: la personne concernée, à condition que l'échange ait été créée dans un contexte d'usager.

Il est possible également d'injecter des dossiers d'usagers, parmi ceux associés à l'échange (l'utilisateur peut choisir parmis les usagers de l'échange, et pas les usagers concernés du parcours).

• si usager principal du parcours est coché, une variable mainPerson, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 1 est coché, une variable person1, de type Person, avec les variants relations, household (ménage) et budget;
• si usager 2 est coché, une variable person2, de type Person, avec les variants relations, household (ménage) et budget;

Documents générés dans le dossier d'une personne: contexte "personne basique"

• une variable person, de type Person, avec les variants relations, household (ménage) et budget;
• une variable thirdParty, de type ThirdParty, uniquement si l'administrateur fonctionnel l'a configuré.

Documents générés dans le dossier d'une personne: contexte "personne avec un tiers"

Ce contexte permet de générer un courrier avec, en paramètre, un tiers.

Cela peut être utile pour, par exemple, générer un courrier vers un tiers déjà enregistré dans la base de donnée de Chill.

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.

Conditions

Il est possible d'afficher une partie du document uniquement dans certaines situations. Pour cela, on insère un substituant qui "ouvre" la condition, et un autre qui la "ferme". Tout ce qui est écrit entre ces deux substituants n'apparaitra dans le document généré que si la condition est remplie.

Afficher un contenu sous condition: if

Balise	Contenu
Balise ouvrante de la condition	if test="v.mainPerson.age > 18"
Balise fermante	/if

Le contenu de test peut être n'importe quel code python: il s'agit d'une expression qui est évaluée, et dont le résultat doit être vrai ou faux. On peut donc y utiliser les opérateurs de comparaison (==, !=, >, >=, <, <=), les opérateurs logiques (and, or, not), l'appartenance à une liste (in), mais aussi les méthodes du langage python sur les textes.

Par exemple, pour n'afficher un paragraphe que lorsque le parcours est au statut "en file active", on écrira:

if test="v.course.step.lower() == 'en file active'"

Dans cet exemple:

• v.course.step est la variable contenant l'étape du parcours (un texte, traduit dans la langue de l'utilisateur);
• .lower() est une méthode python qui met ce texte en minuscules. Cela évite les mauvaises surprises liées aux majuscules (En file active, EN FILE ACTIVE, …);
• == compare le résultat avec le texte 'en file active', entouré de guillemets simples parce qu'il s'agit d'un texte.

::: {.note}

Les textes sont entourés de guillemets simples ('…'), car les guillemets doubles ("…") sont déjà utilisés pour délimiter le contenu de test.

:::

Quelques autres exemples valides:

if test="v.mainPerson.age >= 18 and v.mainPerson.age < 65"

if test="v.person.birthdate.short != ''"

if test="not v.course.emergency"

if test="len(v.course.currentParticipations) > 1"

Choisir parmi plusieurs cas: choose

Lorsque plusieurs cas s'excluent mutuellement, on peut les enchainer: les tests sont évalués dans l'ordre, le contenu du premier when dont le test est vrai est affiché, et, si aucun ne l'est, c'est le contenu de otherwise qui apparait. C'est l'équivalent d'une suite « si … sinon si … sinon ».

Voici un exemple avec deux conditions, mais il est possible d'en indiquer autant que l'on souhaite.

Balise	Contenu
Balise ouvrante	choose test=""
Balise ouvrante de la première condition	when test="v.person.age < 18"
Balise fermante de la première condition	/when
Balise ouvrante de la deuxième condition	when test="v.person.age >= 18 and v.person.age < 65"
Balise fermante de la deuxième condition	/when
Balise restante	otherwise test=""
Balise fermante de la troisième condition	/otherwise
Balise fermante	/choose

Boucles

Les boucles s'appliquent sur les listes: elles permettent de répéter une partie du document pour chaque élément d'une liste. Les variables de type "liste" sont indiquées dans la description des variables par contexte et dans la description des objets (par exemple, "liste de Activity").

Balise	Contenu
Balise ouvrante de la boucle	for each="m in v.loop"
Balise fermante de la boucle	/for

Exemple:

Fonctionnement des projections dans une itération

Dans la balise ouvrante, l'expression s'écrit sous la forme variable in liste. Par exemple, avec p in v.course.currentParticipations:

• v.course.currentParticipations est la liste sur laquelle on itère (ici, les participations en cours du parcours);
• p est le nom de la variable que l'on choisit librement: c'est la "projection" de l'élément courant. À chaque itération, p est remplacée par un élément de la liste, l'un après l'autre.

À l'intérieur de la boucle, on n'utilise donc plus v. pour accéder aux éléments de la liste, mais le nom de la projection. Si les participations sont des objets de type AccompanyingPeriodParticipation, qui contiennent un champ person, on écrira, entre les balises ouvrante et fermante:

p.person.firstName

p.person.lastName

Le contenu placé entre for each="p in v.course.currentParticipations" et /for sera alors répété autant de fois qu'il y a de participations, avec, chaque fois, les données de la participation courante.

::: {.note}

À l'intérieur d'une boucle, les variables du contexte (v.course, v.mainPerson, …) restent accessibles: seule la projection (p, dans l'exemple) change à chaque itération.

:::

Les boucles et les conditions peuvent être combinées. Par exemple, pour n'afficher que les usagers majeurs:

for each="p in v.course.currentParticipations"
    if test="p.person.age >= 18"
        p.person.firstName p.person.lastName
    /if
/for

Il est également possible d'imbriquer des boucles, en prenant soin de choisir un nom de projection différent pour chaque niveau (par exemple p pour les participations, et a pour les activités).