You are here: WikiStart/Docs/Developer/CustomFunctions

---

Custom Tags

Custom functions allow you to create new tags, and define how they should be handled. This way, you may hand over tools to the template designers, that they may use to insert any dynamic content. Think of a site, where your users may register as users and login with their usernames. You could create a new tag that retrieves the name from the database and displays it in the template. Other examples include a gettext implementation.

Using custom functions

Using a custom function is as easy as eating cheese cake. They can be used like the builtin tags tmpl, sub, var, etc.

<patTemplate:tmpl name="page">
<div>
   Today is <patTemplate:time format="m/d/Y"/>
</div>
</patTemplate:tmpl>

This will output "Today is [current date].", where [current day] will be replaced with the current date.

<patTemplate:tmpl name="root">
This is a template that is used to display code.
<patTemplate:phpHighlight>
<?PHP
$i = 0;
while( $i < 10 )
{
  echo "This is line $i.<br />";
  $i++;
}
?>
</patTemplate:phpHighlight>
</patTemplate:tmpl>

In the above example, the PHP code enclosed between the <patTemplate:phpHighlight> tags will be syntax highlighted in the output.

Creating a custom Function

Custom Functions have to be placed in patTemplate/Function and extended from patTemplate_Function. You have to implement one method that represents the function: string patTemplate_Function::call( array params, string content ) The reader will pass an associative array containing all attributes of your tag as well as a string as second parameter, which will contain all character data (and HTML tags) between the opening and closing tags. In this method you may compute the result and return it as a string. This result will then be inserted in the template instead of your function tag as well as the enclosed content. You may use all functions, that are located in the patTemplate/Function folder, as patTemplate will auto-load the classes. Template functions will be evaluated while analyzing the template, there's currently no way to use template variables or any input from the PHP script in the funcitons. Functions may be nested, patTemplate will always evaluate the innermost function first.

Code examples

This example is the code used for the custom function time, which is able to display the current time as well as reformat any timestamp you pass to this.

<?PHP
/**
 * patTemplate function that calculates the current time
 * or any other time and returns it in the specified format.
 *
 * @package       patTemplate
 * @subpackage    Functions
 * @author        Stephan Schmidt <schst@php.net>
 */
class patTemplate_Function_Time extends patTemplate_Function
{
   /**
    * name of the function
    * @access    private
    * @var       string
    */
    var $_name = 'Time';

   /**
    * call the function
    *
    * @access    public
    * @param     array    parameters of the function (= attributes of the tag)
    * @param     string   content of the tag
    * @return    string   content to insert into the template
    */ 
    function call( $params, $content )
    {
        if( !empty( $content ) )
        {
            $params['time'] = $content;
        }
        
        if( isset( $params['time'] ) )
        {
            $params['time'] = strtotime( $params['time'] );
        }
        else
        {
            $params['time'] = time();
        }
        
        return date( $params['format'], $params['time'] );
    }
}?>