Escape characters

A character can be escaped with a backslash (\). In the text, three characters can be escaped. Those are:

• Open and close curly braces: '{' and '}'.
• Newlines: 'n'.
• The escape character, backslash: '\'.

The next example shows how to escape those characters:

Draw line: \{ (4, 10), (3, 5) \}
Game path: C:\\Program files\\games\\
Multiple \
lines \
becomes one

The output of the template is without the backslash and the characters appear normally:

Draw line: { (4, 10), (3, 5) }
Game path: C:\Program files\games\
Multiple lines becomes one

Literal tags

Literal tags are used when the text needs to be processed as it is (literally). The curly braces don't need to be escaped and escape characters can be used. Usually javascript is surrounded by literal tags in the templates. The curly braces don't need to be escaped.

The next example demonstrates how the escaped characters from the previous example can be omitted with literal tags:

{literal}
Draw line: { (4, 10), (3, 5) }
Game path: C:\Program files\games\
{/literal}

Code comments

Code comments start and end with:'{*' and '*}' tags, respectively. Everything inside those tags is considered as comment:

{* Variable $i alternates the value 0 and 1 *}
{$i = 1 - $i}

{* {if $i == 0}
      {$i = 1}
   {else}
      {$i = 0}
   {/if}
*}

Writing only {$i = 1 - $i} would have had the same output.

Multi-line in-line comment

Multi-line in-line comments are created using /* and */. Use this comment to comment a part of a line or comment multiple lines:

{var $a = 1, /*$b = 2, */ $c = 3 }

{$a = 2, /*
 $b = 3,
 $c = 4
 */}

If the result after removing the in-line comments is an empty block then the block will be ignored. The next example has an empty block that won't be visible in the output:

{ /* var $a = 1 */ }

And is of course the same as writing: { }. The empty block will be ignored.

Single-line in-line comment

Single-line in-line comments are created using two slashes: // . Use this to start a comment which continues to the end of the line or until the closing curly brace '}':

{var $a = 1, // $b = 2,
 $c = 3}

