25 mars 2025, 10:36:04

Elysa Jouve

Implémentation et utilisation des macros Freemarker dans les templates

Le rendu des macros par framework est visible sur le style Guide BO.

Table des matières

Les macros

Les macros visent à remplacer le code HTML dans le but de réduire la maintenance et de faciliter les migrations à d’autres frameworks CSS. Elles contiennent une présentation homogène et cohérente pensée pour l’ensemble des pages du back-office, de ce fait, leur usage est réservé au back office.

Les macros ressemblent à du HTML pour que cela reste lisible, mais aussi à du HTML avec classes Bootstrap puisqu’elles ont été écrites initialement pour fonctionner avec ce framework CSS. Certains noms de macros font donc référence à des composants Bootstrap. Pour plus d’informations sur ces composants, veuillez consulter la documentation.

Beaucoup de paramètres de macros correspondent simplement aux attributs HTML du même nom (name, id, title, type, href, class, action…).

D’autres paramètres font appel à des fonctions et permettent d’ajouter des classes pour répondre à des besoins de présentation :

hide=['all'|'xs','sm','md','lg','xl'] : Ce paramètre permet de spécifier la visibilité d’un élément. Soit on le cache pour tous les breakpoints (‘all’), soit on le cache pour certains breakpoints (xs, sm, md, lg, ou xl).
align='left|right|center' : permet de gérer l’alignement d’un élément dans la page.

Enfin, ce paramètre permet d’ajouter d’autres attributs :

params : permet d’ajouter d’autres éléments non inclus dans les paramètres de la macro pour plus de souplesse.

Ces paramètres se retrouvent communément dans la plupart des macros.

Structure de la page

Sans onglets

