Twig

Le Twig est un format de modélisation d'HTML à partir de données dynamiques.
Sa documentation technique est accessible sur ce lien : https://twig.symfony.com/doc/2.x/templates.html.

Les pages web dynamiques, qui peuvent être créées au format Twig dans yoprocess, sont en réalité un cumul de diverses technologies pré-packagées ensemble : le moteur Twig pour le traitement de la donnée dynamique, du HTML pour la structure de la page, des class CSS pré-définies sur YoProcess etc.

Penses-bête

Voici quelques explications sur les classes CSS et éléments HTML élémentaires qui peuvent être utilisées lors de la création d'une page web dynamique.

La grille

La grille HTML permet de placer les éléments les uns à côté des autres (ligne et colonne) de façon à construire la structure de la page en prenant en compte une adaptabilité automatique selon la taille de la fenêtre du navigateur ou l'appareil (mobile, tablette etc.). La grille est indiquée en plaçant une classe `grid` sur un élément HTML (ex : <div class="grid">).

À l'intérieur de cet élément, il est possible de définir des rangées, et chacune d'elle peut contenir une ou plusieurs colonnes. Une rangée est définie par la classe row (ex : <div class="row">).

À l'intérieur de l'élément correspondant à une rangée, une colonne est définie par un élément HTML cell-? ou le ? est un nombre de 1 à 12 inclus. Chaque rangée est constituée de 12 unités de largeur.

Exemple de deux colonnes de mêmes tailles :

<div class="row">
   <div class="cell-6">Ma colonne 1</div>
   <div class="cell-6">Ma colonne 2</div>
</div>

Nb : la somme des éléments cell- d'une rangée doit toujours valoir 12 unités.

Le responsive : la grille permet de gérer automatiquement la "responsiveness" des éléments de la page. Par exemple, un bloc `cell-6` occupera la moitié (6/12) de l'espace sur un écran normal, mais sera extrapolé pour utiliser 100% de l'espace sur un écran plus petit, faisant passer les blocs suivants en dessous. Il est possible d'utiliser les classes d'ordination de Material Web Components Layout, de la forme layout-grid__cell--order-<INDEX> pour indiquer l'ordre d'un élément par rapport à un autre lors des réorganisations automatiques dûes à la taille de l'écran (ex : des colonnes qui passent les unes en dessous des autres).

Les classes CSS pré-définies

De nombreuses classes sont pré-définies et permettent de styliser les divers éléments de la page web dynamique. Voici les plus élémentaires :

• surface elv1 : permet de passer le fond d'un élément en blanc et de rajouter les ombrages correspondant à une "élévation" basse. Ces deux classes sont utilisées pour créer le typique bloc blanc de contenu.

• m-? ou p-? : permet de définir en pixel les 4 marges CSS d'un élément (margin = marge externe, padding = marge interne). Le ? peut être remplacée par un nombre parmi ceux de la liste suivante : 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 12, 13, 15, 16, 17, 20, 24, 25, 30, 35.

• mt-?, pb-? (variantes top / bottom / left / right) : pour modifier seulement 1 des marges d'un éléments il suffit d'accoler un "t" (top), un "b" (bottom), un "l" (left), ou un "r" (right), au "m" (margin) ou au "p" (padding) tel que défini précédemment. Ex : mt-16 rajoutera une marge supérieure de 16px. Autre exemple : p-0 pr-8 indique que les 4 marges internes sont nulles (0px) sauf la marge de droite qui prend 8px.

• text-center : permet de centrer le texte dans un bloc. Variantes existantes : text-justify, text-left, text-right.

• bold, italic, underline, uppercase : leur nom est explicite, ils sont cumulables sur un même élément.

• grey-text, warning-text, danger-text, info-text, success-text, primary-text : passe le texte dans la couleur correspondante. Respectivement : gris, orange, rouge, bleu, vert, et couleur-par-défaut de l'application (ex : sur YoProcess, le bleu Yo).

Intégrer des SmartDocs

Certains bouts de code Twig (helpers) ont été prévus pour facilement intégrer un lien vers les options de téléchargement des SmartDocs.

Exemple : intégration d'un bandeau SmartDoc avec options par défaut de téléchargement pdf et docx

