[UP]
Reference
 Dialogs
 Data types
 Data types (O'Caml)
 Data types (Perl)
 Events
 Templates
 Session management and security
 Internationalization
 Output encodings
 Processing instructions
 The UI language
 The standard UI library
 WDialog API (O'Caml)
 Runtime models
   
Data types

The WDialog system has its own type system for the values of instance variables of dialogs. On the one hand, such values must be simple to manipulate from programs (which implies a simple representation); on the other hand, such values must be powerful enough to express the states of interactors.

The string type

There are at least three applications for string types:

  • String variables can be included as dynamic text into generated HTML pages, i.e. the program computes some text to be put at a certain place of the HTML code. This can be achieved by the element ui:dynamic, or by using bracket expressions.

  • String variables can be tied to interactors which use strings as base type. The most common example are text input boxes which can be created by the ui:text element.

  • Sections of code can be included or excluded depending on whether a string variable has a certain value; see ui:if, and ui:ifvar.

In computer science, there is a common understanding of what strings are; so it is not necessary to explain here their fundamentals. However, we state here that every character can be a member of a string (even null characters) and that strings can be reasonably long (for a typical web application, 1MB might suffice as maximum length). The supported character sets are ISO-8859-1 (Latin 1) and UTF-8 (Unicode).

In variable declarations (ui:variable), the string type may be referred to by the literal

string

In order to denote initial string values of variables, one can use the ui:string-value element.

Declared enumerator types

Several interactors allow the user to choose a set of values from a given base set. For example, the HTML select tag lists several options, and one can individually select which options to choose. For such cases, it is possible to declare an enumerator, which is a new type enumerating all possible options. An example (see also ui:enumeration):

<ui:dialog name="example">
  <ui:enumeration name="sex">
    <ui:enum internal="male"/>
    <ui:enum internal="female"/>
  </ui:enumeration>
  ...
  <ui:variable name="person's_sex" type="sex"/>
  ...
  <ui:page name="select_your_sex">
     ...
     <ui:select variable="person's_sex" multiple="no"/>
     ..
  </ui:page>
  ...
</ui:dialog>

An enumerator has the following properties:

  • The type defines a list of literals (here "male" and "female"); also called the internal values. An instance of the type is a subset of these values. (In our example, these subsets will have a cardinality of <= 1 because multiple="no" restricts the ui:select interactor such that only one item can be selected. Actually only the subsets {}, {"male"} and {"female"} are possible.)

  • It is not possible to have the same internal item twice in a subset.

  • The items are ordered. This is important for the visualization, because although sets are often meant without order, eventually there must be an order when the items are displayed. (In our example, this means that the selection box will first display "male", and then "female".)

Furthermore, the internal items may have corresponding external values. The internal value is used to identify the item in an algorithm or in a database, and the external value is the corresponding representation when the item is displayed. If not defined, the same literals are used for the internal and the external values. Example:

  <ui:enumeration name="sex">
    <ui:enum internal="male"   external="You are a man"/>
    <ui:enum internal="female" external="You are a woman"/>
  </ui:enumeration>

Enumerators have the following applications:

  • Enumerator variables can be tied to interactors (ui:select, ui:checkbox, ui:radio) working on sets of items.

  • It is possible to use enumerators as index to associative values (see below), and to iterate over the index domain (see ui:enumerate).

In order to specify initial values of enumerator variables, one can apply the ui:enum-value element.

The dynamic enumerator type

Declared enumerators are restricted as the possible items must all be known at the time when they are declared. Sometimes the items are only known at run time, and in this case dynamic enumerators may be the solution.

Like declared enumerators, values of dynamic enumerators are ordered sets of internal items with corresponding external values; the difference is that you may add any pair (int,ext) of internal/external pairs at run time to a dynamic enumerator. In the following example, the user can select a subset of things of a computed base set of things:

<ui:dialog name="example">
  ...
  <ui:variable name="selected_things"   type="dynamic-enumerator"/>
  <ui:variable name="possible_things" type="dynamic-enumerator"/>
  ...
  <ui:page name="select_your_things">
     ...
     <ui:select variable="selected_things" base="possible_things"
                multiple="yes"/>
     ..
  </ui:page>
  ...
</ui:dialog>

It is assumed that the prepare_page method of the dialog class fills the variable possible_things in a reasonable way. The ui:select interactor needs now two attributes, one (base) determining the list of items to display, and the other one (variable) containing the subset of items that are actually selected by the user. In contrast to declared enumerators, the latter attribute does not imply the base set, so it is necessary to specify it additionally.

In order to specify initial values of dynamic enumerator variables, one can apply the ui:dyn-enum-value element.

The dialog type

It is possible to declare instance variables whose values are complete dialog objects. An important motivation for this possibility are sub dialogs, i.e. dialogs which can be called from arbitrary other dialogs, and which are able to return to their caller object whatever it was.

Consider the following (incomplete) example:

<ui:dialog name="calling_dialog" start-page="...">
  ...
  <ui:variable name="v" .../>
  ...
  <ui:page name="calling_page">
    ...
    As in many other dialogs, you can now go to our
    <ui:a name="call_event">special dialog</ui:a>.
    ...
  </ui:page>
</ui:dialog>

<ui:dialog name="called_dialog" start-page="called_page">
  ...
  <ui:variable name="caller" type="dialog"/>
  ...
  <ui:page name="called_page">
    ...
    You can now do ... this ... and ... that.
    <ui:a name="return_event">Return to previous dialog.</ui:a>
    ...
  </ui:page>
</ui:dialog>

The handle methods of both objects must perform special actions, which can be described as follows:

  • calling_dialog: The handle method is invoked when the user clicks on the hyperlink pointing to the "special dialog", and in this case the method receives the call_event. The special action is to (1) create the new dialog instance for called_dialog, (2) initialize the variable caller with the current dialog (which is calling_dialog), and (3) change the current dialog seen by the user to called_dialog. This causes that the system shows the called_page as next page.

  • called_dialog: The handle method is invoked when the user clicks on the hyperlink "Return to previous dialog". The event sent to the method is return_event, and the following actions are needed to actually return: (1) Fetch the previous dialog instance from the variable caller, and (2) change the current dialog to this instance. This causes that the system shows the last page of this dialog again.

Note that there are no dialog literals in the UI language; variables of dialog type can only be set from the program. It is, however, possible to access the inner variables of a dialog variable by using the dot notation, see the section about Dot notation (v1.v2) for details.

Associative variables

Often, it is necessary to manage lists of interactors. Of course, it is possible to generate the HTML code by instantiating a page fragment several times (you can describe page fragments by ui:template elements); however, the question arises how to refer to the first, the second, ... the nth generated interactor. One possibility would be to generate the names of the interactors; but this can be complicated. Because of this, the WDialog system provides a general solution to refer to generated interactors.

All interactor elements know the attribute index which can be used as a second identifier besides the name or the variable to which the interactor is bound. For example, the following two buttons will trigger different events when the user clicks at them:

  <ui:button name="click" index="1" label="Select this"/>
  <ui:button name="click" index="2" label="Select that"/>

The event structure sent to the handle method of the object contains both the name of the button and the index value, if present. Note that index values may be arbitrary strings (the system encodes "unsafe characters" such that they can be safely transported over the HTTP/CGI connection).

Many interactors are tied to variables. For example, the ui:text element displays an input box which initially shows the current value of the variable, and when the user modifies the box, the changed value will automatically be transferred back to the variable. This shows that if we want indexed interactors, we need indexed variables to which these interactors can be bound.

In the terminology of WDialog these variables are called associative. The value of an associative variable is a mapping from keys (indexes) to values where the (index,value) pairs are ordered (for the same reason why enumerators are ordered: when they are displayed, an order is required).

For example, it is possible to declare an associative variable of strings

  <ui:variable name="v" type="string" associative="yes"/>

and to refer to this variable from input boxes:

  <ui:text variable="v" index="1"/>
  <ui:text variable="v" index="2"/>
  ...

Here, the first input box accesses and modifies the value of v which is stored at the key "1", and the second box the value which is stored at the key "2". Both input boxes refer to the same variable, but they actually access different components of the variable.

It is not only possible to declare associative string variables, but also associative enumerators, dynamic enumerators and dialogs.

In order to specify default values of associative variables, one can use the ui:alist-value element.