I. Introduction

Qu'est-ce qu'un système de template en PHP ? Il s'agit d'un moyen permettant à un programmeur PHP de travailler de son côté, tout en permettant à un graphiste XHTML par exemple de travailler du sien. Le programmeur PHP aura un fichier .php, le graphiste un fichier .tpl (template). Le système de template mettra en relation ces deux fichiers afin de n'en former plus qu'un seul à la fin.
L'intéret d'un tel système est justement de ne pas mélanger PHP et HTML, pour faciliter la vie des graphistes en général. PhpBB utilise donc un système de template qui lui permet de gérer les thèmes du forum sans jamais aller modifier les fichiers PHP, ce qui explique qu'il est si pratique de faire des thèmes pour ce forum.

I-A. Installer le système

Cette partie de concerne que ceux qui souhaitent utiliser ce système de template en dehors du cadre phpBB. Vous devez tout d'abord télécharger le fichier template.php disponible ici. Placez le ou vous voullez sur votre FTP et incluez le ensuite dans chaque fichier où vous comptez l'utiliser :

 
Sélectionnez
include('template.php');

II. 1. Les bases de l'utilisation du système

II-A. 1.1. Votre premier fichier parsé

Vous avez donc créer pour tester tout ce que nous allons faire dans le tutorial un fichier test.php ainsi qu'un autre test.tpl. Le premier fichier contient

 
Sélectionnez
<?php

include('template.php');

?>

le second :

 
Sélectionnez
<b>test !</b>

Maintenant nous allons faire communiquer les deux fichiers ensemble pour finalement afficher le résultat HTML, dans le .php mettez maintenant :

 
Sélectionnez
<?php

include('template.php');



// On créé une instance de la classe template, passez en paramètre le répertoire ou se trouvent tous vos fichiers templates

$template = new Template('./');



// On assigne a un alias "test" le nom du fichier .tpl qu'on compte utiliser

$template->set_filenames(array('test' => 'test.tpl'));



// On parse le fichier HTML, c'est à dire qu'on assigne aux fichier template toutes les données qu'on à créer dans le .php

$template->pparse('test');

?>

Le résultat visible à l'écran :

test !

II-B. 1.2. Les variables de templates

Vous pouvez créer dans votre fichier template des variables, qui seront renseignées depuis le fichier .php. La syntaxe des variables est {NOM_DE_LA_VARIABLE}.Par exemple dans votre fichier .tpl mettez :

 
Sélectionnez
Je m'appel <b>{NAME}</b> et mon adresse IP est : <i>{IP}</i>

Dans votre fichier .php mettez :

 
Sélectionnez
<?php

include('template.php');



// On créé une instance de la classe template, passez en paramètre le répertoire ou se trouvent tous vos fichiers templates

$template = new Template('./');



// On assigne a un alias "test" le nom du fichier .tpl qu'on compte utiliser

$template->set_filenames(array('test' => 'test.tpl'));



// On assigne un tableau de variables au template, en clef se situe le nom de la variable dans 

// le fichier .tpl, en valeur ce qu'on lui donne comme valeur

$template->assign_vars(array(

        'NAME' =>               'Genova',

        'IP' =>                 $_SERVER['REMOTE_ADDR'],

));



// On parse le fichier HTML, c'est à dire qu'on assigne aux fichier template toutes les données qu'on à créer dans le .php

$template->pparse('test');

?>

Le résultat visible à l'écran :

Je m'appel {NAME} et mon adresse IP est : {IP}

III. 2. Les blocs

III-A. 2.1. Créer un bloc

Les blocs sont des outils très pratiques qui correspondent à des boucles en PHP. Par exemple si vous souhaitez afficher X fois la même chose vous pourrez créer un bloc contenant ce que vous souhaitez afficher, et lui dire de s'afficher autant de fois que vous le souhaitez. Le plus simple est de voir ça en exemple. Dans votre fichier .tpl mettez ce code :

 
Sélectionnez
<!-- BEGIN mon_bloc -->

<b>Hello ! Mon nom est {NAME} et mon IP est : {IP}</b><br />

<!-- END mon_bloc -->

Maintenant dans votre fichier .php mettez ceci :

 
Sélectionnez
<?php

include('template.php');



// On créé une instance de la classe template, passez en paramètre le répertoire ou se trouvent tous vos fichiers templates

$template = new Template('./');



// On assigne a un alias "test" le nom du fichier .tpl qu'on compte utiliser

$template->set_filenames(array('test' => 'test.tpl'));



// On assigne un tableau de variables au template, en clef se situe le nom de la variable dans 

// le fichier .tpl, en valeur ce qu'on lui donne comme valeur

$template->assign_vars(array(

        'NAME' =>               'Genova',

        'IP' =>                 $_SERVER['REMOTE_ADDR'],

));



