ui:richbutton

This element displays an HTML4-style richly rendered button. The generated HTML code consists of an BUTTON 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 way events are generated is very similar to the ui:button element. Nevertheless, here is an example:

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

Here, the button event has the name "b". In order to check whether this event occured in the handle method, 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:richbutton 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.

Declaration

Level: Generative element

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

Additionally, ui:richbutton must only 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.
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 BUTTON HTML element. This means that especially the onclick attribute may be specified.

Sub elements

The ui:richbutton elements may contain any HTML code, or any UI language code that expands to HTML code. The inner elements are rendered as the surface of the button.

Generated HTML code

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

<button type="SUBMIT" name="..." value="...">
  inner elements
</button>

Known Problems

As the underlying BUTTON element is a recent addition to HTML, not every browser supports it (well). Problems include:

The BUTTON element is not recognized at all (example: Netscape 4 browsers)
The BUTTON element is rendered but the wrong events are generated (example: all Internet Explorers)

Nevertheless, many browsers support this element very well (e.g. Mozilla, Opera, Lynx), and it is only a matter of time until this element can be recommended for web sites. Until then, I would not use it unless there is some strategy how to avoid the problems. For example, server-side browser sniffing can be used to detect whether the element is supported, and if so, a better-looking HTML page is generated by using ui:richbutton instead of ui:button.