17 févr. 2022, 16:38:57

Elysa Jouve

Lutece v6 : Macros Freemarker pour le back-office

Table des matières

Introduction

En vue de faciliter la migration des templates en cas de changement de framework ou de version de framework CSS, de nouvelles macros ont été développées pour le back-office. Celles-ci visent notamment à faciliter le passage à Bootstrap 4 dans les mois à venir. Les nouvelles macros ont également pour but de permettre plus de modularité dans leur utilisation.

Les anciennes macros (< v5)

Les macros suivantes existent toujours dans commons.html pour assurer la transition entre les anciennes et les nouvelles macros, mais devront être remplacées progressivement au fur et à mesure de la migration :

comboWithParams (remplacée par select)
comboSortedWithParams (remplacée par select)
comboWithParamsAndLength (remplacée par select)
combo (remplacée par select)
fieldInputText (remplacée par formGroup + input)
fieldInputPassword (remplacée par formGroup + input)
fieldTextArea (remplacée par formGroup + input)
fieldInputWrapper (remplacée par formGroup)
fieldStaticText (remplacée par formGroup + staticText)
fieldInputCalendar (remplacée par formGroup + inputGroup + inputGroupItem)
fieldInputCheckBox (remplacée par formGroup + checkBox)
fieldInputRadioBox (remplacée par formGroup + radioButton)
fieldInputCheckBoxInline (remplacée par formGroup + checkBox)
fieldInputRadioBoxInline (remplacée par formGroup + radioButton)
fieldInputCombo (remplacée par formGroup + select)
boxSized (remplacée par box)
rowBox (remplacée par row + columns + box)
rowBoxHeader (remplacée par boxHeader)
headerButtons (remplacée par la saisie de paramètres dans boxHeader)
table (réécrite)
td (réécrite)

Les macros suivantes restent pour le moment inchangées :

radioImageList
checkboxList
sort
pagination
paginationAdmin
paginationPageLinks
paginationCombo
paginationItemCount
item_navigation
dataTable
filterPanel
messages
tableHeadBodySeparator

Les macros réécrites

Boutons

actionButtons : réécrite pour utiliser les nouvelles macros

Les nouvelles macros

Lignes et colonnes

row

Pour créer une nouvelle ligne qui contiendra les colonnes. Les marges négatives du composant row (-15px à gauche et à droite) permettent de conserver l’alignement.

Rendu HTML :

<div class="row"></div>

Appel de la macro :

<@row></@row>

Macro :

<#macro row class='' id='' params=''>
    <div class="row<#if class!==''><#${class}></#if>
        <#if id!=='')> id="${id}"></#if>
        <#if params!=='')>${params}</#if>
        <#nested/>
    </div>
</#macro>

Paramètres :

class (string)
id (string)
params (permet d’ajouter d’autres attributs)

columns

Le système de 12 colonnes de Bootstrap permet de répartir son contenu et de le rendre responsive (voir la documentation de Bootstrap). Les colonnes sont contenues dans un row.

Rendu HTML :

<div class="col-xs-12 col-sm-12 col-md-12 col-lg-12">
    <p>Your content here...</p>
</div>

Appel de la macro :

<@columns>
    <p>Your content here...</p>
</@columns>

Macro :

<#macro columns offsetXs=0 offsetSm=0 offsetMd=0 offsetLg=0 offsetXl=0 pushXs=0 pushSm=0 pushMd=0 pushLg=0 pushXl=0 pullXs=0 pullSm=0 pullMd=0 pullLg=0 pullXl=0 xs=12 sm=0 md=0 lg=0 xl=0 id='' class='' params=''>
    <div class="col-xs-${xs}<#if sm!=0> col-sm-${sm}</#if><#if md!=0> col-md-${md}</#if><#if lg!=0> col-lg-${lg}</#if><#if xl!=0> col-xl-${xl}</#if><#if offsetXs!=0> col-xs-offset-${offsetXs}</#if><#if offsetSm!=0> col-sm-offset-${offsetSm}</#if><#if offsetMd!=0> col-md-offset-${offsetMd}</#if><#if offsetLg!=0> col-lg-offset-${offsetLg}</#if><#if offsetXl!=0> col-xl-offset-${offsetXl}</#if><#if pushXs!=0> col-xs-push-${pushXs}</#if><#if pushSm!=0> col-sm-push-${pushSm}</#if><#if pushMd!=0> col-md-push-${pushMd}</#if><#if pushLg!=0> col-lg-push-${pushLg}</#if><#if pushXl!=0> col-xl-push-${pushXl}</#if><#if pullXs!=0> col-xs-pull-${pullXs}</#if><#if pullSm!=0> col-sm-pull-${pullSm}</#if><#if pullMd!=0> col-md-pull-${pullMd}</#if><#if pullLg!=0> col-lg-pull-${pullLg}</#if><#if pullXl!=0> col-xl-pull-${pullXl}</#if>">
        <#nested/>
    </div>