// On va afficher 5 fois le bloc

for ($i = 0; $i < 5; $i++)

{

        // Cette fonction va créer le bloc, a chaque passage elle empilera le bloc a la suite, c'est à dire que 

        // l'appeler 5 fois de suite va créer le bloc 5 fois

        $template->assign_block_vars('mon_bloc', array());

}



// On parse le fichier HTML, c'est à dire qu'on assigne aux fichier template toutes les données qu'on à créer dans le .php

$template->pparse('test');

?>

Le résultat visible à l'écran :

Je m'appel Genova et mon adresse IP est : 127.0.0.1
Je m'appel Genova et mon adresse IP est : 127.0.0.1
Je m'appel Genova et mon adresse IP est : 127.0.0.1
Je m'appel Genova et mon adresse IP est : 127.0.0.1
Je m'appel Genova et mon adresse IP est : 127.0.0.1

III-B. 2.2. Les blocs imbriqués

Vous pouvez imbriquer des blocs, de la même façon que vous imbriquez des boucles en PHP. Par exemple mettez dans votre fichier .tpl :

 
Sélectionnez
<!-- BEGIN mon_bloc -->

<b>Je suis dans le premier bloc</b><br />

        <!-- BEGIN mon_second_bloc -->

        <i>Je suis dans le second bloc moi par contre</i><br />

        <!-- END mon_second_bloc -->

<br />

<!-- END mon_bloc -->

Et dans votre fichier .php :

 
Sélectionnez
<?php

include('template.php');



// On créé une instance de la classe template, passez en paramètre le répertoire ou se trouvent tous vos fichiers templates

$template = new Template('./');



// On assigne a un alias "test" le nom du fichier .tpl qu'on compte utiliser

$template->set_filenames(array('test' => 'test.tpl'));



// On va afficher 3 fois le premier bloc

for ($i = 0; $i < 3; $i++)

{

        // Cette fonction va créer le bloc, a chaque passage elle empilera le bloc a la suite

        $template->assign_block_vars('mon_bloc', array());



        // On va afficher a chaque fois autant de fois le second bloc que $i

        for ($j = 0; $j < $i + 1; $j++)

        {

                // Veuillez noter que pour créer un second bloc dans un bloc parent, il faut les écrire avec la

                // notation mon_bloc.mon_second_bloc.mon_troisieme_bloc.etc ...

                $template->assign_block_vars('mon_bloc.mon_second_bloc', array());

        }

}

// On parse le fichier HTML, c'est à dire qu'on assigne aux fichier template toutes les données qu'on à créer dans le .php
$template->pparse('test');
?>

Le résultat visible à l'écran :

Je suis dans le premier bloc
Je suis dans le second bloc moi par contre

Je suis dans le premier bloc
Je suis dans le second bloc moi par contre
Je suis dans le second bloc moi par contre

Je suis dans le premier bloc
Je suis dans le second bloc moi par contre
Je suis dans le second bloc moi par contre
Je suis dans le second bloc moi par contre

III-C. 2.3. La notation des sous blocs

Comme expliqué dans les commentaires, vous remarquerez que lorsqu'on créé un bloc dans un autre bloc, celui ci est considéré comme son fils. Ainsi la notation du nom du block dans la méthode assign_block_vars() ne sera pas mon_second_bloc mais mon_bloc.mon_second_bloc. Ainsi pour un exemple de fichier template comme ceci :

 
Sélectionnez
<!-- BEGIN bloc1 -->

        <!-- BEGIN bloc2 -->

                <!-- BEGIN bloc3 -->

                <!-- END bloc3 -->

        <!-- END bloc2 -->

<!-- END bloc1 -->

Vous devrez faire mettre comme nom dans la méthode bloc1.bloc2.bloc3 pour afficher le troisième bloc. Veuillez noter qu'il ne faut pas appeler le troisième bloc si les deux premiers n'ont pas été appelé.

III-D. 2.4. Les variables de blocs

Nous avons vu dans la première partie du tutorial l'utilisation de variables simples. Ces variables sont accessibles en permanance dans le fichie template. Il est possible aussi de créer des variables spécifiques à des blocs, et de donner des valeurs différentes a ces variables à chaque tour du bloc. Nous allons voir ça avec un exemple, dans votre .tpl mettez :

 
Sélectionnez
Voici une variable globale au template qui vaut : {VAR_GLOBAL}<br />

<!-- BEGIN mon_bloc -->

<b>Hello ! Mon nom est {mon_bloc.NAME}</b><br />

<!-- END mon_bloc -->

Maintenant dans votre fichier .php mettez ceci :

 
Sélectionnez
<?php

include('template.php');



// On créé une instance de la classe template, passez en paramètre le répertoire ou se trouvent tous vos fichiers templates

$template = new Template('./');



