This element displays a selection box offering the user a number of choices, and the user can select one or multiple items of the list. The generated HTML code consists of a SELECT element, whose name attribute is set to a special identifier which is recognized by the system when the form is submitted.

It is important to distinguish between two sets of values: The base set contains all items of the list, whereas the active set is the smaller set enumerating only the selected items of the list.

There are three ways to specify these sets:

• One can bind the selection list to a declared enumerator variable. In this case, the base set are all values declared in the ui:enumeration, and the active set are the current contents of the variable.

• One can explicitly specify an enumerator variable in the base attribute; the current contents of this variable will be taken as base set. In this case, it is possible to bind the selection list to a dynamic enumerator (for which no declaration exists that could set the base set implicitly). The active set are the current contents of this variable.

• Alternatively, the selection list can also be bound to a string variable when base is an enumerator. This is very useful for selections of the type 1 of N. The string variable contains the currently selected item of the base set, i.e. the active set has exactly one element.

As all input elements, the selection list must be bound to a variable (specified by the variable attribute). When the page is displayed, the base set determines the items of the selection list, and the current contents of the variable = the active set determines which of the items are selected. When the page is submitted, the active set is written back to the variable. Note that it is not possible to modify the base set by user interactions, and so there is no mechanism that writes such modifications back to a base set variable (if there is any). This means that (currently[1]) only the active set of the selection list is tied to a variable.

Level: Generative

<!ELEMENT ui:select EMPTY>
<!ATTLIST ui:select
          variable  NMTOKEN      #REQUIRED
          index     CDATA        #IMPLIED
          base      NMTOKEN      #IMPLIED
          baseindex CDATA        #IMPLIED
          multiple  (yes|no)     "no"
          size      CDATA        #IMPLIED
          cgi       (auto|keep)  "auto"
>

The following attributes have a special meaning:

• variable:Specifies the variable to which the active set of the selection list is tied. This must be a declared or dynamic enumerator variable, or a string variable. If the index attribute is also specified, this variable must be an associative enumerator, or an associative string.

• index: Specifies the index value of the element of the associative variable to which the active set is tied.

• base: Specifies the variable determining the base set of the selection list. This must be a declared or dynamic enumerator variable. If the baseindex attribute is also specified, this variable must be an associative enumerator. If the base attribute is omitted, and the variable specified by variable is a declared enumerator, the set of all declared values of this enumerator will be used as base set. It is an error to omit this attribute if the variable specified by variable is not a declared enumerator.

• baseindex: Specifies the index value of the element of the associative variable specified by the base attribute.

• multiple: Specifies whether the selection list allows multiple selections ("yes") or not ("no").

• size: Specifies the size of the visual layout of the selection list, i.e. the number of items that can be manipulated without scrolling. If omitted, and if multiple="no", the selection list will be usually rendered as drop-down menu.

• cgi: The value "auto" means that the name of the CGI variable associated with the selection list is determined automatically. This works perfectly unless you want to refer to this variable from Javascript or from some other manually written event decoder. The value "keep" causes that the name of the CGI variable is predictable: it is var_ concatenated with the name of the variable (of the active set). However, it is not allowed to specify "keep" if there is also an index value. Furthermore, the variable name should only contain alphanumeric characters, because not all punctuation characters can be safely transported over the CGI protocol.

If there are any other attributes, these are added to the generated SELECT HTML element. This means that especially onblur, onchange, onfocus, and onselect may be specified.

The ui:select element does not have sub elements.

The ui:select element generates HTML code which roughly looks as follows:

<select name="..." ...>
  <option value="..." [selected]>...
  ...
</select>

Here, the base set is { "0", "1" }, i.e. simply the values declared for the enumeration bool. This means that the selection list will offer the values "0" and "1" (but the user will see "false" and "true" because the external values are the visible ones). The active set is tied to the variable b, and b is initialized with { "0" }. When the page is first displayed, the selection list will show "false". Any changes resulting from user interaction will be written back to b; i.e. if the user selects "true", the active set becomes { "1" }, and if he goes back to "false", the active set will again be { "0" }.

<ui:dialog name="sample" start-page="sample_page">
  <ui:enumeration name="bool">
    <ui:enum internal="0" external="false"/>
    <ui:enum internal="1" external="true"/>
  </ui:enumeration>

  <ui:variable name="b" type="bool">
    <ui:enum-value>
      <ui:enum-item internal="0">
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        Please select your boolean value:
        <ui:select variable="b"/>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

In this example, the base set is considered dynamic, for example it might be initialized from a database. However, the following fragment simply sets the base set candidates to a fixed list of candidates; I hope you can imagine that this could also be done by additional code in a really dynamic way. Consequently, the active set must be considered as dynamic, too, because the active set is always a subset of the base set. The active set vote is empty at the beginning, and the selection list will show only unselected items. After the user has clicked "OK", the selection will be written back to vote, which will be either empty or contain one candidate name.

<ui:dialog name="sample" start-page="sample_page">
  <ui:variable name="candidates" type="dynamic-enumerator">
    <ui:dyn-enum-value>
      <ui:dyn-enum-item internal="1234" external="Smith, Joe"/>
      <ui:dyn-enum-item internal="763"  external="Jackson, Dave"/>
      <ui:dyn-enum-item internal="128"  external="Miller, Jack"/>
    </ui:dyn-enum-value>
  </ui:variable>

  <ui:variable name="vote" type="dynamic-enumerator"/>

  <ui:page name="sample_page">
    <html>
      <body>
        Please vote for your favourite candidate:
        <ui:select variable="vote" base="candidates" size="3"/>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

The task is the same as in example 2. As you can only select one of the candidates, it is also possible to declare vote as string. This string should be initialized to one of the possible values, otherwise it is left to the browser (and unspecified) to initialize the dropdown list.

<ui:dialog name="sample" start-page="sample_page">
  <ui:variable name="candidates" type="dynamic-enumerator">
    <ui:dyn-enum-value>
      <ui:dyn-enum-item internal="1234" external="Smith, Joe"/>
      <ui:dyn-enum-item internal="763"  external="Jackson, Dave"/>
      <ui:dyn-enum-item internal="128"  external="Miller, Jack"/>
    </ui:dyn-enum-value>
  </ui:variable>

  <ui:variable name="vote" type="string">
    <ui:string-value>763</ui:string-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        Please vote for your favourite candidate:
        <ui:select variable="vote" base="candidates" size="3"/>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

[1]

This is a restriction of HTML. I can imagine a selection list to which the user can add missing items, and I think such an extension would be practical in many situations. Perhaps the WWW Consortium adds this feature some day.