</#macro>

Paramètres :

xs (int) : nombre de colonnes à afficher (mobile). Par défaut 12
sm (int) : nombre de colonnes à afficher (tablette). Par défaut 0
md (int) : nombre de colonnes à afficher (tablette/petit écran desktop). Par défaut 0
lg (int) : nombre de colonnes à afficher (grand écran desktop). Par défaut 0
xl (int) : nombre de colonnes à afficher (très grand écran desktop). Par défaut 0
offsetXs, offsetSm, offsetMd, offsetLg, offsetXl (int) : spécifie le décalage de l’élément sur la grille
pushXs, pushSm, pushMd, pushLg, pushXl, pullXs, pullSm, pullMd, pullLg, pullXl (int) : réarrange l’ordre des colonnes (voir : Reorder CSS Columns Using Bootstrap)
id (string)
class (string)
params (permet d’ajouter d’autres attributs)

Tableaux

table

HTML :

<div class="table-responsive">
    <table>
        <tr>
            <td>Your text here...</td>
        </tr>
    </table>
</div>

Appel de la macro :

<@table>
    <tr>
        <td>Your text here...</td>
    </tr>
</@table>

Macro :

<#macro table responsive=true class='' id='' params=''>
    <#if responsive><div class="table-responsive"></#if>
    <table class="table table-hover table-condensed<#if class!==''> ${class}</#if>" id="${id}">
        <#nested/>
    </table>
    <#if responsive></div></#if>
</#macro>

Paramètres :

responsive (boolean)
class (string) : pour des classes supplémentaires ex : ‘table-striped’, ‘table-bordered’. Les classes ‘table-hover’ et ‘table-condensed’ sont incluses par défaut.
id (string)
params (permet d’ajouter d’autres attributs)

td

HTML :

<td></td>

Appel de la macro :

<@td></@td>

Macro :

<#macro td xs=0 sm=0 md=0 lg=0 xl=0 class='' id='' params=''>
    <td class="<#if xs!=0>col-xs-${xs}</#if><#if sm!=0> col-sm-${sm}</#if><#if md!=0> col-md-${md}</#if><#if lg!=0> col-lg-${lg}</#if><#if xl!=0> col-xl-${xl}</#if><#if class!=''> ${class}</#if>" id="${id}" <#if params!=''>${params}</#if>>
        <#nested/>
    </td>
</#macro>

Paramètres :

xs (int)
sm (int)
md (int)
lg (int)
xl (int)
class (string)
id (string)
params (permet d’ajouter d’autres attributs)

Formulaires

tform

Rendu HTML :

<form class="form-horizontal" method="post" role="form">
    ...
</form>

Appel de la macro :

<@tform>
    ...
</@tform>

Macro :

<#macro tform class='form-horizontal' class2='' action='' method='post' name='' id='' role='form' params=''>
    <form class="${class}<#if class2!=''> ${class2}</#if>" id="${id}" <#if action!=''>action="${action}"</#if> method="${method}" role="${role}" <#if params!=''>${params}</#if>>
        <#nested/>
    </form>
</#macro>

Paramètres :

class2 (string) : ‘form-inline’, ‘navbar-form’, ‘navbar-left’, ‘search-form’…
action (string)
method (string) : par défaut ‘post’
name (string)
id (string)
role (string) : par défaut ‘form’
params (string) : (permet d’ajouter d’autres attributs)