// On assigne a un alias "test" le nom du fichier .tpl qu'on compte utiliser

$template->set_filenames(array('test' => 'test.tpl'));



// On assigne un tableau de variables au template, en clef se situe le nom de la variable dans 

// le fichier .tpl, en valeur ce qu'on lui donne comme valeur

$template->assign_vars(array(

        'VAR_GLOBAL' =>         'une certaine valeur',

));



// On créé un tableau

$ary = array('pierre', 'paul', 'jacques');



// La boucle prendra successivement les valeurs du tableau

foreach ($ary AS $value)

{

        // Cette fonction va créer le bloc, a chaque passage elle empilera le bloc a la suite

        $template->assign_block_vars('mon_bloc', array(

                'NAME' =>               $value,

        ));

}



// On parse le fichier HTML, c'est à dire qu'on assigne aux fichier template toutes les données qu'on à créer dans le .php

$template->pparse('test');

?>

Le résultat visible à l'écran :

Voici une variable globale au template qui vaut : une certaine valeur
Hello ! Mon nom est pierre
Hello ! Mon nom est paul
Hello ! Mon nom est jacques

III-E. 2.5. La notation des variables de blocs

Vous aurez remarqué que les variables de blocs portent comme syntaxe {bloc1.bloc2.blocN.VARIABLE}. Voici un exemple de fichier .tpl valide :

 
Sélectionnez
{VARIABLE_GLOBALE}

<!-- BEGIN bloc1 -->

        Bonjour {bloc1.VARIABLE1}

        <!-- BEGIN bloc2 -->

                <!-- BEGIN bloc3 -->

                voici {bloc1.bloc2.bloc3.VARIABLE3} ainsi que {bloc1.bloc2.VARIABLE2}

                <!-- END bloc3 -->

        <!-- END bloc2 -->

<!-- END bloc1 -->

Un exemple de fichier invalide avec les variables de blocs :

 
Sélectionnez
{VARIABLE_GLOBALE}

<!-- BEGIN bloc1 -->

        Bonjour {bloc1.VARIABLE1}

        <!-- BEGIN bloc2 -->

                <!-- BEGIN bloc3 -->

                voici {bloc1.bloc2.bloc3.VARIABLE3} ainsi que {bloc1.bloc2.VARIABLE2}

                <!-- END bloc3 -->

                Cette variable n'existe pas et est fausse : {bloc1.bloc2.bloc3.VARIABLE4}

        <!-- END bloc2 -->

<!-- END bloc1 -->

III-F. 2.6. Un exemple d'utilisation des blocs avec phpBB

Dans cette dernière partie concernant les blocs, nous allons voir un exemple concret sur l'utilité des blocs, en se servant des données de phpBB. Nous allons afficher la liste des membres. Dans votre fichier .tpl :

 
Sélectionnez
<table>

   <!-- BEGIN user -->

   <tr>

      <td>{user.ID}</td>

      <td>{user.NAME}</td>

   </tr>

   <!-- END user -->

</table>

Et dans le fichier .php, sans prendre en compte l'instance des classes et la connexion à la base de donnée :

 
Sélectionnez
// On prend les valeurs de la table phpbb_users

$sql = 'SELECT user_id, username FROM ' . USERS_TABLE;

$result = $db->sql_query($sql) OR die('erreur SQL');



$template->set_filenames(array('body' => 'test.tpl');



while ($user = $db->sql_fetchrow($result))

{

        // On affiche les membres ligne par ligne

        $template->assign_block_vars('user', array(

                'ID' => $user['user_id'],

                'NAME' => $user['username']

        ));

}



$template->pparse('body');

IV. 3. Solutions aux quelques erreurs que vous pourrez rencontrer

IV-A. 3.1. Template->make_filename(): Error - file (…)fichier.tpl dœs not exist

Cette erreur signifie que votre fichier .tpl n'a pas été trouvé, ou n'est pas accessible en lecture. Vérifiez le chemin mis lors de l'instance de la classe.

IV-B. 3.2. Parse error: parse error, unexpected $end in (…)template.php(127) : eval()'d code on line 114

Cette erreur signifie que vous avez une erreur de syntaxe lors de la fusion des fichiers PHP et template, normalement c'est que vous avez fait une erreur au niveau des blocs. Vérifiez bien que chacun de vos blocs <!-- BEGIN … --> sont fermés par des <!-- END … -->, que vous n'avez pas mis de caractères bizarres (ne mettez que des caractères alphanumériques pour les variables et les blocs), que vous n'avez pas oublier un espace dans la syntaxe du bloc.

IV-C. 3.3. Template->loadfile(): No file specified for handle alias

Cette erreur signifie que vous tentez d'utiliser un alias dans la méthode pparse() qui n'a pas été créé. Vérifiez bien la concordance avec la méthode set_filenames()