ui:a

This element displays a hyperlink referring to a position or function within the application. The generated HTML code consists of an A element with a "javascript:..." href, and some hidden fields which are set from the Javascript code bound to the hyperlink. When the hyperlink is clicked, these fields are filled, and the form is submitted. The system recognizes that the hyperlink has been clicked by checking for these special fields.

Note: This element works only for browsers which are capable of executing Javascript code!

When the user clicks on the hyperlink, a hyperlink 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 hyperlink, 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 hyperlink events:

<ui:dialog name="sample" start-page="p1">
  <ui:page name="p1">
    <html>
      <body>
        <h1>Hyperlink test</h1>
        This is a <ui:a name="b">hyperlink</ui:a>.
      </body>
    </html>
  </ui:page>
</ui:dialog>

Here, the hyperlink event has the name "b". In order to check whether this event occured in the handle method, the following piece of code is recommended. Note that hyperlink events are actually handled in exactly the same way as button events. O'Caml:

method handle() =
  match self # event with
    Button "b" ->             (* yes, it's also Button for hyperlinks! *)
      ... (* 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') {   # "BUTTON" works also for hyperlinks
        ... # Do whatever you want to do
    } elsif ... # other cases
    ;
    return undef;
}

If the ui:a element sets the index attribute, the hyperlink is identified by the pair (name,index). When the user clicks on such an indexed link, an indexed hyperlink event is generated. The index value can be used to distinguish between several instances of hyperlinks 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:a name="view" index="4523">View Details</ui:a></td>
          </tr>
          <tr>
            <td>William S. Burroughs</td>
            <td>Naked Lunch</td>
            <td><ui:a name="view" index="8612">View Details</ui:a></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 hyperlink 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 ui:a ANY>
<!ATTLIST ui:a
          name  NMTOKEN     #REQUIRED
          index CDATA       #IMPLIED
          goto  NMTOKEN     #IMPLIED
          cgi   (auto|keep) "auto"
>

Additionally, ui:a must only occur inside ui:form. ui:a must not contain another ui:a element.

Attributes

The following attributes have a special meaning:

name:Specifies the name of the hyperlink.
index: Specifies the index value of the link. If this attribute is present, the hyperlink becomes an indexed link; otherwise the hyperlink is a plain link.
goto: Specifies which page is the next page if the hyperlink is clicked. 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 link 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 hyperlink 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 anchor_ concatenated with the name of the link. However, it is not allowed to specify "keep" if there is also an index value. Furthermore, the hyperlink 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 A HTML element. This means that especially the onclick, onmouseover, and onmouseout attributes may be specified. It is possible to set also the target value, but I do not recommend this (it may have strange effects).

Sub elements

The contents of ui:a are rendered as hyperlink zone.

Generated HTML code

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

<a href="javascript:...">...</a>
<input type="hidden" name="..." value="...">