Composants de formulaires

formGroup

Rendu HTML :

<div class="form-group">
    ...
</div>

Appel de la macro :

<@formGroup>
    ...
</@formGroup>

Macro :

<#macro formGroup formStyle='horizontal' class='' groupStyle='' rows=1 labelKey='' labelFor='' labelId='' helpKey='' id='' mandatory=false showLabel=true params=''>
    <div class="form-group<#if groupStyle!=''> has-${groupStyle} has-feedback</#if><#if class!=''> ${class}</#if>" id="${id}" <#if params!=''>${params}</#if>>
        <#if rows=1>
            <#if labelKey!='' && formStyle='horizontal'>
                <#assign labelClass="col-xs-12 col-sm-3 control-label">
                <#assign divClass="col-xs-12 col-sm-9 col-md-6 col-lg-6">
            <#elseif formStyle='inline'>
                <#assign labelClass=''>
            <#else>
                <#assign divClass="col-xs-12 col-sm-offset-3 col-sm-6">
            </#if>
        <#else>
            <#assign labelClass="col-xs-12">
            <#assign divClass="col-xs-12">
        </#if>
        <#if labelKey!=''>
            <label class="${labelClass}" for="${labelFor}">${labelKey}<#if mandatory> <i class="icon-asterisk"></i></#if></label>
        </#if>
        <div class="${divClass}">
            <#nested/>
        </div>
    </div>
</#macro>

Paramètres :

formStyle (string) : Le style du formulaire, selon les spécifications de Bootstrap. Options possibles : '', ‘inline’, ‘horizontal’, ‘navbar-form’, ‘navbar-left’… L’option par défaut est ‘horizontal’
class (string) : Classe additionnelle
groupStyle : Classe facultative pour signaler les erreurs ou avertissements sur les champs du formulaire. Options possibles : ‘success’, ‘warning’, ‘error’
rows (int) : Ce paramètre définit si le label et le champ qui lui est associé sont sur la même ligne (valeur : 1) ou sur deux lignes différentes (valeur : 2). Par défaut la valeur est à 1, et ce réglage correspond à la plupart des formulaires du back office.
labelKey (string) : Label du champ de formulaire contenu dans le groupe
labelFor (string) : Valeur de l’attribut “for” du label servant à lier le label à un élément du formulaire
labelId (string) : Ajoute un ID sur le label du champ
helpKey (string) : Texte d’aide du champ de formulaire
id (string)
mandatory (boolean) : Définit si le champ du formulaire est obligatoire (true/false)
showLabel (boolean) : Permet de choisir si le label sera visible ou pas. S’il est caché, celui-ci sera tout de même lisible par les lecteurs d’écran
params (string) : (permet d’ajouter d’autres attributs)

input

Cette macro permet d’appeler tous types d’input texte, et fichier. Le type est défini par un simple argument. Les inputs doivent être contenus par un formGroup.

HTML :

<textarea></textarea>

<input type="text" class="form-control" />
<input type="password" class="form-control" />
<input type="email" class="form-control" />
<input type="file" class="form-control" />
<input type="search" class="form-control" />
<input type="number" class="form-control" />

Appel de la macro :

<@input type='textarea' />
<@input type='text' />
<@input type='password' />
<@input type='email' />
<@input type='file' />
<@input type='search' />
<@input type='number' />

Macro :