{@pageContainer
    {@pageColumn
        {@pageHeader title=''} 
            Boutons d'action
        {/pageHeader}
        Contenu la page
    {/pageColumn}
{/pageContainer}

La macro columns inclut la possibilité d’utiliser le système de grilles du framework CSS avec les paramètres xs, sm, md, lg et xl. Les paramètres de type offset permettent de décaler les colonnes sur la grille.

Avec onglets

{@pageContainer
    {@pageColumn
        {@pageHeader title=''} 
            Boutons d'action
        {/pageHeader}
        {@tabs
            {@tabList
                {@tabLink href='panel1' active=true title='' /}
                {@tabLink href='panel2' title='' /}
            {/tabList}
            {@tabContent
                {@tabPanel id='panel1' active=true}
                    ...
                {/tabPanel}
                {@tabPanel id='panel2'}
                    ...
                {/tabPanel}
            {/tabContent}
        {/tabs}
    {/pageColumn}
{/pageContainer}

Lignes et colonnes

Le système de grilles est utilisable avec les macros de la façon suivante :

row pour une nouvelle ligne
columns pour les colonnes avec les valeurs correspondant aux breakpoints (de 1 à 12 colonnes) avec les paramètres xs, sm, md, lg et xl prenant des valeurs de 1 à 12 ainsi que des paramètres offset pour décaler les colonnes.

{@row
    {@columns
        ...
    {/columns}
{@row}

Formulaires

Le formulaire

La macro tform sert à afficher les éléments de type form.

Paramètres :

type : horizontal ou inline

La macro fieldSet permet de grouper les champs et incorpore la légende de chaque groupe.

{@tform method='post' action=''
   {@fieldSet legend=''} ... {/fieldSet}
...
{/tform}

Les éléments de formulaires

Tous les éléments de formulaire doivent être inclus dans des conteneurs formGroup :

{@formGroup labelFor='' labelKey='' helpKey=''
    Ici l'élément de formulaire
{/formGroup}

labelFor fait référence à l’attribut name du type de champ inclus dans le formGroup (indispensable pour cocher un bouton radio ou une case à cocher en cliquant sur le label par exemple), labelKey correspond au contenu du label du champ, et helpKey contient le texte d’aide du champ.

Le paramètre mandatory est hérité par le champ enfant, auquel sera automatiquement ajouté l’attribut required. Une astérisque sera également ajoutée au label pour indiquer visuellement le caractère obligatoire du champ.

L’attribut groupStyle de la macro formGroup permet d’ajouter dynamiquement une classe au champ, après soumission du formulaire, afin de représenter son état d’erreur ou de succès, par exemple.

Input text, search, password, email, file, number, hidden

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='text' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='search' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='password' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='email' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='file' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='number' name='' id='' value='' /}
{/formGroup}
{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='hidden' name='' id='' value='' /}
{/formGroup}

Input date, datetime, daterange, time

Input date

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='date' name='' id='' value='' /}
{/formGroup}

Input datetime

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='datetime' name='' id='' value='' /}
{/formGroup}

Input time

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='time' name='' id='' value='' /}
{/formGroup}

Input time avec limites :

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='time' name='' id='' value='' minTime='16:00' maxTime='22:30' /}
{/formGroup}

Input time avec une valeur par défaut :

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='time' name='' id='' value='' defaultDate='13:45' /}
{/formGroup}

Ranges

C’est un plugin de FlatPickr qui fournit cette fonctionnalité (js/admin/bootstrap-flatpickr-rangePlugin.js).

Input daterange

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='daterange' dateRangeEndId='' name='' id='' value='' /}
{/formGroup}

Le paramètre dateRangeEndId doit être renseigné sur le premier champ date, rien pour le second (qui peut même être de type text).

Input datetimerange

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='datetimerange' name='' id='' value='' /}
{/formGroup}

Textarea

{@formGroup labelFor='' labelKey='' helpKey=''
    {@input type='textarea' name='' id='' value='' /}
{/formGroup}

Select

Toutes les macros combo doivent être remplacées par la macro select qui couvre les différents cas d’usage des anciennes macros combo.

Select avec liste de valeurs

{@select name='page_template_code' id='page_template_code'
    {@hashmark;list pages_list as key, value
        <option value="${key}">${value}</option>
    {/hashmark;list}
{/select}

{@select name='order_id' id='order_id-${group.id?html}' default_value=group.order?string items=order_list sort=true size='sm' /}

Select avec contenu HTML uniquement

{@select id='status' name='status'
    {@hashmark;if default_user_status = 1
        <option value="0">Activé</option>
        <option value="1" selected="selected">Désactivé</option>
    {@hashmark;else
        <option value="0" selected="selected">Activé</option>
        <option value="1">Désactivé</option>
    {/hashmark;if}
{/select}

Checkbox

{@checkBox labelFor='status1' labelKey='Status' name='status' id='status1' value='1' /}

Le paramètre labelFor doit correspondre à l’ID de la checkbox.

Radio button

{@radioButton labelFor='form_id' labelKey='Form' name='form' id='form_id' value='2' /}

Le paramètre labelFor doit correspondre à l’ID du bouton radio.

Boutons

Button

Exemple de bouton de validation simple d’un formulaire :

{@button type='submit' title='Modifier' buttonIcon='check' /}

Exemple de bouton Annuler :

{@button type='submit' name='cancel' value='cancel' buttonIcon='times' title='Annuler' cancel=true size='' /}

Paramètres :

Le paramètre cancel ajoute l’attribut formnovalidate au bouton ainsi qu’une couleur différente d’un bouton de soumission du formulaire.
Le paramètre formId permet de lier le bouton au formulaire dans le cas où, pour des besoins de présentation, le bouton se trouverait à l’extérieur du formulaire.
Le paramètre buttonTargetId permet de lier un bouton de type button à un autre élément de la page (un div, par exemple) afin d’utiliser les fonctionnalités JavaScript de type collapse ou remove.

aButton

Cette macro représente un lien simple sous la forme d’un bouton, avec la classe associée.

{@aButton href='jsp/admin/AdminLogin.jsp' title='Annuler' buttonIcon='close' /}

{@aButton href='jsp/admin/features/RemoveExternalFeature.jsp?external_feature_id=${external_feature.id}' title='Supprimer' hideTitle=['all'] buttonIcon='trash' color='danger' size='sm' /}

Groupes d’éléments ou de boutons

inputGroup

Cette macro et sa sous-macro inputGroupItem permettent de grouper un champ et un bouton (sous forme de bouton ou de texte). Le bouton peut être placé à gauche ou à droite en fonction de si on place inputGroupItem avant ou après le champ.

{@inputGroup
    {@input type='text' /}
    {@inputGroupItem
        {@button type='submit' /}
    {/inputGroupItem}
{/inputGroup}

btnGroup

Cette macro permet de grouper des boutons.

{@btnGroup
    {@button type='button' /}
    {@button type='submit' /}
    {@aButton href='' /}
{/btnGroup}

Composants dynamiques

Accordéon

{@accordionContainer id='PARENT_ID'
    {@accordionPanel collapsed=true childId='CHILD_ID'
        {@accordionHeader title='Header Title' id='HEADER_ID' parentId='PARENT_ID' /}
        {@accordionBody
            Contenu
        {/accordionBody}
    {/accordionPanel}
{/accordionContainer}

Exemple d’accordéon avec une liste :

{@accordionContainer id='accordion'
    {@hashmark;list groups_list as group
        {@accordionPanel collapsed=true childId='${group.id}_child'
            {@accordionHeader title='${group.name}' id='${group.id}_header' /}
            {@accordionBody
                <p>${group.description}</p>
            {/accordionBody}
        {/accordionPanel}
    {/hashmark;list}
{/accordionContainer}

Notes :

Le paramètre childId de la macro accordionPanel correspond à l’ID de l’élément collapsable accordionBody. L’ID de l’élément lui est ajouté par la macro.

Boutons collapse/expand

Les styles possibles sont card-control collapse et card-control remove.

Bouton collapse

{@button type='button' title='Button' style='card-control collapse' buttonTargetId='#example' buttonIcon='minus' size='sm' /}