PHPTAL

This attribute defines one or more variables which may be used later in the template.

Making a shortcut to a long path:

<span tal:define="global destname path/to/existing/variable" />

Creating a string inside the template:

<span tal:define="global destname string:some string" />

Defining more than one variable at the same time:

<span tal:define="global fname string:paul; lname string:dupond" />

Defining a string containing another variable:

<span tal:define="global hello string:hello $fname welcome on this page" />

A small trick which uses output buffers:

<span tal:define="global hello">hello ${fname} welcome on this page</span>

You may also use tal:define with other attributes, it will be executed before any other attributes.

In above examples, the span tag won't show up because it has no printable content nor attributes. Even the last example does not show the message because the 'hello' variable grabs it.

On the other hand:

<span tal:define="hello string:hello ${fname} welcome on this page"
      tal:content="hello"
/>

Will both set the hello variable and print it.

BUT the following is irregular because tal:define will calculate the content of the node before being executed and tal:content IS the content of the node. Whatever is inside the span is just ignored. Thus hello won't be defined and an exception will be thrown.

<span tal:define="hello" tal:content="hello">
  hello ${fname} welcome on this page
</span>

In above examples, you may have spotten the 'global' keywords before some variables names. In PHPTAL you can either define a variable globally or locally.

A global variable will be accessible from any xml node of your templates or called macros.

<span tal:define="global hello string:hello world"/>
<p tal:content="hello"/>

On the contrary, a local variable is only available inside the tag it is defined in:

<span tal:define="hello string:hello world"/>
<p tal:content="hello"/> <!-- will produce an undefined variable error -->

The entity and its content will be shown only if the condition is evaluated to true.

<span tal:condition="identified"> Welcome member ...  </span>

<span tal:condition="not: identified">
  Please login before accessing this page
</span>

If the php backend does not provide your templates with enough methods, you will often have to fall back to php for special conditions:

<span tal:comment="show only if more than five items in the cart"
      tal:condition="php: cart.countItems() GT 5">...</span>

This may put too much logic inside the template and it is sometimes preferable to provide boolean attributes or accessible methods to the template:

<span tal:condition="cart/hasMoreThanFiveItems">...</span>

<span tal:condition="fullfillNumerousItems">...</span>

This attribute handles iterable objects like arrays, associative arrays, and objects implementing the PHP5 Iterable class.

The repeat attribute repeats its element and its content until the end of the specified resource.

<tr tal:repeat="item some/result">
  <td tal:content="item">text replaced by item</td>
</tr>

