ui:dialog

An ui:dialog element describes the object behind a series of interactions (dialog) that base on shared state variables. The object has the following properties:

The object consists of a number of instance variables. These variables must be declared with the ui:variable directive. Every variable has a type and a value. It is possible to set a default value to which the variable is initialized when the object is being created.
The object can be visualized as one of the defined pages (see ui:page). The elements describing the visualization can access the instance variables of the object, either reading them only (such as in ui:dynamic), or associating them with interactor elements which can be modified by the user of the application (such as in ui:text).
The object remembers which page has been displayed last; this page is called the current page.
When the user clicks on a hyperlink (see ui:a) or on a button (see ui:button), an event is triggered and sent to the object.

The programmer can associate an O'Caml or Perl class to the object, and this class is then treated as extension to the default behaviour of the object. You can find detailed descriptions of the dialog properties in the chapter about dialogs.

Declaration

Level: Dialog structure

<!ELEMENT ui:dialog ( ( ui:enumeration |
                        ui:variable |
                        ui:context |
                        ui:page )* ) >

<!ATTLIST ui:dialog
          name          NMTOKEN #REQUIRED
          start-page    NMTOKEN #REQUIRED
          lang-variable NMTOKEN #IMPLIED
>

Restrictions: There must at most only one ui:context sub element. There must be at least the ui:page mentioned by start-page.

Attributes

name: The name of the object which must be unique among all objects of the application.
start-page: The name of the page to which the current page property is initialized when the object is created.
lang-variable: The name of a string variable that contains the selected language. It is required that this variable is declared by ui:variable. For more information, see the chapter Internationalization.

Sub elements

The following sub elements may be contained in ui:dialog in arbitrary order:

ui:enumeration: Declarations of enumerator types
ui:variable: Declarations of instance variables
ui:context: Optionally, a default binding for dynamic template parameters
ui:page: One or more pages describing possible visualizations of the dialog. At least the page defined by start-page must exist.

Example


<ui:dialog name="name_dialog" start-page="change_name">
  <ui:variable name="first_name" type="string"/>
  <ui:variable name="last_name" type="string"/>

  <ui:page name="change_name">
    <html>
      <body>
        <h1>Please enter your name here:</h1>

        <table>
          <tr>
            <td>First name:</td>
            <td><ui:text variable="first_name"/></td>
          </tr>
          <tr>
            <td>Last name:</td>
            <td><ui:text variable="last_name"/></td>
          </tr>
        </table>

        <p><ui:button name="name_changed" label="Done" goto="show_name"/></p>
      </body>
    </html>
  </ui:page>

  <ui:page name="show_name">
    <html>
      <body>
        <h1>Welcome!</h1>

        Welcome, <ui:dynamic variable="first_name"/>
<ui:dynamic variable="last_name"/>!
      </body>
    </html>
  </ui:page>
</ui:dialog>