ui:button

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

When the user clicks on the button, a Button event is generated (unless the index attribute is specified; see below); the handle callback method of the dialog object can check whether the current event is the event associated with this button, and the method can execute code depending on the result of this check. For a description of possible events see Events. The following example illustrates button events:

<ui:dialog name="sample" start-page="p1">
  <ui:page name="p1">
    <html>
      <body>
        <h1>Button test</h1>
        This is a <ui:button name="b" label="Button"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Here, the button event has the name "b". In order to check in the handle method whether this event occured, the following piece of code is recommended. O'Caml:

method handle =
  match self # event with
    Button "b" ->
      ... (* Do whatever you want to do *)
  | ... (* other cases *)

- Perl:

sub handle {
    my ($self) = @_;
    my ($e, $name) = $self->event;
    if ($e eq 'BUTTON' && $name eq 'b') {
        ... # Do whatever you want to do
    } elsif ... # other cases
    ;
    return undef;
}

If the ui:button element has the index attribute, the button is identified by the pair (name,index). When the user clicks on such an indexed button, an Indexed_button event is generated. The index value can be used to distinguish between several instances of buttons of the same type. For example, a book store may offer the customer several books:

<ui:dialog name="sample" start-page="view_records">
  <ui:page name="view_records">
    <html>
      <body>
        <h1>View books</h1>
        <table>
          <tr>
            <th>Author</th>
            <th>Title</th>
            <th>Action</th>
          </tr>
          <tr>
            <td>Damon Runryon</td>
            <td>Guys and Dolls</td>
            <td><ui:button name="view" label="View Details" index="4523"/></td>
          </tr>
          <tr>
            <td>William S. Burroughs</td>
            <td>Naked Lunch</td>
            <td><ui:button name="view" label="View Details" index="8612"/></td>
          </tr>
        </table>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Here, the index value is the database ID of the record. The typical code to check for such a button in the handle callback is - O'Caml:

method handle =
  match self # event with
    Indexed_button("view", index) ->
      ... (* Do whatever you want to do *)
  | ... (* other cases *)

- Perl:

sub handle {
    my ($self) = @_;
    my ($e, $name, $index) = $self->event;
    if ($e eq 'INDEXED_BUTTON' && $name eq 'view') {
        ... # Do whatever you want to do
    } elsif ... # other cases
    ;
    return undef;
}

Note that the transport mechanism for the strings specified for name and/or index is 8 bit clean (at least if cgi="auto"). This means that the name and index strings may be composed of all characters of the character set.

Declaration

Level: Generative element

<!ELEMENT ui:button EMPTY>
<!ATTLIST ui:button
          name  NMTOKEN     #REQUIRED
          index CDATA       #IMPLIED
          label CDATA       #IMPLIED
          goto  NMTOKEN     #IMPLIED
          cgi   (auto|keep) "auto"
>

Additionally, ui:button must occur inside ui:form.

Attributes

The following attributes have a special meaning:

name: Specifies the name of the button.
index: Specifies the index value of the button. If this attribute is present, the button becomes an indexed button; otherwise the button is a plain button.
label: Specifies the text appearing on the button.
goto: Specifies which page is the next page if the button is pressed. The variable containing the next page is initialized with the name specified here before the handle method is invoked. This means that the action of the button is to go to this page, unless the action is overridden in the handle method.
cgi: The value "auto" means that the name of the CGI variable associated with the button 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 button_ concatenated with the name of the button. However, it is not allowed to specify "keep" if there is also an index value. Furthermore, the button 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:button elements do not have sub elements.

Generated HTML code

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

<input type="SUBMIT" name="..." value="...">