ui:enumerate

This elements instantiates a template several times. It is possible to enumerate the members of a declared enumerator type, and it is possible to enumerate the values of an enumerator variable (declared or dynamic). For every member the template is expanded, and the resulting texts are concatenated.

$int and $ext

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

The parameter $int is set to the internal value of the member, and the parameter $ext is set to the corresponding external value of the member while the template is being expanded for the corresponding member.

Declaration

Level: Control structure

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

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

Attributes

template: Names the template to instantiate. Note that the current language of the dialog may also influence which template is selected.
type: The type to enumerate. There must be an ui:enumeration for this type. If type is present, neither variable nor index must be specified.
variable: Selects the variable containing the enumerated values. This variable must be either a declared or a dynamic enumerator. If variable is present, the attribute type must not be specified.
index: If the variable is an associative list over enumerators, this attribute selects the component to use.

Sub elements

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.

Example


<ui:dialog name="preferred-colors" start-page="input-color">
  <ui:enumeration name="color">
    <ui:enum internal="ff0000" external="red"/>
    <ui:enum internal="00ff00" external="green"/>
    <ui:enum internal="0000ff" external="blue/>
  </ui:enumeration>

  <ui:variable name="prefcol" type="color"/>

  <ui:page name="input-color">
    <html>
      <body>
        Select your preferred colors:
        <ui:select variable="prefcol" multiple="yes"/>
        <ui:button name="ok" label="OK" goto="print-color"/>
      </body>
    </html>
  </ui:page>

  <ui:page name="print-color">
    <html>
      <body>
        You have selected:
        <ui:enumerate variable="prefcol" template="print">
          <ui:iter-empty>Nothing!</ui:iter-empty>
          <ui:iter-sep>, </ui:iter-sep>
        </ui:enumerate>
      </body>
    </html>
  </ui:page>
</ui:dialog>
    
<ui:template name="print" from-caller="ext">
  "$ext"
</ui:template>

In this example, the variable prefcol, a declared enumerator of type color is iterated. For all selected colors the template print is called which puts the external names into double quotes. Furthermore, the separator is a comma followed by a space character. If no color is selected, the special string "Nothing!" is printed instead.

Assumed that the user has selected red and blue, the output of this example is:

You have selected: "red", "blue"