Wiki ⇒ v10 Developer's manual ⇒ Themes ⇒ CPG Dragonfly™ CMS

14. 4: Themes Parent

TAL (Template Attribute Language)

The new Dragonfly CMS v10 uses a template system based on Zope's TAL system (wikipedia).
However, METAL is not supported.

More information can be found at:
Using Zope Page Templates
Advanced Page Templates
Appendix C: Zope Page Templates Reference

TAL Commands

TAL consists of eight different commands (highest priority first): define, condition, repeat, include, content, replace, attributes, and omit-tag. Commands are attributes on HTML or XML tags, e.g. <div tal:content="article">Article goes here</div>


Syntax: tal:define="[local | global] name expression [; define-expression...]"

Description: Sets the value of "name"to "expression". By default the name will be applicable in the "local" scope, which consists of this tag, and all other tags nested inside this tag. If the "global" keyword is used then this name will keep its value for the rest of the document.

Example: <div tal:define="global title book/theTitle; local chapterTitle book/chapter/theTitle">


Syntax: tal:condition="expression"

Description: If the expression evaluates to true then this tag and all its children will be output. If the expression evaluates to false then this tag and all its children will not be included in the output.

Example: <h1 tal:condition="IDENTITY/isAdmin">Welcome admin to this page!</h1>


Syntax: tal:condition-else="expression"

Description: This attribute is added in our system to construct faster if/elseif/else blocks. If the expression is omitted it is interpreted as the else block, else it is an elseif block. If the expression evaluates to true then this tag and all its children will be output. If the expression evaluates to false then this tag and all its children will not be included in the output.

Example: <h1 tal:condition-else="IDENTITY/isMember">Welcome member to this page!</h1>


Syntax: tal:repeat="name expression"

Description: Evaluates "expression", and if it is a sequence, repeats this tag and all children once for each item in the sequence. The "name" will be set to the value of the item in the current iteration, and is also the name of the repeat variable. The repeat variable is accessible using the TAL path: repeat/name and has the following properties:

  1. index - Iteration number starting from zero

  2. number - Iteration number starting from one

  3. even - True if this is an even iteration

  4. odd - True if this is an odd iteration

  5. start - True if this is the first item in the sequence

  6. end - True if this is the last item in the sequence. For iterators this is never true

  7. length - The length of the sequence. For iterators this is maxint as the length of an iterator is unknown

  8. letter - The lower case letter for this iteration, starting at "a"

  9. Letter - Upper case version of letter

  10. roman - Iteration number in Roman numerals, starting at i

  11. Roman - Upper case version of roman


	<tr tal:repeat="fruit basket">
	<td tal:content="repeat/fruit/number"></td>
	<td tal:content="fruit/name"></td>


Syntax: tal:include="filename"

Description: Replaces the contents of the tag with the structure of the template "filename" content.

Example: <div tal:include="dragonfly/media/photoswipe"/>


Syntax: tal:content="[text | structure] expression"

