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:
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
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:
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:
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:
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.
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.