Utilisation des templates et fragments

Templates ou Fragments ?

Les templates et fragments fonctionnent de façon similaire. Quelle différence entre template et fragment ?

Un template est utilisé par un package et a donc des variables associées ($obj, $ui plus d'autres éventuellement). Les fichiers de templates sont dans le répertopire templates des packages.

Un fragment est un snippet HTML qui n'a pas de variables associées. Les fichiers de fragments sont dans le répertoire fragments du thème utilisé.

Templates

Utilisation de base

Un template est caractérisé par son nom, qui sert pour l'appel PHP. Pour utiliser un template, on utilise un objet Ui :

// appeler un template de visualisation
// arguments : - nom du template
//             - tableau des variables du template (optionnel)
//             - langue à utiliser (optionnel)
getUi($classOrInstance)->display('view', $paramArray, $lang); 
 
// appeler un template d'édition
// on peut aussi passer des paramètres, voir la page Wiki de gestion des formulaires
getUi($classOrInstance)->makeForm('edit');

Le nom du template doit être associé à un fichier de template. Par exemple, le template view est généralement utilisé pour visualiser un objet. Par défaut, le système va donc chercher automatiquement un fichier templates/view_{lang}.tpl.php en ajoutant l'extension .tpl.php et en utilisant diverses langues (voir plus bas). Pour trouver le fichier, la double cascade est appliquée pour prendre le fichier au plus proche de l'objet utilisé.

Templates et Versions linguistiques

Un template peut être disponible dans plusieurs versions linguistiques. Le template de nom toto pourra donc être associé à N fichiers toto_fr.tpl.php, toto_es.tpl.php... et enfin le fichier par défaut toto.tpl.php. Lorsque le template toto est utilisé, Sydonie va donc chercher un fichier toto_{lang} avec lang qui sera pris dans cet ordre :

1. dans la langue spécifée dans l'appel au template
2. dans la langue de l'interface
3. dans les langues spécifiées dans les préférences du navigateur
4. la langue par défaut du site
5. si rien n'est trouvé, cherche le fichier toto.tpl.php

Variables du template

Un template peut utiliser des variables. Pour cela, l'appel doit avoir en argument un tableau associatif :

// appeler un template de visualisation
// arguments : - nom du template
//             - tableau des variables du template (optionnel)
//             - langue à utiliser (optionnel)
 
$paramArray = array(
              'tata' => $maVar,
              'titi' => $truc
              )
 
getUi($classOrInstance)->display('view', $paramArray);

Le template pourra alors utiliser les variables $tata et $titi. De plus, si la variable contient un objet Sydonie (i.e. une instance qui dérive de Abstract_SydonieBase), alors la variable UI associée $tataUi et $titiUi est automatiquement créée.

Configuration avancée

Il est possible de modifier l'association entre nom du template et fichier de template. Ces informationq sont spécifiées dans le fichier templates.xml du package, qui utilise la double cascade. La page Nommage des templates, best practices explique comment réaliser cela et les règles de bonnes pratiques à utiliser.

Développement et Debugging

Dans le cas où Sydonie ne trouve aucun fichier de template correspondant au nom demandé, un template de Abstract_SydonieBase sera utilisé :

• template templateLanguageHelp si le mode DEBUG ou TEMPLATE_DEBUG est activé. Ce template affiche un message précisant le nom du template non trouvé et les possibles raisons de son affichage.
• template emptyTemplate en mode production. Ce template affiche juste un commentaire HTML (visible donc dans le code source de la page produite)

Fragments

Utilisation de base

Le principe de fonctionnement et d'utilisation des fragments est quasiment identique. La différence principale est que les fragments ne dépendent pas d'un package et sont stockés dans le répertoire fragments du thème utilisé.

Un fragment est caractérisé par son nom, qui sert pour l'appel PHP réalisé avec la fonction getFragment. On peut passer en argument (optionnel) un tableau de variables qui seront dispopnibles dans le fragment (comme pour les templates, voir ci-dessus) et spécifier une langue :

// appeler un fragment
// arguments : - nom du fragment
//             - tableau des variables du fragment (optionnel)
//             - langue à utiliser (optionnel)
getFrament('footer', $paramArray, $lang);

Sydonie va alors chercher dans répertoire fragments le fichier footer/footer_{lang}.html.php puis footer_{lang}.html.php en utilisant le même principe que pour les templates et les labels :

1. dans la langue spécifée dans l'appel au template
2. dans la langue de l'interface
3. dans les langues spécifiées dans les préférences du navigateur
4. la langue par défaut du site
5. si rien n'est trouvé, cherche le fichier footer/footer.php puis footer.php

Bonnes pratiques

Dans le cas d'un site où les fragments seront disponibles en diverses versions linguistiques, il est fortement recommandé de créer un répertoire par fragment, par exemple :

Développement et Debugging

Dans le cas où Sydonie ne trouve aucun fichier de fragment correspondant au nom demandé, Sydonie utilise un template de Abstract_SydonieBase :

• template fragmentLanguageHelp si le mode DEBUG ou TEMPLATE_DEBUG est activé. Ce template affiche un message précisant les possibles raisons de son affichage.
• template emptyTemplate en mode production. Ce template affiche juste un commentaire HTML (visible donc dans le code source de la page produite)