Description: Replaces the contents of the tag with the value of "expression". By default, or if the "text" keyword is present, the value of the expression will be escaped as required (i.e. characters "&<> will be escaped). If the "structure" keyword is present then the value will be output with no escaping performed.

Example: <h1 tal:content="IDENTITY/nickname"></h1>


Syntax: tal:replace="[text | structure] expression"

Description: Behaves identically to tal:content, except that the tag is removed from the output (as if tal:omit-tag had been used).

Example: <h1>Welcome <b tal:replace="IDENTITY/nickname"></b></h1>


Syntax: tal:attributes="name expression[;attributes-expression]"

Description: Evaluates each "expression" and replaces the tag's attribute "name". If the expression evaluates to nothing then the attribute is removed from the tag. If the expression evaluates to default then the original tag's attribute is kept. If the "expression" requires a semi-colon then it must be escaped by using ";;".

Example: <a tal:attributes="href IDENTITY/website;title IDENTITY/nickname">Your Homepage</a>


Syntax: tal:omit-tag="expression"

Description: Removes the tag (leaving the tags content) if the expression evaluates to true. If expression is empty then it is taken as true.

Example: <h1><b tal:omit-tag="not:IDENTITY/isMember">Welcome</b> to this page!</h1>

TALES Expressions

The expressions used in TAL are called TALES expressions. The simplest TALES expression is a path which references a value, e.g. page/body references the body property of the page object.


Syntax: [path:]string[|TALES Expression]

Description: A path, optionally starting with the modifier 'path:', references a property of an object. The '/' delimiter is used to end the name of an object and the start of the property name. Properties themselves may be objects that in turn have properties. The '|' ("or") character is used to find an alternative value to a path if the first path evaluates to 'Nothing' or does not exist.

Example: <p tal:content="book/chapter/title | string:Untitled"></p>

There are several built in paths that can be used in paths:

  1. nothing - acts as NULL in PHP

  2. default - keeps the existing value of the node (tag content or attribute value)

  3. repeat - access the current repeat variable (see tal:repeat)

  4. attrs - a dictionary of original attributes of the current tag


Syntax: exists:path

Description: Returns true if the path exists, false otherwise. This is particularly useful for removing tags from output when the tags will have no content.

Example: <p tal:omit-tag="not:exists:book/chapter/title" tal:content="book/chapter/title"></p>


Syntax: not:tales-path

Description: Returns the inverse of the tales-path. If the path returns true, not:path will return false.

Example: <p tal:condition="not:IDENTITY/isMember">Welcome anonymous to the site!</p>


Syntax: string:text

Description: Evaluates to a literal string with value text while substituting variables with the form ${pathName} and $pathName

Example: <b tal:content="string:Welcome ${IDENTITY/nickname}!"></b>


Syntax: php:php-code

Description: Evaluates the php-code and returns the result. The PHP code must be properly escaped, e.g. "php: 1 < 2" must be written as "php: 1 &lt; 2". The PHP code has access to many PHP functions, including the TALES path as ${path}

Example: <div tal:condition="php: ${basket/items} &gt; 0">Checkout!</div>

I18N Commands


Syntax: i18n:attributes="name[ expression][;attributes-expression]"

Description: This attribute will allow us to translate attributes, such as the alt attribute in the img tag. The i18n:attributes attribute specifies a list of attributes to be translated with optional message IDs for each; if multiple attribute names are given, they must be separated by semicolons. Note that the value of the particular attributes come either from the expression or from the attribute value or from the data inserted by tal:attributes. If an attibute is to be both computed using tal:attributes and translated, the translation service is passed the result of the TALES expression for that attribute.

Example 1: <img src="" alt="Visit us" tal:attributes="alt context/greeting" i18n:attributes="alt"/>

Example 2: <img src="" alt="Visit us" i18n:attributes="alt 'Visit us'"/>


Syntax: i18n:translate="[expression]"

Description: This attribute is used to mark content for translation. If this attribute is specified with an empty string as the value, the message ID is computed from the content of the element bearing this attribute. Otherwise, the value of the element gives the message ID.

Example 1: <a i18n:translate="">Your Homepage</a>

Example 2: <a i18n:translate="My Homepage">Your Homepage</a>

Example 3: <a i18n:translate="" tal:content="product/name">Product name translated</a>

v9 theme in v10

Mostly a v9 theme is compatible with v10, however you are encouraged to use the faster v10 system.
It is much cleaner then the old v9 HTML and PHP, and is written in XML for different outputs.
Just copying your old "/themes/*/template/*.html" files to "themes/*/html/*.xml" will not work.
You must also convert the template code like the following examples:

<var>{VAR_WITHOUT_HTML}</var><var tal:content="VAR_WITHOUT_HTML"><var>
{VAR_WITH_HTML}<var tal:replace="structure VAR_WITH_HTML"></var>
<!-- IF VAR -->.....<div tal:condition="VAR">...
<!-- IF not VAR -->...<div tal:condition="not:VAR">...
...<!-- ELSEIF VAR -->......</div><div tal:condition-else="VAR">...
...<!-- ELSE -->......</div><div tal:condition-else="">...
...<!-- ENDIF -->...</div>
<!-- BEGIN loop -->...<div tal:repeat="row loop">...
<var>{loop.VAR}</var><var tal:content="row/VAR"><var><
...<!-- END loop -->...</div>
<!-- INCLUDE file.html --><var tal:replace="structure php:here.toString('file')"/>

v9 example:

<!-- BEGIN user_details -->
	<!-- IF postrow.user_details.TARGET -->
	<a href="{postrow.user_details.URL}" target="{postrow.user_details.TARGET}">
<img src="{postrow.user_details.IMG}" alt="{postrow.user_details.TITLE}" title="{postrow.user_details.TITLE}"/>
</a> <!-- ELSE --> <a href="{postrow.user_details.URL}">
<img src="{postrow.user_details.IMG}" alt="{postrow.user_details.TITLE}" title="{postrow.user_details.TITLE}"/>
</a> <!-- ENDIF --> <!-- END user_details -->

v10 equivalent:

<a tal:repeat="d postrow/user_details" tal:attributes="href d/URL; target d/TARGET">
	<img tal:attributes="src d/IMG; alt d/TITLE; title d/TITLE"/>

Created: Sunday, March 27, 2016 (17:23:35) by DJ Maze
Updated: Thursday, August 09, 2018 (00:57:37) by DJ Maze