Lutece : guide développeur
Le framework CSS responsive : Bootstrap
Depuis la version 4.0 sortie en octobre 2012 , Lutece s'appuie sur le framework CSS Bootstrap diffusé en Open Source par la société Twitter. Ce framework a la particularité de gérer le responsive design (conception adaptative en traduction litérale) , c'est à dire la capacité d'une page HTML à s'adapter à l'environnement dans lequel elle est consultée. La même page ne s'affichera pas de la même façon sur un téléphone mobile, une tablette ou sur un écran de grande dimension. Ces mécanismes s'appuie notamment sur la largeur de la page.
Les versions 4.x de Lutece utilisent des versions 2.x de Bootstrap. Twitter a conçu la version 3 de son framework en rupture de compatibilité avec la version 2, ce pour améliorer significativement les possibilités "responsives". La prise en compte de la nouvelle version 3 de Bootstrap dans Lutece v5 a nécessité la réalisation d'une feuille de style CSS de compatibilité de manière à limiter les problèmes d'incompatibilité.
En version 5 de Lutece, il a également été ajouté une feuille de style complémentaire, Admin-LTE, pour étendre les possibilités graphique dans le back office.
| Version Lutece | Back Office | Front Office |
|---|---|---|
| v4 | Bootstrap v2 | Bootstrap v2 par défaut |
| v5 | CSS de compatibilité Bootstrap v2/v3 + AdminLTE | Bootstrap v3 par défaut |
NB : La feuille de style CSS du Front Office est une proposition par défaut. Dans la pratique, un Front Office Lutece peut intégrer n'importe quelle charte graphique.
Enfin, Lutece v5 prévoit des macros Freemarker pour l'écriture de blocs de code HTML courants (inputs, box, ...) de manière à créer un niveau d'abstraction et garantir la portabilité du code HTML au fil des évolutions des versions de Bootstrap. Il est fortement recommandé d'utiliser ces macros décrites ci-dessous.
Utilisation de Bootstrap dans le Back Office Lutece v5
Une page d'administration Lutece à partir de la version 5 utilise Bootstrap 3 + AdminLTE et doit respecter les contraintes suivantes:
Les blocs de code HTML doivent être dans une section row / col / box (exemple en pleine largeur).
Bloc admin
<div class="row" >
<div class="col-xs-12 col-sm-12 col-md-12">
<div class="box [box-solid] [box-primary | box-success | box-info | box-danger | box-warning]">
<div class="box-header">
<h3 class="box-title"># i18n{myplugin.feature.title}</h3>
[ <div class="box-tools pull-right">...</div> ]
</div>
<div class="box-body">
...contenu...
</div>
</div>
</div>
</div>
Ecriture de ce bloc avec les macros FreeMarker Lutece v5
<@rowBoxHeader i18nTitleKey="myplugin.feature.title" >
...
</@rowBoxHeader>
ou si il y a des boutons d'actions au niveau de la barre d'outils (en haut à droite) il faut utiliser les macros @rowBox, @boxHeader et @boxBody au lieu de @rowBoxHeader.
<@rowBox>
<@boxHeader i18nTitleKey="myplugin.feature.title">
<@headerButtons>
<form class="form-inline pull-right spaced" method="post" action="jsp/admin/plugins/myplugins/MyAction.jsp">
....
</form>
</@headerButtons>
</@boxHeader>
<@boxBody>
....
</@boxBody>
</@rowBox>
Les boutons, liens d'actions relatifs aux paramètres avancés ou à l'ajout de contenus doivent se situer en haut à droite de l'écran dans la balise <div class="box-tools"> du box-header.
Les actions
le formulaire doit hériter des classes css bootstrap form-inline et pull-right
<div class="box-tools pull-right">
<form class="form-inline pull-right" method="post" action="jsp/admin/plugins/plugin/ManageAdvancedParameters.jsp">
<button class="btn btn-primary btn-xs btn-flat" type="submit" >
<span class="fa fa-cog" ></span>
<span class="hidden-xs" ></span>
</button>
</form>
<a class="btn btn-default btn-xs btn-flat" title="${action.description}" >
<span class="fa fa-close"></span>
</a>
</div>
Les boutons
Les boutons, qu'ils soient sous forme de lien, balise <a>, ou de boutons de formulaire, balise <button>, doivent avoir les propriétés suivantes:
- Ils doivent tous hériter à minima des classes btn et btn-default pour un bouton gris standard.
- Ils doivent contenir une icône fa (font awesome) balise <span> ou <i> (spécifique à Bootstrap) : exemple <span class="fa fa-plus"></span> pour un bouton ajout d'un contenu.
- Le libellé si un peu long doit être masqué en mode téléphone mobile en utilisant la class "hidden-xs" placés dans une balise <span>
- Les bouton d'actions sont généralement de classe btn-primary. Les exceptions sont pour les boutons Retour ou Annuler classe btn-default, et les boutons Supprimer qui héritent eux de la classe btn-danger. On peut trouver aussi btn-success, btn-info ou btn-warning.
- La taille des bouton est gérée par les classes btn-xs que l'on trouvera dans les box-tools, btn-sm, btn-lg et btn-block.
| Bouton de modification | fa fa-pencil |
| Bouton de suppression | fa fa-trash |
| Bouton d'activation | fa fa-check |
| Bouton de validation | fa fa-check |
| Bouton d'annulation | fa fa-close |
Les modèles de page d'administration
Les sections suivantes donnent un aperçu des modèles standard d'interface back office.
Elles abordent également l'utilisation des macros freemarker V5 facilitant l'écriture de ces dernières.
Le modèle Manage
Ce modèle est le modèle standard d'accueil d'un plugin. Il affiche généralement la liste des ressources, avec les actions associées dans un tableau.
Les boutons d'ajout d'une ressource et de paramètres avancés sont placés en haut de la page.
La liste des ressources est affichée dans un tableau ayant les class css table table-condensed table-striped.
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12">
<div class="box box-primary">
<div class="box-header">
<h3 class="box-title"># i18n{calendar.manage_calendars.tableLabel}</h3>
<div class="box-tools">
<form class="form-inline pull-right spaced" method="post" action="jsp/admin/plugins/calendar/CreateCalendar.jsp">
<button class="btn btn-xs btn-flat btn-primary" type="submit" >
<i class="fa fa-plus"></i>
<span class="hidden-phone" ># i18n{calendar.manage_calendars.buttonAddCalendar}</span>
</button>
</form>
<#if permission_advanced_parameter>
<form class="form-inline pull-right" method="post" action="jsp/admin/plugins/calendar/ManageAdvancedParameters.jsp">
<button class="btn btn-xs btn-flat btn-primary" type="submit" >
<i class="fa fa-cog"></i>
<span class="hidden-phone" ># i18n{calendar.manage_calendars.labelAdvancedParameters}</span>
</button>
</form>
</#if>
</div>
</div>
<@paginationAdmin paginator=paginator combo=1 form=0 />
<div class="box-body table-responsive">
<table class="table table-hover table-condensed">
<thead>
<tr>
<th># i18n{calendar.manage_calendars.columnTitleLabel}</th>
<th># i18n{calendar.manage_calendars.columnTitleActions}</th>
</tr>
</thead>
<tbody>
<tr>
<td>
...
</td>
<td>
<a class="btn btn-primary btn-xs btn-flat pull-left spaced" href="#" title="# i18n{calendar.modify_calendar.pageTitle}" >
<span class="fa fa-pencil"></span>
</a>
...
</td>
</tr>
</tbody>
</table>
</div>
<@paginationAdmin paginator=paginator combo=0 form=1 />
</div>
</div>
</div>
Ecriture de ce bloc avec les macros FreeMarker Lutece v5
<@rowBox>
<@boxHeader i18nTitleKey="calendar.manage_calendars.tableLabel">
<@headerButtons>
<form class="form-inline pull-right spaced" method="post" action="jsp/admin/plugins/calendar/CreateCalendar.jsp">
<button class="btn btn-xs btn-flat btn-primary" type="submit" >
<i class="fa fa-plus"></i>
<span class="hidden-phone" ># i18n{calendar.manage_calendars.buttonAddCalendar}</span>
</button>
</form>
<#if permission_advanced_parameter>
<form class="form-inline pull-right" method="post" action="jsp/admin/plugins/calendar/ManageAdvancedParameters.jsp">
<button class="btn btn-xs btn-flat btn-primary" type="submit" >
<i class="fa fa-cog"></i>
<span class="hidden-phone" ># i18n{calendar.manage_calendars.labelAdvancedParameters}</span>
</button>
</form>
</#if>
</@headerButtons>
</@boxHeader>
<@boxBody>
<@paginationAdmin paginator=paginator combo=1 form=0 />
<@table>
<tr>
<th># i18n{calendar.manage_calendars.columnTitleLabel}</th>
<th># i18n{calendar.manage_calendars.columnTitleActions}</th>
</tr>
<@tableHeadBodySeparator />
<tr>
<td>
...
</td>
<td>
<a class="btn btn-primary btn-xs pull-left spaced" href="#" title="# i18n{calendar.modify_calendar.pageTitle}" >
<span class="fa fa-pencil"></span>
</a>
...
</td>
</tr>
</@table>
<@paginationAdmin paginator=paginator combo=0 form=1 />
</@boxBody>
</@rowBox>
Le modèle Create et le modèle Modify
Ce modèle est déstiné à étre utilisé dans les interfaces de création et de modification des ressources
<div class="row">
<div class="col-xs-12 col-sm-12 col-md-12">
<div class="box box-primary">
<div class="box-header">
<h3 class="box-title"># i18n{ria.create_activity.pageTitle}</h3>
</div>
<div class="box-body">
<form class="form-horizontal" method="post" name="create_calendar" action="jsp/admin/plugins/calendar/DoCreateCalendar.jsp">
<div class="form-group">
<label class="control-label col-xs-12 col-sm-3 col-md-3" for="calendar_name"> # i18n{calendar.create_calendar.name} *</label>
<div class="col-xs-12 col-sm-8 col-md-6">
<input type="text" class="form-control input-sm" id="calendar_name" name="calendar_name" tabindex="1" maxlength="250" >
</div>
</div>
...
<div class="form-group">
<div class="col-xs-12 col-sm-offset-3 col-sm-8 col-md-offset-3 col-md-8">
<button class="btn btn-primary btn-flat" type="submit" >
<span class="fa fa-check"></span> # i18n{portal.util.labelValidate}
</button>
<a class="btn btn-default btn-flat" href="jsp/admin/plugins/calendar/ManageCalendars.jsp" >
<span class="fa fa-close"></span> # i18n{portal.util.labelCancel}
</a>
</div>
</div>
</form>
</div>
</div>
</div>
</div>
Ecriture de ce bloc avec les macros FreeMarker Lutece v5
<@rowBoxHeader i18nTitleKey="ria.create_activity.pageTitle" >
<form class="form-horizontal" method="post" name="create_calendar" action="jsp/admin/plugins/calendar/DoCreateCalendar.jsp">
<@fieldInputText i18nLabelKey="calendar.create_calendar.name" inputName="calendar_name" mandatory=true maxlength=250 />
...
<@actionButtons url2='jsp/admin/plugins/calendar/ManageCalendars.jsp' />
</form>
</@rowBoxHeader>
Les dashboards
Au niveau de l'accueil du back-office, les dashboard utilisent des box comme vu plus haut. Il peut y avoir des styles particuliers avec 'small-box" et un fond de couleur bg-info par exemple ajouter pour certains dashboards.
<div class="small-box bg-red">
<div class="inner">
<h3>${memory}</h3>
<p> Mémoire en Mo (Utilisée / Max.)</p>
</div>
<div class="icon">
<i class="fa fa-tasks"></i>
</div>
<a href="${url}" class="small-box-footer">
Mémoire en Mo (Utilisée / Max.)<i class="fa fa-arrow-circle-right"></i>
</a>
</div>
<div class="small-box bg-red">
<div class="inner">
<#list connections as connection>
<h3>${connection.name}</h3>
<p>${connection.code} Connexions (Utilisées / Max.)</p>
</#list>
</div>
<div class="icon">
<i class="fa fa-database"></i>
</div>
<a href="${url}" class="small-box-footer">
Connexions (Utilisées / Max.)<i class="fa fa-arrow-circle-right"></i>
</a>
</div>
