Jan 5, 2017 4:34:46 PM Elysa Jouve EJO avatar   468    

Lutece v6 : Macros Freemarker pour le back-office

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

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=''>
	<div class="row<#if class!=''> ${class}</#if>"<#if id!=''> id="${id}"</#if>>
		<#nested>
	</div>
</#macro>

Paramètres :

  • class (string)
  • id (string)

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 xs=12 sm=12 md=12 lg=12 xl=12 id='' class=''>
	<div class="col-xs-${xs} col-sm-${sm} col-md-${md} col-lg-${lg}
	<#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 class!=''> ${class}</#if>"<#if id!=''> id="${id}"</#if>>
		<#nested>
	</div>
</#macro>

Paramètres :

  • xs (int) : nombre de colonnes à afficher (mobile)
  • sm (int) : nombre de colonnes à afficher (tablette)
  • md (int) : nombre de colonnes à afficher (tablette/petit écran desktop)
  • lg (int) : nombre de colonnes à afficher (grand écran desktop)
  • xl (int) : nombre de colonnes à afficher (très grand écran desktop)
  • offsetXs, offsetSm, offsetMd, offsetLg, offsetXl (int) : spécifie le décalage de l'élément sur la grille
  • pushXs, pushSm, pushMd, pushLg, pushXl (int) : réarrange l'ordre des colonnes (voir : Reorder CSS Columns Using Bootstrap)
  • id (string)
  • class (string)

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}"<#if params!=''> ${params}</#if>>
		<#nested>
	</table>
	<#if responsive>
	</div>
	</#if>
</#macro>

Paramètres :

  • responsive (boolean)
  • class (string) : 'table-striped', 'table-bordered'
  • id (string)
  • params (string)

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=''>
	<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><#if id!=''> ${id}</#if>">
		<#nested>
	</td>
</#macro>

Paramètres :

  • xs (int)
  • sm (int)
  • md (int)
  • lg (int)
  • xl (int)
  • class (string)
  • id (string)

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>"<#if id!=''> id="${id}"</#if><#if action!=''> action="${action}"</#if><#if method!=''> method="${method}"</#if><#if name!=''> name="${name}"</#if><#if role!=''> role="${role}"</#if><#if params!=''> ${params}</#if>>
		<#nested>
	</form>
</#macro>

Paramètres :

  • class2 (string) : 'form-inline', 'form-horizontal', 'navbar-form', 'navbar-left', 'search-form'... L'option par défaut est 'form-horizontal'
  • action (string)
  • method (string)
  • name (string)
  • id (string)
  • role (string)
  • params (string)

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='' helpKey='' id='' mandatory=false showLabel=true>
	<div class="form-group<#if groupStyle!=''> has-${groupStyle} has-feedback</#if><#if class!=''> ${class}</#if>"<#if id!=''> id="${id}"</#if>>
		<#if rows=1>
			<#if labelKey!='' && formStyle='horizontal'>
				<#assign labelClass = "col-xs-12 col-sm-3 col-md-3 col-lg-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 col-md-offset-3 col-md-6 col-lg-offset-3 col-lg-6">
			</#if>
		<#else>
			<#assign labelClass = "col-xs-12 col-sm-12 col-md-12 col-lg-12">
			<#assign divClass = "col-xs-12 col-sm-12 col-md-12 col-lg-12">
		</#if>
		<#if labelKey!=''>
		<label class="${labelClass}<#if showLabel=false> sr-only</#if>" for="${labelFor}">
			${labelKey}
			<#if mandatory=false>
				 (facultatif)
			<#elseif mandatory=true>
				 <@icon style='asterisk' />
			</#if>
		</label>
		</#if>
		<#if formStyle="horizontal">
		<div class="${divClass}">
		</#if>
			<#assign mandatory = mandatory>
			<#nested>
			<#if class='success'>
				<@icon style='check' class='form-control-feedback' />
			<#elseif class='warning'>
				<@icon style='warning' class='form-control-feedback' />
			<#elseif class='error'>
				<@icon style='close' class='form-control-feedback' />
			</#if>
		<#if helpKey!='' && formStyle!='inline'><span class="help-block">${helpKey}</span></#if>
		<#if formStyle="horizontal">
		</div>
		</#if>
	</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
  • helpKey (string) : Texte d'aide du champ de formulaire
  • 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
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><#if richtext> richtext</#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><#if pattern!=''>pattern=${pattern}</#if>><#if mandatory && !richtext> required</#if><#if labelFor!=''> aria-describedby="${labelFor}_help"</#if>><#nested></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 id!=''> id="${id}"</#if><#if params!=''> ${params}</#if><#if pattern!=''>pattern=${pattern}</#if><#if mandatory> required</#if> />
	</#if>
</#macro>

Paramètres :

  • type (string) : '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 checked=false mandatory=mandatory>
	<#if orientation='vertical'>
	<div class="checkbox">
	</#if>
	<label<#if orientation='horizontal'> class="checkbox-inline"</#if><#if labelFor!=''> for="${labelFor}"</#if>>
		<input type="checkbox" id="${id}" name="${name}" value="${value}"<#if tabIndex!=''> tabindex="${tabIndex}"</#if><#if checked> checked</#if><#if disabled> disabled</#if><#if mandatory> required</#if>>
		<#if labelKey!=''>
			${labelKey}
		<#else>
			&#160;
		</#if>
	</label>
	<#if orientation='vertical'></div></#if>
