PHPTAL Manual

Defines variables in the template.

It takes one or multiple semicolon-separated variable definitions.

Making a shortcut to a long path:

<div tal:define="destname path/to/existing/variable">…</div>

Defining more than one variable at the same time:

<span tal:define="fname string:Paul; lname string:Dupond">…</span>

Each definition may start with global keyword which makes variable available everywhere later in the template and all macros. Global variables can be redefined.

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

On the contrary, a local variable is only available inside the element it is defined in (and inside macros that are called in this element):

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

Creating a string inside the template:

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

Defining a string containing another variable:

<span tal:define="fname string:Paul; hello string:Hello $fname! Welcome to this page" />

A small trick which uses content of the element (useful if you need to define very complex value):

<span tal:define="global hello">Hello ${fname}! Welcome to this page</span>

In above example, the <span> tag won't show up because it has no printable content (hello variable grabs it) nor attributes.

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

<p tal:condition="identified"> Welcome member … </p>

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

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/hasEnoughItems">…</span>

This attribute handles iterable objects like arrays, associative arrays, and objects implementing the PHP5 Iterator 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. The following code will work if playersRanking contains object that implements PHP's Iterator 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 elements's open and close tag, its content will still be evaluated.

<span tal:omit-tag="condition">
  if the condition is true, then only this text will appear and 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 create element optionally, e.g. hide a link if certain condition is met.

If you want element that is never output, you can use tal:block

<tal:block tal:repeat="x php:range(1,10)">only this text will appear, ten times.</tal:block>

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

<span tal:replace="string:this beautiful string">
  this ugly string and span
</span>

Will produce:

this beautiful 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>

Semicolon (;) separates attributes. If you want semicolon to be output in an attribute, you have to double it (;;).

A somewhat complicated example involving tal:repeat:

<tr tal:repeat="ranking playerRankings"
    tal:attributes="class php: repeat.ranking.odd ? 'odd' : NULL">
    …
</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 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:attributes="class css-odd:repeat/ranking/odd">
  …
</tr>

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

… tal:attributes="title object/tooltip | nothing"> 

<input type="checkbox" tal:attributes="checked object/isChecked"/>

This attribute replaces the element with the tal:on-error content if any runtime error is detected while generating the element, such as reference to non-existent variable or macro.

<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 all variables from their caller. 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.xhtml/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.xhtml/main_menu"/>

Macro can call itself. This way you can output arrays recursively:

<ul metal:define-macro="show-list">
    <li tal:repeat="item list">
        <tal:block tal:condition="php:is_array(item)" tal:define="list item" metal:use-macro="show-list" />
        <tal:block tal:condition="php:!is_array(item)" tal:content="item" />
    </li>
</ul>

<!-- this code uses "macroname" variable as name of macro to call back -->
<ul metal:define-macro="macro-with-callback">
    <li tal:repeat="item list">
        <tal:block metal:use-macro="${macroname}"/>
    </li>
</ul>

<!-- define callback -->
<div metal:define-macro="my-callback">
    this will be called every time
</div>

<!-- use it with the first macro -->
<div tal:define="macroname 'my-callback'" metal:use-macro="macro-with-callback"/>

This attribute must appear inside 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 can occur only inside metal:use-macro element.

This explicitly tells PHPTAL to replace a defined slot with the content provided inside 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">
  <div i18n:translate="welcome">…</div>
</div>

Defines which attributes should be translated. Takes semicolon-separated list of attributes and keys similar to those for i18n:translate.

<img i18n:attributes="alt 'picture alternative text';title thetitle" alt="Picture" title="${thetitle}" />

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 the 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.

By defaults translations are assumed to contain only text, so PHPTAL escapes all "<" characters.

You can use structure keyword in i18n:translate to disable escaping and use translated text as-is:

<div i18n:translate="structure '<b>bold text</b>'" />

Gives:

<div><b>bold text</b></div>

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 contain 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 a 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).

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

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

<div phptal:cache="100d per php:news.id . news.last_modified_date">…</div>

This attribute allows us to change the behavior of PHPTALES. The default behaviors 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/property/10/othermethod/hashkey takes relatively long to interpret (but don't worry about this too much – don't optimize until you find that it is really a problem with performance!)

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 object with a property; find that its value 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 object, 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().property[10].otherMethod().hashkey"></td>
      </tr>
    </table>
  </body>
</html>

Please note that the above example does the same as:

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

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"/>

Because '<', '>' and '&' characters are cumbersome to use in XML, PHPTAL provides alternative syntax for PHP operators using these characters, and a few more for consistency.

These operators can be used only 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 '->' is replaced by dots '.' and variable names are 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 returns true if the path specified after it exists, and false otherwise. It is analogous to PHP's isset().

Normally using a path which doesn't exist throws an error like "Cannot find variable 'foo' in current scope". Thus, uncertain paths must be checked first:

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

This expression returns true if the path specified after it exists and has value that evaluates to true (the value can be of any type). It is analogous to PHP's !empty() construct.

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.xhtml" 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 preformatted 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 | php:get_default_title()" />

PHPTAL tries to use best defaults possible and you shouldn't need to change any of the settings.

All of these are methods of the PHPTAL class. set* methods return instance of their class, so you can chain them:

<?php
echo $phptal->setPhpCodeDestination('/tmp/phptal')->setOutputMode(PHPTAL::XML)->setTemplate('tpl.zpt')->execute();
?>

is the same as:

<?php
$phptal->setPhpCodeDestination('/tmp/phptal');
$phptal->setOutputMode(PHPTAL::XML);
$phptal->setTemplate('tpl.zpt');
echo $phptal->execute();
?>

There are other set* methods for filters, internationalization, etc. They have been described in other sections of this manual.

Executes the template and returns final markup.

PHPTAL keeps all variables after execution and this method can be called multiple times. You can use it to create multiple versions of the same page (by changing only some variables between executions) or to generate multiple different templates with same variables (by calling setTemplate() between executions).

Since most common use of execute() method is to echo its output, PHPTAL offers convenience method that echoes output immediately without buffering. This enables streaming of arbitrarily large output without hitting memory limit.

The code:

<?php
    $tpl = new PHPTAL('template.xhtml');
    $tpl->echoExecute();
?>

is same as:

<?php
    $tpl = new PHPTAL('template.xhtml');
    echo $tpl->execute();
?>

but little faster.

Adds new pre filter that will be applied to the template. Pre filters can modify source code and parsed DOM nodes of the template. Pre filters are applied in other they've been set.

See description of PHPTAL_PreFilter for more information how to write your own pre filter.

This method may be called by the template to change the current output language and/or locale (e.g. en_US).

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.

Return language that has been set.

<?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;
            break;
        }
        return $this->_currentLang;
    }
    …
    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;
    }
    …
}
?>

PHPTAL class calls this method to inform your translation service what encoding is used by the template. translate() method should return strings in that encoding. If you always use the same encoding for templates and translation files (i.e. UTF-8), you can leave this method empty.

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.xhtml');

    // tell PHPTAL to use our translator
    $tpl->setTranslator($tr);

    // output translated template
    echo $tpl->execute();
}
catch (Exception $e){
    echo $e;
}

If you need to translate some other text, that is not in the template (e.g. plaintext e-mail message), you can reuse PHPTAL's translator:

$tr = $tpl->getTranslator();

$subject = $tr->translate("Registration information");

$tr->setVar("user",$username);
$message = $tr->translate("Dear ${user}, thanks for registering!");

mail($email, $subject, $message);

If you're using PHPTAL's standard gettext™ translator, you can use gettext() too.

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.