ui:enumeration and ui:enum

Once an enumerator type has been declared, it can be referred to in variable declarations (see ui:variable) by setting the type attribute of the variable to the name of the enumerator type. Furthermore, the new type can be used in the ui:translate element to map internal tokens to external representations in the user interface. Another application of enumerator types is the possibility to enumerate their values by the ui:enumerate element.

The declaration looks like:

<ui:enumeration name="sample_enum">
  <ui:enum internal="int1" external="ext1"/>
  <ui:enum internal="int2" external="ext2"/>
  ...
</ui:enumeration>

The ui:enum elements specify the possible values of the enumerator. Every value has an internal and an external representation; the internal value is used to identify the value in programs while the external value is taken to display the value in the user interface. If the external value is missing, it defaults to the same value as the internal value.

Variables of the declared enumerator have set values: The set is a subset of the values specified in the enumerator declaration. For example, the variable

<ui:variable name="sample_var" type="sample_enum"/>

has possible values: {}, {"int1"}, {"int2"}, {"int1","int2"}, and so on.

The order of the ui:enum declarations determines the order of the enumerated values. Especially, this order is used when enumerators are visualized (for example, by ui:select interactors).

Declaration

Level: Dialog structure

<!ELEMENT ui:enumeration ( ui:enum )*>

<!ATTLIST ui:enumeration
          name NMTOKEN #REQUIRED>

<!ELEMENT ui:enum EMPTY>

<!ATTLIST ui:enum
          internal NMTOKEN  #REQUIRED
          external CDATA    #IMPLIED>

Attributes

The ui:enumeration element has only one attribute:

name: The name of the enumerator type

The ui:enum element has these attributes:

internal: Specifies the internal token of an enumerated value
external: Optionally, this attributes specifies the external representation of an enumerated value. If missing, the external value defaults to the same string as the internal value.

Example

<ui:dialog name="print_list" ...>
  <ui:enumeration name="list_length_type">
    <ui:enum internal="10" external="10 items per page"/>
    <ui:enum internal="20" external="20 items per page"/>
    <ui:enum internal="50" external="50 items per page"/>
    <ui:enum internal="100" external="100 items per page"/>
  </ui:enumeration>
  ...
  <ui:variable name="list_length" type="list_length_type">
    <!-- The default value of this variable: -->
    <ui:enum-value>
      <ui:enum-item internal="10"/>
    </ui:enum-value>
  </ui:variable>
  ...
  <ui:page name="select_list_length">
    <html>
      <body>
        Please select the number of items per page:
        <ui:select variable="list_length"/>
        ...
      </body>
    </html>
  </ui:page>
  ...
</ui:dialog>