SmartDoc

2022-08-30T18:15:00Z

Damien : /* Visible if */

<h1 id="smartdoc">SmartDoc</h1>

<h2 id="introduction">Introduction</h2>
En premier lieu, un SmartDoc doit être clairement identifié par son doc-id, qui doit être strictement le même que le doc-id spécifié dans la [[DocList]]
La nouvelle feuille du [[Fichier de Paramétrage]] qui a vocation à être un SmartDoc doit donc se nommer précisément : Doc “le_doc-id”
Par exemple :
Ici, la [[DocList]] mentionne un seul SmartDoc, dont le doc-id est “demo-hercule” :
[[Fichier:DocList 1.png|frame|none|Une DocList classique]]
En conséquence, la feuille correspondante se nomme demo-hercule
[[Fichier:Capture d’écran 2019-07-24 à 11.19.59.png|frame|none]]
Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”
<h2 id="metadonn-es-datastore-options-list-labels">Metadonnées, datastore, options, list labels</h2>
[[Fichier:Smartdoc options 1.png|sans_cadre|1200px|néant]]
=== Métadonnées ===

 C'est un simple espace de commentaire 

=== DataStore ===

[[DataStore]] : C’est l'id du [[DataStore]] auquel les variables utilisées dans le document sont associées. Par défaut, mainstore.

=== Options ===

La colonne "Options" permet de définir des options relatives au document courant.
Cette cellule attend un contenu au format YAML.

==== L'option "title-num-display" ====

L'option "title-num-display" permet de définir le format d’affichage pour la numérotation de chaque titre du document.

Si cette option vaut <code>none</code> ou <code>disabled</code> les titres et les références affichées dans ce document seront "désactivées" et ne s'afficheront donc pas.

Au contraire, pour personnaliser le format de la numérotation, cette option attend une liste clés-valeurs (texte indenté, YAML), où chaque clé est un niveau de titre (de 1 à 6 inclus), et pour chaque niveau, trois attributs peuvent être saisis : <code>style</code>, <code>format</code>, et <code>format-ref</code> (voir exemple imagée ci-dessous).

Les valeurs possible pour l'attribut <code>style</code> sont :
:: - "decimal" : numérotation décimale classique en chiffre arabe (1, 2 , 3 …) ;
:: - "upper-roman" : nombre romain majuscule (I, II, III, IV etc.) ;
:: - "lower-roman" : nombre romain minuscule (i, ii, iii, iv etc.) ;
:: - "upper-alpha" : numérotation alphabétique majuscule (A, B, C, D, E) ;
:: - "lower-roman" : numérotation alphabétique minuscule (a, b, c, d...) ;
:: - "none" : aucune numérotation pour ce niveau de titre ;

L'attribut <code>format</code> attend une chaîne de caractère qui permet de représenter le contexte (préfixe, suffixe…) de la numérotation à afficher avant chaque Titre.
Cette chaîne doit contenir au moins une fois un $1, $2, $3 … $6, qui seront remplacés par la numérotation pur le niveau concerné.
L'attribut <code>format-ref</code> fonctionne de la même façon que l'attribut précédent mais il permet de représenter la numérotation à afficher dans chaque référence intégrée au sein du document (voir [[Smartdoc/titre-et-references|SmartDocument, faire une référence à un titre]]).

Ces attributs doivent contenir au moins une fois un code numéroté tel que <code>$1</code>, <code>$2</code>, <code>$3</code> … <code>$6</code>, qui permettra d'être remplacé par la numérotation du niveau concerné.

'''Exemple''' : le format “<code>$1)</code>“ s'affichera “''A)''”, "''B)''", "''C)''" etc. (s'il est combiné au style <code>"upper-alpha"</code>), ou "i)", "ii)", "iii)" (style <code>"lower-roman"</code>).

'''Autre exemple''' : “<code>Article $1.$2</code>“ s'affichera “Article 1.A”, "Article 1.B", "Article 2.A" … (combiné avec un niveau 1 au style <code>décimal</code> et un niveau 2 en <code>upper-roman</code>).

'''Exemple complet :'''
[[Fichier:Gestion des titres.png|frame|none|Gestion du format des titres]]
D'après la configuration de l'image ci-dessus, les titres :
* de niveau 1 seront de la forme : “ARTICLE 8 - Lorem ipsum”
* de niveau 2 seront de la forme : “2 Lorem ipsum ”
* de niveau 3 seront de la forme : “2-5 Lorem ipsum ”
* de niveau 4 seront de la forme : “2-5-10 Lorem ipsum ”
* de niveau 5 seront de la forme : “a. Lorem ipsum ”
* de niveau 6 seront de la forme : “ iv ) Lorem ipsum

=== List-Labels ===
Introduction
List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. Autrement dit, elle permet d'établir des "dictionnaires de correspondance" permettant de faire correspondre un libellé à une valeur.
Par exemple :
[[Fichier:List Label.png|none|frame|La gestion des List Labels]]
Une fois un List-Label préparé, il est possible de l'utiliser grâce au traitement Label
Contexte
La colonne "Choices" du `Fields-Form` vous permet de spécifier les choix qui doivent apparaitre dans le formulaire. Chaque choix :
- s'écrit sur une ligne différente, ligne qui doit se terminer par un point-virgule ;
- chaque choix s'écrit en deux parties séparées par un ":" afin d'indiquer, à gauche, la valeur à stocker en base de données (et à utiliser dans les [[Conditions|visible ifs]]) et à droite la valeur à afficher dans le formulaire. On parle de couple "valeur : libellé".
Par exemple
[[Fichier:Dg.png|thumb|none|375px]]

Mise en place
Le document n'est pas à même de décider sous quelle forme afficher la variable correspondante aux choix d'un champ de type "choix"
Si rien n'est spécifié, le document affichera ce qui est stocké dans la base de données 
Il est toutefois possible d'indiquer au document des libellés et pour cela intervient le filtre <code>:label(xxx)`</code>.
Par exemple, on peut imaginer un dictionnaire nommé "fonctions" pour indiquer que "dg" doit s'afficher "Directeur Général", et un autre dictionnaire nommé "fonctions_abrégées" qui indiquerait au contraire que "dg" doit s'afficher "Dir. G.".
Il sera alors possible, dans le contenu du SmartDoc, de faire appel au dictionnaire de votre choix :
<ul>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions")}</code></li>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions_abrégées")}</code></li>
</ul>

Les dictionnaires sont définis via la case D2 (List Labels) des onglets "Doc".
Ils sont écrits sous la forme suivante :

[[Fichier:D2.png|none|thumb|175px]]
⚠ Notez les espaces d'indentation qui permettent d'indiquer au système l'imbrication / hiérarchie de l'info. C'est à dire qu'ici, val1 et val2 appartiennent au premier dictionnaire, alors que valA et valB appartiennent au second dictionnaire. Sans cette indentation, le système ne saurait pas reconnaitre si la ligne correspond à la déclaration d'un nouveau dictionnaire ou à un couple valeur/libellé. 
→ A noter : On peut aussi utiliser un libellé référencé dans une “[[Choice-List]]”.
Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : <code>countries: @pays</code> .
On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, <code>{PAYS_NAISS:label("countries")}</code>.
La colonne A qui donne France si la variable PAYS_NAISS vaut “FR”.

<h2 id="templates-docx">Les modèles .docx</h2>

Le SmartDoc consiste à définir du "contenu dynamique", bien qu'il soit possible de définir certains styles de base (couleurs, gras, italiques, titres etc.), la mise en page du document lui même reste limitée. C'est en cela que les "modèles .docx" peuvent être utile.

Chaque SmartDoc peut se baser sur un modèle de fichier, au format .docx. Le contenu dynamique sera tout simplement "injecté" dans le document à l'endroit indiqué.
Le modèle peut, par exemple, prévoir un habillage (page de couverture, page de garde etc.), prévoir des entêtes et pieds-de-page, mais surtout, peut permettre de définir les marges du document et les styles des paragraphes et des titres (tailles, couleurs, espacement...).
Le contenu dynamique, créé au travers du SmartDoc, se retrouvera simplement injecté dans le modèle prédéfini.

'''Définir un modèle et l'associer à un ou plusieurs SmartDoc'''

Pour pouvoir utiliser un modèle, il suffit de le rajouter dans la Doc-List, en lui donnant un identifiant unique, et en indiquant le type <code>docx-template</code> (vous pouvez aussi préciser un titre, une description).

Une fois le modèle présent dans la Doc-List, il est possible de l'associer à un SmartDoc en utilisant l'option : <code>docx-template: mon-template</code>.

'''Préparer son modèle et l'injection du contenu'''

Le modèle .docx peut être préparé comme un document classique : définir les styles des titres et des paragraphes, définir les marges et les interlignes, une page de couverture et des pieds-de-pages etc.
Pour définir où le contenu dynamique devra être injecté, il faut utiliser la syntaxe suivante : <code>${ @inject all }</code>. Ainsi, l'intégralité du contenu du SmartDoc sera intégrée à cet endroit même du modèle.
Il est aussi possible de demander l'intégration d'un seul [[Blocs | bloc du SmartDoc]], en indiquant, à la place de <code>all</code>, l'identifiant du SmartDoc et le nom exact du bloc.

Par exemple, dans un SmartDoc nommé <code>contrat</code>, un bloc défini par <code>#BLOC dénomination</code>, pourra être injecté dans le modèle .docx avec la syntaxe suivante :
<pre>${ @inject contrats :: dénomination }</pre>

'''''Nb :''' notez les 2 fois 2 points (<code>::</code>) pour séparer l'identifiant du SmartDoc concerné et le nom exact du bloc à injecter.''

'''Pour aller plus loin :'''
* Vous pouvez trouver plus d'informations sur les modèles docx et sur la manière de les mettre en place sur la [[Docx-template|page dédiée du Wiki]].
* Il est parfaitement possible d'utiliser plusieurs injections dans un même modèle .docx. Il vous suffit d'utiliser plusieurs fois la syntaxe <code>${ @inject ... }</code> dans le document modèle.
* Le contenu injecté peut lui-même inclure d'autres blocs (voir [[Smartdoc/include| les "inclusions" (includes) d'un SmartDoc]]), des boucles, des titres etc.
* Dans certains cas, il peut être problématique d'injecter un bloc, lui même contenu dans [[Boucles | une boucle du SmartDoc]]. En effet, la boucle a pour conséquence de "contextualiser" la variable sur laquelle elle boucle, si vous injectez ce contenu hors de ce contexte, le SmartDoc ne saura pas comment interpréter la variable correspondante à une occurence de la boucle.

== Contenu, options, styles, [[Conditions|visible ifs]], commentaires ==

[[Fichier:SmartDoc options 2.png|1200px|sans_cadre|néant]]
<h3 id="contenu">Contenu</h3>
 Un SmartDoc est constitué d'une suite ordonnée d'[[Élément_de_contenu|éléments de contenu]]. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'éléments de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).
Le “contenu” du SmartDoc est ce qui sera effectivement “imprimé” dans le document final qui sera transmis à l’utilisateur.
Ce contenu, en plus d’être dynamique grâce au “visible-ifs” comme le reste du système, accepte aussi l’utilisation de variables.
<h4 id="bases">Bases</h4>
C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.
On peut se servir des [https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML balises HTML basiques] pour mettre en forme le texte rentré ici.
Les balises suivants sont utilisables

* a,
* br,
* b,
* strong,
* i,
* em,
* ol,
* ul,
* li,
* hr,
* span


==== Contenu spécial ou dynamique ====

Ils sont de la forme <code>{ @… }</code> et s'integre parmi le contenu.

:: — <code>{ @line-break }</code> : ajout un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : <code>{@line-break}</code> Plusieurs saut de ligne (par exemple 2) : <code>{@line-break:2}</code>

:: — <code>{@page-break</code>} : ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : <code>{@page-break}</code>.
:: Le saut de page est effectif dans les exports .docx ou .pdf, mais est simulé par une simple ligne verticale dans les prévisualisations HTML.

:: — <code>{@ref:my title id}</code> : ajout d’une référence vers un titre : comme pour intégrer une variable, il est possible d’intégrer un lien vers un titre du document (le titre peut se trouver avant ou après la référence dans le contenu). Pour intégrer une référence, il suffit d’utiliser la syntaxe <code>{@ref:my title id}</code> pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. Le fonctionnement des références croisées est décrit en détail [[Smartdoc/titre-et-references|ici]].
:::: Nb : si plusieurs titres ont le même title-id alors la référence pointe vers le premier de la page.
:::: Nb : si la référence pointe vers un titre qui n’existe pas dans le document (ou est invisible), elle sera remplacée par le texte “[référence manquante]”.
:::: Par défaut, la référence à un titre se contente d’afficher le titre (càd, le contenu du bloc titre).

:::: Une chaine de caractère étant retournée, il est possible d’appliquer les filtres classiques.
:::: Exemple : ''Comme décrit dans la section'' <code>{@ref:droit-acheteur:uppercase}</code>.
:::: Le traitement <code>:num</code> peut-être appliqué dans la syntaxe afin d’afficher la référence sous forme numérique et tenant compte des titres parents.
:::: Exemple : ''Comme décrit dans la section ''<code>{@ref:droit-acheteur:num}</code>… => ''Comme décrit dans la section '' '''3.1.1.2'''

:::: Pour les cas des références vers des titres ayant l’option title-article à “true” le nombre retourné sera simplement celui de l’article dans le cas du traitement “:num”.
:::: Pour les cas des références vers des titres ayant l’option title-no-count , le traitement “:num” n’aura alors aucun effet.

:: — <code>{@summary}</code>Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : <code>{@summary}</code>

:: — <code>{ @doc-meta(title) }</code> : permet d'insérer une méta-donnée du document courant. Les 3 paramètres possibles sont : <code>title</code>, <code>description</code>, ou <code>id</code>. Pratique, par exemple, pour citer le titre du document au sein du contenu, malgré peut-être la présence d'un clausier et de blocs injectés d'un autre document.

==== Comment rendre dynamique le contenu d'un [[SmartDoc]] ? ====

Pour rendre dynamique le contenu du SmartDoc, il est possible de lui intégrer les valeurs des variables telles qu'elles ont été collectée dans un formulaire, ou calculée via une variable dynamique etc.

La syntaxe pour intégrer un contenu dynamique est reconnaissable car il est systématiquement placé entre accolades : <code>{ … }</code>.

Une variable peut être intégrée de façon brute (Exemple : ''"Je m'appelle { PRENOM }."'').
L'affichage brut pouvant parfois être trop limitatif, une syntaxe de "traitements SmartDoc" est disponible. Par exemple, le traitement <code>:uppercase</code> appliqué sur une variable la fera afficher en majuscule. Exemple :: ''"Je m'appelle <code>{ PRENOM:uppercase }</code>."'').

<h5 id="les-primitives">Les primitives</h5>
Une primitive est un élément qui a une valeur.
Par exemple: la variable PRENOM va valoir “Damien”. Ou tout simplement un nombre (ex: 36) ou une chaine de caractère (ex: "une chaise")
Pour intégrer une valeur : les variables du dataset sont intégrées dans le contenu à partir d’une syntaxe simple : la variable est placée, sans espace, entre deux accolades.
Exemple :
Le vendeur, né le <code>{DATE_NAISSANCE}</code>, à <code>{VILLE_NAISSANCE}</code> ... 

==== Les traitements dans le SmartDoc ====

Les traitements peuvent être définies comme une modification appliquée sur un contenu. Par exemple, le traitement <code>uppercase</code> permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère. 
Pour appliquer un traitement sur une primitive, on utilise le signe : <code>:</code> Ce qui donne Mon prénom est <code>{PRENOM:uppercase}</code> qui donne Mon prénom est DAMIEN même quand la variable <code>PRENOM</code> vaut “DaMien”.
Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : <code>:</code>
Exemple :
Le vendeur s’appelle <code>{PRENOM:uppercase}</code>
Il est possible d'enchaîner les traitements. 
Exemple :L'acheteur a payé <code>{PRIX:letters:uppercase}</code> euros.
Ici, la valeur contenue dans la variable "PRIX" sera d'abord convertie en lettres, puis mise automatiquement en MAJUSCULES.
On obtiendra un résultat du type : "L'acheteur a payé TRENTE euros", alors que la valeur de départ sera "30".
A noter : les traitements peuvent s’appliquer aussi sur de simples chaînes de caractères et pas seulement des variables. Ex : L'acheteur a payé {"32 000":letters:uppercase} euros.

==== Traitements disponibles et syntaxe spécifique ====

<code>:uppercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en majuscule
 
<code>:lowercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en minuscule
 
<code>:letters</code> : ne s'applique que sur une valeur numérique, et permet de la convertir en "toutes-lettres" (ex : <code>312</code> => <code>Trois-cent-douze</code>).
 
<code>:capitalize</code> : ne s'applique que sur une chaine de caractères, et permet de passer en majuscule la première lettre de chaque mot. Ex: <code>NOM:capitalize</code> 
Option : si l'option 1 (ou "yes") est passée en paramètre de ce traitement, alors seule la première lettre du premier mot sera mise en majuscule. Ex: <code>NOM:capitalize(1)</code> , <code>NOM:capitalize(yes)</code>… 
 
