SmartDoc

SmartDoc

WIP

Introduction

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 (voir ici)

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” <img src="/capture_d’écran_2019-07-15_à_17.00.59.png" alt="capture_d’écran_2019-07-15_à_17.00.59.png">

En conséquence, la feuille correspondante se nomme demo-hercule <img src="/capture_d’écran_2019-07-15_à_17.01.27.png" alt="capture_d’écran_2019-07-15_à_17.01.27.png">

Quant aux colonnes détaillées ci-dessous, elles doivent toutes obligatoirement être remplies, à l’exception de la colonne D “List Labels”

Metadonnées, datastore, options, list labels

• Métadonnées : ? Simple espace de commentaire ?
• Datastore : C’est le DataStore auquel les variables utilisées dans le document sont associées
• 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 : <img src="/capture_d’écran_2019-07-18_à_14.04.14.png" alt="capture_d’écran_2019-07-18_à_14.04.14.png">

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”

• List-Labels : cette colonne permet d’effectuer une conversion entre des choix d’une variable de type “choices” du SmartForm et le SmartDoc. L’utilisation des List Labels nécessite préalablement de savoir comment utiliser des <a href="#variables">variables</a> et comment leur appliquer un traitement dans un SmartDoc.

Par exemple : <img src="/capture_d’écran_2019-07-18_à_14.20.46.png" alt="capture_d’écran_2019-07-18_à_14.20.46.png">

Ici, le label “genre” s’adresse à une variable qui peut prendre deux valeurs en fonction de la réponse de l’utilisateur : M. ou Mme. .

Grâce à l’utilisation d’un List Label, si la réponse de l’utilisateur est “M.”, le système affichera “un homme” dans le document final. Concrètement, il faudra appeler la variable avec par exemple {CIVILITÉ:labels("genre")} qui donne UN HOMME si la variable CIVILITÉ vaut M. . A noter : On peut aussi utiliser un libellé référencé dans une “Choices-List”. Par exemple, il est possible de créer un List Label nommé “countries” qu’on configurerait de la manière suivante : countries: @pays .

On peut alors l’utiliser de la même façon au sein d’un document avec, par exemple, {PAYS_NAISS:labels("pays")} qui donne France si la variable PAYS_NAISS vaut “FR”. Contenu

Contenu, options, styles, visible if, commentaires

Contenu

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.

En ce sens, on distingue le contenu “fixe”, qui ne fait pas appel aux variables et qui constitue la majorité du contenu, du contenu faisant appel aux variables.

Ici, la cellule contient une phrase au contenu fixe, seule une date doit changer en fonction d’une date de signature, c’est là qu’on appelle le contenu de la variable {DATELIMITESIGNATURE}

Le contenu fixe

WIP

C’est ici qu’il faut entrer le contenu “brut” du texte : c’est-à-dire le corps du texte.

On peut se servir de <a href="https://developer.mozilla.org/fr/docs/Apprendre/Commencer_avec_le_web/Les_bases_HTML">balises HTML basiques</a> pour mettre en forme le texte rentré ici.

Est-ce qu'on détaille balises HTML basiques : ol, ul, etc ... ?

Le contenu variable <a name="variables"></a>

La syntaxe dynamique à l’intérieur du contenu des SmartDoc est dans un format propre à Hercule, et se distingue du reste du texte car elle est entre { et }.

Il est possible d’utiliser les variables de deux manières : en “primitive” ou en appliquant un traitement qu’on appelle une “fonction”.

Les primitives

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 {DATE_NAISSANCE}, à {VILLE_NAISSANCE} ...

Les fonctions

Les fonctions peuvent être définies comme un traitement appliqué sur une primitive. Par exemple, la fonction uppercase permet de mettre en majuscule une primitive de catégorie chaîne-de-caractère.

Pour appliquer une fonction sur une primitive, on utilise le signe : : Ce qui donne Mon prénom est {PRENOM:uppercase} qui donne Mon prénom est DAMIEN même quand la variable PRENOM vaut “DaMien”.

Comme vu précédemment, pour intégrer une valeur avec un traitement, on procède en utilisant : :

Exemple : Le vendeur s’appelle {PRENOM:uppercase}

Il est possible d'enchaîner les traitements.

Exemple : L'acheteur a payé {PRIX:letters:uppercase} 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.

Liste des fonctions intégrés

Pour l’instant, les traitements intégrés sont :