Within a loop, you can access the current loop information (and that of its parent for nested loops) using specific repeat/* paths.

In the above example:

"item" depends on the receiver variable defined in tal:repeat expression.

The most common usage of tal:repeat is in using some SQL database result. Providing you use a library implementing the Iterator PHP interface:

<table>
  <thead>
    <tr>
      <th>Position</th>
      <th>Player</th>
      <th>Score</th>
    </tr>
  </thead>
  <tbody>
    <tr tal:repeat="ranking playersRanking">
      <td tal:content="ranking/position"/>
      <td tal:content="ranking/player"/>
      <td tal:content="ranking/score"/>
    </tr>
  </tbody>
</table>

This attribute asks the PHPTAL parser to ignore the entity's open and close tag, its content will still be evaluated.

<span tal:omit-tag="">
  only this text will appear, span open and close will be removed
</span>

Will produce:

only this text will appear, span open and close will be removed

This attribute is useful when you want to define a macro, a loop, a condition, or any other template logic that mustn't show it's root tag.

This attribute will replace the entire tag with a value, or by nothing if no value is given.

<span tal:replace="string:this beautyfull string">
  this uggly string and span
</span>

Will produce:

this beautyfull string

tal:replace can also be used to create samples in source templates, but remove them from final output.

<table>
  <tr tal:repeat="item myresult">
    <td tal:content="item">item value</td>
  </tr>
  <tr tal:replace="">
    <td>sample 1</td>
  </tr>
  <tr tal:replace="">
    <td>sample 2</td>
  </tr>
</table>

This attribute replaces the tag content with the evaluation of its expression.

<span tal:define="myvar string:my string"/>
<span tal:content="myvar">will be replaced</span>

Will produce:

<span>my string</span>

This attribute changes tag attribute(s) value(s).

<a href="http://www.foo.com" title="some foo link"
   tal:attributes="href somelink/href; title somelink/title" 
  tal:content="somelink/text"
>sample link</a>

With a 'somelink' having:

$somelink->href = "http://www.google.com";
$somelink->title = "google search engine";
$somelink->text = "the google search engine";

Will produce:

<a href="http://www.google.com" 
title="google search engine">the google search engine</a>

A somewhat complicated example involving tal:repeat:

<tr tal:repeat="ranking playerRankings"
    tal:attribute="class php: repeat.ranking.odd ? 'odd' : false">
    ...
</tr>

The php: modifier will be explained later, basically if the line is odd then tr will have a class attribute with "odd" as value, otherwise, no class attribute will be set.

The "condition ? then : else" is a regular PHP expression which must be used with care but has proven to be useful on more than one occasion.

A better way to achieve the same result would be to ask your PHP coder to create a custom modifier for your needs (see PHP integration / custom modifiers) which would be used as follows:

<tr tal:repeat="ranking playerRankings"
    tal:attribute="class css-odd:repeat/ranking/odd">
  ...
</tr>

The modifier would return "odd" if repeat/ranking/odd is true, false otherwise.

This attribute replaces the tag by the tal:on-error expression evaluation if a path error is detected in the tag content, or if any php exception is thrown in the tag content.

<span tal:on-error="string:No username defined here"
      tal:content="user/name">the user name here</span>

If an error occurs accessing 'name' or 'user', the error string will be shown at the tag's place.

This also works on more than one level of template:

<span tal:on-error="string:error occurred somewhere">
  <span tal:content="user/firstname"/>
  <span tal:content="user/lastname"/>
  <span metal:use-macro="userMenu" />
</span>

This attribute declares a macro. Think of macros as library of small templates which can be reused in any other template.

<div metal:define-macro="main_menu">
  <ul>
    <li><a href="/">home</a></li>
    <li><a href="/products">products</a></li>
    <li><a href="/contact">contact</a></li>
  </ul>

  <div>
    Last modified:
    <span tal:content="mdate">page modification date</span>
  </div>
</div>

Macros inherit from the caller's dictionary. In the above example, the variable 'mdate' depends on the template that calls the macro.

This attribute calls a macro and includes its result in the current template.

<span
  tal:comment="main_menu template requires 'mdate' variable"
  tal:define="mdate page/last_modified"
  metal:use-macro="main_menu"
/>

You can refer to external macros defined in other templates by specifying the template source file.

<span metal:use-macro="site_macros.html/main_menu"/>

It is interesting to note that you can also use the PHPTAL inline replacement feature inside the use-macro attribute value:

<span metal:use-macro="${design}/site_macros.html/main_menu"/>

This attribute must appear under a metal:define-macro tag.

Slots can be replaced by caller template with some custom dynamically-generated XML/XHTML.

Slots can be thought of like reverse includes, a macro can be an entire page and slots customize this page depending on the URL. For instance, a slot may contain the latest news in the home page or user actions when the member is logged in.

<span metal:define-slot="news_place">
  <table>
    <tr tal:repeat="item php:latestNews()">
      <td tal:content="item/value">news description</td>
    </tr>
  </table>
</span>

The above example defines a place called 'news_place' which can be overwritten by caller templates. See next section for the continuation of this example.

This attribute occurs only under metal:use-macro context.

This explicitly tells PHPTAL to replace a defined slot with the content provided under the metal:fill-slot attribute.

<span tal:condition="logged" metal:fill-slot="news_place">
  <h2>user menu</h2>
  <ul>
    <li><a href="/user/action/inbox">inbox</a></li>
    <li><a href="/user/action/new">new mail</a></li>
    <li><a href="/user/action/disconnect">disconnect</a></li>
  </ul>
</span>

Slots give the opportunity to define really customizable and reusable page templates with a simple push technology.

This attribute defines some text part that must be translated using PHPTAL's translation system.

<div i18n:translate="string:welcome_message">Welcome here</div>

In the above example, PHPTAL will looks for a translation key named 'welcome_message' and will replace the content of the tag with the equivalent in currently requested language.

<div i18n:translate="">Welcome here</div>

This usage is a little different, no translation key is given, thus PHPTAL will use the content of the tag 'Welcome here' as the translation key. This is a regular translation if translation system knows the key 'Welcome here'.

If no translation is found, the key will be used as the translation result. That's why using readable message instead of keys may be a good choice.

Please note that the key to translate may be contained in a variable, to allow dynamic key selection.

<div tal:define="welcome random_welcome_message"/>
<did i18n:translate="welcome">...</div>

This attribute sets a translation variable value.

Translations may contain ${xxx} strings where "xxx" is the name of a variable that needs to be interpolated dynamically.

The value of this variable will be set to the tag and its content. If you don't need tag around the value, use tal:replace instead of tal:content. tal:omit-tag may help if the value is a concatenation of strings.

<span i18n:name="myVar" tal:content="some/path"/>
<!-- <span>${some/path}</span> -->

<span i18n:name="myVar" tal:replace="some/path"/>
<!-- ${some/path} -->

<span i18n:name="myVar">foo</span>
<!-- <span>foo</span> -->

<span i18n:name="myVar" tal:omit-tag="">foo</span>
<!-- foo -->

An example of i18n usage:

<div i18n:translate="">
  Welcome <span i18n:name="user" tal:replace="user/name"/>,
  you have <span i18n:name="mails" tal:replace="user/nbrMails"/>
  unread mails.
</div>

The translation key of this example will be:

"Welcome ${user}, you have ${mails} unread mails."

PHPTAL will replace ${user} with ${user/name} and ${mails} with ${user/nbrMails} in translation.

More information about I18N with PHPTAL is available in the PHP section of this book.

This attribute toggles the activation of PHPTAL debugging for the content of the tag it is defined in.

The debug mode stores information like filename and source line number in the template, so exceptions thrown by incorrect path access will contains more information about where they where thrown.

<html>
  <head>
    ...
  </head>
  <body>
    <div id="menu">
      ...
    </div>
    <div id="leftPane" phptal:debug=""
      tal:comment="this div seems buggy, keep
      trace of where errors are thrown">
          ...
    </div>
  </body>
</html>

This attribute causes output of entire element (including its tag) to be cached on disk and not re-evaluated until cache expires.

Content of this attribute is duration (how long element should be kept in cache) written as number with 'd', 'h', 'm' or 's' suffix.

<div class="footer" phptal:cache="3h">...</div>

<div> will be evaluated at most once per 3 hours.

Duration can be followed by optional "per" parameter that defines how cache should be shared. By default cache is shared between all pages that use that template. You can add "per url" to have separate copy of given element for every URL.

             
<ol id="breadcrumbs" phptal:cache="1d per url">...</ol>

<ol> will be cached for one day, separately for each page.

You can add "per expression" to have different cache copy for every different value of an expression (which MUST evaluate to a string). Expression cannot refer to variables defined using tal:define on the same element.

             
<ul id="user-info" phptal:cache="25m per object/id">...</ul>

<ul> will be cached for 25 minutes, separately for each object ID.

Limitations:

This attribute allows us to change the behaviour of PHPTALES. The default behaviours is to interpret attribute expressions in a very ZPT way. But sometimes you just would like to have PHP there, and you end up using php: modifier everywhere.

Another problem concerning PHPTALES is the way PHPTAL has to interpret paths. For example, myobject/mymethod/10/othermethod/hashkey takes a very long to interpret.

PHPTAL has (at runtime) to take myobject and discover that it is an object; find out that 'mymethod' is a method of this object (rather than a variable), and then to call it; explore the result to determine that it is an array; find the 'ten' element of this array, and determine that it is an object; decide that othermethod is a method of this object (rather than a variable), and get the result of its execution; find that it is an associative array, and then retrieve the value for the key 'hashkey'.

Of course this was an extreme example and most of the time we don't care, because the process is fast enough. But what if this very long path is called inside a big tal:repeat ? D'oh! phptal:tales can help us here:

<html>
  <body>
    <table phptal:tales="php">
      <tr tal:repeat="myobject document.getChildren()">
        <td
          tal:content="myobject.mymethod()[10].otherMethod()['hashkey']"></td>
      </tr>
    </table>
  </body>
</html>

Well, I am not sure that the example above compiles, but you get the idea of what you can do with phptal:tales. All tal, metal, i18n paths will be plain PHP expressions.

Please note that the above example do the same as:

<html>
  <body>
    <table>
      <tr tal:repeat="myobject php:document.getChildren()">
        <td 
          tal:content="php:myobject.mymethod()[10].otherMethod()['hashkey']"></td>
      </tr>
    </table>
  </body>
</html>

'php:' modifier is explained in its own chapter.

This is the default modifier used in TAL expression when no other modifier is specified.

The following lines will give the same result:

<span tal:content="data/user/name"/>
<span tal:content="path:data/user/name"/>
<span>${data/user/name}</span>

Inside the template or inside expression strings, you can refer to a context variable using its path in the form ${path/to/my/variable}

<h1>${document/title}</h1>
<span tal:replace="string:welcome ${user/name}, 
this page has been readed ${page/countRead} times"/>

As '<' and '>' should be removed from attribute expression. PHPTAL provides some equivalent good old text-comparison operators.

These statements will mostly appear in tal:condition attributes, and in php: expressions.

Because expressions are separated by a ';' character, and because '$' marks the start of a path, you must use:

<span tal:replace="string:this is a $$100 page"/>
string:foo $bar baz       <!-- will replace $bar -->
string:foo $$bar baz      <!-- no interpolation -->
string:foo ; php:doFoo()  <!-- two different expressions -->
string:foo ;; php:doFoo() <!-- only string -->

This expression evaluates what follows as a regular php expression except that '->' are replaced by dots '.' and variable names does not need to be prefixed with a dollar '$' sign.

A dot '.' separated from the rest of expression by spaces is assumed to be a concatenation sign.

php:htmlentities(foo)
php:'string ${varReplaced}'
php:'string ${some.path().to[0].var}'
php:NOT foo OR (bar GT baz)
php:a + b
php:array('a', 'b', 'c')
php:range(0, 90)
php:foo . a.b.c(e) . htmlentities(SomeClass::staticMethod()) 
php:SomeClass::ConstOfClass
php:SomeClass::$staticVar

php: should be used with care and won't be needed in 80% of your templates but sometimes you will need to invoke some special php method to be certain whether a user is logged in, or to retrieve specific complex data depending on some conditions, dynamically inside the template.

This expression is a boolean one, useful in tal:condition statements.

<span tal:condition="not: logged">not logged</span>

This expression is a boolean expression, it will returns true if the path specified after it exists of not.

<span tal:condition="exists: user/preferences"
      tal:content="user/preferences">
  user preferences here if defined
</span>

It is important to keep in mind that using a path which doesn't exist will throw and exception. Thus, uncertain paths must be checked first.

This is not an expression but a keyword, allowing template designers to keep the content of a tag as an alternative value if an error occurs, or if something is not defined.

<span tal:define="myVar path/to/possible/var | default">
  default my var value
</span>

<span tal:content="some/var | other/path | default">
  no some/var and no other/path found here
</span>

<a href="unknown.html" title="Unknown page"
   tal:attributes="href item/href | default; title item/title | default"
   tal:content="item/title | default">Unknown page</a>

Above examples introduce the '|' character that allows the definition of alternatives for defines or prints.

This is not an expression modifier but a keyword.

While printing variables inside PHPTAL templates, you will have noticed that PHPTAL encodes each variable to ensure the validity of the output document.

Sometimes, you may use HTML/XML variables which must be echoed as is.

<h1 tal:content="structure document/title"/>
<span tal:replace="structure document/content"/>

In above examples, we assume that $document->title and $document->content are variables containing preformated HTML which must be echoed as is.

An expression chain is a list of expressions separated by '|' characters.

While evaluating expressions separated by '|', PHPTAL will stop its evaluation when an expression value is not null and no error was raised while evaluating the expression.

As a string: expression is always true, string: always terminates an expression chain whatever expression may follow.

You can use php: expressions inside expression chains, like any other expression.

<h1 tal:content="page/title | page/alternativeTitle | default>
  untitled page
</h1>

This method may be called by the template to change the current output language.

Its arguments are a list of possible languages (use func_get_args() to get the argument array). The first known language should be used by your service.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
...
    public function setLanguage(){
        $langs = func_get_args();
        foreach ($langs as $lang){
            // if $lang known use it and stop the loop
            $this->_currentLang = $lang;
            return;
        }
    }
    ...
    private $_currentLang;
}
?>

If you decided to store your translations into separate files, one for each application, for example, this method allows you to select the translation domain from your templates (i18n:domain).

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    ...
    public function useDomain($domain){
        if (!array_key_exists($domain, $this->_domains)){
            $file = "domains/$this->_currentLang/$domain.php";
            $this->_domains[$domain] = include($file);
        }
        $this->_currentDomain = $this->_domains[$domain];
    }
    ...
    private $_currentDomain;
    private $_domains = array();
}
?>

The above example is a possible translation solution where keys are stored in php files which return an associative array of key => translation.

This method matches i18n:name calls. It builds an interpolation context for later translate calls.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    ...
    public function setVar($key, $value){
        $this->_context[$key] = $value;
    }
    ...
    private $_context = array();
}
?>

The last and most important method to implement, it asks your service to translate the specified key for the currently selected language.

<?php
require_once 'PHPTAL/TranslationService.php';

class MyTranslator implements PHPTAL_TranslationService {
    ...
    public function translate($key){
        $value = $this->_currentDomain[$key];
        
        // interpolate ${myvar} using context associative array
        while (preg_match('/\${(.*?)\}/sm', $value, $m)){
            list($src,$var) = $m;
            if (!array_key_exists($var, $this->_context)){
                $err = sprintf('Interpolation error, var "%s" not set', 
                               $var);
                throw new Exception($err);
            }
            $value = str_replace($src, $this->_context[$var], $value);
        }
        
        return $value;
    }
    ...
}
?>

The PHP gettext extension requires a specific structure which will contain your translation files.

/path/to/your/translation_root/en_US/LC_MESSAGES/
/path/to/your/translation_root/en_GB/LC_MESSAGES/
/path/to/your/translation_root/fr_FR/LC_MESSAGES/
/path/to/your/translation_root/es_ES/LC_MESSAGES/
... and so on ...

The language code is composed of two characters defining the language itself (en, fr, es, ...) and two characters defining the country (US, GB, FR, ES, ...).

The directory pattern is:

<path_to_where_you_want>/<ll_CC>/LC_MESSAGES/

PO files are plain text files that contain your translation. You can safely edit them by hand.

po minimalistic example (en_US/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "A small sentence in english"

Once edited, each PO file must be indexed using:

msgfmt mydomain.po -o mydomain.mo

This command won't work if you don't have gettext tools installed on your system.

This will produce a MO file (machine object) indexing your translation for quick access.

Then you have to translate this file in other languages.

po minimalistic example (fr_FR/LC_MESSAGES/mydomain.po):

msgid ""
msgstr ""
"Content-Type: text/plain; charset=utf-8\n"
"Content-Transfer-Encoding: 8bit\n"

msgid "Simple test"
msgstr "Une petite phrase en français"

The translation file must also be indexed:

msgfmt mydomain.po -o mydomain.mo

The domain is matched against your translation file names. In above examples we used 'mydomain' as domain name.

You can have more than one domain for the same application, it can enhance gettext's performance to split your application translations in more than one file.

<?php
require_once 'PHPTAL.php';
require_once 'PHPTAL/GetTextTranslator.php';

try {
    $tr = new PHPTAL_GetTextTranslator();
    
    // set language to use for this session (first valid language will 
    // be used)
    $tr->setLanguage('en_GB.utf8', 'en_GB');
    
    // register gettext domain to use
    $tr->addDomain('mydomain', '/path/to/your/translation_root/');

    // specify current domain
    $tr->useDomain('mydomain');

    $tpl = new PHPTAL('mytemplate.html');

    // tell PHPTAL to use our translator
    $tpl->setTranslator($tr);
}
catch (Exception $e){
    echo $e;
}

The I18N namespace allows some variable interpolation in your translations.

# english 
msgid "welcome"
msgstr "Welcome ${name} you have ${n} mails !"

# french  
msgid "welcome"
msgstr "Bienvenue ${name} vous avez recu ${n} messages !"

A template can use this interpolation as follows:

<span i18n:translate="welcome">
  Welcome
  <span i18n:name="name" tal:replace="user/name"/>
  you currently have
  <span i18n:name="n" tal:replace="user/unreadeMails"/>
  unread messages !
</span>

Because i18n:translate contains a value 'welcome', the template data will be ignored and the message given by gettext will be used instead.