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>