<code>:img</code> : transforme une chaine de caractère (url) en image dans le document. Ex : <code>{"https://api.memegen.link/images/puffin.jpg":img}</code> va permettre d'intégrer l'image présente à cette URL dans le document.
 Nb: dans les version v0.9-v0.11 l'intégration d'une image distante (via <code>:img</code>) n'est plus possible dans les exports .docx / .pdf si un modèle de document (voir docx template) est utilisé. En effet, la norme DocX ne permet pas/plus l'intégration d'image / objet si le fichier est créé par un TemplateEngine.

 
<code>:num</code>: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre.
Exemple : </code>Comme décrit dans la section {@ref:droit-acheteur:num}, vous...</code>. Le fonctionnement des références croisées est décrit en détail [[http://wiki.hercule.co:3002/index.php/Smartdoc/titre-et-references|ici]]
 
<code>:french-datetime</code> : ne s'applique que sur une date ou une chaîne de caractère au format "Date". Ce traitement permet de transformer la date au format "30/12/1985 à 12h45".
 
<code>:french-date</code> : ne s'applique que sur une date ou une chaîne de caractère au format "YYYY-MM-DD" (format international). Ce traitement permet de transformer la date fournie dans le format Français "jj/mm/aaaa". Depuis la version v0.10, ce filtre est "facultatif" car il est appliqué par défaut sur les dates ou les chaînes au format de date. 
 
<code>:num-format</code> : ne s'applique que sur une valeur numérique, et permet de la formater pour son affichage. Ce traitement peut prendre 3 paramètres '''facultatifs'''. 
<ul>
<li>Le 1er permet (numérique et facultatif) permet d'indiquer le nombre de décimale souhaitées (par défaut, 2 chiffres ou 0 si la partie décimale est nulle).</li>
<li>Le second paramètre (chaîne, facultative) correspond au séparateur des milliers (par défaut : un espace).</li>
<li>Le troisième paramètre (chaîne, facultative) correspond au caractère à afficher pour le séparateur décimal (par défaut : <code>,</code>).</li>
</ul>
Quelques exemples : <ul>
<li> - soit une variable numérique VAR_PI qui vaut <code>3,1451</code>. L'affichage par défaut <code>{ VAR_PI }</code> affichera <code>3,14</code>. L'affichage <code>{ VAR_PI:num-format(3) }</code> affichera <code>3,145</code>. </li>
<li> - pour la variable PRICE (numérique) qui vaudrait <code>9 999,99</code>, l'affichage <code>{ PRICE:num-format }</code> affichera <code>9 999,99</code> (dans ce cas le `:num-format` est facultatif). Par contre, l'affichage <code>{ PRICE:num-format(1,',', '.') }</code> affichera <code>9,999.9</code> (1 chiffre après la virgule, séparateur des milliers et décimaux modifiés).</li>
</ul>

 

<code>:join</code> : limité à une variable de liste plate (issue d'un [[Fields-Form|multiples-choices]] principalement) → permet d'afficher les différentes valeurs de la liste sous la forme suivante : <code>Valeur1, Valeur2, Valeur3, et Valeur4</code>. Les différentes valeurs contenues dans la variable sont affichées les unes à la suite des autres, séparées par des virgules; la dernière valeur est précédée de la conjonction de coordination <code>et</code>.
:: Il est possible de personnaliser le séparateur, par exemple <code>LIST:join(" ou ")</code> → renvoie <code>Valeur1 ou Valeur2 ou Valeur3</code>.
:: Et il est même possible de personnaliser indépendamment le séparateur du dernier élément grâce à un second paramètre. Exemple <code>LIST:join(" ou ", " ou bien même ")</code> → renvoie <code>Valeur1 ou Valeur2 ou bien même Valeur3</code>.

 
<code>:list</code> : '''utilisable uniquement pour les variables [[Fields-Form|multiples-choices]]''' → permet d'afficher les différentes valeurs de la liste dans le SmartDoc sous la forme d'une liste à puce; chacune des valeurs de la liste démarre une nouvelle puce
 
<code>:label</code> : dont le fonctionnement est expliqué [[SmartDoc#List-Labels|plus haut]].
 
<code>:substr(x,y)</code> : permet de tronquer une chaîne de caractères. Par exemple pour une variable PRENOM qui vaudrait "Maximilien", on pourra utiliser la notation suivante : <code>{PRENOM:substr(2,4)}</code>, qui donnera en pratique "ximi" ;


 
<code>:string-replace([remplaceur], [remplacé])</code> : permet de remplacer une chaîne par une autre chaîne dans le contenu d'une variable de type "string".
Par exemple pour une variable VAR qui vaudrait "Damien", l'expression <code>VAR:string-replace("F", "D")</code> donnera "Famien". 
Si le paramètre "remplacé" n'est pas fourni, ce sera par défaut un saut de ligne qui sera recherché. Par exemple pour une variable ADDRESS qui contient des sauts de ligne, l'expression <code>ADDRESS:string-replace(", ")</code> va remplacer chaque saut de ligne de l'adresse par <code>, </code> ce qui permet de passer un texte multi-lignes dans un format une-ligne. 
A savoir : un saut de ligne se note <code>"\n"</code>, il est donc aussi possible de remplacer, par exemple, des tirets <code>-</code> par des sauts de ligne avec l'expression <code>ADDRESS:string-replace("\n", "-")</code>.


 

<code>:default("texte par défaut")</code> permet de définir une valeur "par défaut" à afficher dans le SmartDoc si la variable sur laquelle le filtre est appliqué est vide.

<h3 id="options">Options</h3>
*<code>break</code> (facultatif) : valeur possible <code>none</code> , <code>before</code> ou <code>after</code>.
Permet d’intégrer un saut de ligne. Par défaut, toutes les entrées sont en break: after.
Si after est indiqué (ou si rien n’est indiqué puisque c’est la valeur par défaut), alors le bloc se terminera par un saut de ligne et le bloc suivant s’affichera sur une nouvelle ligne.
Si before est indiqué, l’entrée s’affiche sur une nouvelle ligne (le saut de ligne intervient avant l’entrée).
Si none est indiqué, il n’y a pas de saut de ligne, les entrées s'enchaînent.
*<code>title-level</code> (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6.
*<code>title-id</code> (facultatif) : la valeur attendue est une chaîne de caractères alpha-numériques sans sauts de ligne et dont les caractères suivants sont interdits : :, {, }, "
Cette option permet d’assigner un identifiant au titre concerné, de cette façon il sera possible de faire référence à ce titre via un “bookmark” (voir plus haut, “ajout de référence”).
Nb: cet attribut n’est possible QUE si l’attribut title-level est lui aussi renseigné.
*<code>title-article</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”.
Quand cette option est à “true”, le titre sera considéré comme un “titre d’article”. Il sera donc préfixé par "ARTICLE 1 - " ou le nombre “1” sera remplacé par l’index de l’article en question.
*<code>title-no-count</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”. Quand cette option est à “true”, le titre ne sera pas numéroté, ni dans les sommaires, ni préfixe par aucun type de numérotation.

=== Styles ===

La colonne Styles est facultative, et permet de personnaliser les styles de la ligne de contenu concernée.

Les styles sont fournies dans un format inspiré de la norme [https://www.w3schools.com/css CSS] (mais fortement simplifiée).
Ce format permet de définir plusieurs instructions stylistiques, chacune se terminant par un point-virgule (<code>;</code>) et un saut de ligne. Exemple d'une cellule dont le texte devra être en taille 18px et dans la couleur rouge (''#FF0000'' en couleur hexadécimale) :
font-size:18px;
color:#FF0000;

Chaque instruction est donc formée : d'un attribut de style (voir la liste ci-dessous), puis d'un séparateur (caractère <code>:</code>), puis de la valeur du style souhaité, et se termine par un point-virgule (<code>;</code>) et un saut de ligne.
Il est autorisé de placer un espace après le séparateur "<code>:</code>" mais attention à ce que ce espace ne soit pas "particulier" (espace insécable etc.) car cela mettrait en danger l'interprétation du style et il se peut qu'il ne soit pas du tout pris en compte.

Les instructions de styles autorisées sont :

:: '''Définir une police de caractère spécifique :'''
:::: L'attribut “<code>font-family</code>” permet de spécifier la police à utiliser.
:::: Plusieurs noms de police peuvent être proposées (dans l'ordre de priorité). Si le lecteur (navigateur, logiciel de traitement de texte…) utilisé ne supporte pas la première police, le système tentera d’utiliser la deuxième police, puis la troisième, ainsi de suite ...
:::: Exemple : <code>font-family:Times New Roman, Times;</code>
:::: Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Le cas échéant, on utilisera "Times".

:: '''Définir la taille du texte'''
:::: <code>font-size:14px;</code>
:::: Dans cet exemple, la taille du texte sera forcée à 14px.

:: '''Italique :'''
:::: <code>font-style:italic;</code>

:: '''Gras :'''
:::: <code>font-weight:bold</code>

:: '''Souligner le texte :'''
:::: <code>text-decoration:underline;</code>

:: '''Alignement :'''
:::: <code>text-align:right;</code> (aligner à droite)
:::: <code>text-align:left;</code> (aligner à gauche)
:::: <code>text-align:center</code> (centrer sur la page)
:::: <code>text-align:justify</code> (justifier)

NOTE : ''la suite est à finaliser et mettre au propre''

*Définir une bordure
<code>border: 1px #777777 solid</code>

*Choisir une couleur de fond pour le texte
<code>background-color: #FFFF00</code>
La couleur doit être indiquée au format hexadecimal
*Choisir une couleur pour le texte
<code>color: #FF0000</code>
La couleur doit être indiquée au format hexadecimal
<h3 id="refs">[[Smartdoc/titre-et-references|Les références croisées]]</h3>
Les références croisées font l'objet d'une [[Smartdoc/titre-et-references|page dédiée]].

=== Visible if ===

Ici, les [[Conditions|visible ifs]] permettront de conditionner l’apparition des contenus dans le Document.
Le fonctionnement est similaire au reste du système, et est détaillé dans la page relative aux [[Conditions|Visible ifs]].

'''Particularité :''' les [[Conditions|visible ifs]] des SmartDocs peuvent utiliser la variable spéciale <code>_CURRENT_DOC_ID</code> (type ''string'') qui contient l'identifiant du document courant.

=== Utiliser les [[Boucles]] ===
Les boucles permettent de répéter un groupe d'informations autant de fois que nécessaire, cette notion est détaillée dans la [[Boucles|page correspondante]].

=== Commentaire ===
Ce champ permet à celui qui paramètre de laisser toute indication utile à la compréhension de son fichier de paramétrage.
L’utilisateur final ne verra jamais ce qui est écrit dans ce champ.
<h2 id="autre">Autres fonctionnalités présentes dans le SmartDoc</h2>

SmartDoc

2022-08-30T18:13:44Z

Damien :

<h1 id="smartdoc">SmartDoc</h1>

<h2 id="introduction">Introduction</h2>
En premier lieu, un SmartDoc doit être clairement identifié par son doc-id, qui doit être strictement le même que le doc-id spécifié dans la [[DocList]]
La nouvelle feuille du [[Fichier de Paramétrage]] qui a vocation à être un SmartDoc doit donc se nommer précisément : Doc “le_doc-id”
Par exemple :
Ici, la [[DocList]] mentionne un seul SmartDoc, dont le doc-id est “demo-hercule” :
[[Fichier:DocList 1.png|frame|none|Une DocList classique]]
En conséquence, la feuille correspondante se nomme demo-hercule
[[Fichier:Capture d’écran 2019-07-24 à 11.19.59.png|frame|none]]
Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”
<h2 id="metadonn-es-datastore-options-list-labels">Metadonnées, datastore, options, list labels</h2>
[[Fichier:Smartdoc options 1.png|sans_cadre|1200px|néant]]
=== Métadonnées ===

 C'est un simple espace de commentaire 

=== DataStore ===

[[DataStore]] : C’est l'id du [[DataStore]] auquel les variables utilisées dans le document sont associées. Par défaut, mainstore.

=== Options ===

La colonne "Options" permet de définir des options relatives au document courant.
Cette cellule attend un contenu au format YAML.

==== L'option "title-num-display" ====

L'option "title-num-display" permet de définir le format d’affichage pour la numérotation de chaque titre du document.

Si cette option vaut <code>none</code> ou <code>disabled</code> les titres et les références affichées dans ce document seront "désactivées" et ne s'afficheront donc pas.

Au contraire, pour personnaliser le format de la numérotation, cette option attend une liste clés-valeurs (texte indenté, YAML), où chaque clé est un niveau de titre (de 1 à 6 inclus), et pour chaque niveau, trois attributs peuvent être saisis : <code>style</code>, <code>format</code>, et <code>format-ref</code> (voir exemple imagée ci-dessous).

Les valeurs possible pour l'attribut <code>style</code> sont :
:: - "decimal" : numérotation décimale classique en chiffre arabe (1, 2 , 3 …) ;
:: - "upper-roman" : nombre romain majuscule (I, II, III, IV etc.) ;
:: - "lower-roman" : nombre romain minuscule (i, ii, iii, iv etc.) ;
:: - "upper-alpha" : numérotation alphabétique majuscule (A, B, C, D, E) ;
:: - "lower-roman" : numérotation alphabétique minuscule (a, b, c, d...) ;
:: - "none" : aucune numérotation pour ce niveau de titre ;

L'attribut <code>format</code> attend une chaîne de caractère qui permet de représenter le contexte (préfixe, suffixe…) de la numérotation à afficher avant chaque Titre.
Cette chaîne doit contenir au moins une fois un $1, $2, $3 … $6, qui seront remplacés par la numérotation pur le niveau concerné.
L'attribut <code>format-ref</code> fonctionne de la même façon que l'attribut précédent mais il permet de représenter la numérotation à afficher dans chaque référence intégrée au sein du document (voir [[Smartdoc/titre-et-references|SmartDocument, faire une référence à un titre]]).

Ces attributs doivent contenir au moins une fois un code numéroté tel que <code>$1</code>, <code>$2</code>, <code>$3</code> … <code>$6</code>, qui permettra d'être remplacé par la numérotation du niveau concerné.

'''Exemple''' : le format “<code>$1)</code>“ s'affichera “''A)''”, "''B)''", "''C)''" etc. (s'il est combiné au style <code>"upper-alpha"</code>), ou "i)", "ii)", "iii)" (style <code>"lower-roman"</code>).

'''Autre exemple''' : “<code>Article $1.$2</code>“ s'affichera “Article 1.A”, "Article 1.B", "Article 2.A" … (combiné avec un niveau 1 au style <code>décimal</code> et un niveau 2 en <code>upper-roman</code>).

'''Exemple complet :'''
[[Fichier:Gestion des titres.png|frame|none|Gestion du format des titres]]
D'après la configuration de l'image ci-dessus, les titres :
* de niveau 1 seront de la forme : “ARTICLE 8 - Lorem ipsum”
* de niveau 2 seront de la forme : “2 Lorem ipsum ”
* de niveau 3 seront de la forme : “2-5 Lorem ipsum ”
* de niveau 4 seront de la forme : “2-5-10 Lorem ipsum ”
* de niveau 5 seront de la forme : “a. Lorem ipsum ”
* de niveau 6 seront de la forme : “ iv ) Lorem ipsum

=== List-Labels ===
Introduction
List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. Autrement dit, elle permet d'établir des "dictionnaires de correspondance" permettant de faire correspondre un libellé à une valeur.
Par exemple :
[[Fichier:List Label.png|none|frame|La gestion des List Labels]]
Une fois un List-Label préparé, il est possible de l'utiliser grâce au traitement Label
Contexte
La colonne "Choices" du `Fields-Form` vous permet de spécifier les choix qui doivent apparaitre dans le formulaire. Chaque choix :
- s'écrit sur une ligne différente, ligne qui doit se terminer par un point-virgule ;
- chaque choix s'écrit en deux parties séparées par un ":" afin d'indiquer, à gauche, la valeur à stocker en base de données (et à utiliser dans les [[Conditions|visible ifs]]) et à droite la valeur à afficher dans le formulaire. On parle de couple "valeur : libellé".
Par exemple
[[Fichier:Dg.png|thumb|none|375px]]

Mise en place
Le document n'est pas à même de décider sous quelle forme afficher la variable correspondante aux choix d'un champ de type "choix"
Si rien n'est spécifié, le document affichera ce qui est stocké dans la base de données 
Il est toutefois possible d'indiquer au document des libellés et pour cela intervient le filtre <code>:label(xxx)`</code>.
Par exemple, on peut imaginer un dictionnaire nommé "fonctions" pour indiquer que "dg" doit s'afficher "Directeur Général", et un autre dictionnaire nommé "fonctions_abrégées" qui indiquerait au contraire que "dg" doit s'afficher "Dir. G.".
Il sera alors possible, dans le contenu du SmartDoc, de faire appel au dictionnaire de votre choix :
<ul>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions")}</code></li>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions_abrégées")}</code></li>
</ul>

Les dictionnaires sont définis via la case D2 (List Labels) des onglets "Doc".
Ils sont écrits sous la forme suivante :

[[Fichier:D2.png|none|thumb|175px]]
⚠ Notez les espaces d'indentation qui permettent d'indiquer au système l'imbrication / hiérarchie de l'info. C'est à dire qu'ici, val1 et val2 appartiennent au premier dictionnaire, alors que valA et valB appartiennent au second dictionnaire. Sans cette indentation, le système ne saurait pas reconnaitre si la ligne correspond à la déclaration d'un nouveau dictionnaire ou à un couple valeur/libellé. 
→ A noter : On peut aussi utiliser un libellé référencé dans une “[[Choice-List]]”.
Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : <code>countries: @pays</code> .
On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, <code>{PAYS_NAISS:label("countries")}</code>.
La colonne A qui donne France si la variable PAYS_NAISS vaut “FR”.

<h2 id="templates-docx">Les modèles .docx</h2>

Le SmartDoc consiste à définir du "contenu dynamique", bien qu'il soit possible de définir certains styles de base (couleurs, gras, italiques, titres etc.), la mise en page du document lui même reste limitée. C'est en cela que les "modèles .docx" peuvent être utile.

Chaque SmartDoc peut se baser sur un modèle de fichier, au format .docx. Le contenu dynamique sera tout simplement "injecté" dans le document à l'endroit indiqué.
Le modèle peut, par exemple, prévoir un habillage (page de couverture, page de garde etc.), prévoir des entêtes et pieds-de-page, mais surtout, peut permettre de définir les marges du document et les styles des paragraphes et des titres (tailles, couleurs, espacement...).
Le contenu dynamique, créé au travers du SmartDoc, se retrouvera simplement injecté dans le modèle prédéfini.

'''Définir un modèle et l'associer à un ou plusieurs SmartDoc'''

Pour pouvoir utiliser un modèle, il suffit de le rajouter dans la Doc-List, en lui donnant un identifiant unique, et en indiquant le type <code>docx-template</code> (vous pouvez aussi préciser un titre, une description).

Une fois le modèle présent dans la Doc-List, il est possible de l'associer à un SmartDoc en utilisant l'option : <code>docx-template: mon-template</code>.

'''Préparer son modèle et l'injection du contenu'''

Le modèle .docx peut être préparé comme un document classique : définir les styles des titres et des paragraphes, définir les marges et les interlignes, une page de couverture et des pieds-de-pages etc.
Pour définir où le contenu dynamique devra être injecté, il faut utiliser la syntaxe suivante : <code>${ @inject all }</code>. Ainsi, l'intégralité du contenu du SmartDoc sera intégrée à cet endroit même du modèle.
Il est aussi possible de demander l'intégration d'un seul [[Blocs | bloc du SmartDoc]], en indiquant, à la place de <code>all</code>, l'identifiant du SmartDoc et le nom exact du bloc.

Par exemple, dans un SmartDoc nommé <code>contrat</code>, un bloc défini par <code>#BLOC dénomination</code>, pourra être injecté dans le modèle .docx avec la syntaxe suivante :
<pre>${ @inject contrats :: dénomination }</pre>

'''''Nb :''' notez les 2 fois 2 points (<code>::</code>) pour séparer l'identifiant du SmartDoc concerné et le nom exact du bloc à injecter.''

'''Pour aller plus loin :'''
* Vous pouvez trouver plus d'informations sur les modèles docx et sur la manière de les mettre en place sur la [[Docx-template|page dédiée du Wiki]].
* Il est parfaitement possible d'utiliser plusieurs injections dans un même modèle .docx. Il vous suffit d'utiliser plusieurs fois la syntaxe <code>${ @inject ... }</code> dans le document modèle.
* Le contenu injecté peut lui-même inclure d'autres blocs (voir [[Smartdoc/include| les "inclusions" (includes) d'un SmartDoc]]), des boucles, des titres etc.
* Dans certains cas, il peut être problématique d'injecter un bloc, lui même contenu dans [[Boucles | une boucle du SmartDoc]]. En effet, la boucle a pour conséquence de "contextualiser" la variable sur laquelle elle boucle, si vous injectez ce contenu hors de ce contexte, le SmartDoc ne saura pas comment interpréter la variable correspondante à une occurence de la boucle.

