Ecriture d'un gabarit

Un gabarit est modélisé par un ou plusieurs fichiers XSL qui, à partir des données XML fournies par le CMS, permet de générer du HTML pour afficher la page web à l'utilisateur.

Tous les gabarits sont définis dans un dossier nommé templates (cms/skins/[skinName]/templates). Dans ce dossier se trouve autant de répertoires que de gabarits. Chaque répertoire porte le nom identifiant le gabarit (page ou index, par exemple).  Un dossier de gabarit est composé de ressources statiques, d'une feuille de style (template.xsl) et d'un fichier de définition (template.xml) :

RépertoireDétails

  • le fichier template.xml permet de présenter le gabarit et de décrire les différentes zones.
  • le répertoire resources contient les ressources statiques du template (notamment les images et les feuille de style CSS). L'intégrateur est libre d'organiser ce dossier à sa guise.
  • le fichier template.xsl, dans le dossier cms/skins/[skinName]/templates/[templateName]/stylesheets, combiné avec les contenus et les données dynamiques, permet de construire les pages HTML du site web

Il doit exister au minimum un gabarit nommé, celui-ci doit contenir au moins une zone nommée, ce sont les valeurs par défaut utilisées par l'application Ametys. Il est également fortement recommandé d'avoir une zone dans tous les gabarits.

En général, certains éléments sont identiques sur toutes les pages (l'entête et le pied de page, par exemple) ; dans ce cas un ou plusieurs fichiers XSL communs, placés dans le répertoire cms/skins/[skinName]/stylesheets puis importés dans les différents template.xsl des gabarits permet de mutualiser la définition de ces éléments.

Surcharger les templates utiles

Le fichier template-default.xsl du noyau Ametys comporte des templates prédéfinis. Il est possible de les surcharger dans le fichier cms/skins/[skinName]/templates/[templateName]/stylesheets/template.xsl d'un gabarit.

Les templates définis dans ce fichier sont :

  • le template favico, qui permet de définir une favicon pour le site
  • le template head-meta-top, qui permet de définir les métadonnées d'entête
  • le template head-js-jquery qui permet de faire les imports de fichiers jquery
  • le template head-css-jquery, qui permet d'importer un thème jquery
  • le template head-js-pirobox, qui permet d'importer les scripts Pirobox
  • le template head-css-pirobox qui permet d'importer les styles utilisés par Pirobox.
Le template favico

Par défaut, le favicon est extraite du noyau. Pour définir une nouvelle favicon pour un projet donné, il est conseillé de surcharger ce template et de définir une règle Apache côté site pour que le favicon soit toujours disponible, même lorsque le CMS ne fonctionne pas.

Il faut impérativement placer les fichiers de favicon côté site de sorte que le favicon soit toujours disponible, même lorsque le CMS ne fonctionne pas.

Il est recommandé de surcharger le favicon au niveau d'une XSL commune à tous les gabarits.

Favico
Le favicon doit toujours être défini en deux formats : format GIF et format ICO, certains navigateurs ne prenant en compte que l'un ou l'autre des deux formats.

<xsl:template name="favico">
        <link rel="icon" type="image/gif" href="{$uri-prefix}/kernel/resources/img/runtime_favico.gif" />
        <link rel="shortcut icon" type="image/x-icon" href="{$uri-prefix}/kernel/resources/img/runtime_favico.ico" />
</xsl:template>

Les métadonnées d'entête

Le template head-meta-top permet de définir les balises <meta> dans l'entête de page. Il est possible de définir des métadonnées par gabarit en surchargeant ce template dans le fichier template.xsl d'un gabarit.

Imports des scripts et des thèmes jQuery 

Par défaut, jQuery est importé. Il est possible de supprimer l'import de jQuery ou bien de compléter cet import avec des plugins, en définissant le template XSL nommé head-js-jquery. Cela est rarement nécessaire puisque la plupart des plugins jQuery nécessaires à l'affichage d'une page sont déjà importés par les contenus et services selon les cas.

Le préfixe jQuery est transformé par $j pour éviter les conflits avec d'autres librairies, veillez à le conserver si vous surchargez le template head-js-jquery.

<script type="text/javascript">
    $j = jQuery.noConflict();
</script>

Le thème jQuery utilisé par défaut dans Ametys est le thème "lightness", pour importer un thème différent, il faut définir le nouvel import dans un template nommé head-css-jquery.

Import de Pirobox

Pirobox est une librairie construite avec jQuery qui permet l'affichage et le zoom des images. Cette librairie est importée par défaut dans Ametys. Pour changer les paramètres de lancement de Pirobox, modifier le template XSL head-js-pirobox.

Tout comme jQuery, il est également possible de ne modifier que le thème de Pirobox, thème "Black" par défaut, en redéfinissant le template XSL head-css-pirobox.