The eZ Template Component

Now we come to the interesting part of this article. We have all the basics in place to start looking at the template for our action.

The main template

{use $action}
    {var
        $menu = array( "Back to site" => array( "action" => "sitedetails", "site" => $action->site-id ) )
    }
    {include "header.ezt" send $action, $menu}
    <h1>Search details for search "{$action->search->query}" about site "{$action->site->site}"</h1>
    <h2>Results</h2>
     <table width="100%" class="data">
      <tr>
       <th>Query date</th>
       <th>Rank</th>
       <th>More details</th>
      </tr>
     {cycle $rowStyle = array( "light", "dark" )}
     {foreach $action->results as $result}
        <tr class="{$rowStyle}">
         <td>
          {date_timestamp_format( "Y-m-d H:i", $result->timestamp )}
         </td>
         <td>
          {$result->rank}
         </td>
         <td>
          <a href="index.php?{url_parameters_build( array( "action" => "resultdetails", "result" => $result->id ) )}">details</a>
         </td>
        </tr>
       {increment $rowStyle}
     {/foreach}
     </table>
    {include "footer.ezt"}

If you are familiar with Smarty, you will find it easy to understand our template language, since it is very similar to the Smarty language. However, in contrast to Smarty, the eZ Template component is written only for PHP 5.1 or greater, while Smarty maintains compatibility with PHP 4. Each template instruction is wrapped in curly braces ("{", "}") and each of these instructions may output text (so you do not need to specify a command like echo for printing text). All printed text is automatically escaped using PHP's htmlentities() function (assuming that we did not change the context of the template, which is XHTML by default). If, for some reason, you need to print non-escaped text, you can use the raw command.

The first template instruction is the use command, which retrieves the variables that have been sent to the template. (Remember that we did that in the main controller.) After that, the variable $action is available for use.

Next we define a new variable called $menu. This is a multi-dimensional associative array that represents a menu structure. (In the context of the eZ Template component we talk about associative arrays as hashes, so I will use that term from now on.) As you can see, the hash is defined in exactly the same way that it is done in PHP. The menu structure defines a link named "Back to site". The link name is assigned to an array of parameters that needs to be sent to the main controller to show the site we want to link to. We will show how the menu is generated from this array in a moment.

Next we include another template that is responsible for displaying the HTML header and the menu. Including a template works exactly like processing a template from PHP; you have to send it the variables that it will need. Here we send our $action and the newly generated $menu variables. But before we look at the included template, let's finish with the main template.

In the next line (6), some HTML code gets generated. We print a first-level heading and, for the first time, echo some data. As already mentioned, this is quite easy - you just wrap the variable that will be output in curly braces. Access to object attributes works the same as with PHP. Note, though, that for now it is not possible to call methods on objects from a template. If you need to access methods, you can try to emulate this through overloading in your class. This is a very limited approach, but it may be sufficient in some cases.

In line 14 we see a special feature of the eZ Template component - the "cycle". A cycle is a single-dimensional array (or a hash). It is special because you can iterate over it in an infinite loop. When the cycle reaches the end, it will start from the beginning again. Our cycle $rowStyle contains two elements: the strings "light" and "dark", which refer to CSS classes. Each time you use the cycle variable, it will return its currently selected value. To advance its internal pointer to the next value, call the increment statement (line 27).

In line 15 we use a foreach loop to iterate over all results stored in our action. The foreach loop is closed in line 28, using the statement:

{/foreach}

As you can see, ending blocks in the template language are similar to the HTML construct.

Inside the foreach we use a template function for the first time. Line 18 refers to a function called date_timestamp_format(). This function works exactly like PHP's date() function: it takes a format string to determine how to display a date and an optional timestamp to format. If the latter is not specified, the current time will be used. In most cases, we named the functions in our template language differently from the PHP functions to provide a unique naming scheme. You will also see that with parameter orders. Where PHP is sometimes very inconsistent, the order is always the same for our functions.

Line 24 contains another function call. The function url_parameters_build() wraps around PHP's http_build_query() function, which takes a hash and builds an HTTP-GET query string from it. The last line in this template includes another template, which simply closes the HTML constructs from the " header.ezt" template we included previously. There is nothing special in there.

Included templates

On line 5 of the main template we included another template that prints the HTML header and the menu structure for each page. Remember that we sent the $action and $menu variables to this template.

{use $action, $menu = array()}
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 
    <html>
    <head>
     <link rel="stylesheet" type="text/css" href="css/standard.css" />
     <title>GoogleRankCheck - {$action->title}</title>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    </head>
    <body>
    {include "menu.ezt" send $menu}

Again we have a use statement on the first line. This is always necessary to make external variables available to a template. The reason for this mechanism is simple: in a complex system, you might have duplicate variable names, which can be avoided via a mechanism called aliasing. Aliasing is not done in the use statement but in the include statement. So, if you want to rename a variable for a template you include, you can write:

{include "test.ezt" send $foo as $bar}

You can also send static values to a template using this method. In the use statement of the header template, we define a default value for the $menu variable. If no value is sent to the template, it will be an empty array.

We are already familiar with the rest of the code in this template, so we will proceed to the menu template, which gets included in the last line.

{use $menu}
    {var
        $menuStd = array(
            "Main page" => array( "action" => "sitelist" ),
        )
    }
    {
        $menu = array_merge( $menuStd, $menu )
    }
    <table>
    <tr>
    {foreach $menu as $menuName => $menuParams}
        <td>[<a href="index.php?{url_parameters_build( $menuParams )}">{$menuName}</a>]</td>
    {/foreach}
    </tr>
    </table>

The menu template is responsible for generating a menu on each page of our application. The lines 2-6 define a hash of default links that should be available on every page. After that, on line 8, the received menu hash is merged with these default links. The array_merge() function works exactly as it does in PHP. Lines 12-14 iterate over the resulting menu hash and generate a table of menu items. Again we use the url_parameters_build() function on the GET parameter array that is defined for each menu item.