This elements instantiates a template several times. For every component of a compound variable the template is expanded, and the resulting texts are concatenated. The following types of variables can be iterated:

• Dynamic enumerators: The members of the set are iterated in turn

• Associations: The elements of the associative variable are iterated in turn

• Strings: Even strings can be iterated. The string is regarded as a list of words; the words must be separated by white space.

For an overview over templates, see the chapter Templates.

See also the similar element ui:enumerate that works for declared enumerators.

The element iterates over the components of the given variable. For every component, the named template is called, and the lexical parameters $int and $ext identify the components. These parameters are always passed to the template (and additionally, the parameters given by ui:param, and the current context parameters are passed, too).

If the variable is a dynamic enumerator, $int will be set to the internal values of the components, and $ext will be set to the external values of the components.

If the variable is associative, $int will be set to the keys of the components, and $ext will be set to the associated values of the components, if possible. The latter is only defined for associative string variables. For other types of associations, the parameter $ext is simply empty.

If the variable is a string (list of words), $int will be set to the index number of the words (0 for the first word, 1 for the second word, etc.). The parameter $ext will be set to the words themselves.

Level: Control structure

<!ELEMENT ui:iterate ( ( ui:param )*,
                       ( ui:iter-empty )?,
                       ( ui:iter-head )?,
                       ( ui:iter-foot )?,
                       ( ui:iter-separator )?
                     )
>

<!ATTLIST ui:iterate
          template NMTOKEN   #REQUIRED
          variable NMTOKEN   #REQUIRED
          index    CDATA     #IMPLIED
>

• template: Names the template to instantiate. Note that the current language of the dialog may also influence which template is selected (see below).

• variable: Selects the variable containing the iterated values. This variable must be either a dynamic enumerator, or an association, or a string.

• index: If the variable is an associative list over dynamic enumerators or strings, this attribute selects the component to use.

• ui:param: Passes additional lexical parameters to the called template.

• ui:iter-empty: If existing, and if the iterated variable is empty, the nodes below ui:iter-empty are expanded instead of the template.

• ui:iter-head: If existing, and the iterated variable is non-empty, the nodes below ui:iter-head are prepended to the concatenated template instances.

• ui:iter-foot: If existing, and the iterated variable is non-empty, the nodes below ui:iter-foot are appended to the concatenated template instances.

• ui:iter-separator: If existing, and the iterated variable contains more than one component, the nodes below ui:iter-separator are placed between the template instances.

If a certain language is selected for the dialog, this also affects the template system. In particular, it is first checked if the used template is defined for this language, and if so, this version of the template will be used. Otherwise, it is checked whether there is a template without xml:lang attribute, and if it can be found, this version will be used.

For more information, see the chapter about Internationalization.

<ui:dialog name="sample" start-page="show">
  <ui:variable name="fruit_index">
    <ui:string-value>0 3</ui:string-value>
  </ui:variable>

  <ui:variable name="fruit" type="dynamic-enumerator">
    <ui:dyn-enum-value>
      <ui:dyn-enum-item internal="0" external="apple"/>
      <ui:dyn-enum-item internal="1" external="ananas"/>
      <ui:dyn-enum-item internal="2" external="pineapple"/>
      <ui:dyn-enum-item internal="3" external="banana"/>
    </ui:dyn-enum-value>
  </ui:variable>

  <ui:page name="show">
    <html>
      <body>
        <p>Available fruit:
          <ui:iterate variable="fruit" template="display-fruit"/>
        </p>

        <p>Selected fruit according to index:
          <ui:iterate variable="fruit_index" template="display-fruit-idx"/>
        </p>
      </body>
    </html>
  </ui:page>
</ui:dialog>

<ui:template name="display-fruit" from-caller="ext">
  <tt>$ext</tt>
</ui:template>

<ui:template name="display-fruit-idx" from-caller="int">
  <tt>$[translate(fruit,$int)]</tt>
</ui:template>