ui:checkbox

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

The checkbox must be tied to an enumerator variable (either a declared one, or a dynamic enumerator); 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 checkbox. The rule is as follows: The checkbox is in the state "checked" iff the specified value occurs in the set of values currently stored in the specified variable.

The checkbox widget will be initialized to the state given by this rule when the current page is displayed. Furthermore, 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. However, other members of the enumerator variable than the specified one remain unchanged.

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

In the following example, the customer can select which kind of fruit he orders. The variable customer_wish is initialized with the set {"apple"}, and because of this, the page appears initially with a checked "apple" box and unchecked "banana" and "ananas" boxes. The checkboxes simply visualize the current state of the variable. When the customer has selected his items and presses the "OK" button, the variable customer_wish is automatically updated from the state of the input widgets, and reflects again the current state of the boxes. From the handle callback method, one can read the variable customer_wish and interpret the contents.

<ui:dialog name="sample" start-page="sample_page">
  <ui:enumeration name="fruit">
    <ui:enum internal="apple"  external="Apple"/>
    <ui:enum internal="banana" external="Banana"/>
    <ui:enum internal="ananas" external="Ananas"/>
  </ui:enumeration>

  <ui:variable name="customer_wish" type="fruit">
    <ui:enum-value>
      <ui:enum-item internal="apple"/>
    </ui:enum-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        Please select what you want:
        <ul>
          <li><ui:checkbox variable="customer_wish" value="apple"/>
              Apples</li>
          <li><ui:checkbox variable="customer_wish" value="banana"/>
              Bananas</li>
          <li><ui:checkbox variable="customer_wish" value="ananas"/>
              Ananas</li>
        </ul>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Declaration

Level: Generative

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

Additonally, ui:checkbox 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 checkbox is tied. Unless the index attribute is present, the variable must be a declared enumerator or a dynamic enumerator. If there is an index attribute, the variable must be an associative list of either declared or dynamic enumerators.
index: Specifies the index value of the element of the associative variable to which the checkbox is tied.
value: Specifies the internal value whose presence in the enumerator is represented by the checkbox.
cgi: The value "auto" means that the name of the CGI variable associated with the checkbox 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:checkbox does not have sub elements.

Tips

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

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

<ui:dialog name="sample" start-page="sample_page">
  <ui:enumeration name="fruit">
    <ui:enum internal="apple"  external="Apple"/>
    <ui:enum internal="banana" external="Banana"/>
    <ui:enum internal="ananas" external="Ananas"/>
  </ui:enumeration>

  <ui:variable name="customer_wish" type="fruit">
    <ui:enum-value>
      <ui:enum-item internal="apple"/>
    </ui:enum-value>
  </ui:variable>

  <ui:page name="sample_page">
    <html>
      <body>
        Please select what you want:
        <ul>
          <ui:enumerate template="list_item"
                        type="fruit"/>
        </ul>
        <ui:button name="ok" label="OK"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>