repeat: Repeat an element

Syntax

tal:repeat syntax:

      argument      ::= variable_name expression
      variable_name ::= Name

Description

The tal:repeat statement replicates a sub-tree of your document once for each item in a sequence. The expression should evaluate to a sequence. If the sequence is empty, then the statement element is deleted, otherwise it is repeated for each value in the sequence. If the expression is default, then the element is left unchanged, and no new variables are defined.

The variable_name is used to define a local variable and a repeat variable. For each repetition, the local variable is set to the current sequence element, and the repeat variable is set to an iteration object.

Repeat Variables

You use repeat variables to access information about the current repetition (such as the repeat index). The repeat variable has the same name as the local variable, but is only accessible through the built-in variable named repeat.

The following information is available from the repeat variable:

• index - repetition number, starting from zero.
• number - repetition number, starting from one.
• even - true for even-indexed repetitions (0, 2, 4, ...).
• odd - true for odd-indexed repetitions (1, 3, 5, ...).
• start - true for the starting repetition (index 0).
• end - true for the ending, or final, repetition.
• first - true for the first item in a group - see note below
• last - true for the last item in a group - see note below
• length - length of the sequence, which will be the total number of repetitions.
• letter - repetition number as a lower-case letter: "a" - "z", "aa" - "az", "ba" - "bz", ..., "za" - "zz", "aaa" - "aaz", and so forth.
• Letter - upper-case version of letter.
• roman - repetition number as a lower-case roman numeral: "i", "ii", "iii", "iv", "v", etc.
• Roman - upper-case version of roman.

You can access the contents of the repeat variable using path expressions or Python expressions. In path expressions, you write a three-part path consisting of the name repeat, the statement variable's name, and the name of the information you want, for example, repeat/item/start. In Python expressions, you use normal dictionary notation to get the repeat variable, then attribute access to get the information, for example, "python:repeat['item'].start".

Note that first and last are intended for use with sorted sequences. They try to divide the sequence into group of items with the same value. If you provide a path, then the value obtained by following that path from a sequence item is used for grouping, otherwise the value of the item is used. You can provide the path by passing it as a parameter, as in "python:repeat['item'].first(color)", or by appending it to the path from the repeat variable, as in "repeat/item/first/color".

Examples

Iterating over a sequence of strings::

Inserting a sequence of table rows, and using the repeat variable to number the rows:

      <table>
        <tr tal:repeat="item here/cart">
            <td tal:content="repeat/item/number">1</td>
            <td tal:content="item/description">Widget</td>
            <td tal:content="item/price">$1.50</td>
        </tr>
      </table>

Nested repeats:

      <table border="1">
        <tr tal:repeat="row python:range(10)">
          <td tal:repeat="column python:range(10)">
            <span tal:define="x repeat/row/number; 
                              y repeat/column/number; 
                              z python:x*y"
                  tal:replace="string:$x * $y = $z">1 * 1 = 1</span>
          </td>
        </tr>
      </table>

Insert objects. Seperates groups of objects by meta-type by drawing a rule between them:

      <div tal:repeat="object objects">
        <h2 tal:condition="repeat/object/first/meta_type"
            tal:content="object/meta_type">Meta Type</h2>
        <p tal:content="object/getId">Object ID</p>
        <hr tal:condition="repeat/object/last/meta_type" />
      </div>

Note, the objects in the above example should already be sorted by meta-type.