Exemple d'intégration d'un SmartDoc dans une page web dynamique (modèle Twig)

  {% 
    include '@helpers/doc-row.html.twig' with {
       doc_id: 'contrat-travail',
       doc_name: "Contrat de travail"
    } 
  %}

Exemple : intégration d'un smartdoc avec des options facultatives

   {% 
      include '@helpers/doc-row.html.twig' with {
        doc_id: 'contrat-travail',
        doc_name: "Contrat de travail",
        formats: ['pdf'],
        separator: 'none',
        custom_class: 'pt-24'
      } 
   %}

• "doc_id" : permet de spécifier l'identifiant sur SmartDoc à intégrer dans la page web dynamique. (obligatoire)
• "doc_name" : permet de spécifier le nom d'affichage du document. (obligatoire)
• "formats" : permet de spécifier sous forme d'un tableau le ou les formats de téléchargement à afficher parmi "pdf" et "docx". Par défaut : ['pdf', 'docx']
• "separator" : permet d'indiquer si un séparateur horizontal doit s'afficher. 3 options possibles : "bottom" (l'afficher au dessous), "top" (l'afficher au dessus), et "none" (ne pas l'afficher). Valeur par défaut : "bottom"
• "custom_class" : permet de spécifier des classes CSS à rajouter sur l'élément. Pratique pour par exemple rajouter des paddings et gérer automatiquement l'espacement entre chaque bandeau de SmartDoc. Option facultative, avec aucune valeur par défaut.

Intégrer des conditions

@TODO / @TOCOMPLETE

Le format Twig permet d'intégrer des conditions, à l'instar d'un Fichier de Paramétrage.

Néanmoins, la syntaxe n'est pas tout à fait la même.

Base syntaxique

On ouvrira une condition de la manière suivante :

   {% if (CONDITION) %}

On fermera sa condition de la manière suivante :

   {% endif %}

Il est aussi possible d'utiliser l'expression suivante ("sinon") pour gérer tous les cas non prévus dans la condition initiale :

  
   {% else %} 

Précisions

Pour mettre au point une condition, il est possible d'utiliser tout type de Dynvar ou de Variable.

On notera que le signe = doit toujours s'écrire en double : ==

Par exemple :

   {% if (CIVILITE == "Monsieur" %}
<p>Vous êtes un homme</p>
   {% endif %}

Concernant les contains, les conditions doivent être formées légèrement différemment

La syntaxe à adopter sera la suivante :

   {% if ("Valeur" in VARIABLE) %}
<p>Vous êtes un homme</p>
   {% endif %}

Par exemple :

   {% if ("Chasse" in HOBBIES) %}
<p>Vous êtes un chasseur</p>
   {% endif %}

Intégrer une liste de SmartDocs

@TODO / @TOCOMPLETE

Ex :

   {% 
      include '@helpers/smartdocs-list.html.twig' with {
        formats: ['pdf'],
        separator: 'none',
        custom_class: 'pt-24',
        exclude: ['contrat-machin'] 
      } 
   %}

Intégrer des pièces uploadées

Afficher un bandeau de téléchargement d'une pièce PDF uploadée via un SmartForm :

  {% include '@helpers/form-attachment-row.html.twig' with {
      att_name: "Pièce d'identité",
      form_id: 'infos_employee',
      form_field_id: 'pieces.infos.area-0.ID_RECTO'
  } %}

• "att_name" : permet d'indiquer le libellé de la pièce. (obligatoire)
• "form_id" : permet d'indiquer l'identifiant du SmartForm concerné. (obligatoire)
• "form_field_id" : permet d'indiquer le chemin d'identification du champ de formulaire (obligatoire)

Intégrer des SmartForms

@TODO / @TOCOMPLETE

Renvoyer vers le sommaire du formulaire qui a débouché sur la page-web-dynamique (twig) actuelle, en vue-externe : Nb : le formulaire sera en "lecture seule" s'il a été soumis.

  {{ path("shared_sf_summary", { token: token.token, open: 1} ) }}

• L'option "open" est facultative, si elle est précisé et qu'elle a une valeur "truthy" (ex : 1), alors le sommaire du formulaire sera visible en "tout ouvert" par défaut.

Renvoyer vers le formulaire spécifié, en conservant le type d'accès actuel (externe, connecté etc.) : @TODO

  {{ smartform_link("default", { open: 1, path: "employer.infos" } ) }}