Nommage des templates, best practices

Principes généraux

Chaque package dispose d'un répertoire templates dans lequel sont placés tous les templates nécessaires au package (en fonction de la double cascade). Le fichier templates.xml liste les templates, et fait un lien entre le nom du template (code>templateName</code>) et le fichier correspondant.

<template templateName="creationEmailText" lang="fr" fileName="emails/creation/creationEmailText_fr.tpl.php" />

Pour homogéneiser le nommage des templates, nous proposons les pratiques suivantes.

organisation de sous-répertoires

Le répertoire des templates peut lui-même être organisé en sous-répertoires.

Faire coïncider les noms des sous-répertoires avec les fichiers d'actions qui les utilisent semble une bonne pratique.

On essaiera également de proposer deux répertoire standard :

• uiMessages pour regrouper les divers messages devant apparaître sur l'interface de l'utilisateur (en général de courts templates indiquant le déroulement d'une action)
• emails pour regrouper le contenu des divers mails qui sont envoyés aux utilisateurs. (note : nous conservons l'expression en anglais email pour désigner ce que les français appellent simplement "mail")

nommage des templates

Chaque template doit avoir :

• Son nom propre, qui est en général le templateName, écrit en camelCase
• suivi de _xx, où xx représente la langue.
• avec l'extension .tpl.php

On peut définir un template sans mentionner la langue, mais cela ne constitue pas une bonne pratique, car limite les extensions futures et la réutilisation du code.

En revanche, si tous les templates sont nommés avec l'indication de langue, il faut prévoir dans le fichier templates.xml un élément template par défaut (i.e. sans mention de langue) et choisir le fichier de template qui sera considéré comme celui par défaut.

    <template templateName="creationEmailText" lang="en" fileName="emails/creation/creationEmailText_en.tpl.php" />
    <template templateName="creationEmailText" lang="fr" fileName="emails/creation/creationEmailText_fr.tpl.php" />
    <template templateName="creationEmailText" fileName="emails/creation/creationEmailText_fr.tpl.php" />

templates de mail

Il convient de toujours prévoir deux formes d'un même mail :

• en format texte, pour pouvoir être lu en toute circonstance
• en format html, pour une meilleure présentation de l'information

Une bonne pratique de nommage consiste à faire suivre le nom du template par les mentions Text ou Html (toujours dans le modèle camelCase)

  creationEmailText_fr.tpl.php
  creationEmailHtml_fr.tpl.php