<#macro input name type='text' value='' class='' size='' inputSize=0 maxlength=0 placeHolder='' rows=4 cols=40 richtext=false tabIndex='' id='' mandatory=mandatory disabled=false readonly=false pattern='' params='' title='' min=0 max=0>
    <#if type='textarea'>
        <textarea name="${name}" class="form-control<#if size!=''> input-${size}</#if><#if class!=''> ${class}</#if>" rows="${rows}" cols="${cols}" <#if tabIndex!=''>tabindex="${tabIndex}"</#if><#if placeHolder!=''> placeholder="${placeHolder}"</#if><#if title!=''> title="${title}"</#if><#if disabled> disabled</#if><#if readonly> readonly</#if><#if id!=''> id="${id}"</#if><#if params!=''>${params}</#if>></textarea>
    <#elseif type='text' || type='search' || type='password' || type='email' || type='file' || type='number'>
        <input class="form-control<#if size!=''> input-${size}</#if><#if class!=''> ${class}</#if>" id="${id}" name="${name}" type="${type}" value="${value}" <#if tabIndex!=''>tabindex="${tabIndex}"</#if><#if placeHolder!=''> placeholder="${placeHolder}"</#if><#if title!=''> title="${title}"</#if><#if maxlength gt 0> maxlength="${maxlength}"</#if><#if inputSize!=0> size="${inputSize}"</#if><#if disabled> disabled</#if><#if readonly> readonly</#if><#if params!=''>${params}</#if><#if pattern!=''> pattern="${pattern}"</#if><#if mandatory> required</#if><#if min!=0> min="${min}"</#if><#if max!=0> max="${max}"</#if> />
    <#else>
        <i class="icon-warning">Type non supporté</i>
    </#if>
</#macro>

Paramètres :

type (string) : ‘text’, ‘textarea’, ‘text’, ‘search’, ‘password’, ‘email’, ‘file’, ‘number’. La valeur par défaut est ‘text’
value (string)
class (string)
size (string) : classe Bootstrap déterminant la taille du texte et du champ. Valeurs possibles : ‘sm’, ‘lg’
inputSize (int) : l’attribut size html
maxlength (int)
placeHolder (string)
rows (int) : uniquement pour textarea
cols (int) : uniquement pour textarea
richtext (boolean) : active l’option de texte enrichi, uniquement pour textarea
tabIndex (string)
id (string)
mandatory (boolean) : hérité du contenant formGroup
disabled (boolean)
readonly (boolean)
pattern : [A-F][0-9]{5}
params (string)
title (string)
min (int) : paramètre compatible avec input type=‘number’
max (int) : paramètre compatible avec input type=‘number’

checkBox

HTML (checkbox vertical) :

<div class="checkbox">
    <label>
        <input type="checkbox" /> Label
    </label>
</div>

Appel de la macro :

<@checkBox labelKey='Label' />

HTML (checkbox horizontal) :

<label class="checkbox-inline">
    <input type="checkbox" /> Label
</label>

Appel de la macro :

<@checkBox orientation='horizontal' labelKey='Label' />

Macro :

<#macro checkBox name id='' labelKey='' labelFor='' orientation='vertical' value='' tabIndex='' title='' disabled=false readonly=false checked=false mandatory=mandatory params=''>
    <#if orientation='vertical'>
        <div class="checkbox">
    <#if orientation='horizontal'>
            <label class="checkbox-inline" <#if labelFor!=''>for="${labelFor}"</#if>>
    <#if labelKey!=''>${labelKey}</#if> 
    <input type="checkbox" id="${id}" name="${name}" <#if value!=''>value="${value}"</#if><#if tabIndex!=''>tabindex="${tabIndex}"</#if><#if checked> checked</#if><#if disabled> disabled</#if><#if readonly> readonly</#if><#if params!=''>${params}</#if> />
        </label>
    </#if>
        </div>
    </#if>
</#macro>

Paramètres :

name (obligatoire)
id (string)
labelKey (string) : label de la case à cocher
labelFor (string) : valeur de l’attribut “for” du label, servant à lier le label à un élément du formulaire
orientation (string) : la valeur par défaut est ‘vertical’
value (string)
tabIndex (string)
title (string)
disabled (boolean)
readonly (boolean)
checked (boolean)
mandatory (boolean) : hérité du contenant formGroup
params (string) : (permet d’ajouter d’autres attributs)

radioButton

HTML (radio vertical) :

<div class="radio">
    <label>
        <input type="radio" /> Label
    </label>
</div>

Appel de la macro (radio vertical) :

<@radioButton labelKey='Label' />

HTML (radio horizontal) :

<label class="radio-inline">
    <input type="radio" /> Label
</label>

Appel de la macro (radio horizontal) :

