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

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.

{{tpl:tag}}

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

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.

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(); ?>';
	}
}

$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()').'; ?>';
	}
}

<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.

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.

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>.

$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); ?>';
	}
}

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.

$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)); ?>';
	}
}

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).