== Contenu, options, styles, [[Conditions|visible ifs]], commentaires ==

[[Fichier:SmartDoc options 2.png|1200px|sans_cadre|néant]]
<h3 id="contenu">Contenu</h3>
 Un SmartDoc est constitué d'une suite ordonnée d'[[Élément_de_contenu|éléments de contenu]]. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'éléments de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).
Le “contenu” du SmartDoc est ce qui sera effectivement “imprimé” dans le document final qui sera transmis à l’utilisateur.
Ce contenu, en plus d’être dynamique grâce au “visible-ifs” comme le reste du système, accepte aussi l’utilisation de variables.
<h4 id="bases">Bases</h4>
C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.
On peut se servir des [https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML balises HTML basiques] pour mettre en forme le texte rentré ici.
Les balises suivants sont utilisables

* a,
* br,
* b,
* strong,
* i,
* em,
* ol,
* ul,
* li,
* hr,
* span


==== Contenu spécial ou dynamique ====

Ils sont de la forme <code>{ @… }</code> et s'integre parmi le contenu.

:: — <code>{ @line-break }</code> : ajout un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : <code>{@line-break}</code> Plusieurs saut de ligne (par exemple 2) : <code>{@line-break:2}</code>

:: — <code>{@page-break</code>} : ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : <code>{@page-break}</code>.
:: Le saut de page est effectif dans les exports .docx ou .pdf, mais est simulé par une simple ligne verticale dans les prévisualisations HTML.

:: — <code>{@ref:my title id}</code> : ajout d’une référence vers un titre : comme pour intégrer une variable, il est possible d’intégrer un lien vers un titre du document (le titre peut se trouver avant ou après la référence dans le contenu). Pour intégrer une référence, il suffit d’utiliser la syntaxe <code>{@ref:my title id}</code> pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. Le fonctionnement des références croisées est décrit en détail [[Smartdoc/titre-et-references|ici]].
:::: Nb : si plusieurs titres ont le même title-id alors la référence pointe vers le premier de la page.
:::: Nb : si la référence pointe vers un titre qui n’existe pas dans le document (ou est invisible), elle sera remplacée par le texte “[référence manquante]”.
:::: Par défaut, la référence à un titre se contente d’afficher le titre (càd, le contenu du bloc titre).

:::: Une chaine de caractère étant retournée, il est possible d’appliquer les filtres classiques.
:::: Exemple : ''Comme décrit dans la section'' <code>{@ref:droit-acheteur:uppercase}</code>.
:::: Le traitement <code>:num</code> peut-être appliqué dans la syntaxe afin d’afficher la référence sous forme numérique et tenant compte des titres parents.
:::: Exemple : ''Comme décrit dans la section ''<code>{@ref:droit-acheteur:num}</code>… => ''Comme décrit dans la section '' '''3.1.1.2'''

:::: Pour les cas des références vers des titres ayant l’option title-article à “true” le nombre retourné sera simplement celui de l’article dans le cas du traitement “:num”.
:::: Pour les cas des références vers des titres ayant l’option title-no-count , le traitement “:num” n’aura alors aucun effet.

:: — <code>{@summary}</code>Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : <code>{@summary}</code>

:: — <code>{ @doc-meta(title) }</code> : permet d'insérer une méta-donnée du document courant. Les 3 paramètres possibles sont : <code>title</code>, <code>description</code>, ou <code>id</code>. Pratique, par exemple, pour citer le titre du document au sein du contenu, malgré peut-être la présence d'un clausier et de blocs injectés d'un autre document.

==== Comment rendre dynamique le contenu d'un [[SmartDoc]] ? ====

Pour rendre dynamique le contenu du SmartDoc, il est possible de lui intégrer les valeurs des variables telles qu'elles ont été collectée dans un formulaire, ou calculée via une variable dynamique etc.

La syntaxe pour intégrer un contenu dynamique est reconnaissable car il est systématiquement placé entre accolades : <code>{ … }</code>.

Une variable peut être intégrée de façon brute (Exemple : ''"Je m'appelle { PRENOM }."'').
L'affichage brut pouvant parfois être trop limitatif, une syntaxe de "traitements SmartDoc" est disponible. Par exemple, le traitement <code>:uppercase</code> appliqué sur une variable la fera afficher en majuscule. Exemple :: ''"Je m'appelle <code>{ PRENOM:uppercase }</code>."'').

<h5 id="les-primitives">Les primitives</h5>
Une primitive est un élément qui a une valeur.
Par exemple: la variable PRENOM va valoir “Damien”. Ou tout simplement un nombre (ex: 36) ou une chaine de caractère (ex: "une chaise")
Pour intégrer une valeur : les variables du dataset sont intégrées dans le contenu à partir d’une syntaxe simple : la variable est placée, sans espace, entre deux accolades.
Exemple :
Le vendeur, né le <code>{DATE_NAISSANCE}</code>, à <code>{VILLE_NAISSANCE}</code> ... 

==== Les traitements dans le SmartDoc ====

Les traitements peuvent être définies comme une modification appliquée sur un contenu. Par exemple, le traitement <code>uppercase</code> permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère. 
Pour appliquer un traitement sur une primitive, on utilise le signe : <code>:</code> Ce qui donne Mon prénom est <code>{PRENOM:uppercase}</code> qui donne Mon prénom est DAMIEN même quand la variable <code>PRENOM</code> vaut “DaMien”.
Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : <code>:</code>
Exemple :
Le vendeur s’appelle <code>{PRENOM:uppercase}</code>
Il est possible d'enchaîner les traitements. 
Exemple :L'acheteur a payé <code>{PRIX:letters:uppercase}</code> euros.
Ici, la valeur contenue dans la variable "PRIX" sera d'abord convertie en lettres, puis mise automatiquement en MAJUSCULES.
On obtiendra un résultat du type : "L'acheteur a payé TRENTE euros", alors que la valeur de départ sera "30".
A noter : les traitements peuvent s’appliquer aussi sur de simples chaînes de caractères et pas seulement des variables. Ex : L'acheteur a payé {"32 000":letters:uppercase} euros.

==== Traitements disponibles et syntaxe spécifique ====

<code>:uppercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en majuscule
 
<code>:lowercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en minuscule
 
<code>:letters</code> : ne s'applique que sur une valeur numérique, et permet de la convertir en "toutes-lettres" (ex : <code>312</code> => <code>Trois-cent-douze</code>).
 
<code>:capitalize</code> : ne s'applique que sur une chaine de caractères, et permet de passer en majuscule la première lettre de chaque mot. Ex: <code>NOM:capitalize</code> 
Option : si l'option 1 (ou "yes") est passée en paramètre de ce traitement, alors seule la première lettre du premier mot sera mise en majuscule. Ex: <code>NOM:capitalize(1)</code> , <code>NOM:capitalize(yes)</code>… 
 
<code>:img</code> : transforme une chaine de caractère (url) en image dans le document. Ex : <code>{"https://api.memegen.link/images/puffin.jpg":img}</code> va permettre d'intégrer l'image présente à cette URL dans le document.
 Nb: dans les version v0.9-v0.11 l'intégration d'une image distante (via <code>:img</code>) n'est plus possible dans les exports .docx / .pdf si un modèle de document (voir docx template) est utilisé. En effet, la norme DocX ne permet pas/plus l'intégration d'image / objet si le fichier est créé par un TemplateEngine.

 
