====== Creation of a tpl tag for a plugin or a theme  ======

===== Introduction =====

For a plugin or a theme, existing [[2.0:resources:themes:tags|tpl]] tags are not always enough, and we sometimes need to create our own. For this purpose, we have to write functions in the _public.php file of the plugin/theme.

There are two kinds of tpl tags : value tags and instruction blocks.

<note important>
A tpl function must return a PHP code, which will be interpreted every time the page is displayed. If the function returns HTML code, the content will be stored in the cache and will change only when the cache is cleared.
</note>

===== Values =====

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

This kind of tag returns a string.

==== Declaration statement ====

The declaration is made with the ''addValue()'' function :

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

The first parameter is the tpl tag name. Here, its name is ''CoreVersion''.

The second parameter indicates a class, and a function belonging to this class. Here, the ''CoreVersion'' function of the ''tplMyMoreTpl'' class will be called.

==== Class and function ====

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

This function displays Dotclear's version number. The first line of the function allows us to use [[2.0:resources:themes:tags:common-tag-filters|template tags attributes]].

They are not always necessary so the function could be simplified :

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

==== Complete code ====

<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>
The declaration statement is made outside of the class.
</note>

===== Instructions blocks =====

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

This is a **block** tag. The difference between **value** tags and **block** tags lies in their syntax (<tpl:tag> instead of {{tpl:tag}) but also their behaviors. **Block** tags return a block of PHP code that allows loops, conditional loops, etc.

==== Declaration statement ====

In this case, the function ''addBlock()'' is used instead of ''addValue()''

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

The first parameter is the tpl tag name. Here, its name is ''EntryIfPosition''.

The second parameter must be a class and a function belonging to this class. Here, the function ''EntryIfPosition'' of the ''tplMyMoreTpl'' class will be called.

==== Class and function ====

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

This function checks a post's position compared to the "is" argument that contains accepted position, separed by comas. The function takes two parameters :
 * **$attr** which is an array. This way, the parameter "is" of this tag ''<tpl:EntryIfPosition is="1">'' can be retrieved in the function using ''$attr['is']''.
  * **$content**  which is the content between the ''<tpl:EntryIfPosition is="1">'' and ''</tpl:EntryIfPosition>'' tags.

<note warning>
This last parameter is very important. Forgetting it would mean the loop won't care for the content placed in between the tags.
</note>

==== Complete code ====

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

===== Demonstration of the template cache influence =====

The following code uses mt_rand(1, 1000) in order to generate a random number between 1 and 1000. In the first function ''Cache()'', the number is generated then directly returned by the function and written as such in the cache. In the second function ''NoCache()'', the number is not stored in the cache : the function is evaluated for every display, thus the number will be different every time.

<note important>
If ''tpl_use_cache'' is set to false in about:config, these two functions will have the same behavior as nothing will be stored in cache.
</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>
These functions don't use filters : filters are meant to be used on strings and would have no effect on numbers
</note>

The code to add in your template file is :

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

Forcing the refresh of the page (with  ''Ctrl'' + ''F5'' or  ''Ctrl'' + ''R'') will change the second number but not the first one.

//(Examples are from the plugin myMoreTpl by Kozlika) (//Instruction blocks// written by Tomtom33).//