</#macro>

Paramètres :

  • name (obligatoire)
  • id (string)
  • labelKey (string) : label affiché à côté 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)
  • checked (boolean)
  • mandatory (boolean) : hérité du contenant formGroup
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='' helpKey='' orientation='vertical' tabIndex='' title='' disabled=false checked=false>
	<#if orientation='vertical'>
		<div class="radio">
	</#if>
			<label<#if orientation='horizontal'> class="radio-inline"</#if>>
				<input type="radio" id="${id}" name="${name}" value="${value}"<#if tabIndex!=''> tabindex="${tabIndex}"</#if><#if checked> checked</#if><#if disabled> disabled</#if>>
			<#if labelKey!=''>
					${labelKey}
			<#else>
					&#160;
			</#if>
			</label>
<#if orientation='vertical'></div></#if>
</#macro>

select

Rendu HTML :

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

Appel de la macro :

<@select name='list' />

Macro :

<#macro select name items=0 default_value=0 id=name size='' sort=false list=false multiple=0 params='' title=''>
	<select id="${id}" name="${name}" class="form-control<#if size!=''> input-${size}</#if>" <#if (multiple &gt; 0)>multiple size="${multiple}"</#if><#if params!=''> ${params}</#if><#if title!=''> ${title}</#if>>
	<#if list>
		<#if sort=true>
			<#list items?sort_by("name") as item>
			<#if default_value="${item.code}">
			<option selected="selected" value="${item.code}" <#if !item.name?has_content>label="${i18n("portal.util.labelEmpty")}"</#if>>${item.name}</option>
			<#else>
			<option value="${item.code}" <#if !item.name?has_content>label="${i18n("portal.util.labelEmpty")}"</#if>>${item.name}</option>
			</#if>
			</#list>
		<#else>
			<#list items as item>
			<#if default_value="${item.code}">
			<option selected="selected" value="${item.code}" <#if !item.name?has_content>label="${i18n("portal.util.labelEmpty")}"</#if>>${item.name}</option>
			<#else>
			<option value="${item.code}" <#if !item.name?has_content>label="${i18n("portal.util.labelEmpty")}"</#if>>${item.name}</option>
			</#if>
			</#list>
		</#if>
	<#else>
		<#nested>
	</#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.
  • list (boolean) : indique si une liste d'objets est passée à la liste déroulante. Par défaut est false.
  • sort (boolean) : seulement si list est vrai. 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) : tous paramètres supplémentaires (saisie libre)
progressBar

Fonctionne avec le script JQuery "Complexify".

Rendu HTML :

<div class="progress">
		<div id="progressbar" class="progress-bar progress-bar-striped" role="progressbar">
			<div id="complexity">0%</div>
		</div>
	</div>

Appel de la macro :

<@progressBar />

Macro :

<#macro progressBar description=''>
	<div class="progress">
		<div id="progressbar" class="progress-bar progress-bar-striped" role="progressbar">
			<div id="complexity">0%</div>
		</div>
	</div>
	<#if description!=''>
		<span class="progress-description">${description}</span>
	</#if>
</#macro>

Paramètre :

  • description (string)
staticText

Ce composant peut être adapté à une utilisation dans des formulaires pour afficher une valeur fixe non modifiable, ou bien en-dehors d'un formulaire.

HTML :

<p class="form-control-static">
	...
</p>

Appel de la macro :

<@staticText>
	...
</@staticText>

Macro :

<#macro staticText inForm=true color=''>
    <p class="<#if inForm>form-control-static</#if><#if color!=''> text-${color}</#if>">
        <#nested>
    </p>
</#macro>

Paramètres :

  • inForm (boolean) : par défaut à true, pour utiliser dans un formulaire, ajoute la classe "form-control-static".
  • color (string) : permet de spécifier une classe de couleur parmi les couleurs de Bootstrap (muted/primary/success/info/warning/danger) ou celles d'AdminLTE (red/yellow/aqua/blue/black/light-blue/green/gray/navy/teal/olive/lime/orange/fuchsia/purple/maroon)

Boutons et liens

button
aButton
dropdownMenu

Groupements de composants

inputGroup
inputGroupItem
btnGroup
btnToolbar

Icônes

icon

Onglets

tabs

listTabs

tabContent

Accordéons

accordionContainer

accordionPanel

accordionHeader

accordionBody

Modales

modal

modalHeader

modalBody

modalFooter

Listes

listGroup

unstyledList

dropdownList

Autres composants

tag

breadcrumbs

coloredBg

Macros pour composants AdminLTE

Le back office embarque la feuille de style d'AdminLTE, permettant d'utiliser des composants Bootstrap stylisés et plus attrayants visuellement. Ceux-ci sont utilisés dans la grande majorité des templates du back office de Lutece.

infoBox (AdminLTE)

callout (AdminLTE)

alert (AdminLTE)

box (AdminLTE)

smallBox (AdminLTE)

errorPage (AdminLTE)