Hyla Tpl
#tpl #template #phplib

• Accueil
• Introduction
• Documentation
• Exemples
• Téléchargement
• Actualité
• Promotion
• Aide / Bugs

Fonctionnalités

L'Api

Dans cette section sont décrit les méthodes utiles pour se servir convenablement de Hyla Tpl.

Le constructeur

Le constructeur s'utilise très simplement, dans l'exemple suivant, on va instancier Hyla_Tpl avec en paramètre le chemin vers le dossier contenant les fichier gabarit.
Ensuite, sur la ligne suivante, à l'aide de la méthode importFile, on importe le fichier test.tpl qui portera le nom de test.

<?php

require 'hyla_tpl.class.php';



$tpl = new Hyla_Tpl('tpl');

$tpl->importFile('test', 'test.tpl');



[...]

Liste des méthodes

Voici la liste des méthodes :

importFile(name, file, path)

Déclare un fichier de gabarit « file » portant le nom « name » dans le dossier « path » si il ne se trouve pas dans le dossier courant.

setCurrentFile(name)

Spécifie le fichier de gabarit courant, attention, il s'agit bien du nom du fichier donné en premier argument à la méthode importFile.

setVar(name, value)

Donne la valeur « value » à la variable de gabarit nommée « name », voir les variables

setVars(array)

Donne un tableau de valeurs de variables, voir les tableaux de variables

setL10nCallback(callback)

Déclare la fonction de rappel pour la traduction, voir principes de la traduction.

get(name)

Retourne le contenu du bloc nommé « name »

render(name)

Effectue un rendu du bloc nommé « name »

registerVarFunction(name, function_name)

Enregistre la fonction « function_name » appelable depuis la gabarit par « name », voir ajouter des fonctions de variables

registerFunction(name, function_name)

Enregistre la fonction « function_name » appelable depuis la gabarit par « name », voir ajouter des fonctions

getFunctionList(bool)

Retourne la liste des fonctions définies sous la forme d'un tableau, si la second argument est à true, les fonctions définies par l'utilisateurs seront aussi retournées.

removeUnknowVar(bool)

Permet de spécifier si le moteur de gabarit supprime les variables vides du gabarit ou non.

displayError(bool)

Spécifie si les erreurs doivent être affichée ou non

logError(bool)

Enregistre les erreurs

getVersion()

Retourne le numéro de la version (ex: 0.7.0)

Les variables

Depuis le controleur, il est bien sûr possible de donner des valeurs à des variables dans votre fichier template.
Cela se fait avec la méthode setVar.

$tpl->setVar('toto', 'Coucou');

Dans le fichier gabarit, on déclare la variable simplement comme ceci :

{$toto}

Tableau de variables

Il est tout à fait possible de spécifier à une variable un tableau ou un objet.
Dans ce cas, on accède aux éléments du tableau ou de l'objet à l'aide du . dans les 2 cas, on s'abstrait ainsi dans le gabarit du type de données.

// En spécifiant un tableau

$user = array('name' => 'Marc', 'age' => 23);

$tpl->setVar('user', $user);

// En spécifiant un objet

$obj = new user();

$obj->name = 'Paul';

$obj->age = 34;



$tpl->setVar('user', $obj);

Dans le fichier gabarit, on fera la même chose dans les 2 cas :

Je suis {$user.name} et mon age est de {$user.age} ans !

Fonctions pour les variables

Exemple 1 : Appel de fonction pour une variable

Il est possible d'envoyer le contenu d'une variable à des fonctions avec l'opérateur barre verticale (|) de la manière suivante :

<p>{$toto|upper}</p>

Si la variable toto vaut « coucou la terre ! », le résultat sera :

Exemple 2 : Appel de plusieurs fonctions

Il est possible de chainer les fonctions avec l'opérateur barre verticale | :

<p>{$toto|upper|ucfirst}</p>

Donnera ainsi :

Valeur par défaut pour les variables

Il est possible de définir des valeurs par défaut pour les variables qui ne serait pas remplies depuis le controlleur.

{$variable (Ma valeur par défaut) }

Renverra :

Il est également possible de spécifier la valeur par défaut avec une fonction de traduction de cette manière, voir la documentation sur la traduction pour plus d'information :

{$variable _(Hello World !) }

Mixons tout ça

Mixons tout ce que nous venons de voir sur les variables :

{$variable (<p>Ma valeur par défaut</p>)|upper|trim|escape}

Renverra ceci si la variable $variable est vide :

Renverra ceci si la variable $variable vaut « <p>Valeur de variable</p> » :

Ajouter des fonctions de variables

Hyla Tpl vous permet de définir des fonctions pour les variables directement depuis le controlleur à l'aide de la méthode registerVarFunction, voici un exemple d'utilisation.

[...]

function quote($var) {

    return "« $var »";

}



$tpl->registerVarFunction('quote', 'quote');

[...]

{$citation|quote}

Modification de variables dans la vue

