Cette documentation présente le nouveau système de template de FSB, particulièrement au niveau des fichiers templates où pas mal de nouveautés / modifications sont apparues. Le principe d'utilisation du template est similaire à celui de la version1 de FSB, a savoir les variables de templates, les balises spéciales, etc ... Les balises cependant changent de nom et de syntaxe. Il est important de savoir que ce système de template a été réalisé dans un seul et unique but : permettre aux personnes souhaitant créer des thèmes, d'avoir le plus possible d'outil à leur disposition afin de créer des combinaisons toujours plus uniques. Ce système permet en effet de créer n'importe quel type de templates, sans jamais devoir aller modifier les fichiers PHP.
{VARIABLE} est une simple variable de template. Elle peut s'utiliser n'importe ou dans le template concerné.
{block1.block2.VARIABLE} est une variable locale à un block. Elle ne peut donc s'utiliser que entre les balises de son block qui est block1.block2.
${variable} est une variable PHP, il suffit de créer une variable $foo dans le fichier PHP pour pouvoir l'utiliser dans le template sous la forme ${foo}. Il est aussi possible d'utiliser les tableaux PHP, par exemple :
Mon adresse IP est le ${_SERVER['REMOTE_ADDR']}
$VARIABLE est une variable de template pour les balises <if>, elle contient la même valeur que {VARIABLE}
$block1.block2.VARIABLE est une variable de block pour les balises <if>, elle contient la même valeur que {block1.block2.VARIABLE}
{LG_VARIABLE} prendra automatiquement la valeur de la variable de langue $lg['variable'], utilisez donc cette syntaxe pour ne pas surcharger le fichier PHP en assignement de variables de langues.
{block.ITERATOR} contient l'itération dans le block de template, à partir de 0 jusqu'à la fin de la boucle. Cette variable est très utilie pour alterner des styles un tour sur deux par exemple
{block.SIZEOF} contient le nombre de tours totaux pour le block
{block.FIRST_ROW} définit si on est ou non dans le premier tour du block
{block.LAST_ROW} définit si on est ou non dans le dernier tour du block
<block name=“block”> ... </block> sert à créer un block. Ce block correspond en gros à une boucle PHP qui va afficher X fois le même code HTML en faisant varier les variables de block. Il est possible d'imbriquer les blocks entre eux, si par exemple vous souhaitez imbriquer un block1 vous devrez utiliser cette syntaxe pour le second block :
<block name="block1"> Mon code HTML <block name="block1.block2"> Code HTML dans un second block </block> </block>
<blockelse name=“block”> ... </block> est à utiliser juste après un block pour afficher un code si le block ne comportait aucune itération. Par exemple :
<block name="mon_block"> J'execute mon block autant de fois qu'il y a d'itération avec une variable {mon_block.VAR} </block> <blockelse name="mon_block"> Par contre si le block n'a jamais éxécuté j'affiche une fois ce code </block>
Du point de vue PHP cette balise corespondrait au if () dans un code du type :
for ($i = 0; $i < $count; $i++) { echo 'test'; } if (!$count) { echo 'Si $count vaut 0, donc que la boucle n\'existe pas, j\'affiche ça'; }
<switch name=“mon_switch”> ... </switch> est un switch ayant comme nom mon_switch. Cette balise est une sorte d'intérupteur ouvert / fermé qui définit si on affiche ou pas le code situé entre la balise d'ouverture et de fermeture. Veuillez noter que si vous souhaitez faire un interupteur variable dans un block il est recommandé d'utiliser les instructions <if> (expliqué si dessous). Voici un exemple avec les switchs :
<switch name="mon_switch"> Code affiché si le switch est activé </switch>
Il est possible d'utiliser des opérateurs logiques dans les switch. Par exemple le code ci dessous s'executera si un des deux switchs foo ou bar est définit :
<switch name="foo | bar"> Code affiché si le switch est activé </switch>
l'opérateur & est aussi supporté, ainsi que les parenthèses :
<switch name=”(foo | bar) & myswitch”>
Code affiché si le switch est activé
</switch>
<if content=”...”> ... </if> est une instruction de controle. Elle permet de poser une condition et d'afficher le code HTML entre les deux balises, si cette condition est vraie. Le système de template utilise le moteur PHP afin de vérifier cette condition, aussi vous pouvez rendre votre condition aussi complexe que dans un if () PHP. Voici un exemple basique d'utilisation :
<if content="1 == 1"> Code affiché si 1 est égal à 1 (donc ce code sera affiché puisque la condition est vraie) </if>
Il est possible d'utiliser des variables de template dans les conditions, via la syntaxe que nous avons vu plus haut :
<if content="$VARIABLE == 'test'"> Code affiché si la variable de template VARIABLE vaut 'test' </if>
Enfin, il est possible d'utiliser des variables de blocks, et ainsi d'utiliser cette instruction sous forme de switch dans un block :
<if content="$forum.IS_READ == TRUE"> Code affiché si la variable IS_READ du block 'forum' vaut TRUE </if> <if content="$forum.IS_READ"> Code affiché si la variable IS_READ du block 'forum' vaut TRUE <else> Code affiché si la variable IS_READ du block 'forum' vaut FALSE </if> <if content="!$forum.IS_READ"> Code affiché si la variable IS_READ du block 'forum' vaut FALSE <else> Code affiché si la variable IS_READ du block 'forum' vaut TRUE </if>
<elseif content=”...”> est un équivalent du elseif () PHP, et permet de retester une condition si la première est fausse.
<else> est un équivalent du else PHP, et permet d'imposer le code qui suit si toutes les conditions ont échouées, par exemple :
<if content="$VARIABLE == 'test'"> Code affiché si la variable de template VARIABLE vaut 'test' <else> Sinon, si VARIABLE ne vaut pas 'test', on affiche ce code </if>
A notre qu'il est possible d'utiliser un <else> dans un switch, par exemple :
<switch name="mon_switch"> Code affiché si le switch est activé <else> Code affiché si le switch n'est pas activé </switch>
<include name=“fichier.html” /> permet d'inclure un fichier template dans un autre. La balise <include name=“fichier.html” /> sera remplacée par le contenu du fichier fichier.html, qui est un fichier dans le répertoire de template du forum.
<?php ... ?> permet d'utiliser du PHP dans le template, la syntaxe des balises est celle de PHP. Par exemple :
Je m'appel : <?php $name = 'skywalker'; echo $name; ?>
<variable name=”...” value=”...” /> permet de créer une variable de template et de lui donner une valeur. Par exemple :
<variable name="TEST" value="ceci est un test" />
affichage de la variable crée : {TEST}
Un petit plus qui pourra être utile dans certains cas, l'utilisation de fonctions PHP directement dans le template (donc sur des variable de templates par exemple). La syntaxe étant #mafonction{'argument1', 'argument2', 'etc ...'}. Un petit exemple :
Voici une variable de template affichée telle quelle : {VARIABLE}
Maintenant voici la même variable en majuscule : #strtoupper{$VARIABLE}
Voici un nombre entier arrondi : #round{$INT, 2}
Il est bien sur possible de passer plusieurs arguments aux fonctions ... Notez cependant que la fonction utilisée DOIT avoir une valeur de retour pour afficher quelque chose.
$tpl→set_file('alias', 'fichier.html'); sert à assigner un fichier template à un alias nommé ici alias.
$tpl→set_vars(array('VARIABLE' ⇒ 'valeur'), 'alias'); sert à assigner des variables de templates. Les clefs du tableau seront les noms des variables, avec une valeur de donné. L'alias à spécifié est facultatif, et est par défaut le dernier alias définit par la méthode set_file().
$tpl→set_blocks('block', array('VARIABLE' ⇒ 'valeur'), 'alias'); sert à créer un block et à lui donner des variables. Les clefs du tableau seront les noms des variables, avec une valeur de donné. L'alias à spécifié est facultatif, et est par défaut le dernier alias définit par la méthode set_file().
$tpl→set_switch('mon_switch', 'alias'); sert à créer un switch. L'alias à spécifié est facultatif, et est par défaut le dernier alias définit par la méthode set_file().
$tpl→unset_switch('mon_switch', 'alias'); sert à supprimer un switch. L'alias à spécifié est facultatif, et est par défaut le dernier alias définit par la méthode set_file().
$tpl→parse('alias') sert à parser le fichier template définit par son alias.
$tpl→prepare_file('alias') sert à signaler l'existence d'un alias, dont on ne connait pas encore le nom du fichier template. Par exemple :
(...) $tpl->prepare_file('main'); $tpl->set_vars(array( 'VAR' => 'valeur', 'VAR2' => 'autre', ); $tpl->set_file('main', 'fichier.html'); $tpl->parse('main'); (...)
Voici un exemple final de code PHP avec un code HTML, toute la partie initialisation n'a pas été mise (instance des classes, etc ...). Voici le fichier test.php :
(...) /* ** Affichage de la liste des membres */ $sql = 'SELECT u_id, u_login FROM ' . SQL_PREFIX . 'users WHERE u_id <> 0 ORDER BY u_login, u_id'; $result = $db->query($sql); $tpl->set_file('main', 'test.html'); $tpl->set_vars(array( 'TITLE' => 'Liste des membres', )); $user_exists = FALSE; while ($row = $db->row($result)) { $user_exists = TRUE; $tpl->set_blocks('user', array( 'LOGIN' => $row['u_login'], )); } if (!$user_exists) { $tpl->set_switch('no_user'); } $tpl->parse('main'); (...)
Le fichier test.html :
{TITLE}<br />
<block name="user">
<!-- On change le style un tour sur deux -->
<if content="$user.ITERATOR % 2">
<span style="color: #FF0000">
<else>
<span style="color: #0000FF">
</if>
{user.LOGIN}
</span>
</block>
<switch name="no_user">
Aucun membre
</switch>
Afin d'accélérer légèrement l'affichage des pages et d'économiser quelques ressources serveurs, les templates sont mis en cache (soit dans un fichier sur le FTP, soit dans la base de donnée si le répertoire ne possède pas les droits d'écriture). Pour comprendre l'utilité de la mise en cache il faut d'abord comprendre le fonctionement du parse du template. Lorsque la méthode $tpl→parse('alias') est appelée, elle fait fusioner le contenu du fichier template avec les variables de templates créées, le résultat obtenu est un mélange de code PHP et HTML, qui est ensuite éxécuté par PHP à l'aide de la fonction eval(). La phase de fusion est assez complexe et necessite l'appel de nombreuses fonctions PCRE (preg_match() et preg_replace() notament). La mise en cache consiste a sauvegarder cette fusion de façon a ne plus avoir besoin de repasser par la phase de fusion les autres fois, ce qui fait une belle économie.
Dans certains cas vous souhaiterez pouvoir récupérer le contenu d'un template afin de pouvoir l'afficher dans un autre template en le passant par une variable. Dans FSB1 il était possible de le faire, dans la version 2 vous ne pourrez pour la simple raison que les templates sont parsés différéments. Cependant il est possible d'obtenir le résultat que vous désirez, cela à l'aide de la balise <include>. Cette balise va inclure le contenu d'un autre template, en utilisant les variables de templates définies dans votre fichier PHP. Vous remarquerez que dans FSB2 cette balise est souvent utilisée, notament pour inclure headers et footers, afin de laissez une grande liberté aux graphistes.
Contributeurs : Grummfy