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

===== Introduction =====

Pour un plugin ou un thème, les balises [[2.0:resources:themes:tags|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.

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

===== Les valeurs =====

<code tpl>
{{tpl:tag}}
</code>

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

==== Déclaration de la balise ====

Elle se fait avec la fonction ''addValue()'' :

<code php>
$core->tpl->addValue('CoreVersion',array('tplMyMoreTpl','CoreVersion'));
</code>

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

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

Cette fonction affiche la version de Dotclear. Le paramètre de la fonction et sa première ligne servent à utiliser les [[2.0:resources:themes:tags:common-tag-filters|attributs des balises de template]].

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

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

==== Le code complet ====

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

<note warning>
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.
</note>

===== Les blocs d’instruction =====

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

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()'' :

<code php>
$core->tpl->addBlock('EntryIfPosition',array('tplMyMoreTpl','EntryIfPosition'));
</code>

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

<code php>
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); ?>';
	}
}
</code>

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

<note warning>
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.
</note>

==== Le code complet ====

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

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

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

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

<note tip>
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.
</note>

Le code à utiliser dans votre fichier template :

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

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