Voir la source de 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 <code>templates</code> des packages.

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

==Templates==

===Utilisation de base===

Un template est caractérisé par son <strong>nom</strong>, qui sert pour l'appel PHP. Pour utiliser un template, on utilise un objet Ui :
<source lang="php">
// 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'); 
</source>

Le nom du template doit être associé à un fichier de template. Par exemple, le template <code>view</code> est généralement utilisé pour visualiser un objet. Par défaut, le système va donc chercher automatiquement un fichier <code>templates/view_{lang}.tpl.php</code> en ajoutant l'extension <code>.tpl.php</code> et en utilisant diverses langues (voir plus bas). Pour trouver le fichier, la <em>double cascade</em> 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 <code>toto</code> pourra donc être associé à N fichiers <code>toto_fr.tpl.php</code>, <code>toto_es.tpl.php</code>... et enfin le fichier par défaut <code>toto.tpl.php</code>. Lorsque le template <code>toto</code> est utilisé, Sydonie va donc chercher un fichier <code>toto_{lang}</code> avec <code>lang</code> qui sera pris dans cet ordre :

<ol>
<li>dans la langue spécifée dans l'appel au template</li>
<li>dans la langue de l'interface</li>
<li>dans les langues spécifiées dans les préférences du navigateur</li>
<li>la langue par défaut du site</li>
<li>si rien n'est trouvé, cherche le fichier <code>toto.tpl.php</code></li>
</ol>

===Variables du template===

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

<source lang="php">
// 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); 
</source>

Le template pourra alors utiliser les variables <code>$tata</code> et <code>$titi</code>. 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 <code>$tataUi</code> et <code>$titiUi</code> est automatiquement créée.


===Configuration avancée===

Il est possible de modifier l'association entre <em>nom du template</em> et <em>fichier de template</em>. Ces informationq sont spécifiées dans le fichier <code>templates.xml</code> du package, qui utilise la <em>double cascade</em>. 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 <code>templateLanguageHelp</code> 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 <code>emptyTemplate</code> 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 <code>fragments</code> du thème utilisé. 

Un fragment est caractérisé par son <strong>nom</strong>, qui sert pour l'appel PHP réalisé avec la fonction <code>getFragment</code>. 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 :
<source lang="php">
// appeler un fragment
// arguments : - nom du fragment
//             - tableau des variables du fragment (optionnel)
//             - langue à utiliser (optionnel)
getFrament('footer', $paramArray, $lang); 
</source>

Sydonie va alors chercher dans répertoire <code>fragments</code> le fichier <code>footer/footer_{lang}.html.php</code> puis <code>footer_{lang}.html.php</code> en utilisant le même principe que pour les templates et les labels :
<ol>
<li>dans la langue spécifée dans l'appel au template</li>
<li>dans la langue de l'interface</li>
<li>dans les langues spécifiées dans les préférences du navigateur</li>
<li>la langue par défaut du site</li>
<li>si rien n'est trouvé, cherche le fichier <code>footer/footer.php</code> puis <code>footer.php</code></li>
</ol>


===Bonnes pratiques===

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

[[Fichier:FragmentsTree.png]]

===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 <code>fragmentLanguageHelp</code> si le mode DEBUG ou TEMPLATE_DEBUG est activé. Ce template affiche un message précisant les possibles raisons de son affichage.
* template <code>emptyTemplate</code> en mode production. Ce template affiche juste un commentaire HTML (visible donc dans le code source de la page produite)