Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

Variable usage

Template variables must be referenced using dollar ($) notation, for example: $my_variable, $object_array, etc. An eZ Publish template variable is case sensitive. In other words, $lollipop is not the same variable as $LolliPop. Template variables can be created by the system (from PHP code) or by the author of the template (from within template code). Regardless of where a variable was created, it can be changed using the "set" function. Some templates have preset variables, for example, the main template (pagelayout) provides access to a collection of variables.

Creating and destroying variables

All variables used in a template must be declared and defined by the "def" function (short for define) before they can be used. A variable exists until the "undef" function (short for undefine) is used in order to destroy it. A previously declared variable will be automatically destroyed at the end of the template file in which it was created. The following example demonstrates the most basic use of the "def" and "undef" functions.

{def $temperature=32}
 
    {$temperature}
 
{undef}

The output of the example will be "32". After the {undef} function is called, the $temperature variable will not be available. Both the "def" and the "undef" function can be used with multiple variables at the same time. In addition, the "undef" function can be used without any parameters. When called without parameters the "undef" function automatically destroys all variables that were previously created within the template. The following example demonstrates how the "def" and "undef" functions can be used to create and destroy multiple variables at the same time.

{def $weather='warm' $celsius=32 $fahrenheit=90}
 
The weather is {$weather}: {$celsius} C / {$fahrenheit} F <br />
 
{undef $celsius $fahrenheit}
 
The weather is still {$weather}. <br />
 
{undef}

The output of this example will be:

The weather is warm: 32 C / 90 F
 The weather is still warm.

In the example above, the "def" function is used to create three new variables: $temperature, $celsius and $fahrenheit. The "undef" function is used twice. The first time, it is used to destroy the $celsius and $fahrenheit variables. The second is time it is called without parameters and thus the remaining variables (in this case only $temperature) will be destroyed. For more information, please refer to the documentation page of the "def" and "undef" functions.

Changing the contents of variables

The contents/value of a variable can be changed at any time using the "set" function. Please note that this function can be used to change the value of any variable, regardless of if it was created by the system or inside a template. No warning will be given if a system variable is changed. The "set" function can be used to change the value of any variable regardless of the variable's current type and the type of the new value. In other words, this function is capable of changing the type of a variable. The "set" function can not be used to change the value of an element/attribute of an array, hash or an object. In fact, the elements/attributes of arrays, hashes and objects can not be changed from within template code. The following example demonstrates the usage of the "set" function.

{def $weather='warm'}
 
The weather is {$weather}. <br />
 
{set $weather='cold'}
 
The weather is {$weather}.
 
{undef}

The output of the example will be:

The weather is warm.
 The weather is cold.

Just like the "def" and "undef" functions, the "set" function can work with multiple variables at the same time. For more information, please refer to the documentation page of the "set" function.

Changing the contents of global variables

Global variables are changed just like a regular variable, but in this case we will need to use the scope parameter to declare it a global variable. For more information, please refer to the documentation page of the "set" template function.

{def $color='red'}
Before: My car is {$color}.
{set scope=global $color='blue'}
After: My car is {$color}.

The output of the example will be:

Before: My car is red.
After: My car is blue. 

The $color global variable in the previous example will be treated as a global variable, but will not be view cache safe. Please note that only the $persistent_variable global variable is view cache safe.

Global variables can also be defined using the operators ezpagedata_set()ezpagedata_append() or ezpagedata(), which will require ezwebin to be installed. The eZ Website Interface extension is already included by default in eZ Flow and eZ Demo packages, but not with plain_site.

Accessing array elements

The elements of a simple/vector array can only be accessed using numerical indexes. This method is called "index look-up". The elements of an associative array can be accessed by using the key identifiers. This method is called "identifier lookup". The following example demonstrates the different lookup methods.

Index look-up

Index look-up is carried out by appending a period/dot and an index number to the name of a simple/vector or associative array. Index look-up may also be carried out by appending a matching pair of brackets that encapsulate the desired index value. The following example demonstrates how to access the elements of a simple array using index look-up. Please note the different syntax (dot and brackets).

{def $sentence=array( 'Life', 'is', 'very', 'good!' )}
 
