ui:imagebutton

This element displays an imagebutton, i.e. a button rendered as an image. The generated HTML code consists of an INPUT element with TYPE=IMAGE, 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, an Image_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 image button events:

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

Here, the image 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
    Image_button("b",x,y) ->
      ... (* Do whatever you want to do *)
  | ... (* other cases *)

- Perl:

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

In both cases, the variables x and y contain the position of the click relative to the origin of the button.

If the ui:imagebutton element sets the index attribute, the button is identified by the pair (name,index). When the user clicks on such an indexed imagebutton, an Indexed_image_button event is generated. The index value can be used to distinguish between several instances of buttons of the same type. For instance, 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:imagebutton name="view" src="view.gif" index="4523"/></td>
          </tr>
          <tr>
            <td>William S. Burroughs</td>
            <td>Naked Lunch</td>
            <td><ui:imagebutton name="view" src="view.gif" 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_image_button("view", index, x, y) ->
      ... (* Do whatever you want to do *)
  | ... (* other cases *)

- Perl:

sub handle {
    my ($self) = @_;
    my ($e, $name, $index, $x, $y) = $self->event;
    if ($e eq 'INDEXED_IMAGE_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 ui:imagebutton EMPTY>
<!ATTLIST ui:imagebutton
          name  NMTOKEN     #REQUIRED
          index CDATA       #IMPLIED
          src   CDATA       #REQUIRED
          align CDATA       #IMPLIED
          goto  NMTOKEN     #IMPLIED
          cgi   (auto|keep) "auto"
>

Additionally, ui:imagebutton 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.
src: Specifies the image file containing the image bitmap.
align: Specifies the align attribute of the generated HTML element. Defaults to BOTTOM according to HTML standards.
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 imagebutton_ 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:imagebutton elements do not have sub elements.

Generated HTML code

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

<input type="IMAGE" name="..." src="..." align="...">