<code>:num</code>: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre.
Exemple : </code>Comme décrit dans la section {@ref:droit-acheteur:num}, vous...</code>. Le fonctionnement des références croisées est décrit en détail [[http://wiki.hercule.co:3002/index.php/Smartdoc/titre-et-references|ici]]
 
<code>:french-datetime</code> : ne s'applique que sur une date ou une chaîne de caractère au format "Date". Ce traitement permet de transformer la date au format "30/12/1985 à 12h45".
 
<code>:french-date</code> : ne s'applique que sur une date ou une chaîne de caractère au format "YYYY-MM-DD" (format international). Ce traitement permet de transformer la date fournie dans le format Français "jj/mm/aaaa". Depuis la version v0.10, ce filtre est "facultatif" car il est appliqué par défaut sur les dates ou les chaînes au format de date. 
 
<code>:num-format</code> : ne s'applique que sur une valeur numérique, et permet de la formater pour son affichage. Ce traitement peut prendre 3 paramètres '''facultatifs'''. 
<ul>
<li>Le 1er permet (numérique et facultatif) permet d'indiquer le nombre de décimale souhaitées (par défaut, 2 chiffres ou 0 si la partie décimale est nulle).</li>
<li>Le second paramètre (chaîne, facultative) correspond au séparateur des milliers (par défaut : un espace).</li>
<li>Le troisième paramètre (chaîne, facultative) correspond au caractère à afficher pour le séparateur décimal (par défaut : <code>,</code>).</li>
</ul>
Quelques exemples : <ul>
<li> - soit une variable numérique VAR_PI qui vaut <code>3,1451</code>. L'affichage par défaut <code>{ VAR_PI }</code> affichera <code>3,14</code>. L'affichage <code>{ VAR_PI:num-format(3) }</code> affichera <code>3,145</code>. </li>
<li> - pour la variable PRICE (numérique) qui vaudrait <code>9 999,99</code>, l'affichage <code>{ PRICE:num-format }</code> affichera <code>9 999,99</code> (dans ce cas le `:num-format` est facultatif). Par contre, l'affichage <code>{ PRICE:num-format(1,',', '.') }</code> affichera <code>9,999.9</code> (1 chiffre après la virgule, séparateur des milliers et décimaux modifiés).</li>
</ul>

 

<code>:join</code> : limité à une variable de liste plate (issue d'un [[Fields-Form|multiples-choices]] principalement) → permet d'afficher les différentes valeurs de la liste sous la forme suivante : <code>Valeur1, Valeur2, Valeur3, et Valeur4</code>. Les différentes valeurs contenues dans la variable sont affichées les unes à la suite des autres, séparées par des virgules; la dernière valeur est précédée de la conjonction de coordination <code>et</code>.
:: Il est possible de personnaliser le séparateur, par exemple <code>LIST:join(" ou ")</code> → renvoie <code>Valeur1 ou Valeur2 ou Valeur3</code>.
:: Et il est même possible de personnaliser indépendamment le séparateur du dernier élément grâce à un second paramètre. Exemple <code>LIST:join(" ou ", " ou bien même ")</code> → renvoie <code>Valeur1 ou Valeur2 ou bien même Valeur3</code>.

 
<code>:list</code> : '''utilisable uniquement pour les variables [[Fields-Form|multiples-choices]]''' → permet d'afficher les différentes valeurs de la liste dans le SmartDoc sous la forme d'une liste à puce; chacune des valeurs de la liste démarre une nouvelle puce
 
<code>:label</code> : dont le fonctionnement est expliqué [[SmartDoc#List-Labels|plus haut]].
 
<code>:substr(x,y)</code> : permet de tronquer une chaîne de caractères. Par exemple pour une variable PRENOM qui vaudrait "Maximilien", on pourra utiliser la notation suivante : <code>{PRENOM:substr(2,4)}</code>, qui donnera en pratique "ximi" ;


 
<code>:string-replace([remplaceur], [remplacé])</code> : permet de remplacer une chaîne par une autre chaîne dans le contenu d'une variable de type "string".
Par exemple pour une variable VAR qui vaudrait "Damien", l'expression <code>VAR:string-replace("F", "D")</code> donnera "Famien". 
Si le paramètre "remplacé" n'est pas fourni, ce sera par défaut un saut de ligne qui sera recherché. Par exemple pour une variable ADDRESS qui contient des sauts de ligne, l'expression <code>ADDRESS:string-replace(", ")</code> va remplacer chaque saut de ligne de l'adresse par <code>, </code> ce qui permet de passer un texte multi-lignes dans un format une-ligne. 
A savoir : un saut de ligne se note <code>"\n"</code>, il est donc aussi possible de remplacer, par exemple, des tirets <code>-</code> par des sauts de ligne avec l'expression <code>ADDRESS:string-replace("\n", "-")</code>.


 

<code>:default("texte par défaut")</code> permet de définir une valeur "par défaut" à afficher dans le SmartDoc si la variable sur laquelle le filtre est appliqué est vide.

<h3 id="options">Options</h3>
*<code>break</code> (facultatif) : valeur possible <code>none</code> , <code>before</code> ou <code>after</code>.
Permet d’intégrer un saut de ligne. Par défaut, toutes les entrées sont en break: after.
Si after est indiqué (ou si rien n’est indiqué puisque c’est la valeur par défaut), alors le bloc se terminera par un saut de ligne et le bloc suivant s’affichera sur une nouvelle ligne.
Si before est indiqué, l’entrée s’affiche sur une nouvelle ligne (le saut de ligne intervient avant l’entrée).
Si none est indiqué, il n’y a pas de saut de ligne, les entrées s'enchaînent.
*<code>title-level</code> (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6.
*<code>title-id</code> (facultatif) : la valeur attendue est une chaîne de caractères alpha-numériques sans sauts de ligne et dont les caractères suivants sont interdits : :, {, }, "
Cette option permet d’assigner un identifiant au titre concerné, de cette façon il sera possible de faire référence à ce titre via un “bookmark” (voir plus haut, “ajout de référence”).
Nb: cet attribut n’est possible QUE si l’attribut title-level est lui aussi renseigné.
*<code>title-article</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”.
Quand cette option est à “true”, le titre sera considéré comme un “titre d’article”. Il sera donc préfixé par "ARTICLE 1 - " ou le nombre “1” sera remplacé par l’index de l’article en question.
*<code>title-no-count</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”. Quand cette option est à “true”, le titre ne sera pas numéroté, ni dans les sommaires, ni préfixe par aucun type de numérotation.

=== Styles ===

La colonne Styles est facultative, et permet de personnaliser les styles de la ligne de contenu concernée.

Les styles sont fournies dans un format inspiré de la norme [https://www.w3schools.com/css CSS] (mais fortement simplifiée).
Ce format permet de définir plusieurs instructions stylistiques, chacune se terminant par un point-virgule (<code>;</code>) et un saut de ligne. Exemple d'une cellule dont le texte devra être en taille 18px et dans la couleur rouge (''#FF0000'' en couleur hexadécimale) :
font-size:18px;
color:#FF0000;

Chaque instruction est donc formée : d'un attribut de style (voir la liste ci-dessous), puis d'un séparateur (caractère <code>:</code>), puis de la valeur du style souhaité, et se termine par un point-virgule (<code>;</code>) et un saut de ligne.
Il est autorisé de placer un espace après le séparateur "<code>:</code>" mais attention à ce que ce espace ne soit pas "particulier" (espace insécable etc.) car cela mettrait en danger l'interprétation du style et il se peut qu'il ne soit pas du tout pris en compte.

Les instructions de styles autorisées sont :

:: '''Définir une police de caractère spécifique :'''
:::: L'attribut “<code>font-family</code>” permet de spécifier la police à utiliser.
:::: Plusieurs noms de police peuvent être proposées (dans l'ordre de priorité). Si le lecteur (navigateur, logiciel de traitement de texte…) utilisé ne supporte pas la première police, le système tentera d’utiliser la deuxième police, puis la troisième, ainsi de suite ...
:::: Exemple : <code>font-family:Times New Roman, Times;</code>
:::: Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Le cas échéant, on utilisera "Times".

:: '''Définir la taille du texte'''
:::: <code>font-size:14px;</code>
:::: Dans cet exemple, la taille du texte sera forcée à 14px.

:: '''Italique :'''
:::: <code>font-style:italic;</code>

:: '''Gras :'''
:::: <code>font-weight:bold</code>

:: '''Souligner le texte :'''
:::: <code>text-decoration:underline;</code>

:: '''Alignement :'''
:::: <code>text-align:right;</code> (aligner à droite)
:::: <code>text-align:left;</code> (aligner à gauche)
:::: <code>text-align:center</code> (centrer sur la page)
:::: <code>text-align:justify</code> (justifier)

NOTE : ''la suite est à finaliser et mettre au propre''

*Définir une bordure
<code>border: 1px #777777 solid</code>

*Choisir une couleur de fond pour le texte
<code>background-color: #FFFF00</code>
La couleur doit être indiquée au format hexadecimal
*Choisir une couleur pour le texte
<code>color: #FF0000</code>
La couleur doit être indiquée au format hexadecimal
<h3 id="refs">[[Smartdoc/titre-et-references|Les références croisées]]</h3>
Les références croisées font l'objet d'une [[Smartdoc/titre-et-references|page dédiée]].

=== Visible if ===

Ici, les [[Conditions|visible ifs]] permettront de conditionner l’apparition des contenus dans le Document.
Le fonctionnement est similaire au reste du système, et est détaillé dans la page relative aux [[Conditions|Visible ifs]].

Particularité: les [[Conditions|visible ifs]] des SmartDocs peuvent utiliser la variable spéciale <code>_CURRENT_DOC_ID</code> (type ''string'') qui contient l'identifiant du document courant.

=== Utiliser les [[Boucles]] ===
Les boucles permettent de répéter un groupe d'informations autant de fois que nécessaire, cette notion est détaillée dans la [[Boucles|page correspondante]].

=== Commentaire ===
Ce champ permet à celui qui paramètre de laisser toute indication utile à la compréhension de son fichier de paramétrage.
L’utilisateur final ne verra jamais ce qui est écrit dans ce champ.
<h2 id="autre">Autres fonctionnalités présentes dans le SmartDoc</h2>

SmartDoc

2022-08-30T16:31:39Z

Damien : /* Contenu spécial ou dynamique */

<h1 id="smartdoc">SmartDoc</h1>

<h2 id="introduction">Introduction</h2>
En premier lieu, un SmartDoc doit être clairement identifié par son doc-id, qui doit être strictement le même que le doc-id spécifié dans la [[DocList]]
La nouvelle feuille du [[Fichier de Paramétrage]] qui a vocation à être un SmartDoc doit donc se nommer précisément : Doc “le_doc-id”
Par exemple :
Ici, la [[DocList]] mentionne un seul SmartDoc, dont le doc-id est “demo-hercule” :
[[Fichier:DocList 1.png|frame|none|Une DocList classique]]
En conséquence, la feuille correspondante se nomme demo-hercule
[[Fichier:Capture d’écran 2019-07-24 à 11.19.59.png|frame|none]]
Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”
<h2 id="metadonn-es-datastore-options-list-labels">Metadonnées, datastore, options, list labels</h2>
[[Fichier:Smartdoc options 1.png|sans_cadre|1200px|néant]]
=== Métadonnées ===

 C'est un simple espace de commentaire 

=== DataStore ===

[[DataStore]] : C’est l'id du [[DataStore]] auquel les variables utilisées dans le document sont associées. Par défaut, mainstore.

=== Options ===

La colonne "Options" permet de définir des options relatives au document courant.
Cette cellule attend un contenu au format YAML.

==== L'option "title-num-display" ====

L'option "title-num-display" permet de définir le format d’affichage pour la numérotation de chaque titre du document.

Si cette option vaut <code>none</code> ou <code>disabled</code> les titres et les références affichées dans ce document seront "désactivées" et ne s'afficheront donc pas.

Au contraire, pour personnaliser le format de la numérotation, cette option attend une liste clés-valeurs (texte indenté, YAML), où chaque clé est un niveau de titre (de 1 à 6 inclus), et pour chaque niveau, trois attributs peuvent être saisis : <code>style</code>, <code>format</code>, et <code>format-ref</code> (voir exemple imagée ci-dessous).

Les valeurs possible pour l'attribut <code>style</code> sont :
:: - "decimal" : numérotation décimale classique en chiffre arabe (1, 2 , 3 …) ;
:: - "upper-roman" : nombre romain majuscule (I, II, III, IV etc.) ;
:: - "lower-roman" : nombre romain minuscule (i, ii, iii, iv etc.) ;
:: - "upper-alpha" : numérotation alphabétique majuscule (A, B, C, D, E) ;
:: - "lower-roman" : numérotation alphabétique minuscule (a, b, c, d...) ;
:: - "none" : aucune numérotation pour ce niveau de titre ;

L'attribut <code>format</code> attend une chaîne de caractère qui permet de représenter le contexte (préfixe, suffixe…) de la numérotation à afficher avant chaque Titre.
Cette chaîne doit contenir au moins une fois un $1, $2, $3 … $6, qui seront remplacés par la numérotation pur le niveau concerné.
L'attribut <code>format-ref</code> fonctionne de la même façon que l'attribut précédent mais il permet de représenter la numérotation à afficher dans chaque référence intégrée au sein du document (voir [[Smartdoc/titre-et-references|SmartDocument, faire une référence à un titre]]).

Ces attributs doivent contenir au moins une fois un code numéroté tel que <code>$1</code>, <code>$2</code>, <code>$3</code> … <code>$6</code>, qui permettra d'être remplacé par la numérotation du niveau concerné.

'''Exemple''' : le format “<code>$1)</code>“ s'affichera “''A)''”, "''B)''", "''C)''" etc. (s'il est combiné au style <code>"upper-alpha"</code>), ou "i)", "ii)", "iii)" (style <code>"lower-roman"</code>).

'''Autre exemple''' : “<code>Article $1.$2</code>“ s'affichera “Article 1.A”, "Article 1.B", "Article 2.A" … (combiné avec un niveau 1 au style <code>décimal</code> et un niveau 2 en <code>upper-roman</code>).

'''Exemple complet :'''
[[Fichier:Gestion des titres.png|frame|none|Gestion du format des titres]]
D'après la configuration de l'image ci-dessus, les titres :
* de niveau 1 seront de la forme : “ARTICLE 8 - Lorem ipsum”
* de niveau 2 seront de la forme : “2 Lorem ipsum ”
* de niveau 3 seront de la forme : “2-5 Lorem ipsum ”
* de niveau 4 seront de la forme : “2-5-10 Lorem ipsum ”
* de niveau 5 seront de la forme : “a. Lorem ipsum ”
* de niveau 6 seront de la forme : “ iv ) Lorem ipsum

=== List-Labels ===
Introduction
List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. Autrement dit, elle permet d'établir des "dictionnaires de correspondance" permettant de faire correspondre un libellé à une valeur.
Par exemple :
[[Fichier:List Label.png|none|frame|La gestion des List Labels]]
Une fois un List-Label préparé, il est possible de l'utiliser grâce au traitement Label
Contexte
La colonne "Choices" du `Fields-Form` vous permet de spécifier les choix qui doivent apparaitre dans le formulaire. Chaque choix :
- s'écrit sur une ligne différente, ligne qui doit se terminer par un point-virgule ;
- chaque choix s'écrit en deux parties séparées par un ":" afin d'indiquer, à gauche, la valeur à stocker en base de données (et à utiliser dans les [[Conditions|visible ifs]]) et à droite la valeur à afficher dans le formulaire. On parle de couple "valeur : libellé".
Par exemple
[[Fichier:Dg.png|thumb|none|375px]]

Mise en place
Le document n'est pas à même de décider sous quelle forme afficher la variable correspondante aux choix d'un champ de type "choix"
Si rien n'est spécifié, le document affichera ce qui est stocké dans la base de données 
Il est toutefois possible d'indiquer au document des libellés et pour cela intervient le filtre <code>:label(xxx)`</code>.
Par exemple, on peut imaginer un dictionnaire nommé "fonctions" pour indiquer que "dg" doit s'afficher "Directeur Général", et un autre dictionnaire nommé "fonctions_abrégées" qui indiquerait au contraire que "dg" doit s'afficher "Dir. G.".
Il sera alors possible, dans le contenu du SmartDoc, de faire appel au dictionnaire de votre choix :
<ul>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions")}</code></li>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions_abrégées")}</code></li>
</ul>

Les dictionnaires sont définis via la case D2 (List Labels) des onglets "Doc".
Ils sont écrits sous la forme suivante :

[[Fichier:D2.png|none|thumb|175px]]
⚠ Notez les espaces d'indentation qui permettent d'indiquer au système l'imbrication / hiérarchie de l'info. C'est à dire qu'ici, val1 et val2 appartiennent au premier dictionnaire, alors que valA et valB appartiennent au second dictionnaire. Sans cette indentation, le système ne saurait pas reconnaitre si la ligne correspond à la déclaration d'un nouveau dictionnaire ou à un couple valeur/libellé. 
→ A noter : On peut aussi utiliser un libellé référencé dans une “[[Choice-List]]”.
Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : <code>countries: @pays</code> .
On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, <code>{PAYS_NAISS:label("countries")}</code>.
La colonne A qui donne France si la variable PAYS_NAISS vaut “FR”.

<h2 id="templates-docx">Les modèles .docx</h2>

Le SmartDoc consiste à définir du "contenu dynamique", bien qu'il soit possible de définir certains styles de base (couleurs, gras, italiques, titres etc.), la mise en page du document lui même reste limitée. C'est en cela que les "modèles .docx" peuvent être utile.

Chaque SmartDoc peut se baser sur un modèle de fichier, au format .docx. Le contenu dynamique sera tout simplement "injecté" dans le document à l'endroit indiqué.
Le modèle peut, par exemple, prévoir un habillage (page de couverture, page de garde etc.), prévoir des entêtes et pieds-de-page, mais surtout, peut permettre de définir les marges du document et les styles des paragraphes et des titres (tailles, couleurs, espacement...).
Le contenu dynamique, créé au travers du SmartDoc, se retrouvera simplement injecté dans le modèle prédéfini.

'''Définir un modèle et l'associer à un ou plusieurs SmartDoc'''

Pour pouvoir utiliser un modèle, il suffit de le rajouter dans la Doc-List, en lui donnant un identifiant unique, et en indiquant le type <code>docx-template</code> (vous pouvez aussi préciser un titre, une description).

Une fois le modèle présent dans la Doc-List, il est possible de l'associer à un SmartDoc en utilisant l'option : <code>docx-template: mon-template</code>.

'''Préparer son modèle et l'injection du contenu'''

Le modèle .docx peut être préparé comme un document classique : définir les styles des titres et des paragraphes, définir les marges et les interlignes, une page de couverture et des pieds-de-pages etc.
Pour définir où le contenu dynamique devra être injecté, il faut utiliser la syntaxe suivante : <code>${ @inject all }</code>. Ainsi, l'intégralité du contenu du SmartDoc sera intégrée à cet endroit même du modèle.
Il est aussi possible de demander l'intégration d'un seul [[Blocs | bloc du SmartDoc]], en indiquant, à la place de <code>all</code>, l'identifiant du SmartDoc et le nom exact du bloc.

Par exemple, dans un SmartDoc nommé <code>contrat</code>, un bloc défini par <code>#BLOC dénomination</code>, pourra être injecté dans le modèle .docx avec la syntaxe suivante :
<pre>${ @inject contrats :: dénomination }</pre>

'''''Nb :''' notez les 2 fois 2 points (<code>::</code>) pour séparer l'identifiant du SmartDoc concerné et le nom exact du bloc à injecter.''

'''Pour aller plus loin :'''
* Vous pouvez trouver plus d'informations sur les modèles docx et sur la manière de les mettre en place sur la [[Docx-template|page dédiée du Wiki]].
* Il est parfaitement possible d'utiliser plusieurs injections dans un même modèle .docx. Il vous suffit d'utiliser plusieurs fois la syntaxe <code>${ @inject ... }</code> dans le document modèle.
* Le contenu injecté peut lui-même inclure d'autres blocs (voir [[Smartdoc/include| les "inclusions" (includes) d'un SmartDoc]]), des boucles, des titres etc.
* Dans certains cas, il peut être problématique d'injecter un bloc, lui même contenu dans [[Boucles | une boucle du SmartDoc]]. En effet, la boucle a pour conséquence de "contextualiser" la variable sur laquelle elle boucle, si vous injectez ce contenu hors de ce contexte, le SmartDoc ne saura pas comment interpréter la variable correspondante à une occurence de la boucle.

== Contenu, options, styles, [[Conditions|visible ifs]], commentaires ==

[[Fichier:SmartDoc options 2.png|1200px|sans_cadre|néant]]
<h3 id="contenu">Contenu</h3>
 Un SmartDoc est constitué d'une suite ordonnée d'[[Élément_de_contenu|éléments de contenu]]. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'éléments de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).
Le “contenu” du SmartDoc est ce qui sera effectivement “imprimé” dans le document final qui sera transmis à l’utilisateur.
Ce contenu, en plus d’être dynamique grâce au “visible-ifs” comme le reste du système, accepte aussi l’utilisation de variables.
<h4 id="bases">Bases</h4>
C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.
On peut se servir des [https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML balises HTML basiques] pour mettre en forme le texte rentré ici.
Les balises suivants sont utilisables

* a,
* br,
* b,
* strong,
* i,
* em,
* ol,
* ul,
* li,
* hr,
* span


==== Contenu spécial ou dynamique ====

Ils sont de la forme <code>{ @… }</code> et s'integre parmi le contenu.

:: — <code>{ @line-break }</code> : ajout un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : <code>{@line-break}</code> Plusieurs saut de ligne (par exemple 2) : <code>{@line-break:2}</code>

:: — <code>{@page-break</code>} : ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : <code>{@page-break}</code>.
:: Le saut de page est effectif dans les exports .docx ou .pdf, mais est simulé par une simple ligne verticale dans les prévisualisations HTML.

:: — <code>{@ref:my title id}</code> : ajout d’une référence vers un titre : comme pour intégrer une variable, il est possible d’intégrer un lien vers un titre du document (le titre peut se trouver avant ou après la référence dans le contenu). Pour intégrer une référence, il suffit d’utiliser la syntaxe <code>{@ref:my title id}</code> pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. Le fonctionnement des références croisées est décrit en détail [[Smartdoc/titre-et-references|ici]].
:::: Nb : si plusieurs titres ont le même title-id alors la référence pointe vers le premier de la page.
:::: Nb : si la référence pointe vers un titre qui n’existe pas dans le document (ou est invisible), elle sera remplacée par le texte “[référence manquante]”.
:::: Par défaut, la référence à un titre se contente d’afficher le titre (càd, le contenu du bloc titre).

:::: Une chaine de caractère étant retournée, il est possible d’appliquer les filtres classiques.
:::: Exemple : ''Comme décrit dans la section'' <code>{@ref:droit-acheteur:uppercase}</code>.
:::: Le traitement <code>:num</code> peut-être appliqué dans la syntaxe afin d’afficher la référence sous forme numérique et tenant compte des titres parents.
:::: Exemple : ''Comme décrit dans la section ''<code>{@ref:droit-acheteur:num}</code>… => ''Comme décrit dans la section '' '''3.1.1.2'''