{$a = 4 //, $b = 5, $c = 6}

This example declares the variables $a and $c and assigns in the second statement the value 4 to variable $a.

Boolean

The boolean type contains either the value: true or the value false. The next example set the $isValid variable to true.

{var $isValid = true}

Some of the operators return boolean values. An example is the '==' operator. The Expressions section discusses the operators in more detail. The next example uses the '==' operator:

{var $isValid = ($number == 6) }

It checks first whether the variable $number is equal to the value 6. The result is either true or false. The result is assigned to the variable $isValid.

Integer

Integers are specified in a decimal notation only. To use octals or hexadimals the number needs to be converted with the appropriate function. Examples are:

{2}
{4}
{math_hex_to_dec("1F")}

See the methods: math_bin_to_dec, math_hex_to_dec, math_oct_to_dec, math_dec_to_bin, ath_dec_to_hex, and math_dec_to_oct for more information about those conversions.

Float

Floating point numbers are values that contain a real value. Some examples:

{1.0}
{-100.234214}
{3.14}

It is also possible to express an exponent in the float. The exponent is marked with the character 'e' or 'E' followed by one or more digits:

{1.0e3   // 1000  }
{2e4     // 20000 }
{1e-2    // 0.01  }
{0.1e-2  // 0.001 }
{-3.1e2  // -310  }

String

The string consist of a series of characters enclosed between single or double quotes:

{'a string'    // Using single quotes }
{"hello world" // Using double quotes }

In the string we use the backslash (\) as escape character. For the single quoted string the escape characters are:

Examples of the single quoted strings are:

{'This string contains a \'quotes\' and backslashes (\\).'}
{'A single \ works also.'}
{'Characters like \n, \t, ", {, }, $, etc can be used without problems'}

The double quoted string allows more special characters than the single quoted string. Most useful escape characters are probably the variables and newlines that can be included in the string. The escape characters for the double quoted strings are:

The next example inserts newlines in the string:

{"Hello\nHello"}

The output of the template above is:

Hello
Hello

Some other examples of using single and double quoted strings:

{" a \"quoted\" string "}
{'Newlines are added with the \\n command.'}
{'\tThis string starts with a tab (\\t).'}

Array

The array is just like in PHP an ordered map. It can be used as an array or as a table that maps values to keys. There are two ways to create an array. The first method has the following syntax:

array( [ key => ] value, [ key2 => ] value2, ... )

The parts between brackets are optional. So the key can be omitted. In that case, it would simply create an array. First value has the index 0, the next value has index 1, and so on. The next example creates an array which consists of 3 elements:

{var $names = array( "Bernard", "Manny", "Fran" )}

The array values, and in this case the names, can be accessed:

{$names[0] // Outputs "Bernard"}
{$names[2] // Outputs "Fran"}
{$names[3] // Is not allowed }

The array with keys maps the key to a value:

{var $personInfo = array( "first_name" => "Bernard", "last_name" => "Black" ) }

To access the information:

{$personInfo["first_name"] // Outputs "Bernard"}
{$personInfo["last_name"] // Outputs "Black"}

The second method to create an array is to use the .. (dot-dot) operator

<number1>..<number2>

The operator creates an array that contains the numbers from number1 to number2. The next example creates an array that contains the numbers: 3, 4, 5, 6, and 7.

{var $nrs = 3..7 } {$nrs[0] // Outputs 3}

This method is especially useful to use in a foreach loop. The following example loops 10 times, and prints the number from 1 until 10:

{foreach 1..10 as $i}
    Number: {$i}
{/foreach}

The Foreach section describes this loop in more detail.

Object

Objects are only available when they are sent from the user application. It is not possible to create an object inside the Template language. The template language restricts the accessibilities from the object only to its properties; thus function calls are not permitted. The next example is a part of an user application that sends an object to a template:

1. <?php
3. class MyClass
4. {
5. public function __get( $name )
6. {
7. return "Hello $name";
8. }
10. public function __set( $name, $value )
11. {
12. throw new Exception ("Setting $name is not allowed");
13. }
14. }
16. $t = new ezcTemplate();
17. $t->send->obj = new MyClass; // Create an object and assign it to "obj"
18. $t->process("my_template.ezt");
20. ?>

The class in the example above has two 'magic' PHP functions. Fetching any property is allowed, whereas setting a property value throws an Exception. The template code that belongs to the user application:

{use $obj // Import the "obj" }

{$obj->Bernard // Calls the  __get method on the object which returns "Hello Bernard"}
{$obj->Bernard = "Fran" // Calls the __set method that throws an exception}

More information about importing objects is described in the External variable declaration (use) section.

Local variable declaration (var)

The declaration of a local variable creates a variable that has only a value inside the current template.

The syntax to declare a local variable is:

{var $<unique_name> [ = <value> ] [ , $<unique_name2> [ = <value> ] ] }

One or multiple variables can be declared with one var statement. A value can be assigned to the variable name, directly. If no value is given to the variable, then it will get the default value null.

The next example declares four variables at the same time:

{var $a = 2, $b = "Hello World", $c = true, $d}

All variables are initialized to a value. (The last variable is initialized to null.)

External variable declaration (use)

The declaration of an external variable creates a variable that usually has a value from outside the current template. Outside the current template is, for example, the application that compiles and executes the template.

The syntax for this type of variable is as follows:

{use $<unique_name> [ = <value> ] [ , $<unique_name2> [ = <value> ] ] }

Besides the use tag it is the same syntax as a local variable declartion.

The variable will be imported from the user application or another template and is now available in the current template. If the declared use variable is not sent to the current template an exception will be raised unless the declared variable is initialized to a value.

{use $a, $b = 2}

Variable $b will be assigned to the value 2 if the variable is not sent to the template. Variable $a will raise an Exception when the variable is not sent.

The next example shows a part of the user application:

$t = new ezcTemplate();

// Send some information to the Template
$t->send->item1 = "Toaster";
$t->send->item2 = "Manny";

// Process the template and print it.
echo $t->process();

The variables $item1 and $item2 are now available in the template if they are declared with use:

{use $item1 = "unknown", $item2 = "unknown"}

Use {$item1} on {$item2}

Cycles

A cycle is a special type of variable that contains a set of values. The cycle variable must be assigned to an array. Values are retrieved one array element at the time. Specific control structures are available to cycle through the set of values. The syntax for the cycle is:

{cycle $<unique_name> [ = <array_value> ] [ , $<unique_name2> [ = <array_value> ] ] }

An array must be assigned to the cycle variable. Otherwise the template compiler may give a compiler error. (Sometimes it is not possible to know at compile time whether the assignment is an array or not.)

The next example declares a cycle, assigns a value, and retrieves the first and second value:

{cycle $rgb = array( "red", "green", "blue" ) }

{$rgb // Print "red"}
{$rgb // Print "red"}
{increment $rgb // Go to the next element}

{$rgb // Print "green"}

See the Increment, Decrement and Reset section for more information.

Scopes

Variable declarations must be done at the highest scope of the template. Declaring a variable in a lower scope will result in a compiler error.

Scopes are usually opened and closed with a start and end template block. Template blocks that open a new scope are: {if .. }{/if}, {while ..} {/while}, {foreach ..} {/foreach}, {switch .. } {/switch}, etc. The next example demonstrates this scoping:

{var $a = 2  // Correct }

{if 2 == 3}
    {* This opens a new scope *}

    {var $b // ERROR! }
{/if}

Returning variables

Templates itself can also return variables to the user application or other templates. The return statement defines the variables that need to be returned:

{return ( <expression> as <variable> | <variable> ) [, ( <expression> as <variable> | <variable> ), ... ] }

The return statement returns one or multiple variables. The caller of the template can retrieve the return values. Consider the following template:

{* Return 6! and "Hello world" *}

{var $fac6 = 6 * 5 * 4 * 3 * 2 }
{return $fac6, "Hello world" as $helloWorld}

The user application can retrieve these values via the receive property of the template. See the next example for a demonstration:

$t = new ezcTemplate();

// Process the template.
$t->process();

// Retrieve the values from the return.
$fac6 = $t->receive->fac6;
$hw   = $t->receive->helloWorld;

// Output Hello world:
echo $hw;

More information about returning variables is described in the Include section.

Capturing content into variables

Sometimes it's useful to capture a specific part of a template in a variable for reuse. This you can do with the capture statement:

{var $var}
{capture $var}
Add some content.
{/capture}

Output it a few more times:
{$var}
{$var}

Be aware that you still have to declare the variable with the {var} block.

Arithmetic operators

The arithmetic operators can be used on all expressions which return a numerical value. The operator itself returns also a numeric value. The table below describes the available arithmetic operators:

Note: The negation in this table is the arithmetic negation. Don't confuse this with the logic negation.

The unary plus operator can also be used, but it doesn't affect the value. It's usually used to clarify that it's not a negative value.

Examples:

{ 2 + 5     // Returns value 7}
{ 2 - 5 }
{ 4 + 3 * 2  // Due to the operator precedence, first the *
             // will be evaluated and thereafter the +. }

{var $a = 2}
{var $b = -$a}

Comparison operators

All comparison operators return a boolean value. The left-hand side and right-hand side should be of the same type. The available comparison operators are:

Examples:

{ 4 == 5 }
{ 2 <= 5 }
{ true != false }
{ 4 == 5 == 6 }

The last example compares 4 with 5. This returns the boolean false. After the first step the comparison is:

{ false == 6 }

The number 6 will be changed into a boolean. Every number except zero will get the boolean value true. Basically the last step of the comparison is:

{ false == true }

And this return the boolean value false.

Logical operators

The logical operators are used on all expressions which return a boolean value. The operator returns also a boolean:

Some usage examples:

{ true || false }
{ $a == 5 && $a != 7 }
{ $a || $b }

XHTML Context

The XHTML Context escapes the HTML characters from the output from the expression blocks. Output outside the blocks are not escaped. See the next example:

{var $lt = "3 < 5"}
<b>{$lt}</b>

This template contains the HTML character '<' in an expression block. This character will be escaped. The output of the template is:

<b>3 &lt 5</b>

The escape characters of the XHTML context are:

If the HTML characters in the expression block should not be escaped then the "raw" block should be used. The next example demonstrates a "raw" block:

{var $myBoldText = "<b>Hello world</b>}

{raw $myBoldText}

This template outputs:

<b>Hello world</b>

See the Raw section for more information.

No Context

The No Context does not escape any characters. Usefull for text output and testing purposes.

Increment

The increment construct sets the cycle variable to the next value in the cycle array:

{cycle $rgb = array("red", "green", "blue" )}

{$rgb // Print "red" }
{increment $rgb}
{$rgb // Print "green" }

If the end of the cycle array is reached, it will jump again to the first value of the array.

Decrement

The decrement construct sets the cycle variable to the previous value in the cycle array:

{cycle $rgb = array("red", "green", "blue" )}

{$rgb // Print "red" }
{decrement $rgb}
{$rgb // Print "blue" }

If the begin of the cycle array is reached, it will jump again to the last value of the array.

Reset

The reset construct sets the cycle variable to the first value in the cycle array:

{cycle $rgb = array("red", "green", "blue" )}

{$rgb // Print "red" }
{increment $rgb}
{$rgb // Print "blue" }

{reset $rgb}
{$rgb // Print "red" }

If, else, elseif

The if construct allows conditional execution of code fragments. The structure is:

{if <expression> }
    <code>
{/if}

If the <expression> evaluates to true, the <code> fragment will be executed. For instance the following code will show "$a is less than $b" if $a is less than $b:

{if $a < $b }
    $a is less than $b.
{/if}

The else construct can be used in an if statement. It contains a code fragment that will be executed if the expression evaluates to false:

{if expression }
   code1
{else}
   code2
{/if}

The code2 is executed when the expression is false. Otherwise code1 is executed.

The elseif construct can be used in an if statement. It adds an extra expression and code block that will be evaluated and executed when the (previous) expression from the if statement does not evaluate to true:

{if $weekday == 0}
    Monday
{elseif $weekday == 1}
    Tuesday
{elseif $weekday == 2}
    Wednesday
{else}
    Thursday, Friday, Saturday, or Sunday.
{/if}

Writing an elseif statement is actually the same as writing them with separate if and else statements. The previous example could be written as:

{if $weekday == 0}
     Monday
{else}
  {if $weekday == 1}
      Tuesday
  {else}
    {if $weekday == 2}
        Wednesday
    {else}
        Thursday, Friday, Saturday, or Sunday.
    {/if}
  {/if}
{/if}

As you can see, this makes the code harder to read.

Switch, Case, Default

The switch construct is quite similar to multiple if and elseif statements. The syntax is as follows:

{switch <expression>}

    <case1> [ case2 [ case3, .. ] ]
    [ default ]

{/switch}

A case block has the following syntax:

{case <literal> [, <literal>, ..]}
    <code>
{/case}

And the default is as follows:

{default}
    <code>
{/default}

The switch statement expects an expression. This expression will then be compared with the literal values from the case statements. The comparison starts and goes to the next literal as the values from the <expression> and <literal> are not equal. The <code> from the first match will be executed and the rest of the cases are skipped.

If none of the cases match, then the default block will be executed. See the example switch statement below:

{switch $weekDay}

    {case 0} Monday {/case}
    {case 1} Tuesday {/case}
    {case 2} Wednesday {/case}
    {case 3, 4, 5, 6}
        Thursday, Friday, Saturday, or Sunday
    {/case}

    {default}
        The $weekDay should be a number between 0 and 6.
    {/default}

 {/switch}

This switch converts the weekday number to a name.

Foreach

A very important construct in the Template language is the foreach. The foreach is a loop structure that iterates over an array. Since this loop is used so often in the templates, it has several convenience tags build in. First we'll show the basic syntax:

{foreach <array> as <value> }
    <code>
{/foreach}

{foreach <array> as <key> => <value> }
    <code>
{/foreach}

Two foreach structures are shown. The first structure takes each element from the array> and assigns it to the variable <value>. The second structure does the same, except that the key of the array is assigned to the variable key.

An example for each structure:

{var $rgb = array( "red", "green", "blue" ) }
{foreach $rgb as $color}
  The color is: {$color}
{/foreach}

{foreach $rgb as $key => $color}
  Array key {$key} contains the color: {$color}
{/foreach}

The output for this example will be:

The color is: red
The color is: green
The color is: blue

Array key 0 contains the color: red
Array key 1 contains the color: green
Array key 2 contains the color: blue

With this syntax we can easily loop any number, and is more convenient than using the while structure. This is demonstrated next:

{foreach 1..10 as $i}
Iteration {$i}
{/foreach}

This works because the 1..10 statement creates an array with the values from 1 until 10.

Often a foreach is used to create some kind of table or list. Several extensions are made available to ease the development:

The foreach loop can have an increment and decrement tag. These tags increment and/or decrement an cycle value, and work exactly the same as the Increment and Decrement control structures. The syntax is almost the same in the foreach:

[increment <variable1> [, variable2, ... ] ]
[decrement <variable1> [, variable2, ... ] ]

These tags are the same as the Increment and Decrement control structures.

This tag is added at the end of the foreach construct. The next example increments the cycle value in every iteration of the loop:

{cycle $blackAndWhite = array( '#00000', '#FFFFFF' )}

{foreach 1..5 as $value increment $blackAndWhite}
    <font color="{$blackAndWhite}">Number: {$value}</font>
{/foreach}

This loop outputs the following code:

<font color="#000000">Number: 1</font>
<font color="#FFFFFF">Number: 2</font>
<font color="#000000">Number: 3</font>
<font color="#FFFFFF">Number: 4</font>
<font color="#000000">Number: 5</font>

The offset and limit code constructs are specified after the cycle increment or decrement tag. The offset and limit constructs are extremely useful for splitting a long table or list over multiple page views. The next example demonstrates this:

{use $hugeArray = array(), $offset = 0}
{foreach $hugeArray as $tableEntry offset $offset limit 100}

  {* Show the information from the $tableEntry *}

{foreach}

See the External variable declaration (use) section for more information. The loop will start at the $offset and won't show the previous elements. The maximum iterations of the loop is 100. Another example shows the numbers from 50 until 100:

{var $hugeArray = 1..1000}

{foreach $hugeArray as $value offset 50 limit 50}
  {$value}
{/foreach}

While

The while loop loops over a code fragment as long as the expression in the while evaluates to true. The syntax of the while loop is as follows:

{while <expression>}
    <code>
{/while}

Usually the expression evaluates whether a counter reaches a certain number. In the code the counter is increased or decreased:

{var $i = 0}
{while $i < 10}
   The number is: {$i}.
   {$i++}
{/while}

This example prints the numbers from 0 until 9. If you write a while loop, make sure that the loop eventually ends. The next example demonstrates another while loop. This loop increments a value from a Cycle. Compare how the same example can be done with a Foreach:

{cycle $blackAndWhite = array( '#00000', '#FFFFFF' )}
{var $i = 1}

{while $i <= 5 }
    <font color="{$blackAndWhite}">Number: {$i}</font>
    {$i++}
    {increment $blackAndWhite}
{/while}

Delimiter

The delimiter can be used (only) inside a loop to do every given iteration a specific action. The syntax is as follows:

{delimiter [modulo <expression> [is <expression>]]}
    <code>
{/delimiter}

The "module...<expression>" part can be omitted and by default the delimiter will be inserted between every iteration of the loop. If a modulo is used, the "is <expression>" part of the delimiter can be omitted and will be interpreted as "is 0".

The delimiter will always be executed between two iterations of the loop. In the next example between every name a comma is inserted:

{var $names = array( 'Bernard', 'Fran', 'Manny' )}
{foreach $names as $name}
{$name}
{delimiter}, {/delimiter}
{/foreach}

The next example demonstrates creates a matrix with 4 rows and 4 columns. The delimiter closes the current row and opens a new one every forth column as the delimiter is only added when "internal counter modulo 4" equals 0. The "internal counter" simply counts the number of executed iterations:

{var $columns = 4}
<table>
<tr>
{foreach 1..16 as $nr}
  <td>{$nr}</td>

  {delimiter modulo $columns}
    </tr><tr>
  {/delimiter}
{/foreach}
</tr>

Continue

The continue statement is used within the looping structures to skip the rest of the current loop iteration and continue execution at the condition evaluation and then the beginning of the next iteration. If a delimiter is available in the looping structure then this delimiter will be added. Use the Skip statement to skip also the delimiter.

The next example show the numbers 1 to 5 separated with a comma. After the numbers 1, 2, and 3 is the token # appended. As the example shows, the numbers higher than 3 will not execute the rest of the foreach anymore. The delimiter is added anyway:

{foreach 1..5 as $i}

{delimiter}
,
{/delimiter}

{$i}
{if $i > 3} {continue} {/if}
#
{/foreach}

The output of the template is:

1 #,
2 #,
3 #,
4 ,
5

Skip

The skip is the same as a continue, except that the delimiter in the loop will be skipped also. The next example show the numbers 1 to 5. The number 1, 2, and 3 have the token # appended and are separated with a comma. As the example shows, the numbers higher than 3 will not execute the rest of the foreach anymore and the delimiter is not appended:

{foreach 1..5 as $i}

{delimiter}
,
{/delimiter}

{$i}
{if $i > 3} {skip} {/if}
#
{/foreach}

And outputs:

1 #,
2 #,
3 #,
4
5

Break

The break ends execution of the current foreach or while structure. The example below prints the numbers 1 and 2. Due to the break, the rest of the loop is skipped:

{foreach 1..10 as $i}
{$i}
{if $i == 2} {break} {/if}
{/foreach}

Include

The include calls other templates which will be executed within the current template. Variables can be passed on and retrieved from the included template. The generic template could then be used at multiple places and is configurable via the given variables.

The syntax of the include is as follows:

{include <template_name | location_object >
 [ send <send_variables> ]
 [ receive <receive_variables> ]

The file that needs to be included is either specified with a string (template_name) or with a location object. The location object is explained in the section Template locations.

The <send_variables> has this syntax:

<expression> as <variable> | <variable>

And the <receive_variables> has almost the same syntax as the <send_variables>:

<variable> as <variable> | <variable>

A next example will clarify the syntax a bit more:

{include "calc_a_plus_b.ezt"
send     2 as $a,
         5 as $b
receive $c as $sum }

The included template calculates the sum of the given variables $a and $b, and returns the answer in variable $c. The expressions "2" and "5" are assigned to the variables $a and $b of the included template. The value of the (returned) variable $c is directly assigned to the variable $sum. The variable $sum does not need to be declared first.

The template "calc_a_plus_b.ezt" is:

{use $a = false, $b = false}

{if $a === false || $b === false}
Variable $a or $b has an incorrect value.
{/if}

{return $a + $b as $c}

The next templates includes the "calc_a_plus_b.ezt" but does not use the expression part of the include:

{var $a = 2, $b = 5}
{include "calc_a_plus_b.ezt"
send     $a, $b
receive $c }

{var $sum = $c}

Raw

The raw construct outputs raw information and is not affected by the Contexts.

For example, the XHTML context is set and an expression contains HTML characters (which should be sent to the output) then use the "raw" block:

{var $myBoldText = "<b>Hello world</b>"}
{raw $myBoldText}

This template outputs:

<b>Hello world</b>

tr_context

Is used to set a default translation context. All tr entries below this construct will then use this translation context if none is specified explicitly. Information on contexts can be found in the Qt Linguist format specification.

This construct is used like:

{tr_context "admin/forget_password"}

Each template can have multiple tr_context statements. The default context that is set with this construct is valid until the next one is encountered.

tr

The tr construct defines a translatable string, the simplest form of this construct is:

{tr "String to translate"}

This will only work however, if there is a default context set with tr_context. In case there is none set, you have to specify it yourself with the "context" parameter. The following two templates are equivalent:

{tr_context "admin/forget_password"}
{tr "String to translate"}

and:

{tr "String to translate" context "admin/forget_password"}

When a translator translates a text, it is sometimes useful to have slightly more information than just the context and the string itself. The tr construct therefore allows to add a comment to the translatable string with the "comment" parameter. This has no effect on how the tr construct is interpreted however. An example:

{tr "Login" context "user/login" comment "Text before login input box"}

In many occasions, the translatable strings allow positional or named parameters to allow for changing the order of arguments. For example the English string "Search for 'appelmoes' returned 3 matches" can be translated in Dutch as: "Er zijn 3 items gevonden bij het zoeken naar 'appelmoes'". A simple concatenation mechanism of multiple translatable strings would no longer work. The tr construct supports parameterized strings in two different ways: with numerical replacement identifiers (such as %1 and %2) and with associative identifiers (such as %search_string and %matches). The following example illustrates how this is done in the simplest possible way:

{tr "Search for '%1' returned '%2' matches" vars 'appelmoes', 3}

If no key is specified for variables, like in the above example, they are automatically given numbers, starting by 1. It is also possible to add specific positions to variables, like:

{tr "Search for '%1' returned '%2' matches" vars 2 => 'appelmoes', 1 => 3}

This is perhaps not so useful for positional parameters like here, but it is necessary for named parameters as illustrated in the example here:

{tr "Search for '%what' returned '%matchcount' matches" vars 'what' => 'appelmoes', 'matchcount' => 3}

It is of course also possible to mix those two cases:

{tr "Search for '%1' returned '%matchcount' matches" vars 'matchcount' => 3, 'appelmoes'}

or:

{tr "Search for '%1' returned '%matchcount' matches" vars 'appelmoes', 'matchcount' => 3}

Variables without any key, are always given positional identifiers in sequential order. When doing so, variables with a named key are ignored, while variables with a numerical key reset the next number in the auto-numbering sequence to the number of the key. The following example shows that:

{tr "%1 %2 %3 %4 context "test" vars 3 => 'three', 'four', 1 => 'one', 'two'}

For information on how to setup translations for your templates, please refer to the section Translations.

Custom blocks in the Template language

Custom blocks add specific behavior to the Template language. The most basic structure of a custom block - without any parameters - is:

'{' <name> '}'

The block starts and ends with curly braces. The <name> identifies the custom block. Optionally, a custom block has also a closing block:

'{' '/' <name> '}'

The name must be the same as the start block, but starts with a forward slash ('/'). The text between the open and close tag is considered as input data. Whether a custom block should have a close tag is up to the developer.

The next example demonstrates a custom block with an open and close tag that capitalizes the text in between:

{capitalize}
    Guybrush Threepwood.
{/capitalize}

Another example that uses a custom block without a close tag:

{capitalize "Guybrush Threepwood."}

Whether or not a custom block has a close tag, it handles the parameters the same. The structure of a custom block is as follows:

'{' block_name [start_expression] [ <param_name> ['='] <value> ... ] '}'

Basically, it describes that a custom block can have:

• One optional expression which is not bound to a parameter name.
• Zero or more named parameters with a value. Between the parameter name and value is an optional equal sign.

Some example blocks that use parameters:

{link "eZ systems" to "http://ez.no"}
{table border=true bgcolor="red"}
{debug}
{calculate 5 plus 5}
{join array( 'Hello', "world" ) with "_"}

{header style="bold"}
    Hello world
{/header}

Note that the values used in the examples are just ordinary expressions. Therefore it is possible to write:

{link "eZ" . " systems" to 'http'. "://" . "ez.no"}
{calculate 2 + 3 plus 1 * 2 + 3}

Again, the optional and required parameters are up to the developer.

Adding a custom block

New custom blocks are added to the Template engine with the ezcTemplateConfiguration::addExtension() method. This method expects the class name which implements the new custom block. The next example adds a custom block to the Template engine which is implemented in MyClass:

$config = ezcTemplateConfiguration::getInstance();
$config->addExtension( "MyClass" );

The custom block class should implement the ezcTemplateCustomBlock interface. This interface has only one method getCustomBlockDefinition(). The class implementing this method should return an ezcTemplateCustomBlockDefinition object from a given block name, if possible.

Custom block definition

The custom block definition describes how the Template engine should interpret the custom block. The information is provided by returning an instance of the ezcTemplateCustomBlockDefinition:

class ezcTemplateCustomBlockDefinition extends ezcTemplateCustomExtension
{
    public $class;
    public $method;

    public $hasCloseTag;

    public $startExpressionName;
    public $optionalParameters = array();
    public $requiredParameters = array();

    public $isStatic;
}

The member variables that should be set in this class are:

The following custom block creates a hyper-link from a name and an URL:

{link "name" to "url" [title "title"]}

This custom block has a:

• Required unnamed parameter that contains the name.
• Required named parameter "to" that contains the URL.
• Optional named parameter "title" that contains the title.

Except for the class and the method name the CustomBlockDefinition should look like:

$def = new ezcTemplateCustomBlockDefinition;

$def->class = "MyLink"
$def->method = "linkMethod"

$def->hasCloseTag = false;
$def->startExpressionName = "from";
$def->optionalParameters = array( "title" );
$def->requiredParameters = array( "from", "to" );

The CB definition should be made available to the Template engine via a class implementing the ezcTemplateCustomBlock interface:

interface ezcTemplateCustomBlock
{
    public static function getCustomBlockDefinition( $name );
}

The class implementing the getCustomBlockDefinition() method should return an ezcTemplateCustomBlockDefinition for the given block name $name. The next code demonstrates a class that implements the interface:

class MyLink implements ezcTemplateCustomBlock
{
    public static function getCustomBlockDefinition( $name )
    {
        switch ($name )
        {
            case "link":
                $def = new ezcTemplateCustomBlockDefinition;
                $def->class = "MyLink";
                //
                // Create definition
                //

                return $def;
        }

        return false;
    }
}

Implementing the custom block

In the CB definition is specified which class and what method should produce the custom block output. A typical implementation to create a hyper-link would be:

public static function link( $parameters )
{
    $title = "";
    if( isset( $parameters["title"] ) )
    {
        $title = "title='". $parameters["title"] ."'";
    }

    return "<a href='".$parameters["to"]."' $title>".$parameters["from"]."</a>"
}

The method implementing the custom block returns a string that will be inserted in the template output. The custom block parameters are provided in the first parameter as an array. The method itself must check whether the optional parameters are sent or not. Required parameters are always available as the template compiler throws a compiler exception if these parameters are absent.

The custom blocks that do have a close tag need a method that accepts two parameters. For example the following custom block has a close tag:

{capitalize}
    Guybrush Threepwood
{/capitalize}

The method that implements the custom block:

public static function capitalize( $parameters, $text )
{
    return strtoupper( $text );
}

The $parameters parameter is never used. The text between the open and close tag of the custom block is always passed in the second parameter.

Example

The 'calc' custom block calculates the sum of the given values. The sum is calculated from the initial value plus or minus the values added to the "plus" and or "minus" parameter. Some usage examples are:

{calc 5 plus 3}
{calc 5 plus array(2,5,2) minus 2}
{calc 2 minus 5}

The custom block could be implemented like:

class CalcCustomBlock implements ezcTemplateCustomBlock
{
    public static function getCustomBlockDefinition( $name )
    {
        switch ($name )
        {
            case "calc":
                $def = new ezcTemplateCustomBlockDefinition;
                $def->class = __CLASS__;
                $def->method = "calculate";
                $def->hasCloseTag = false;
                $def->startExpressionName = "init";
                $def->requiredParameters = array("init");
                $def->optionalParameters = array("plus", "minus");
                return $def;
        }

        return false;
    }

    public static function calculate( $params )
    {
        $result = $params["init"];

        if ( isset( $params["plus"] ) )
        {
            if( is_array( $params["plus"] ) )
            {
                foreach( $params["plus"] as $value )
                {
                    result += $value;
                }
            }
            else
            {
                $result += $params["plus"];
            }
        }

        if ( isset( $params["minus"] ) )
        {
            if( is_array( $params["minus"] ) )
            {
                foreach( $params["minus"] as $value )
                {
                    result -= $value;
                }
            }
            else
            {
                $result -= $params["minus"];
            }
        }

        return $result;
    }
}

This new custom block needs to be assigned to the Template configuration:

$config = ezcTemplateConfiguration::getInstance();
$config->addExtension( "CalcCustomBlock" );

And of course the template can be run like:

$t = new ezcTemplate();
$t->process( "my_template.ezt" );

Custom functions in the Template language

Custom functions are extra functions that can be used in the Template expressions. Some examples are:

Greatest common divisor: {gcd(8, 12)}
{sin( $angle ) * 2}
{matrix_multiply( $m1, $m2)}
{fetch_from_database("items", 2)}

Basically, the second line in the example runs a custom function and multiplies the result with two. This demonstrates that the difference between a custom block and a custom function. Custom functions can be used within an expression. Custom blocks are directly generating an output result.

Adding a new custom function

As with the custom block, custom functions are added to the Template engine by the ezcTemplateConfiguration::addExtension() method. The class name given to this method should implement the ezcTemplateCustomFunction interface. Notice that this is the same as adding a custom block.

$config = ezcTemplateConfiguration::getInstance();
$config->addExtension( "MyClass" );

The example above adds MyClass to the ezcTemplateConfiguration. MyClass implements the getCustomFunctionDefinition() from the ezcTemplateCustomFunction interface. This function returns an ezcTemplateCustomFunctionDefinition object:

class ezcTemplateCustomFunctionDefinition extends ezcTemplateCustomExtension
{
    public $class;
    public $method;
    public $sendTemplateObject = false;

    // Deprecated:
    // public $parameters = array();
}

The $class and $method parameter are the same as for custom blocks. The $parameters variable is obsolete with version 1.2. It used to specify the required and optional parameters for the custom function.

• Required parameters are named strings.
• Optional parameters are named strings enclosed with square brackets. These parameters should be specified after the required parameters.

In version 1.2 and up it uses reflection to find the required and optional parameters. Due some bugs in the reflection classes it works properly in PHP version 5.2 and up.

It is also possible to accept a variable number of (extra) arguments. For this you need to set the variableArgumentList property of the ezcTemplateCustomFunctionDefinition.

The variable $sendTemplateObject adds the possibility to send the current template object to the custom function.

As with functions in PHP the order of the unnamed parameters matter. The next example demonstrates a complete custom function implementation:

class MyClass implements ezcTemplateCustomFunction
{
    public static function getCustomFunctionDefinition( $name )
    {
        switch ($name )
        {
            case "func":
                $def = new ezcTemplateCustomFunctionDefinition();
                $def->class = "MyClass";
                $def->method = "customFunction";

                // Deprecated:
                // $def->parameters = array( "firstParam", "secondParam", "[thirdParam]");

                return $def;
        }

        return false;
    }


    public static function customFunction( $firstParam, $secondParam, $thirdParam = "isOptional" )
    {
        // Implementation.

        return "string";
    }
}

The custom parameters specified in the definition block should also be present in the customFunction implementation. Three parameters are specified, so the customFunction implementation should have three parameters. The last parameter in the parameter definition is specified as optional, so should the last parameter in customFunction be optional.

The interface of the ezcTemplateCustomFunction requires to implement the getCustomFunctionDefinition() method:

interface ezcTemplateCustomFunction
{
    public static function getCustomFunctionDefinition( $name );
}

Named parameters

New in version 1.2 of the Template engine are named parameters. The advantage of named parameters is that the order of the parameters are no longer important and that parameters can be omitted that otherwise was not possible. The next example shows a common custom function retrieving items from the database:

// fetch_item ( select = "*", start = 0, limit = false, orderBy = "id", reverseOrder = false )
{ fetch_item("*", 0, false, "name") } // Fetch everything but order by 'name'

This example fetches everything from the items table and sorts it on "name". Without named parameters the problem is that only the second last parameter needs to be changed and therefore all the previous parameters need to be given.

Named parameters are written in the form "keyword = value". The keyword is the name of the parameter. The equal sign is used as separator because it is not possible to do any assignments within expressions.

Using named parameters the code from the previous example is reduced to:

// fetch_item ( select = "*", start = 0, limit = false, orderBy = "id", reverseOrder = false )
{ fetch_item( orderBy = "name") } // Fetch everything but order by 'name'

Besides that the code is shorter, it is also more descriptive.

Sending template objects

In a few cases the template object is needed in the custom function implementation. With access to the template object, the configuration and other template settings could be retrieved and used.

If the variable sendTemplateObject is set to true, the first parameter in the function contains the template object. The following

The next example adds the custom function templatePath:

class MyClass implements ezcTemplateCustomFunction
{
    public static function getCustomFunctionDefinition( $name )
    {
        switch ($name )
        {
            case "templatePath":
                $def = new ezcTemplateCustomFunctionDefinition;
                $def->class = "MyClass";
                $def->method = "templatePath";
                $def->sendTemplateObject = true;

                return $def;
        }

        return false;
    }


    public static function templatePath( $templateObj )
    {
        return $templateObj->configuration->templatePath;
    }
}