Il est possible modifier la contenu d'une variable depuis la vue de deux manières différentes.

Utilisation de la fonction setVar

<p>{$toto}</p>

{!setvar:toto,'Variable toto créée !'}

<p>{$toto}</p>

{!setvar:toto,'Variable toto modifiée !'}

<p>{$toto}</p>

Affichera ceci :

Explication : La première fois que l'affichage de toto est demandée {$toto}, rien n'est retourné car $toto n'est pas déclaré et n'a pas de valeur par défaut, ensuite, le premier appel à setVar créée la variable $toto, et enfin, le second appel à setVar modifie $toto.

Utilisation de &

setVar et l'opérateur « & » diffère dans le fait que ce dernier change une fois pour toute la valeur d'une variable, ainsi, c'est le dernier appel qui l'emportera.

<p>{$toto}</p>

{&toto,'Variable toto créée !'}

<p>{$toto}</p>

{&toto,'Variable toto modifiée !'}

<p>{$toto}</p>

Affichera ceci :

Les blocs

Un bloc se défini comme ceci :

<!-- BEGIN line -->

<p>

   Contenu du bloc

</p>

<!-- END line -->

La génération d'un bloc se fait en appelant la méthode render.

[...]

$tpl->render('line');

$tpl->render('line');

[...]

Les 2 appels à render ci-dessus généront le code ci-dessous :

Ce sont les blocs du fichier de gabarit courant qui sont rendus, vous pouvez modifier le fichier courant avec la méthode setCurrentFile.
Vous pouvez aussi sélectionner le fichier de la manière suivante :

[...]

$tpl->render('menu:line');

[...]

Dans cet exemple, c'est le bloc line du fichier nommé menu qui sera rendu.

Les blocs else

Nouveauté très utile pour ceux qui viennent de la PhpLib, les blocs else permettent d'afficher un contenu d'un bloc else uniquement lorsque le bloc principal n'a pas été appelé, simplifiant alors le code php.

Un bloc else se défini comme ceci :

<!-- BEGIN line -->

<p>

   Contenu du bloc

</p>

<!-- ELSE line -->

<strong>

    Jamais appelé !

</strong>

<!-- END line -->

Si le bloc line n'est jamais appelé, le contenu du bloc else sera affiché :

Fonctions

Il est possible d'appeler des fonctions directement depuis la vue afin de réaliser certaine actions.

Exemple avec la fonction cycle :

<table>

  <!-- BEGIN line -->

  <tr>

    <td>{!cycle:'Rouge','Jaune'}</td>

  </tr>

  <!-- END line -->

</table>

Si le rendu de line est appelé 4 fois, cela produira le source suivant :

Bien sûr, il existe d'autres fonctions et il est possible d'en ajouter soi-même.

Liste des fonctions prédéfinies

Voici la liste des fonctions prédéfinies, en bleu, le nom de la fonction, en vert, le ou les arguments :

cycle:odd,even,cycle

Permet d'afficher le contenu des paramètres odd et even de manière cyclique avec la fréquence cycle

include:file

Inclu un fichier tpl depuis le dossier défini de tpl défini dans le constructeur (footer.tpl)

import:file

Importe un fichier tpl depuis n'importe quel location (/home/user/tpl/info.tpl)

errors:html

Renvoie la liste des erreurs, si le premier paramètre est à true (par défaut), l'affichage se fera sous forme de html.

setvar:name,value

Modifie une variable

l10n:var

Fonction de traduction

Ajouter des fonctions

Hyla Tpl vous permet de définir des fonctions directement depuis le controlleur à l'aide de la méthode registerFunction, voici un exemple d'utilisation.

[...]

function hello($name = null) {

    return "Hello $name !";

}



$tpl->registerFunction('hello', 'hello');

[...]

Un appel depuis le gabarit à la fonction hello :

{!hello}

Provoquera alors l'affichage suivant :

Un appel depuis le gabarit à la fonction hello avec un paramètre :

{!hello:'world'}

Provoquera alors l'affichage suivant :

La traduction

Il est possible, simplement, de rendre votre gabarit prêt pour une diffusion en plusieurs langues.

Voici un exemple :

[...]

function l10n($var) {

    global $lang;

    if ($lang == 'en')

        return $var;



    $l10n = array(

        'Hello'         =>  'Bonjour',

        'Hello world !' =>  'Bonjour monde !',

    );

    return (array_key_exists($var, $l10n) ? $l10n[$var] : $var);

}



$tpl->setL10nCallback('l10n');

[...]

<p>{_Hello}</p>

<p>{_Hello world !}</p>
    

En fait, le comportement est très simple, lorsque Hyla Tpl rencontre une balise {_XXxxxXXX}, elle appelle la fonction définie par setL10nCallback et affiche le résultat renvoyé par cette dernière.
Par défaut, c'est la méthode _l10n de la classe hyla_tpl qui est appelé, celle-ci retourne tout simplement ce qu'on lui passe dans le premier paramètre.