:::: Pour les cas des références vers des titres ayant l’option title-article à “true” le nombre retourné sera simplement celui de l’article dans le cas du traitement “:num”.
:::: Pour les cas des références vers des titres ayant l’option title-no-count , le traitement “:num” n’aura alors aucun effet.

:: — <code>{@summary}</code>Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : <code>{@summary}</code>

:: — <code>{ @doc-meta(title) }</code> : permet d'insérer une méta-donnée du document courant. Les 3 paramètres possibles sont : <code>title</code>, <code>description</code>, ou <code>id</code>. Pratique, par exemple, pour citer le titre du document au sein du contenu, malgré peut-être la présence d'un clausier et de blocs injectés d'un autre document.

==== Comment rendre dynamique le contenu d'un [[SmartDoc]] ? ====

Pour rendre dynamique le contenu du SmartDoc, il est possible de lui intégrer les valeurs des variables telles qu'elles ont été collectée dans un formulaire, ou calculée via une variable dynamique etc.

La syntaxe pour intégrer un contenu dynamique est reconnaissable car il est systématiquement placé entre accolades : <code>{ … }</code>.

Une variable peut être intégrée de façon brute (Exemple : ''"Je m'appelle { PRENOM }."'').
L'affichage brut pouvant parfois être trop limitatif, une syntaxe de "traitements SmartDoc" est disponible. Par exemple, le traitement <code>:uppercase</code> appliqué sur une variable la fera afficher en majuscule. Exemple :: ''"Je m'appelle <code>{ PRENOM:uppercase }</code>."'').

<h5 id="les-primitives">Les primitives</h5>
Une primitive est un élément qui a une valeur.
Par exemple: la variable PRENOM va valoir “Damien”. Ou tout simplement un nombre (ex: 36) ou une chaine de caractère (ex: "une chaise")
Pour intégrer une valeur : les variables du dataset sont intégrées dans le contenu à partir d’une syntaxe simple : la variable est placée, sans espace, entre deux accolades.
Exemple :
Le vendeur, né le <code>{DATE_NAISSANCE}</code>, à <code>{VILLE_NAISSANCE}</code> ... 

==== Les traitements dans le SmartDoc ====

Les traitements peuvent être définies comme une modification appliquée sur un contenu. Par exemple, le traitement <code>uppercase</code> permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère. 
Pour appliquer un traitement sur une primitive, on utilise le signe : <code>:</code> Ce qui donne Mon prénom est <code>{PRENOM:uppercase}</code> qui donne Mon prénom est DAMIEN même quand la variable <code>PRENOM</code> vaut “DaMien”.
Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : <code>:</code>
Exemple :
Le vendeur s’appelle <code>{PRENOM:uppercase}</code>
Il est possible d'enchaîner les traitements. 
Exemple :L'acheteur a payé <code>{PRIX:letters:uppercase}</code> euros.
Ici, la valeur contenue dans la variable "PRIX" sera d'abord convertie en lettres, puis mise automatiquement en MAJUSCULES.
On obtiendra un résultat du type : "L'acheteur a payé TRENTE euros", alors que la valeur de départ sera "30".
A noter : les traitements peuvent s’appliquer aussi sur de simples chaînes de caractères et pas seulement des variables. Ex : L'acheteur a payé {"32 000":letters:uppercase} euros.

==== Traitements disponibles et syntaxe spécifique ====

<code>:uppercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en majuscule
 
<code>:lowercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en minuscule
 
<code>:letters</code> : ne s'applique que sur une valeur numérique, et permet de la convertir en "toutes-lettres" (ex : <code>312</code> => <code>Trois-cent-douze</code>).
 
<code>:capitalize</code> : ne s'applique que sur une chaine de caractères, et permet de passer en majuscule la première lettre de chaque mot. Ex: <code>NOM:capitalize</code> 
Option : si l'option 1 (ou "yes") est passée en paramètre de ce traitement, alors seule la première lettre du premier mot sera mise en majuscule. Ex: <code>NOM:capitalize(1)</code> , <code>NOM:capitalize(yes)</code>… 
 
<code>:img</code> : transforme une chaine de caractère (url) en image dans le document. Ex : <code>{"https://api.memegen.link/images/puffin.jpg":img}</code> va permettre d'intégrer l'image présente à cette URL dans le document.
 Nb: dans les version v0.9-v0.11 l'intégration d'une image distante (via <code>:img</code>) n'est plus possible dans les exports .docx / .pdf si un modèle de document (voir docx template) est utilisé. En effet, la norme DocX ne permet pas/plus l'intégration d'image / objet si le fichier est créé par un TemplateEngine.

 
<code>:num</code>: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre.
Exemple : </code>Comme décrit dans la section {@ref:droit-acheteur:num}, vous...</code>. Le fonctionnement des références croisées est décrit en détail [[http://wiki.hercule.co:3002/index.php/Smartdoc/titre-et-references|ici]]
 
<code>:french-datetime</code> : ne s'applique que sur une date ou une chaîne de caractère au format "Date". Ce traitement permet de transformer la date au format "30/12/1985 à 12h45".
 
<code>:french-date</code> : ne s'applique que sur une date ou une chaîne de caractère au format "YYYY-MM-DD" (format international). Ce traitement permet de transformer la date fournie dans le format Français "jj/mm/aaaa". Depuis la version v0.10, ce filtre est "facultatif" car il est appliqué par défaut sur les dates ou les chaînes au format de date. 
 
<code>:num-format</code> : ne s'applique que sur une valeur numérique, et permet de la formater pour son affichage. Ce traitement peut prendre 3 paramètres '''facultatifs'''. 
<ul>
<li>Le 1er permet (numérique et facultatif) permet d'indiquer le nombre de décimale souhaitées (par défaut, 2 chiffres ou 0 si la partie décimale est nulle).</li>
<li>Le second paramètre (chaîne, facultative) correspond au séparateur des milliers (par défaut : un espace).</li>
<li>Le troisième paramètre (chaîne, facultative) correspond au caractère à afficher pour le séparateur décimal (par défaut : <code>,</code>).</li>
</ul>
Quelques exemples : <ul>
<li> - soit une variable numérique VAR_PI qui vaut <code>3,1451</code>. L'affichage par défaut <code>{ VAR_PI }</code> affichera <code>3,14</code>. L'affichage <code>{ VAR_PI:num-format(3) }</code> affichera <code>3,145</code>. </li>
<li> - pour la variable PRICE (numérique) qui vaudrait <code>9 999,99</code>, l'affichage <code>{ PRICE:num-format }</code> affichera <code>9 999,99</code> (dans ce cas le `:num-format` est facultatif). Par contre, l'affichage <code>{ PRICE:num-format(1,',', '.') }</code> affichera <code>9,999.9</code> (1 chiffre après la virgule, séparateur des milliers et décimaux modifiés).</li>
</ul>

 

<code>:join</code> : limité à une variable de liste plate (issue d'un [[Fields-Form|multiples-choices]] principalement) → permet d'afficher les différentes valeurs de la liste sous la forme suivante : <code>Valeur1, Valeur2, Valeur3, et Valeur4</code>. Les différentes valeurs contenues dans la variable sont affichées les unes à la suite des autres, séparées par des virgules; la dernière valeur est précédée de la conjonction de coordination <code>et</code>.
:: Il est possible de personnaliser le séparateur, par exemple <code>LIST:join(" ou ")</code> → renvoie <code>Valeur1 ou Valeur2 ou Valeur3</code>.
:: Et il est même possible de personnaliser indépendamment le séparateur du dernier élément grâce à un second paramètre. Exemple <code>LIST:join(" ou ", " ou bien même ")</code> → renvoie <code>Valeur1 ou Valeur2 ou bien même Valeur3</code>.

 
<code>:list</code> : '''utilisable uniquement pour les variables [[Fields-Form|multiples-choices]]''' → permet d'afficher les différentes valeurs de la liste dans le SmartDoc sous la forme d'une liste à puce; chacune des valeurs de la liste démarre une nouvelle puce
 
<code>:label</code> : dont le fonctionnement est expliqué [[SmartDoc#List-Labels|plus haut]].
 
<code>:substr(x,y)</code> : permet de tronquer une chaîne de caractères. Par exemple pour une variable PRENOM qui vaudrait "Maximilien", on pourra utiliser la notation suivante : <code>{PRENOM:substr(2,4)}</code>, qui donnera en pratique "ximi" ;


 
<code>:string-replace([remplaceur], [remplacé])</code> : permet de remplacer une chaîne par une autre chaîne dans le contenu d'une variable de type "string".
Par exemple pour une variable VAR qui vaudrait "Damien", l'expression <code>VAR:string-replace("F", "D")</code> donnera "Famien". 
Si le paramètre "remplacé" n'est pas fourni, ce sera par défaut un saut de ligne qui sera recherché. Par exemple pour une variable ADDRESS qui contient des sauts de ligne, l'expression <code>ADDRESS:string-replace(", ")</code> va remplacer chaque saut de ligne de l'adresse par <code>, </code> ce qui permet de passer un texte multi-lignes dans un format une-ligne. 
A savoir : un saut de ligne se note <code>"\n"</code>, il est donc aussi possible de remplacer, par exemple, des tirets <code>-</code> par des sauts de ligne avec l'expression <code>ADDRESS:string-replace("\n", "-")</code>.


 

<code>:default("texte par défaut")</code> permet de définir une valeur "par défaut" à afficher dans le SmartDoc si la variable sur laquelle le filtre est appliqué est vide.

<h3 id="options">Options</h3>
*<code>break</code> (facultatif) : valeur possible <code>none</code> , <code>before</code> ou <code>after</code>.
Permet d’intégrer un saut de ligne. Par défaut, toutes les entrées sont en break: after.
Si after est indiqué (ou si rien n’est indiqué puisque c’est la valeur par défaut), alors le bloc se terminera par un saut de ligne et le bloc suivant s’affichera sur une nouvelle ligne.
Si before est indiqué, l’entrée s’affiche sur une nouvelle ligne (le saut de ligne intervient avant l’entrée).
Si none est indiqué, il n’y a pas de saut de ligne, les entrées s'enchaînent.
*<code>title-level</code> (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6.
*<code>title-id</code> (facultatif) : la valeur attendue est une chaîne de caractères alpha-numériques sans sauts de ligne et dont les caractères suivants sont interdits : :, {, }, "
Cette option permet d’assigner un identifiant au titre concerné, de cette façon il sera possible de faire référence à ce titre via un “bookmark” (voir plus haut, “ajout de référence”).
Nb: cet attribut n’est possible QUE si l’attribut title-level est lui aussi renseigné.
*<code>title-article</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”.
Quand cette option est à “true”, le titre sera considéré comme un “titre d’article”. Il sera donc préfixé par "ARTICLE 1 - " ou le nombre “1” sera remplacé par l’index de l’article en question.
*<code>title-no-count</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”. Quand cette option est à “true”, le titre ne sera pas numéroté, ni dans les sommaires, ni préfixe par aucun type de numérotation.

=== Styles ===

La colonne Styles est facultative, et permet de personnaliser les styles de la ligne de contenu concernée.

Les styles sont fournies dans un format inspiré de la norme [https://www.w3schools.com/css CSS] (mais fortement simplifiée).
Ce format permet de définir plusieurs instructions stylistiques, chacune se terminant par un point-virgule (<code>;</code>) et un saut de ligne. Exemple d'une cellule dont le texte devra être en taille 18px et dans la couleur rouge (''#FF0000'' en couleur hexadécimale) :
font-size:18px;
color:#FF0000;

Chaque instruction est donc formée : d'un attribut de style (voir la liste ci-dessous), puis d'un séparateur (caractère <code>:</code>), puis de la valeur du style souhaité, et se termine par un point-virgule (<code>;</code>) et un saut de ligne.
Il est autorisé de placer un espace après le séparateur "<code>:</code>" mais attention à ce que ce espace ne soit pas "particulier" (espace insécable etc.) car cela mettrait en danger l'interprétation du style et il se peut qu'il ne soit pas du tout pris en compte.

Les instructions de styles autorisées sont :

:: '''Définir une police de caractère spécifique :'''
:::: L'attribut “<code>font-family</code>” permet de spécifier la police à utiliser.
:::: Plusieurs noms de police peuvent être proposées (dans l'ordre de priorité). Si le lecteur (navigateur, logiciel de traitement de texte…) utilisé ne supporte pas la première police, le système tentera d’utiliser la deuxième police, puis la troisième, ainsi de suite ...
:::: Exemple : <code>font-family:Times New Roman, Times;</code>
:::: Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Le cas échéant, on utilisera "Times".

:: '''Définir la taille du texte'''
:::: <code>font-size:14px;</code>
:::: Dans cet exemple, la taille du texte sera forcée à 14px.

:: '''Italique :'''
:::: <code>font-style:italic;</code>

:: '''Gras :'''
:::: <code>font-weight:bold</code>

:: '''Souligner le texte :'''
:::: <code>text-decoration:underline;</code>

:: '''Alignement :'''
:::: <code>text-align:right;</code> (aligner à droite)
:::: <code>text-align:left;</code> (aligner à gauche)
:::: <code>text-align:center</code> (centrer sur la page)
:::: <code>text-align:justify</code> (justifier)

NOTE : ''la suite est à finaliser et mettre au propre''

*Définir une bordure
<code>border: 1px #777777 solid</code>

*Choisir une couleur de fond pour le texte
<code>background-color: #FFFF00</code>
La couleur doit être indiquée au format hexadecimal
*Choisir une couleur pour le texte
<code>color: #FF0000</code>
La couleur doit être indiquée au format hexadecimal
<h3 id="refs">[[Smartdoc/titre-et-references|Les références croisées]]</h3>
Les références croisées font l'objet d'une [[Smartdoc/titre-et-references|page dédiée]].
<h3 id="visible-if">[[Conditions|Visible if]]</h3>
Ici, les [[Conditions|visible ifs]] permettront de conditionner logiquement l’apparition du texte se trouvant dans la colonne “Contenu”
Le fonctionnement est similaire au reste du système, et est détaillé dans la page relative aux [[Conditions|Visible ifs]]
<h3 id="utiliser-les-loops-boucles-">Utiliser les [[Boucles]]</h3>
Les boucles permettent de répéter un groupe d'informations autant de fois que nécessaire, cette notion est détaillée dans la [[Boucles|page correspondante]]
<h3 id="commentaire">Commentaire</h3>
Ce champ permet à celui qui paramètre de laisser toute indication utile à la compréhension de son fichier de paramétrage.
L’utilisateur final ne verra jamais ce qui est écrit dans ce champ.
<h2 id="autre">Autres fonctionnalités présentes dans le SmartDoc</h2>

SmartDoc

2022-08-30T15:49:29Z

Damien :

<h1 id="smartdoc">SmartDoc</h1>

<h2 id="introduction">Introduction</h2>
En premier lieu, un SmartDoc doit être clairement identifié par son doc-id, qui doit être strictement le même que le doc-id spécifié dans la [[DocList]]
La nouvelle feuille du [[Fichier de Paramétrage]] qui a vocation à être un SmartDoc doit donc se nommer précisément : Doc “le_doc-id”
Par exemple :
Ici, la [[DocList]] mentionne un seul SmartDoc, dont le doc-id est “demo-hercule” :
[[Fichier:DocList 1.png|frame|none|Une DocList classique]]
En conséquence, la feuille correspondante se nomme demo-hercule
[[Fichier:Capture d’écran 2019-07-24 à 11.19.59.png|frame|none]]
Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”
<h2 id="metadonn-es-datastore-options-list-labels">Metadonnées, datastore, options, list labels</h2>
[[Fichier:Smartdoc options 1.png|sans_cadre|1200px|néant]]
=== Métadonnées ===

 C'est un simple espace de commentaire 

=== DataStore ===

[[DataStore]] : C’est l'id du [[DataStore]] auquel les variables utilisées dans le document sont associées. Par défaut, mainstore.

=== Options ===

La colonne "Options" permet de définir des options relatives au document courant.
Cette cellule attend un contenu au format YAML.

==== L'option "title-num-display" ====

L'option "title-num-display" permet de définir le format d’affichage pour la numérotation de chaque titre du document.

Si cette option vaut <code>none</code> ou <code>disabled</code> les titres et les références affichées dans ce document seront "désactivées" et ne s'afficheront donc pas.

Au contraire, pour personnaliser le format de la numérotation, cette option attend une liste clés-valeurs (texte indenté, YAML), où chaque clé est un niveau de titre (de 1 à 6 inclus), et pour chaque niveau, trois attributs peuvent être saisis : <code>style</code>, <code>format</code>, et <code>format-ref</code> (voir exemple imagée ci-dessous).

Les valeurs possible pour l'attribut <code>style</code> sont :
:: - "decimal" : numérotation décimale classique en chiffre arabe (1, 2 , 3 …) ;
:: - "upper-roman" : nombre romain majuscule (I, II, III, IV etc.) ;
:: - "lower-roman" : nombre romain minuscule (i, ii, iii, iv etc.) ;
:: - "upper-alpha" : numérotation alphabétique majuscule (A, B, C, D, E) ;
:: - "lower-roman" : numérotation alphabétique minuscule (a, b, c, d...) ;
:: - "none" : aucune numérotation pour ce niveau de titre ;

L'attribut <code>format</code> attend une chaîne de caractère qui permet de représenter le contexte (préfixe, suffixe…) de la numérotation à afficher avant chaque Titre.
Cette chaîne doit contenir au moins une fois un $1, $2, $3 … $6, qui seront remplacés par la numérotation pur le niveau concerné.
L'attribut <code>format-ref</code> fonctionne de la même façon que l'attribut précédent mais il permet de représenter la numérotation à afficher dans chaque référence intégrée au sein du document (voir [[Smartdoc/titre-et-references|SmartDocument, faire une référence à un titre]]).

Ces attributs doivent contenir au moins une fois un code numéroté tel que <code>$1</code>, <code>$2</code>, <code>$3</code> … <code>$6</code>, qui permettra d'être remplacé par la numérotation du niveau concerné.

'''Exemple''' : le format “<code>$1)</code>“ s'affichera “''A)''”, "''B)''", "''C)''" etc. (s'il est combiné au style <code>"upper-alpha"</code>), ou "i)", "ii)", "iii)" (style <code>"lower-roman"</code>).

'''Autre exemple''' : “<code>Article $1.$2</code>“ s'affichera “Article 1.A”, "Article 1.B", "Article 2.A" … (combiné avec un niveau 1 au style <code>décimal</code> et un niveau 2 en <code>upper-roman</code>).

'''Exemple complet :'''
[[Fichier:Gestion des titres.png|frame|none|Gestion du format des titres]]
D'après la configuration de l'image ci-dessus, les titres :
* de niveau 1 seront de la forme : “ARTICLE 8 - Lorem ipsum”
* de niveau 2 seront de la forme : “2 Lorem ipsum ”
* de niveau 3 seront de la forme : “2-5 Lorem ipsum ”
* de niveau 4 seront de la forme : “2-5-10 Lorem ipsum ”
* de niveau 5 seront de la forme : “a. Lorem ipsum ”
* de niveau 6 seront de la forme : “ iv ) Lorem ipsum

=== List-Labels ===
Introduction
List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. Autrement dit, elle permet d'établir des "dictionnaires de correspondance" permettant de faire correspondre un libellé à une valeur.
Par exemple :
[[Fichier:List Label.png|none|frame|La gestion des List Labels]]
Une fois un List-Label préparé, il est possible de l'utiliser grâce au traitement Label
Contexte
La colonne "Choices" du `Fields-Form` vous permet de spécifier les choix qui doivent apparaitre dans le formulaire. Chaque choix :
- s'écrit sur une ligne différente, ligne qui doit se terminer par un point-virgule ;
- chaque choix s'écrit en deux parties séparées par un ":" afin d'indiquer, à gauche, la valeur à stocker en base de données (et à utiliser dans les [[Conditions|visible ifs]]) et à droite la valeur à afficher dans le formulaire. On parle de couple "valeur : libellé".
Par exemple
[[Fichier:Dg.png|thumb|none|375px]]

Mise en place
Le document n'est pas à même de décider sous quelle forme afficher la variable correspondante aux choix d'un champ de type "choix"
Si rien n'est spécifié, le document affichera ce qui est stocké dans la base de données 
Il est toutefois possible d'indiquer au document des libellés et pour cela intervient le filtre <code>:label(xxx)`</code>.
Par exemple, on peut imaginer un dictionnaire nommé "fonctions" pour indiquer que "dg" doit s'afficher "Directeur Général", et un autre dictionnaire nommé "fonctions_abrégées" qui indiquerait au contraire que "dg" doit s'afficher "Dir. G.".
Il sera alors possible, dans le contenu du SmartDoc, de faire appel au dictionnaire de votre choix :
<ul>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions")}</code></li>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions_abrégées")}</code></li>
</ul>

Les dictionnaires sont définis via la case D2 (List Labels) des onglets "Doc".
Ils sont écrits sous la forme suivante :

[[Fichier:D2.png|none|thumb|175px]]
⚠ Notez les espaces d'indentation qui permettent d'indiquer au système l'imbrication / hiérarchie de l'info. C'est à dire qu'ici, val1 et val2 appartiennent au premier dictionnaire, alors que valA et valB appartiennent au second dictionnaire. Sans cette indentation, le système ne saurait pas reconnaitre si la ligne correspond à la déclaration d'un nouveau dictionnaire ou à un couple valeur/libellé. 
→ A noter : On peut aussi utiliser un libellé référencé dans une “[[Choice-List]]”.
Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : <code>countries: @pays</code> .
On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, <code>{PAYS_NAISS:label("countries")}</code>.
La colonne A qui donne France si la variable PAYS_NAISS vaut “FR”.

<h2 id="templates-docx">Les modèles .docx</h2>

Le SmartDoc consiste à définir du "contenu dynamique", bien qu'il soit possible de définir certains styles de base (couleurs, gras, italiques, titres etc.), la mise en page du document lui même reste limitée. C'est en cela que les "modèles .docx" peuvent être utile.

Chaque SmartDoc peut se baser sur un modèle de fichier, au format .docx. Le contenu dynamique sera tout simplement "injecté" dans le document à l'endroit indiqué.
Le modèle peut, par exemple, prévoir un habillage (page de couverture, page de garde etc.), prévoir des entêtes et pieds-de-page, mais surtout, peut permettre de définir les marges du document et les styles des paragraphes et des titres (tailles, couleurs, espacement...).
Le contenu dynamique, créé au travers du SmartDoc, se retrouvera simplement injecté dans le modèle prédéfini.

'''Définir un modèle et l'associer à un ou plusieurs SmartDoc'''

Pour pouvoir utiliser un modèle, il suffit de le rajouter dans la Doc-List, en lui donnant un identifiant unique, et en indiquant le type <code>docx-template</code> (vous pouvez aussi préciser un titre, une description).

Une fois le modèle présent dans la Doc-List, il est possible de l'associer à un SmartDoc en utilisant l'option : <code>docx-template: mon-template</code>.

'''Préparer son modèle et l'injection du contenu'''

Le modèle .docx peut être préparé comme un document classique : définir les styles des titres et des paragraphes, définir les marges et les interlignes, une page de couverture et des pieds-de-pages etc.
Pour définir où le contenu dynamique devra être injecté, il faut utiliser la syntaxe suivante : <code>${ @inject all }</code>. Ainsi, l'intégralité du contenu du SmartDoc sera intégrée à cet endroit même du modèle.
Il est aussi possible de demander l'intégration d'un seul [[Blocs | bloc du SmartDoc]], en indiquant, à la place de <code>all</code>, l'identifiant du SmartDoc et le nom exact du bloc.

Par exemple, dans un SmartDoc nommé <code>contrat</code>, un bloc défini par <code>#BLOC dénomination</code>, pourra être injecté dans le modèle .docx avec la syntaxe suivante :
<pre>${ @inject contrats :: dénomination }</pre>

'''''Nb :''' notez les 2 fois 2 points (<code>::</code>) pour séparer l'identifiant du SmartDoc concerné et le nom exact du bloc à injecter.''

'''Pour aller plus loin :'''
* Vous pouvez trouver plus d'informations sur les modèles docx et sur la manière de les mettre en place sur la [[Docx-template|page dédiée du Wiki]].
* Il est parfaitement possible d'utiliser plusieurs injections dans un même modèle .docx. Il vous suffit d'utiliser plusieurs fois la syntaxe <code>${ @inject ... }</code> dans le document modèle.
* Le contenu injecté peut lui-même inclure d'autres blocs (voir [[Smartdoc/include| les "inclusions" (includes) d'un SmartDoc]]), des boucles, des titres etc.
* Dans certains cas, il peut être problématique d'injecter un bloc, lui même contenu dans [[Boucles | une boucle du SmartDoc]]. En effet, la boucle a pour conséquence de "contextualiser" la variable sur laquelle elle boucle, si vous injectez ce contenu hors de ce contexte, le SmartDoc ne saura pas comment interpréter la variable correspondante à une occurence de la boucle.