:uppercase : force l’affichage d’une chaîne en majuscule :lowercase : force l’affichage d’une chaîne en minuscule :letters : uniquement pour les variables de type numérique. Converti une variable numérique en toutes-lettres. Il est possible de chaîner les traitements. :capitalize : force la majuscule sur la première lettre de chaque mot :img : transforme une chaine de caractère (url) en image dans le document. Exemple : {"<a href="http://www.gouache.com/logo.png%22:img}">http://www.gouache.com/logo.png%22:img}</a> :num: (uniquement pour les références). Pour une référence à un titre, affiche son numéro au lieu d’afficher le titre. Exemple : Comme décrit dans la section {@ref:droit-acheteur:num}, vous... :french-date : force la valeur d’une variable de date à s’afficher au format jj/mm/aaaa. :french-datetime : force la valeur d’une variable de date à s’afficher au format 30/12/1985 à 12h45. :letters : force la valeur d’une variable numérique à s’afficher en toutes lettres.

Ajout d’un saut de ligne : il est possible de forcer un saut de ligne (ou plusieurs) en utilisant la syntaxe suivante dans un contenu HTML : {@line-break}
Plusieurs saut de ligne (par exemple 2) : {@line-break:2}

Ajout d’un saut de page : il est possible de forcer un saut de page en utilisant la syntaxe suivante dans un contenu HTML : {@page-break}. 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.

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 {@ref:my title id} pour laquelle “my title id” correspond à l’attribut title-id d’un bloc-titre existant dans le document. 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. Ex: Exemple : Comme décrit dans la section {@ref:droit-acheteur:uppercase},

Le traitement “:num” 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 {@ref:droit-acheteur:num}, vous... devient : Comme décrit dans la section 3.1.1.2, vous …

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.

Ajout d’un sommaire automatique : il est possible d’ajouter un sommaire automatique au document (table of contents) en utilisant la syntaxe suivante : {@summary} Lors d’un export Word ou PDF, le sommaire doit être capable d’afficher les numéros de pages en face de chaque entrée (voir <a href="http://phpword.readthedocs.io/en/latest/elements.html#table-of-contents">http://phpword.readthedocs.io/en/latest/elements.html#table-of-contents</a>). Lors d’une prévisualisation HTML, les numéros de page ne sont plus nécessaires, par contre, les entrées du menu doivent fonctionner comme des “ancres” vers les titres concernées (ce sont donc des liens).

Options

break (facultatif) : valeur possible none , before ou after. 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.

title-level (facultatif) : valeurs possibles : 1, 2, 3, 4, 5, 6. Afin d’assurer un parfaite conversion avec les titres Word (Pdf etc.), une gestion propre des “sommaires” etc. les balises h1, h2, h*, sont interdites.

title-id (facultatif) : la valeur attendu 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é. Nb2 : cet attribut peut se retrouver sur plusieurs titres à la fois dans le document.

title-article (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.

title-no-count (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 traiter différemment le contenu de la ligne concernée.

A chaque traitement utilisé, on retournera à la ligne après avoir écrit un ;

Définir la police :

Le traitement “font-family” permet de spécifier la police utilisée.

Ce traitement peut prévoir plusieurs polices, comme un système à plusieurs détentes : si le navigateur 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 :

font-family: Times New Roman, Times, serif; Dans cet exemple, on prévoit d’utiliser Times New Roman en priorité. Si le navigateur ne supporte pas cette police, on cherchera à afficher une police de la famille “Times”. Enfin, si rien de tout cela ne marche, on cherchera à afficher une police de type “Serif”

Définir la taille de la police :

font-size: XXpt; On remplacera XX par la taille de police souhaitée

Mettre en gras/italique/souligné

Mettre en gras : font-weight: bold,

Mettre en italique : font-style: italic;

Souligner le texte : text-decoration: underline;

Définir une bordure

border: 1px #777777 solid

Aligner le texte

text-align: right text-align: left text-align: center text-align: justify

Choisir une couleur de fond pour le texte

background-color: #FFFF00

La couleur doit être indiquée au format hexadecimal

Choisir une couleur pour le texte

color: #FF0000

La couleur doit être indiquée au format hexadecimal

Visible if

Ici, les Visible if 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 <a href="http://wiki.hercule.co/Conditions">conditions</a>

Utiliser les loops (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 <a href="http://wiki.hercule.co/loops">page associée</a>

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.