The 1st element is: {$sentence.0} <br />
The 2nd element is: {$sentence.1} <br />
The 3rd element is: {$sentence[2]} <br />
The 4th element is: {$sentence[3]} <br />
 
{undef}

The code above will output the following:

The 1st element is: Life
 The 2nd element is: is
 The 3rd element is: very
 The 4th element is: good!

Identifier look-up

Identifier look-up can be carried out by appending a period/dot and an identifier name to the name of an associative array. Identifier look-up may also be carried out by appending a matching pair of brackets that encapsulate the desired index value. The following example demonstrates how to access the elements of an associative array using the identifier look-up method. Notice the different syntax (use of dot and brackets).

{def $sentence=hash( 'first',  'Life',
                    'second', 'is',
                    'third',  'very',
                    'fourth', 'good!' )}
 
The 1st element is: {$sentence.first} <br />
The 2nd element is: {$sentence.second} <br />
The 3rd element is: {$sentence[third]} <br />
The 4th element is: {$sentence[fourth]} <br />
 
{undef}

The following output will be produced:

The 1st element is: Life
 The 2nd element is: is
 The 3rd element is: very
 The 4th element is: good!

Accessing object attributes

The attributes of an object can only be accessed using the attributes' identifiers. An identifier is just the name of an attribute (similar to the keys of an associative array). The following example demonstrates how the different attributes of a node object can be accessed from within a template.

The ID of the node: {$node.node_id} <br />
 
The ID of the object encapsulated by the node: {$node.object.id} <br />
 
The name of the object: {$node.object.name} <br />
 
First time the object was published: {$node.object.published|l10n( shortdate )} <br />

If the $node variable contains a node that has ID number 44 and encapsulates object number 13 named "Birthday" published on the first of April in 2003, the following output will be produced:

The ID of the node: 44
 The ID of the object encapsulated by the node: 13
 The name of the object: Birthday
 First time the object was published: 01/04/2003

Balazs Halasy (14/09/2010 11:25 am)

Ricardo Correia (25/01/2013 4:23 pm)

Geir Arne Waaler, Ricardo Correia


Comments

  • Array inspection

    How can I inspect all values of the array when I do not know its size? There are cases when the array is generated dynamically, and I do not know its size.
    • Re: Array inspection

      You can use the FOREACH construct.
    • Re: Array inspection

      Yes, "foreach" is the common idea, but you can also use the function "get_type()" to show the length. Here is an example:

      {def $somearray=...}
      {def $length=$somearray|get_type()}

      {for 0 to $length as $counter}
      {$somearray[$counter]}
      {/for}

      {undef}

      This is more helpful if you want to access the neighbour elements of the actual element, for example. If you do not need a counte, "foreach" is easier to use.
  • Set won`t always work; the Scope parameter

    If you try to use "set" in an inner scope, it will not update a variable outside that scope without the scope-parameter.

    This won`t update the var:

    {def $myVar = "one"}
    {if (#some test that evaluates to true")}
    {set $myVar = "two"}

    This however, will:

    {def $myVar = "one"}
    {if (#some test that evaluates to true")}
    {set $myVar = "two" scope="root"}

    See this page for more info: http://ez.no/doc/ez_publish/techn...nce/template_functions/variables/set

    Hope this saves someone a little time and frustration...

    Cheers,
    Kjartan


  • How to modify an array element??

    Where is the missing part "Changing the contents of array elements"?
    Making a 'set' on an array element destroy the whole array.
    Why there is no cross-link between "/reference/template_operators/arrays/array" and /templates/the_template_language/variable_usage?
    • Re: How to modify an array element??

      Actualy, to have the equivalent to the traditional PHP $myArray[$i]++, I use the following:
      {set $counts = $counts|insert($i,inc($counts[$i]))|remove(inc($i))}
      Huge, isn't it?
      • Re: Re: How to modify an array element??

        I mean :
        $myArray[$i]++
        {set $myArray = $myArray|insert($i,inc($myArray[$i]))|remove(inc($i))}
        • Re: Re: Re: How to modify an array element??

          {$myArray = $myarray|inc()}