== Contenu, options, styles, [[Conditions|visible ifs]], commentaires ==

[[Fichier:SmartDoc options 2.png|1200px|sans_cadre|néant]]
<h3 id="contenu">Contenu</h3>
 Un SmartDoc est constitué d'une suite ordonnée d'[[Élément_de_contenu|éléments de contenu]]. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'éléments de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).
Le “contenu” du SmartDoc est ce qui sera effectivement “imprimé” dans le document final qui sera transmis à l’utilisateur.
Ce contenu, en plus d’être dynamique grâce au “visible-ifs” comme le reste du système, accepte aussi l’utilisation de variables.
<h4 id="bases">Bases</h4>
C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.
On peut se servir des [https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML balises HTML basiques] pour mettre en forme le texte rentré ici.
Les balises suivants sont utilisables

* a,
* br,
* b,
* strong,
* i,
* em,
* ol,
* ul,
* li,
* hr,
* span


==== Contenu spécial ou dynamique ====

Ils sont de la forme <code>{ @… }</code> et s'integre parmi le contenu.

:: — <code>{ @line-break }</code> : ajout un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : <code>{@line-break}</code> Plusieurs saut de ligne (par exemple 2) : <code>{@line-break:2}</code>

:: — <code>{@page-break</code>} : ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : <code>{@page-break}</code>.
:: Le saut de page est effectif dans les exports .docx ou .pdf, mais est simulé par une simple ligne verticale dans les prévisualisations HTML.

:: — <code>{@ref:my title id}</code> : ajout d’une référence vers un titre : comme pour intégrer une variable, il est possible d’intégrer un lien vers un titre du document (le titre peut se trouver avant ou après la référence dans le contenu). Pour intégrer une référence, il suffit d’utiliser la syntaxe <code>{@ref:my title id}</code> pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. Le fonctionnement des références croisées est décrit en détail [[Smartdoc/titre-et-references|ici]].
:::: Nb : si plusieurs titres ont le même title-id alors la référence pointe vers le premier de la page.
:::: Nb : si la référence pointe vers un titre qui n’existe pas dans le document (ou est invisible), elle sera remplacée par le texte “[référence manquante]”.
:::: Par défaut, la référence à un titre se contente d’afficher le titre (càd, le contenu du bloc titre).

:::: Une chaine de caractère étant retournée, il est possible d’appliquer les filtres classiques.
:::: Exemple : Comme décrit dans la section <code>{@ref:droit-acheteur:uppercase}</code>.
:::: Le traitement <code>:num</code> peut-être appliqué dans la syntaxe afin d’afficher la référence sous forme numérique et tenant compte des titres parents.
:::: Exemple : ''Comme décrit dans la section ''<code>{@ref:droit-acheteur:num}</code>… => ''Comme décrit dans la section '' '''3.1.1.2'''

:::: Pour les cas des références vers des titres ayant l’option title-article à “true” le nombre retourné sera simplement celui de l’article dans le cas du traitement “:num”.
:::: Pour les cas des références vers des titres ayant l’option title-no-count , le traitement “:num” n’aura alors aucun effet.

:: — <code>{@summary}</code>Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : <code>{@summary}</code>

:: — <code>{ @doc-meta(title) }</code> : permet d'insérer une méta-donnée du document courant. Les 3 paramètres possibles sont : <code>title</code>, <code>description</code>, ou <code>id</code>. Pratique, par exemple, pour citer le titre du document au sein du contenu, malgré peut-être la présence d'un clausier et de blocs injectés d'un autre document.

==== Comment rendre dynamique le contenu d'un [[SmartDoc]] ? ====

Pour rendre dynamique le contenu du SmartDoc, il est possible de lui intégrer les valeurs des variables telles qu'elles ont été collectée dans un formulaire, ou calculée via une variable dynamique etc.

La syntaxe pour intégrer un contenu dynamique est reconnaissable car il est systématiquement placé entre accolades : <code>{ … }</code>.

Une variable peut être intégrée de façon brute (Exemple : ''"Je m'appelle { PRENOM }."'').
L'affichage brut pouvant parfois être trop limitatif, une syntaxe de "traitements SmartDoc" est disponible. Par exemple, le traitement <code>:uppercase</code> appliqué sur une variable la fera afficher en majuscule. Exemple :: ''"Je m'appelle <code>{ PRENOM:uppercase }</code>."'').

<h5 id="les-primitives">Les primitives</h5>
Une primitive est un élément qui a une valeur.
Par exemple: la variable PRENOM va valoir “Damien”. Ou tout simplement un nombre (ex: 36) ou une chaine de caractère (ex: "une chaise")
Pour intégrer une valeur : les variables du dataset sont intégrées dans le contenu à partir d’une syntaxe simple : la variable est placée, sans espace, entre deux accolades.
Exemple :
Le vendeur, né le <code>{DATE_NAISSANCE}</code>, à <code>{VILLE_NAISSANCE}</code> ... 

==== Les traitements dans le SmartDoc ====

Les traitements peuvent être définies comme une modification appliquée sur un contenu. Par exemple, le traitement <code>uppercase</code> permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère. 
Pour appliquer un traitement sur une primitive, on utilise le signe : <code>:</code> Ce qui donne Mon prénom est <code>{PRENOM:uppercase}</code> qui donne Mon prénom est DAMIEN même quand la variable <code>PRENOM</code> vaut “DaMien”.
Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : <code>:</code>
Exemple :
Le vendeur s’appelle <code>{PRENOM:uppercase}</code>
Il est possible d'enchaîner les traitements. 
Exemple :L'acheteur a payé <code>{PRIX:letters:uppercase}</code> euros.
Ici, la valeur contenue dans la variable "PRIX" sera d'abord convertie en lettres, puis mise automatiquement en MAJUSCULES.
On obtiendra un résultat du type : "L'acheteur a payé TRENTE euros", alors que la valeur de départ sera "30".
A noter : les traitements peuvent s’appliquer aussi sur de simples chaînes de caractères et pas seulement des variables. Ex : L'acheteur a payé {"32 000":letters:uppercase} euros.

==== Traitements disponibles et syntaxe spécifique ====

<code>:uppercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en majuscule
 
<code>:lowercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en minuscule
 
<code>:letters</code> : ne s'applique que sur une valeur numérique, et permet de la convertir en "toutes-lettres" (ex : <code>312</code> => <code>Trois-cent-douze</code>).
 
<code>:capitalize</code> : ne s'applique que sur une chaine de caractères, et permet de passer en majuscule la première lettre de chaque mot. Ex: <code>NOM:capitalize</code> 
Option : si l'option 1 (ou "yes") est passée en paramètre de ce traitement, alors seule la première lettre du premier mot sera mise en majuscule. Ex: <code>NOM:capitalize(1)</code> , <code>NOM:capitalize(yes)</code>… 
 
<code>:img</code> : transforme une chaine de caractère (url) en image dans le document. Ex : <code>{"https://api.memegen.link/images/puffin.jpg":img}</code> va permettre d'intégrer l'image présente à cette URL dans le document.
 Nb: dans les version v0.9-v0.11 l'intégration d'une image distante (via <code>:img</code>) n'est plus possible dans les exports .docx / .pdf si un modèle de document (voir docx template) est utilisé. En effet, la norme DocX ne permet pas/plus l'intégration d'image / objet si le fichier est créé par un TemplateEngine.

 
