iGalerie

Documentation d'iGalerie 2

Le système de template

iGalerie utilise un système de template de type PHP natif. Cela signifie que les fichiers de template sont des fichiers PHP (ils possèdent l'extension tpl.php) dans lesquels on peut écrire directement du code PHP qui sera interprété tel quel. Ces fichiers contiennent essentiellement du code HTML (éventuellement un peu de Javascript et de CSS aussi) et sont construits exactement comme le sont les fichiers HTML d'un site Web classique. On y ajoute simplement du code PHP pour rendre cela dynamique (c'est à dire construire des pages avec un contenu différent selon la requête de l'utilisateur, les données en provenance de la base de données, des événements, etc.).

Exemple de code de template PHP utilisé dans iGalerie :

<?php if ($tpl->disImage('desc')) : ?>
	<p id="image_description"><?php echo $tpl->getImage('desc'); ?></p>
<?php endif; ?>

Explications. Avec $tpl->disImage('desc'), on cherche à savoir si une description est disponible. Si oui, on l'affiche grâce à $tpl->getImage('desc').

Fichiers de template

Tous les fichiers de template sont situés dans un sous-répertoire du répertoire template. Chaque sous-répertoire correspond à un "thème", qui peut être choisi dans la section Thèmes de l'interface d'administration. Le nom de ce sous-répertoire correspond au nom du thème tel qu'il s'affichera dans cette section. Tous les fichiers de template doivent obligatoirement avoir l'extension tpl.php.

Chaque thème doit également posséder un fichier index.tpl.php, qui correspond au fichier de template principal, c'est à dire celui qui sera inclus en premier. Ce fichier peut ainsi contenir les éléments présents sur chaque page de la galerie, comme le doctype, l'en-tête, le pied de page, etc. Ce fichier doit à son tour inclure le fichier de template correspondant à la section courante de la galerie, via cette ligne :

<?php $tpl->inc('page'); ?>

Cette ligne est donc également obligatoire. Pour chaque section de la galerie correspond donc un fichier de template dont le nom correspond la plupart du temps au nom d'URL de la section, où seul le caractère "-" est remplacé par "_". Par exemple, la page des images a pour nom d'URL "image", comme avec "?q=image/15-un-titre". Le fichier de template correspondant à cette section est donc image.tpl.php. Pour la page de création d'une nouvelle catégorie ("?q=new-category"), le fichier de template est new_category.tpl.php.

Méthodes de template

Les méthodes de templates ont été structurées de manière très simple et cohérente. Toutes les données sont récupérées à l'aide de l'objet $tpl qui est déjà instancié par iGalerie. Il n'y a pas à s'en préoccuper, mais juste à s'en servir puisqu'il est disponible dans tous les fichiers de template. Avec lui, on dispose de trois grandes familles de méthodes possédant un préfixe différent selon la fonction qui la caractérise :

  • Méthodes pour la récupération de données (préfixe get) :
    string|integer $tpl->getMethodName([string $arg])
    Fonction : récupérer des données.
    Exemple : afficher le message d'un commentaire :
    <?php echo $tpl->getComment('message'); ?>
    
  • Méthodes pour les structures conditionnelles (préfixe dis) :
    boolean $tpl->disMethodName([string $arg])
    Fonction : déterminer si une composante de la galerie est disponible ou peut être affichée.
    Exemple : déterminer si le commentaire a été posté par un administrateur :
    <?php if ($tpl->disComment('admin')) : ?>
    [...]
    <?php endif; ?>
    
  • Méthodes pour les boucles (préfixe next) :
    boolean $tpl->nextMethodName()
    Fonction : condition d'une boucle while.
    Exemple : créer une boucle sur les commentaires :
    <?php while($tpl->nextComment()) : ?>
    [...]
    <?php endwhile; ?>
    

Il existe deux exceptions, deux méthodes spéciales qui n'entrent dans aucune de ces familles :

  • inc()
    Cette méthode sert à inclure des fichiers "dynamiques", c'est à dire des fichiers différents selon l'action effectuée par l'utilisateur.
  • displayErrors()
    Cette méthode sert à indiquer à iGalerie que les erreurs peuvent être affichées à partir de l'endroit où elle a été appelée. Elle n'a d'effet que si l'option Afficher les erreurs au moment où elles se produisent de la section Options / Avancé est décochée. Si par exemple une erreur PHP s'est produite avant le chargement du template, cette erreur ne sera pas affichée immédiatement; elle le sera uniquement à l'endroit où displayErrors() a été appelé.

Deux points importants sont à noter :

  • Toutes les méthodes de template n'acceptent qu'un seul argument ou aucun.
  • Certaines méthodes ne sont disponibles que pour la ou les page(s) pour lesquelles elles sont destinées. La méthode getAddComment(), par exemple, n'est disponible que pour la page des images. A l'inverse, la méthode getGallery() sera disponible dans tous les fichiers de template.

Il existe des dizaines de méthodes de template. Une méthode peut posséder un argument au maximum, mais cet argument peut prendre plusieurs dizaines de valeurs possibles. Par exemple, pour la page où sont affichées les vignettes des images (fichier album.tpl.php), il y a la méthode getThumb(), qui permet de récupérer toutes les informations utiles pour générer ces vignettes, telles que : statistiques de l'image, identifiant de l'image, dimensions de la vignette, etc. Pour récupérer l'identifiant de l'image, on va utiliser $tpl->getThumb('id'); pour récupérer la hauteur de la vignette, on va utiliser $tpl->getThumb('height'); pour récupérer le titre de l'image on va utiliser $tpl->getThumb('title'); etc.

Dernière modification : 14/04/2011