ui:radio

This element displays a radiobox. The generated HTML code consists of an INPUT element with TYPE=RADIO, whose name attribute is set to a special identifier which is recognized by the system when the form is submitted.

The radiobox must be tied to an enumerator variable (either a declared one, or a dynamic enumerator), or a string variable. The name of the variable must be specified in the variable attribute. Furthermore, there must be a value attribute determining which value is visualized by the radiobox. The rule is as follows: The radiobox is in the state "checked" iff the specified value occurs in the set of values currently stored in the specified variable. A string variable is considered as a one-element set for this purpose.

The radiobox widget will be initialized to the state given by this rule when the current page is displayed. All radioboxes referring to the same variable form a group of boxes, and only one of the boxes can be checked at the same time. If the contents of the variable would cause that more than one box is checked, the browser enforces that only one box remains checked (but it is unspecified which box is selected).

Any state change of the widget caused by user interaction will be propagated back to the enumerator variable when the current page is submitted. This means that if the user checks the box the specified value will be added to the specified enumerator, and that conversely if the user releases the box the specified value will be deleted from the specified enumerator variable. In principle, other values contained in the enumerator variable than the specified one remain unchanged; however, the browser will automatically deselect all other radioboxes of the same group if one radiobox is checked, such that normally the other values of the enumerator are deleted.

Of course, the specified value is an internal value with respect to the difference between internal and external values.

In the following example, the user can answer a yes/no question. The variable user_answer is initialized with the set {"yes"}, and because of this, the page appears initially with a checked "Yes" box and an unchecked "No" box. The radioboxes simply visualize the current state of the variable. When the customer has given the answer and presses the "OK" button, the variable user_answer is automatically updated, and reflects again the current state of the boxes. From the handle callback method, one can read the variable user_answer and interpret the contents.

<ui:dialog name="sample" start-page="sample_page">
  <ui:enumeration name="yesno">
    <ui:enum internal="yes" external="Yes"/>
    <ui:enum internal="no"  external="No"/>
  </ui:enumeration>

  <ui:variable name="user_answer" type="yesno">
    <ui:enum-value>
      <ui:enum-item internal="yes"/>
    </ui:enum-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        What is your answer?
        <ul>
          <li><ui:radio variable="user_answer" value="yes"/>
              Yes</li>
          <li><ui:radio variable="user_answer" value="no"/>
              No</li>
        </ul>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Note that only the empty set and single-valued sets are reasonable values for the user_answer variable. Even if we initialize the variable with multi-valued sets (such as {"yes","no"}), the browser will enforce that only one of the boxes is checked; however, it is unspecified which box remains checked.

Declaration

Level: Generative

<!ELEMENT ui:radio EMPTY>
<!ATTLIST ui:radio
          variable NMTOKEN     #REQUIRED
          index    CDATA       #IMPLIED
          value    NMTOKEN     #REQUIRED
          cgi     (auto|keep)  "auto"
>

Additionally, ui:radio must only occur inside ui:form.

Attributes

The following attributes have a special meaning:

variable: Specifies the variable of the current dialog object to which the radiobox is tied. Unless the index attribute is present, the variable must be a declared enumerator, a dynamic denumerator, or a string. If there is an index attribute, the variable must be an associative list of one of the mentioned types.
index: Specifies the index value of the element of the associative variable to which the radiobox is tied.
value: Specifies the internal value whose presence in the enumerator is represented by the radiobox.
cgi: The value "auto" means that the name of the CGI variable associated with the radiobox is selected 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. 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 INPUT HTML element. This means that especially the onclick attribute may be specified.

Sub elements

ui:radio does not have sub elements.

Tips

Often, it is desired to iterate over all defined values of an enumerator, and to output a radiobox for every item. The following code demonstrates how ui:radio works in conjunction with ui:enumerate; it is a another version of the yes/no example:


<ui:template name="list_item" from-caller="int ext">
  <li>
    <ui:radio variable="user_answer" value="$int"/> $ext
  </li>
</ui:template>

<ui:dialog name="sample" start-page="sample_page">
  <ui:enumeration name="yesno">
    <ui:enum internal="yes" external="Yes"/>
    <ui:enum internal="no"  external="No"/>
  </ui:enumeration>

  <ui:variable name="user_answer" type="yesno">
    <ui:enum-value>
      <ui:enum-item internal="yes"/>
    </ui:enum-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        What is your answer?
        <ul>
          <ui:enumerate template="list_item"
                        type="yesno"/>
        </ul>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>