<code>:num</code>: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre.
Exemple : </code>Comme décrit dans la section {@ref:droit-acheteur:num}, vous...</code>. Le fonctionnement des références croisées est décrit en détail [[http://wiki.hercule.co:3002/index.php/Smartdoc/titre-et-references|ici]]
 
<code>:french-datetime</code> : ne s'applique que sur une date ou une chaîne de caractère au format "Date". Ce traitement permet de transformer la date au format "30/12/1985 à 12h45".
 
<code>:french-date</code> : ne s'applique que sur une date ou une chaîne de caractère au format "YYYY-MM-DD" (format international). Ce traitement permet de transformer la date fournie dans le format Français "jj/mm/aaaa". Depuis la version v0.10, ce filtre est "facultatif" car il est appliqué par défaut sur les dates ou les chaînes au format de date. 
 
<code>:num-format</code> : ne s'applique que sur une valeur numérique, et permet de la formater pour son affichage. Ce traitement peut prendre 3 paramètres '''facultatifs'''. 
<ul>
<li>Le 1er permet (numérique et facultatif) permet d'indiquer le nombre de décimale souhaitées (par défaut, 2 chiffres ou 0 si la partie décimale est nulle).</li>
<li>Le second paramètre (chaîne, facultative) correspond au séparateur des milliers (par défaut : un espace).</li>
<li>Le troisième paramètre (chaîne, facultative) correspond au caractère à afficher pour le séparateur décimal (par défaut : <code>,</code>).</li>
</ul>
Quelques exemples : <ul>
<li> - soit une variable numérique VAR_PI qui vaut <code>3,1451</code>. L'affichage par défaut <code>{ VAR_PI }</code> affichera <code>3,14</code>. L'affichage <code>{ VAR_PI:num-format(3) }</code> affichera <code>3,145</code>. </li>
<li> - pour la variable PRICE (numérique) qui vaudrait <code>9 999,99</code>, l'affichage <code>{ PRICE:num-format }</code> affichera <code>9 999,99</code> (dans ce cas le `:num-format` est facultatif). Par contre, l'affichage <code>{ PRICE:num-format(1,',', '.') }</code> affichera <code>9,999.9</code> (1 chiffre après la virgule, séparateur des milliers et décimaux modifiés).</li>
</ul>

 

<code>:join</code> : limité à une variable de liste plate (issue d'un [[Fields-Form|multiples-choices]] principalement) → permet d'afficher les différentes valeurs de la liste sous la forme suivante : <code>Valeur1, Valeur2, Valeur3, et Valeur4</code>. Les différentes valeurs contenues dans la variable sont affichées les unes à la suite des autres, séparées par des virgules; la dernière valeur est précédée de la conjonction de coordination <code>et</code>.
:: Il est possible de personnaliser le séparateur, par exemple <code>LIST:join(" ou ")</code> → renvoie <code>Valeur1 ou Valeur2 ou Valeur3</code>.
:: Et il est même possible de personnaliser indépendamment le séparateur du dernier élément grâce à un second paramètre. Exemple <code>LIST:join(" ou ", " ou bien même ")</code> → renvoie <code>Valeur1 ou Valeur2 ou bien même Valeur3</code>.

 
<code>:list</code> : '''utilisable uniquement pour les variables [[Fields-Form|multiples-choices]]''' → permet d'afficher les différentes valeurs de la liste dans le SmartDoc sous la forme d'une liste à puce; chacune des valeurs de la liste démarre une nouvelle puce
 
<code>:label</code> : dont le fonctionnement est expliqué [[SmartDoc#List-Labels|plus haut]].
 
<code>:substr(x,y)</code> : permet de tronquer une chaîne de caractères. Par exemple pour une variable PRENOM qui vaudrait "Maximilien", on pourra utiliser la notation suivante : <code>{PRENOM:substr(2,4)}</code>, qui donnera en pratique "ximi" ;


 
<code>:string-replace([remplaceur], [remplacé])</code> : permet de remplacer une chaîne par une autre chaîne dans le contenu d'une variable de type "string".
Par exemple pour une variable VAR qui vaudrait "Damien", l'expression <code>VAR:string-replace("F", "D")</code> donnera "Famien". 
Si le paramètre "remplacé" n'est pas fourni, ce sera par défaut un saut de ligne qui sera recherché. Par exemple pour une variable ADDRESS qui contient des sauts de ligne, l'expression <code>ADDRESS:string-replace(", ")</code> va remplacer chaque saut de ligne de l'adresse par <code>, </code> ce qui permet de passer un texte multi-lignes dans un format une-ligne. 
A savoir : un saut de ligne se note <code>"\n"</code>, il est donc aussi possible de remplacer, par exemple, des tirets <code>-</code> par des sauts de ligne avec l'expression <code>ADDRESS:string-replace("\n", "-")</code>.


 

<code>:default("texte par défaut")</code> permet de définir une valeur "par défaut" à afficher dans le SmartDoc si la variable sur laquelle le filtre est appliqué est vide.

<h3 id="options">Options</h3>
*<code>break</code> (facultatif) : valeur possible <code>none</code> , <code>before</code> ou <code>after</code>.
Permet d’intégrer un saut de ligne. Par défaut, toutes les entrées sont en break: after.
Si after est indiqué (ou si rien n’est indiqué puisque c’est la valeur par défaut), alors le bloc se terminera par un saut de ligne et le bloc suivant s’affichera sur une nouvelle ligne.
Si before est indiqué, l’entrée s’affiche sur une nouvelle ligne (le saut de ligne intervient avant l’entrée).
Si none est indiqué, il n’y a pas de saut de ligne, les entrées s'enchaînent.
*<code>title-level</code> (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6.
*<code>title-id</code> (facultatif) : la valeur attendue est une chaîne de caractères alpha-numériques sans sauts de ligne et dont les caractères suivants sont interdits : :, {, }, "
Cette option permet d’assigner un identifiant au titre concerné, de cette façon il sera possible de faire référence à ce titre via un “bookmark” (voir plus haut, “ajout de référence”).
Nb: cet attribut n’est possible QUE si l’attribut title-level est lui aussi renseigné.
*<code>title-article</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”.
Quand cette option est à “true”, le titre sera considéré comme un “titre d’article”. Il sera donc préfixé par "ARTICLE 1 - " ou le nombre “1” sera remplacé par l’index de l’article en question.
*<code>title-no-count</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”. Quand cette option est à “true”, le titre ne sera pas numéroté, ni dans les sommaires, ni préfixe par aucun type de numérotation.

=== Styles ===

La colonne Styles est facultative, et permet de personnaliser les styles de la ligne de contenu concernée.

Les styles sont fournies dans un format inspiré de la norme [https://www.w3schools.com/css CSS] (mais fortement simplifiée).
Ce format permet de définir plusieurs instructions stylistiques, chacune se terminant par un point-virgule (<code>;</code>) et un saut de ligne. Exemple d'une cellule dont le texte devra être en taille 18px et dans la couleur rouge (''#FF0000'' en couleur hexadécimale) :
font-size:18px;
color:#FF0000;

Chaque instruction est donc formée : d'un attribut de style (voir la liste ci-dessous), puis d'un séparateur (caractère <code>:</code>), puis de la valeur du style souhaité, et se termine par un point-virgule (<code>;</code>) et un saut de ligne.
Il est autorisé de placer un espace après le séparateur "<code>:</code>" mais attention à ce que ce espace ne soit pas "particulier" (espace insécable etc.) car cela mettrait en danger l'interprétation du style et il se peut qu'il ne soit pas du tout pris en compte.

Les instructions de styles autorisées sont :

:: '''Définir une police de caractère spécifique :'''
:::: L'attribut “<code>font-family</code>” permet de spécifier la police à utiliser.
:::: Plusieurs noms de police peuvent être proposées (dans l'ordre de priorité). Si le lecteur (navigateur, logiciel de traitement de texte…) utilisé ne supporte pas la première police, le système tentera d’utiliser la deuxième police, puis la troisième, ainsi de suite ...
:::: Exemple : <code>font-family:Times New Roman, Times;</code>
:::: Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Le cas échéant, on utilisera "Times".

:: '''Définir la taille du texte'''
:::: <code>font-size:14px;</code>
:::: Dans cet exemple, la taille du texte sera forcée à 14px.

:: '''Italique :'''
:::: <code>font-style:italic;</code>

:: '''Gras :'''
:::: <code>font-weight:bold</code>

:: '''Souligner le texte :'''
:::: <code>text-decoration:underline;</code>

:: '''Alignement :'''
:::: <code>text-align:right;</code> (aligner à droite)
:::: <code>text-align:left;</code> (aligner à gauche)
:::: <code>text-align:center</code> (centrer sur la page)
:::: <code>text-align:justify</code> (justifier)

NOTE : ''la suite est à finaliser et mettre au propre''

*Définir une bordure
<code>border: 1px #777777 solid</code>

*Choisir une couleur de fond pour le texte
<code>background-color: #FFFF00</code>
La couleur doit être indiquée au format hexadecimal
*Choisir une couleur pour le texte
<code>color: #FF0000</code>
La couleur doit être indiquée au format hexadecimal
<h3 id="refs">[[Smartdoc/titre-et-references|Les références croisées]]</h3>
Les références croisées font l'objet d'une [[Smartdoc/titre-et-references|page dédiée]].
<h3 id="visible-if">[[Conditions|Visible if]]</h3>
Ici, les [[Conditions|visible ifs]] permettront de conditionner logiquement l’apparition du texte se trouvant dans la colonne “Contenu”
Le fonctionnement est similaire au reste du système, et est détaillé dans la page relative aux [[Conditions|Visible ifs]]
<h3 id="utiliser-les-loops-boucles-">Utiliser les [[Boucles]]</h3>
Les boucles permettent de répéter un groupe d'informations autant de fois que nécessaire, cette notion est détaillée dans la [[Boucles|page correspondante]]
<h3 id="commentaire">Commentaire</h3>
Ce champ permet à celui qui paramètre de laisser toute indication utile à la compréhension de son fichier de paramétrage.
L’utilisateur final ne verra jamais ce qui est écrit dans ce champ.
<h2 id="autre">Autres fonctionnalités présentes dans le SmartDoc</h2>

SmartDoc

2022-07-05T17:40:37Z

Damien : /* Styles */

<h1 id="smartdoc">SmartDoc</h1>

<h2 id="introduction">Introduction</h2>
En premier lieu, un SmartDoc doit être clairement identifié par son doc-id, qui doit être strictement le même que le doc-id spécifié dans la [[DocList]]
La nouvelle feuille du [[Fichier de Paramétrage]] qui a vocation à être un SmartDoc doit donc se nommer précisément : Doc “le_doc-id”
Par exemple :
Ici, la [[DocList]] mentionne un seul SmartDoc, dont le doc-id est “demo-hercule” :
[[Fichier:DocList 1.png|frame|none|Une DocList classique]]
En conséquence, la feuille correspondante se nomme demo-hercule
[[Fichier:Capture d’écran 2019-07-24 à 11.19.59.png|frame|none]]
Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”
<h2 id="metadonn-es-datastore-options-list-labels">Metadonnées, datastore, options, list labels</h2>
[[Fichier:Smartdoc options 1.png|sans_cadre|1200px|néant]]
<h3 id="Métadonnées">Métadonnées</h3>
 C'est un simple espace de commentaire 
<h3 id="Datastore">DataStore</h3>
[[DataStore]] : C’est l'id du [[DataStore]] auquel les variables utilisées dans le document sont associées. Par défaut, mainstore.
<h3 id="title-num-display">Options - title-num-display</h3>
title-num-display : cette colonne permet de définir le format d’affichage pour la numérotation de chaque titre du document. Cette option attend un tableau, où chaque clé est un niveau de titre (de 1 à 6 inclus), et pour chaque niveau, deux attributs à configurer : style et format .
Les valeurs possible pour les attributs style sont :
"upper-roman" : nombre romain majuscule (I, II, III, IV etc...)
"decimal" : numérotation décimale / chiffres arabes (1, 2 , 3 ...)
"lower-roman" : nombre romain minuscule (i, ii, iii, iv etc.)
"lower-alpha” : numérotation alphabétique minuscule (a, b, c, d...)
"upper-alpha" : numérotation alphabétique majuscule (A, B, C, D, E)
En ce qui concerne l’attributs format :
Il attend une chaîne de caractère dans laquelle $1, $2, $3 … $6 seront remplacés par la numérotation (au style attribué).
Exemple : “Article $1.$2” peut donner “Article 3.a”.
Exemple complet :
[[Fichier:Gestion des titres.png|frame|none|Gestion du format des titres]]
Où les titres :
de niveau 1 seront de la forme : “ARTICLE 8 - Lorem ipsum”
de niveau 2 seront de la forme : “2 Lorem ipsum ”
de niveau 3 seront de la forme : “2-5 Lorem ipsum ”
de niveau 4 seront de la forme : “2-5-10 Lorem ipsum ”
de niveau 5 seront de la forme : “a. Lorem ipsum ”
de niveau 6 seront de la forme : “ iv ) Lorem ipsum”
<h3 id="List-Labels">List-Labels</h3>
Introduction
List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. Autrement dit, elle permet d'établir des "dictionnaires de correspondance" permettant de faire correspondre un libellé à une valeur.
Par exemple :
[[Fichier:List Label.png|none|frame|La gestion des List Labels]]
Une fois un List-Label préparé, il est possible de l'utiliser grâce au traitement Label
Contexte
La colonne "Choices" du `Fields-Form` vous permet de spécifier les choix qui doivent apparaitre dans le formulaire. Chaque choix :
- s'écrit sur une ligne différente, ligne qui doit se terminer par un point-virgule ;
- chaque choix s'écrit en deux parties séparées par un ":" afin d'indiquer, à gauche, la valeur à stocker en base de données (et à utiliser dans les [[Conditions|visible ifs]]) et à droite la valeur à afficher dans le formulaire. On parle de couple "valeur : libellé".
Par exemple
[[Fichier:Dg.png|thumb|none|375px]]

Mise en place
Le document n'est pas à même de décider sous quelle forme afficher la variable correspondante aux choix d'un champ de type "choix"
Si rien n'est spécifié, le document affichera ce qui est stocké dans la base de données 
Il est toutefois possible d'indiquer au document des libellés et pour cela intervient le filtre <code>:label(xxx)`</code>.
Par exemple, on peut imaginer un dictionnaire nommé "fonctions" pour indiquer que "dg" doit s'afficher "Directeur Général", et un autre dictionnaire nommé "fonctions_abrégées" qui indiquerait au contraire que "dg" doit s'afficher "Dir. G.".
Il sera alors possible, dans le contenu du SmartDoc, de faire appel au dictionnaire de votre choix :
<ul>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions")}</code></li>
<li>- M. Dupond occupant le poste de <code>{VARFONCT:label("
fonctions_abrégées")}</code></li>
</ul>

Les dictionnaires sont définis via la case D2 (List Labels) des onglets "Doc".
Ils sont écrits sous la forme suivante :

[[Fichier:D2.png|none|thumb|175px]]
⚠ Notez les espaces d'indentation qui permettent d'indiquer au système l'imbrication / hiérarchie de l'info. C'est à dire qu'ici, val1 et val2 appartiennent au premier dictionnaire, alors que valA et valB appartiennent au second dictionnaire. Sans cette indentation, le système ne saurait pas reconnaitre si la ligne correspond à la déclaration d'un nouveau dictionnaire ou à un couple valeur/libellé. 
→ A noter : On peut aussi utiliser un libellé référencé dans une “[[Choice-List]]”.
Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : <code>countries: @pays</code> .
On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, <code>{PAYS_NAISS:label("countries")}</code>.
La colonne A qui donne France si la variable PAYS_NAISS vaut “FR”.

<h2 id="templates-docx">Les modèles .docx</h2>

Le SmartDoc consiste à définir du "contenu dynamique", bien qu'il soit possible de définir certains styles de base (couleurs, gras, italiques, titres etc.), la mise en page du document lui même reste limitée. C'est en cela que les "modèles .docx" peuvent être utile.

Chaque SmartDoc peut se baser sur un modèle de fichier, au format .docx. Le contenu dynamique sera tout simplement "injecté" dans le document à l'endroit indiqué.
Le modèle peut, par exemple, prévoir un habillage (page de couverture, page de garde etc.), prévoir des entêtes et pieds-de-page, mais surtout, peut permettre de définir les marges du document et les styles des paragraphes et des titres (tailles, couleurs, espacement...).
Le contenu dynamique, créé au travers du SmartDoc, se retrouvera simplement injecté dans le modèle prédéfini.

'''Définir un modèle et l'associer à un ou plusieurs SmartDoc'''

Pour pouvoir utiliser un modèle, il suffit de le rajouter dans la Doc-List, en lui donnant un identifiant unique, et en indiquant le type <code>docx-template</code> (vous pouvez aussi préciser un titre, une description).

Une fois le modèle présent dans la Doc-List, il est possible de l'associer à un SmartDoc en utilisant l'option : <code>docx-template: mon-template</code>.

'''Préparer son modèle et l'injection du contenu'''

Le modèle .docx peut être préparé comme un document classique : définir les styles des titres et des paragraphes, définir les marges et les interlignes, une page de couverture et des pieds-de-pages etc.
Pour définir où le contenu dynamique devra être injecté, il faut utiliser la syntaxe suivante : <code>${ @inject all }</code>. Ainsi, l'intégralité du contenu du SmartDoc sera intégrée à cet endroit même du modèle.
Il est aussi possible de demander l'intégration d'un seul [[Blocs | bloc du SmartDoc]], en indiquant, à la place de <code>all</code>, l'identifiant du SmartDoc et le nom exact du bloc.

Par exemple, dans un SmartDoc nommé <code>contrat</code>, un bloc défini par <code>#BLOC dénomination</code>, pourra être injecté dans le modèle .docx avec la syntaxe suivante :
<pre>${ @inject contrats :: dénomination }</pre>

'''''Nb :''' notez les 2 fois 2 points (<code>::</code>) pour séparer l'identifiant du SmartDoc concerné et le nom exact du bloc à injecter.''

'''Pour aller plus loin :'''
* Vous pouvez trouver plus d'informations sur les modèles docx et sur la manière de les mettre en place sur la [[Docx-template|page dédiée du Wiki]].
* Il est parfaitement possible d'utiliser plusieurs injections dans un même modèle .docx. Il vous suffit d'utiliser plusieurs fois la syntaxe <code>${ @inject ... }</code> dans le document modèle.
* Le contenu injecté peut lui-même inclure d'autres blocs (voir [[Smartdoc/include| les "inclusions" (includes) d'un SmartDoc]]), des boucles, des titres etc.
* Dans certains cas, il peut être problématique d'injecter un bloc, lui même contenu dans [[Boucles | une boucle du SmartDoc]]. En effet, la boucle a pour conséquence de "contextualiser" la variable sur laquelle elle boucle, si vous injectez ce contenu hors de ce contexte, le SmartDoc ne saura pas comment interpréter la variable correspondante à une occurence de la boucle.

== Contenu, options, styles, [[Conditions|visible ifs]], commentaires ==

[[Fichier:SmartDoc options 2.png|1200px|sans_cadre|néant]]
<h3 id="contenu">Contenu</h3>
 Un SmartDoc est constitué d'une suite ordonnée d'[[Élément_de_contenu|éléments de contenu]]. Dans la feuille du tableur de paramétrage, il faut créer autant de ligne que d'éléments de contenu dynamique. On défini un nouvel élément pour lui associer une condition de visibilité spécifique (ex : car cet élément ne doit pas s'afficher dans certains cas), ou on veut lui associer un "style" spécifique (ex : mettre une partie du paragraphe en couleur rouge).
