Création d’une balise tpl pour un plugin ou un thème

Introduction

Pour un plugin ou un thème, les balises tpl ne sont pas toujours suffisantes, on a alors besoin de créer une balise tpl. Ces fonctions doivent être placées dans le fichier _public.php d’un plugin ou d’un thème.

Il existe 2 types de balises tpl.

Important :

Les fonctions tpl doivent retourner un bloc de code PHP, qui sera interprété à chaque affichage de la page. Si vous retournez du code HTML, il sera stocké dans le cache et ne pourra être changé qu’en le vidant.

Les valeurs

{{tpl:tag}}

Ce type de balise retourne une chaîne de caractères.

Déclaration de la balise

Elle se fait avec la fonction addValue() :

$core->tpl->addValue('CoreVersion',array('tplMyMoreTpl','CoreVersion'));

Le premier paramètre est le nom de la balise tpl. La balise s’appelera CoreVersion

Le second paramètre doit indiquer une classe et une fonction de cette classe. Ici la fonction CoreVersion de la classe tplMyMoreTpl sera appelée.

La classe et la fonction

class tplMyMoreTpl
{
	public static function CoreVersion($attr)
	{
		$f = $GLOBALS['core']->tpl->getFilters($attr);
 
		return
		'<?php echo '.sprintf($f,'$GLOBALS["core"]->getVersion()').'; ?>';
	}
}

Cette fonction affiche la version de Dotclear. Le paramètre de la fonction et sa première ligne servent à utiliser les attributs des balises de template.

S’il n’est pas nécessaire de les utiliser, la fonction peut être simplifiée :

class tplMyMoreTpl
{
	public static function CoreVersion()
	{
		return
		'<?php echo $GLOBALS["core"]->getVersion(); ?>';
	}
}

Le code complet

$core->tpl->addValue('CoreVersion',array('tplMyMoreTpl','CoreVersion'));
 
class tplMyMoreTpl
{
	public static function CoreVersion($attr)
	{
		$f = $GLOBALS['core']->tpl->getFilters($attr);
 
		return
		'<?php echo '.sprintf($f,'$GLOBALS["core"]->getVersion()').'; ?>';
	}
}

Attention :

Notez bien que si la définition de la fonction se fait dans la classe, sa déclaration au moteur dotclear se fait en dehors de la classe.

Les blocs d’instruction

<tpl:tag>
...
</tpl:tag>

Cette balise est de type bloc. La différence avec les balises valeur décrites au dessus réside dans les marqueurs sur les cotés (< et > à la place de {{ et }) et sur leurs comportements. Ces balises retournent un bloc d’instructions en PHP permettant de faire des boucles et d’y insérer ce que l’on souhaite comme des conditions, test, etc.

Déclaration de la balise

Elle se fait non plus avec la fonction addValue() mais avec addBlock() :

$core->tpl->addBlock('EntryIfPosition',array('tplMyMoreTpl','EntryIfPosition'));

Le premier paramètre est le nom de la balise tpl. La balise s’appellera EntryIfPosition

Le second paramètre doit indiquer une classe et une fonction de cette classe. Ici la fonction EntryIfPosition de la classe tplMyMoreTpl sera appelée.

La classe et la fonction

class tplMyMoreTpl
{
	public static function EntryIfPosition($attr,$content)
	{
		$is = isset($attr['is']) ? trim($attr['is']) : '';
		$expr = self::testInExpr($is,'$idx');
		return
		'<?php $idx = $_ctx->posts->index()+1; if ('.$expr.'): ?>'.
		$content.
		'<?php endif; unset($idx); ?>';
	}
}

Cette fonction vérifie la position du billet (1er, 2e, 3e, etc.) par rapport à l’argument "is" spécifié, qui contient la liste des positions acceptées, séparées par des virgules. Elle prend en paramètres deux variables :

  • $attr qui est un tableau de données. Il permet de passer des paramètres à partir de la balise comme <tpl:EntryIfPosition is="1"> puis de les récupérer dans la fonction par $attr['is']
  • $content qui est le contenu entre les balises <tpl:EntryIfPosition is="1"> et </tpl:EntryIfPosition>.

Attention :

Ce dernier argument est très important, il ne faut surtout pas l’oublier lorsque l’on crée des balises de type bloc sinon la boucle ne prendra pas en compte ce que vous avez écrit entre les deux balises.

Le code complet

$core->tpl->addBlock('EntryIfPosition',array('tplMoreTpl','EntryIfPosition'));
 
class tplMoreTpl
{
	public static function EntryIfPosition($attr,$content)
	{
		$is = isset($attr['is']) ? trim($attr['is']) : '';
		$expr = self::testInExpr($is,'$idx');
		return
		'<?php $idx = $_ctx->posts->index()+1; if ('.$expr.'): ?>'.
		$content.
		'<?php endif; unset($idx); ?>';
	}
}

Démonstration de l'influence du cache des templates

Le code suivant utilise la fonction mt_rand(1, 1000) pour générer un nombre aléatoire entre 1 et 1000. Dans la première fonction Cache() le nombre est généré puis directement retourné par la fonction et sera inscrit tel quel dans le fichier du cache. Dans la seconde fonction NoCache() le nombre n'est pas stocké dans le fichier du cache, la fonction est évaluée à chaque affichage et le nombre sera différent.

Important :

Si la valeur tpl_use_cache est à non dans about:config, il n'y aura jamais de mise en cache et les 2 fonctions auront le même comportement.
$core->tpl->addValue('MTRandCache',array('tplMyTest','Cache'));
$core->tpl->addValue('MTRandNoCache',array('tplMyTest','NoCache'));
 
class tplMyTest
{
	public static function Cache()
	{
		$mt_rand = mt_rand(1, 1000);
 
		return
		'<?php echo(\''.$mt_rand.'\'); ?>';
	}
 
	public static function NoCache()
	{
		return
		'<?php echo(mt_rand(1, 1000)); ?>';
	}
}

Astuce :

Ces fonctions n'utilisent pas les filtres qui sont destinés aux chaînes de caractères, ils n'auraient aucun effet sur un nombre.

Le code à utiliser dans votre fichier template :

<p>{{tpl:MTRandCache}} = {{tpl:MTRandNoCache}}</p>

En forçant le rafraîchissement du cache de votre navigateur (avec les touches Ctrl + F5 ou Ctrl + R) vous devriez voir le second nombre varier alors que le premier nombre restera constant.

(Exemples tirés du plugin myMoreTpl de Kozlika) (partie Les blocs d’instruction rédigée par Tomtom33).

Wiki powered by Dokuwiki.