<@radioButton orientation='horizontal' labelKey='Label' />

Macro :

<#macro radioButton name id='' value='' labelKey='' labelFor='' orientation='vertical' tabIndex='' title='' disabled=false readonly=false checked=false mandatory=mandatory params=''>
    <#if orientation='vertical'>
        <div class="radio">
    <#if orientation='horizontal'>
            <label class="radio-inline" <#if labelFor!=''>for="${labelFor}"</#if>>
    <#if labelKey!=''>${labelKey}</#if> 
    <input type="radio" id="${id}" name="${name}" <#if value!=''>value="${value}"</#if><#if tabIndex!=''>tabindex="${tabIndex}"</#if><#if checked> checked</#if><#if disabled> disabled</#if><#if readonly> readonly</#if><#if mandatory> required</#if><#if params!=''>${params}</#if> />
            </label>
        </div>
    </#if>
</#macro>

Paramètres :

name (obligatoire)
id (string)
labelKey (string) : label du bouton radio
labelFor (string) : valeur de l’attribut “for” du label, servant à lier le label au bouton radio
orientation (string) : la valeur par défaut est ‘vertical’
value (string)
tabIndex (string)
title (string)
disabled (boolean)
readonly (boolean)
checked (boolean)
mandatory (boolean) : hérité du contenant formGroup
params (string) : (permet d’ajouter d’autres attributs)

select

Rendu HTML :

<select name='list'>
    ...
</select>

Appel de la macro :

<@select name='list' />

Macro :

<#macro select name items='' default_value=0 id=name size='' sort=false multiple=0 params='' title=''>
    <select id="${id}" name="${name}" class="form-control<#if size!=''> input-${size}</#if>"<#if (multiple > 0)> multiple size='${multiple}'</#if> <#if params!=''>${params}</#if> <#if title!=''>title="${title}"</#if> >
    <#if items?has_content>
        <#if sort=true><#assign sortedItems=items?sort_by("name")><#list sortedItems as item><#if default_value=='${item.code}'> <option selected="selected" value="${item.code}">${item.name}</option><#else> <option value="${item.code}">${item.name}</option></#if></#list></#if>
    <#else>
        <#list items as item><#if default_value=='${item.code}'> <option selected="selected" value="${item.code}">${item.name}</option><#else> <option value="${item.code}">${item.name}</option></#if></#list>
    </#if>
    </select>
</#macro>

Paramètres :

name (obligatoire)
id : reprend la valeur de name
title (string)
size (string) : classe Bootstrap déterminant la taille du texte et de la liste déroulante. Valeurs possibles : ‘sm’, ‘lg’
items (int) : liste des objets passés à la liste déroulante.
sort (boolean) : Permet de trier la liste par nom. Par défaut est false.
default_value (int) : valeur par défaut de la liste déroulante.
multiple (int) : seulement en cas de choix multiples. Si la valeur de multiple est supérieure à 0, celle-ci sera passée à l’attribut size du select.
params (string) : (permet d’ajouter d’autres attributs)

Lutece v6 : Macros Freemarker pour le back-office

Table des matières

Introduction

Les anciennes macros (< v5)

Les macros réécrites

Boutons

Les nouvelles macros

Lignes et colonnes

row

columns

Tableaux

table

td

Formulaires

tform

Composants de formulaires

formGroup

input

checkBox

radioButton

select

Autres composants

infoBox (AdminLTE)

callout (AdminLTE)

alert (AdminLTE)

box (AdminLTE)

smallBox (AdminLTE)

errorPage (AdminLTE)

Top of the page

Lutece v6 : Macros Freemarker pour le back-office

Table des matières

Introduction

Les anciennes macros (< v5)

Les macros réécrites

Boutons

Les nouvelles macros

Lignes et colonnes

row

columns

Tableaux

table

td

Formulaires

tform

Composants de formulaires

formGroup

input

checkBox

radioButton

select

Autres composants

infoBox (AdminLTE)

callout (AdminLTE)

alert (AdminLTE)

box (AdminLTE)

smallBox (AdminLTE)

errorPage (AdminLTE)