Le “contenu” du SmartDoc est ce qui sera effectivement “imprimé” dans le document final qui sera transmis à l’utilisateur.
Ce contenu, en plus d’être dynamique grâce au “visible-ifs” comme le reste du système, accepte aussi l’utilisation de variables.
<h4 id="bases">Bases</h4>
C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.
On peut se servir des [https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML balises HTML basiques] pour mettre en forme le texte rentré ici.
Les balises suivants sont utilisables

* a,
* br,
* b,
* strong,
* i,
* em,
* ol,
* ul,
* li,
* hr,
* span


==== Contenu spécial ou dynamique ====

Ils sont de la forme <code>{ @… }</code> et s'integre parmi le contenu.

:: — <code>{ @line-break }</code> : ajout un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : <code>{@line-break}</code> Plusieurs saut de ligne (par exemple 2) : <code>{@line-break:2}</code>

:: — <code>{@page-break</code>} : ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : <code>{@page-break}</code>.
:: Le saut de page est effectif dans les exports .docx ou .pdf, mais est simulé par une simple ligne verticale dans les prévisualisations HTML.

:: — <code>{@ref:my title id}</code> : ajout d’une référence vers un titre : comme pour intégrer une variable, il est possible d’intégrer un lien vers un titre du document (le titre peut se trouver avant ou après la référence dans le contenu). Pour intégrer une référence, il suffit d’utiliser la syntaxe <code>{@ref:my title id}</code> pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. Le fonctionnement des références croisées est décrit en détail [[Smartdoc/titre-et-references|ici]].
:::: Nb : si plusieurs titres ont le même title-id alors la référence pointe vers le premier de la page.
:::: Nb : si la référence pointe vers un titre qui n’existe pas dans le document (ou est invisible), elle sera remplacée par le texte “[référence manquante]”.
:::: Par défaut, la référence à un titre se contente d’afficher le titre (càd, le contenu du bloc titre).

:::: Une chaine de caractère étant retournée, il est possible d’appliquer les filtres classiques.
:::: Exemple : Comme décrit dans la section <code>{@ref:droit-acheteur:uppercase}</code>.
:::: Le traitement <code>:num</code> peut-être appliqué dans la syntaxe afin d’afficher la référence sous forme numérique et tenant compte des titres parents.
:::: Exemple : ''Comme décrit dans la section ''<code>{@ref:droit-acheteur:num}</code>… => ''Comme décrit dans la section '' '''3.1.1.2'''

:::: Pour les cas des références vers des titres ayant l’option title-article à “true” le nombre retourné sera simplement celui de l’article dans le cas du traitement “:num”.
:::: Pour les cas des références vers des titres ayant l’option title-no-count , le traitement “:num” n’aura alors aucun effet.

:: — <code>{@summary}</code>Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : <code>{@summary}</code>

:: — <code>{ @doc-meta(title) }</code> : permet d'insérer une méta-donnée du document courant. Les 3 paramètres possibles sont : <code>title</code>, <code>description</code>, ou <code>id</code>. Pratique, par exemple, pour citer le titre du document au sein du contenu, malgré peut-être la présence d'un clausier et de blocs injectés d'un autre document.

==== Comment rendre dynamique le contenu d'un [[SmartDoc]] ? ====

Pour rendre dynamique le contenu du SmartDoc, il est possible de lui intégrer les valeurs des variables telles qu'elles ont été collectée dans un formulaire, ou calculée via une variable dynamique etc.

La syntaxe pour intégrer un contenu dynamique est reconnaissable car il est systématiquement placé entre accolades : <code>{ … }</code>.

Une variable peut être intégrée de façon brute (Exemple : ''"Je m'appelle { PRENOM }."'').
L'affichage brut pouvant parfois être trop limitatif, une syntaxe de "traitements SmartDoc" est disponible. Par exemple, le traitement <code>:uppercase</code> appliqué sur une variable la fera afficher en majuscule. Exemple :: ''"Je m'appelle <code>{ PRENOM:uppercase }</code>."'').

<h5 id="les-primitives">Les primitives</h5>
Une primitive est un élément qui a une valeur.
Par exemple: la variable PRENOM va valoir “Damien”. Ou tout simplement un nombre (ex: 36) ou une chaine de caractère (ex: "une chaise")
Pour intégrer une valeur : les variables du dataset sont intégrées dans le contenu à partir d’une syntaxe simple : la variable est placée, sans espace, entre deux accolades.
Exemple :
Le vendeur, né le <code>{DATE_NAISSANCE}</code>, à <code>{VILLE_NAISSANCE}</code> ... 

==== Les traitements dans le SmartDoc ====

Les traitements peuvent être définies comme une modification appliquée sur un contenu. Par exemple, le traitement <code>uppercase</code> permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère. 
Pour appliquer un traitement sur une primitive, on utilise le signe : <code>:</code> Ce qui donne Mon prénom est <code>{PRENOM:uppercase}</code> qui donne Mon prénom est DAMIEN même quand la variable <code>PRENOM</code> vaut “DaMien”.
Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : <code>:</code>
Exemple :
Le vendeur s’appelle <code>{PRENOM:uppercase}</code>
Il est possible d'enchaîner les traitements. 
Exemple :L'acheteur a payé <code>{PRIX:letters:uppercase}</code> euros.
Ici, la valeur contenue dans la variable "PRIX" sera d'abord convertie en lettres, puis mise automatiquement en MAJUSCULES.
On obtiendra un résultat du type : "L'acheteur a payé TRENTE euros", alors que la valeur de départ sera "30".
A noter : les traitements peuvent s’appliquer aussi sur de simples chaînes de caractères et pas seulement des variables. Ex : L'acheteur a payé {"32 000":letters:uppercase} euros.

==== Traitements disponibles et syntaxe spécifique ====

<code>:uppercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en majuscule
 
<code>:lowercase</code> : ne s'applique que sur une chaine de caractères, et permet de forcer l’affichage de la chaîne en minuscule
 
<code>:letters</code> : ne s'applique que sur une valeur numérique, et permet de la convertir en "toutes-lettres" (ex : <code>312</code> => <code>Trois-cent-douze</code>).
 
<code>:capitalize</code> : ne s'applique que sur une chaine de caractères, et permet de passer en majuscule la première lettre de chaque mot. Ex: <code>NOM:capitalize</code> 
Option : si l'option 1 (ou "yes") est passée en paramètre de ce traitement, alors seule la première lettre du premier mot sera mise en majuscule. Ex: <code>NOM:capitalize(1)</code> , <code>NOM:capitalize(yes)</code>… 
 
<code>:img</code> : transforme une chaine de caractère (url) en image dans le document. Ex : <code>{"https://api.memegen.link/images/puffin.jpg":img}</code> va permettre d'intégrer l'image présente à cette URL dans le document.
 Nb: dans les version v0.9-v0.11 l'intégration d'une image distante (via <code>:img</code>) n'est plus possible dans les exports .docx / .pdf si un modèle de document (voir docx template) est utilisé. En effet, la norme DocX ne permet pas/plus l'intégration d'image / objet si le fichier est créé par un TemplateEngine.

 
<code>:num</code>: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre.
Exemple : </code>Comme décrit dans la section {@ref:droit-acheteur:num}, vous...</code>. Le fonctionnement des références croisées est décrit en détail [[http://wiki.hercule.co:3002/index.php/Smartdoc/titre-et-references|ici]]
 
<code>:french-datetime</code> : ne s'applique que sur une date ou une chaîne de caractère au format "Date". Ce traitement permet de transformer la date au format "30/12/1985 à 12h45".
 
<code>:french-date</code> : ne s'applique que sur une date ou une chaîne de caractère au format "YYYY-MM-DD" (format international). Ce traitement permet de transformer la date fournie dans le format Français "jj/mm/aaaa". Depuis la version v0.10, ce filtre est "facultatif" car il est appliqué par défaut sur les dates ou les chaînes au format de date. 
 
<code>:num-format</code> : ne s'applique que sur une valeur numérique, et permet de la formater pour son affichage. Ce traitement peut prendre 3 paramètres '''facultatifs'''. 
<ul>
<li>Le 1er permet (numérique et facultatif) permet d'indiquer le nombre de décimale souhaitées (par défaut, 2 chiffres ou 0 si la partie décimale est nulle).</li>
<li>Le second paramètre (chaîne, facultative) correspond au séparateur des milliers (par défaut : un espace).</li>
<li>Le troisième paramètre (chaîne, facultative) correspond au caractère à afficher pour le séparateur décimal (par défaut : <code>,</code>).</li>
</ul>
Quelques exemples : <ul>
<li> - soit une variable numérique VAR_PI qui vaut <code>3,1451</code>. L'affichage par défaut <code>{ VAR_PI }</code> affichera <code>3,14</code>. L'affichage <code>{ VAR_PI:num-format(3) }</code> affichera <code>3,145</code>. </li>
<li> - pour la variable PRICE (numérique) qui vaudrait <code>9 999,99</code>, l'affichage <code>{ PRICE:num-format }</code> affichera <code>9 999,99</code> (dans ce cas le `:num-format` est facultatif). Par contre, l'affichage <code>{ PRICE:num-format(1,',', '.') }</code> affichera <code>9,999.9</code> (1 chiffre après la virgule, séparateur des milliers et décimaux modifiés).</li>
</ul>

 

<code>:join</code> : limité à une variable de liste plate (issue d'un [[Fields-Form|multiples-choices]] principalement) → permet d'afficher les différentes valeurs de la liste sous la forme suivante : <code>Valeur1, Valeur2, Valeur3, et Valeur4</code>. Les différentes valeurs contenues dans la variable sont affichées les unes à la suite des autres, séparées par des virgules; la dernière valeur est précédée de la conjonction de coordination <code>et</code>.
:: Il est possible de personnaliser le séparateur, par exemple <code>LIST:join(" ou ")</code> → renvoie <code>Valeur1 ou Valeur2 ou Valeur3</code>.
:: Et il est même possible de personnaliser indépendamment le séparateur du dernier élément grâce à un second paramètre. Exemple <code>LIST:join(" ou ", " ou bien même ")</code> → renvoie <code>Valeur1 ou Valeur2 ou bien même Valeur3</code>.

 
<code>:list</code> : '''utilisable uniquement pour les variables [[Fields-Form|multiples-choices]]''' → permet d'afficher les différentes valeurs de la liste dans le SmartDoc sous la forme d'une liste à puce; chacune des valeurs de la liste démarre une nouvelle puce
 
<code>:label</code> : dont le fonctionnement est expliqué [[SmartDoc#List-Labels|plus haut]].
 
<code>:substr(x,y)</code> : permet de tronquer une chaîne de caractères. Par exemple pour une variable PRENOM qui vaudrait "Maximilien", on pourra utiliser la notation suivante : <code>{PRENOM:substr(2,4)}</code>, qui donnera en pratique "ximi" ;


 
<code>:string-replace([remplaceur], [remplacé])</code> : permet de remplacer une chaîne par une autre chaîne dans le contenu d'une variable de type "string".
Par exemple pour une variable VAR qui vaudrait "Damien", l'expression <code>VAR:string-replace("F", "D")</code> donnera "Famien". 
Si le paramètre "remplacé" n'est pas fourni, ce sera par défaut un saut de ligne qui sera recherché. Par exemple pour une variable ADDRESS qui contient des sauts de ligne, l'expression <code>ADDRESS:string-replace(", ")</code> va remplacer chaque saut de ligne de l'adresse par <code>, </code> ce qui permet de passer un texte multi-lignes dans un format une-ligne. 
A savoir : un saut de ligne se note <code>"\n"</code>, il est donc aussi possible de remplacer, par exemple, des tirets <code>-</code> par des sauts de ligne avec l'expression <code>ADDRESS:string-replace("\n", "-")</code>.


 

<code>:default("texte par défaut")</code> permet de définir une valeur "par défaut" à afficher dans le SmartDoc si la variable sur laquelle le filtre est appliqué est vide.

<h3 id="options">Options</h3>
*<code>break</code> (facultatif) : valeur possible <code>none</code> , <code>before</code> ou <code>after</code>.
Permet d’intégrer un saut de ligne. Par défaut, toutes les entrées sont en break: after.
Si after est indiqué (ou si rien n’est indiqué puisque c’est la valeur par défaut), alors le bloc se terminera par un saut de ligne et le bloc suivant s’affichera sur une nouvelle ligne.
Si before est indiqué, l’entrée s’affiche sur une nouvelle ligne (le saut de ligne intervient avant l’entrée).
Si none est indiqué, il n’y a pas de saut de ligne, les entrées s'enchaînent.
*<code>title-level</code> (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6.
*<code>title-id</code> (facultatif) : la valeur attendue est une chaîne de caractères alpha-numériques sans sauts de ligne et dont les caractères suivants sont interdits : :, {, }, "
Cette option permet d’assigner un identifiant au titre concerné, de cette façon il sera possible de faire référence à ce titre via un “bookmark” (voir plus haut, “ajout de référence”).
Nb: cet attribut n’est possible QUE si l’attribut title-level est lui aussi renseigné.
*<code>title-article</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”.
Quand cette option est à “true”, le titre sera considéré comme un “titre d’article”. Il sera donc préfixé par "ARTICLE 1 - " ou le nombre “1” sera remplacé par l’index de l’article en question.
*<code>title-no-count</code> (facultatif) : valeur booléenne attendue. Par défaut, la valeur est “false”. Quand cette option est à “true”, le titre ne sera pas numéroté, ni dans les sommaires, ni préfixe par aucun type de numérotation.

=== Styles ===

La colonne Styles est facultative, et permet de personnaliser les styles de la ligne de contenu concernée.

Les styles sont fournies dans un format inspiré de la norme [https://www.w3schools.com/css CSS] (mais fortement simplifiée).
Ce format permet de définir plusieurs instructions stylistiques, chacune se terminant par un point-virgule (<code>;</code>) et un saut de ligne. Exemple d'une cellule dont le texte devra être en taille 18px et dans la couleur rouge (''#FF0000'' en couleur hexadécimale) :
font-size:18px;
color:#FF0000;

Chaque instruction est donc formée : d'un attribut de style (voir la liste ci-dessous), puis d'un séparateur (caractère <code>:</code>), puis de la valeur du style souhaité, et se termine par un point-virgule (<code>;</code>) et un saut de ligne.
Il est autorisé de placer un espace après le séparateur "<code>:</code>" mais attention à ce que ce espace ne soit pas "particulier" (espace insécable etc.) car cela mettrait en danger l'interprétation du style et il se peut qu'il ne soit pas du tout pris en compte.

Les instructions de styles autorisées sont :

:: '''Définir une police de caractère spécifique :'''
:::: L'attribut “<code>font-family</code>” permet de spécifier la police à utiliser.
:::: Plusieurs noms de police peuvent être proposées (dans l'ordre de priorité). Si le lecteur (navigateur, logiciel de traitement de texte…) utilisé ne supporte pas la première police, le système tentera d’utiliser la deuxième police, puis la troisième, ainsi de suite ...
:::: Exemple : <code>font-family:Times New Roman, Times;</code>
:::: Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Le cas échéant, on utilisera "Times".

:: '''Définir la taille du texte'''
:::: <code>font-size:14px;</code>
:::: Dans cet exemple, la taille du texte sera forcée à 14px.

:: '''Italique :'''
:::: <code>font-style:italic;</code>

:: '''Gras :'''
:::: <code>font-weight:bold</code>

:: '''Souligner le texte :'''
:::: <code>text-decoration:underline;</code>

:: '''Alignement :'''
:::: <code>text-align:right;</code> (aligner à droite)
:::: <code>text-align:left;</code> (aligner à gauche)
:::: <code>text-align:center</code> (centrer sur la page)
:::: <code>text-align:justify</code> (justifier)

NOTE : ''la suite est à finaliser et mettre au propre''

*Définir une bordure
<code>border: 1px #777777 solid</code>

*Choisir une couleur de fond pour le texte
<code>background-color: #FFFF00</code>
La couleur doit être indiquée au format hexadecimal
*Choisir une couleur pour le texte
<code>color: #FF0000</code>
La couleur doit être indiquée au format hexadecimal
<h3 id="refs">[[Smartdoc/titre-et-references|Les références croisées]]</h3>
Les références croisées font l'objet d'une [[Smartdoc/titre-et-references|page dédiée]].
<h3 id="visible-if">[[Conditions|Visible if]]</h3>
Ici, les [[Conditions|visible ifs]] permettront de conditionner logiquement l’apparition du texte se trouvant dans la colonne “Contenu”
Le fonctionnement est similaire au reste du système, et est détaillé dans la page relative aux [[Conditions|Visible ifs]]
<h3 id="utiliser-les-loops-boucles-">Utiliser les [[Boucles]]</h3>
Les boucles permettent de répéter un groupe d'informations autant de fois que nécessaire, cette notion est détaillée dans la [[Boucles|page correspondante]]
<h3 id="commentaire">Commentaire</h3>
Ce champ permet à celui qui paramètre de laisser toute indication utile à la compréhension de son fichier de paramétrage.
L’utilisateur final ne verra jamais ce qui est écrit dans ce champ.
<h2 id="autre">Autres fonctionnalités présentes dans le SmartDoc</h2>