The UI language
The element ui:variable
ui:variable defines an instance variable for the current dialog
object. The variable has a name, a type, and an initial value (the value the
variable is automatically set to when the object is created). The variable
is assignable ("mutable" in O'Caml terminology).
It is possible to refer to the current value of variables from the
Before the HTML page is generated: In the
callback method of the current dialog object one can get and set the value of
variables by the inherited methods variable and set_variable
(and some derivates of these); see Dialogs.
While the HTML page is being generated: There are lots of
elements which can refer to variables. Especially,
ui:dynamic allows it to insert the current value of a
string value at the current generation position. The interactor elements such
as ui:text are tied to variables, i.e. they reflect the
current value of variables, and when the user changes the value of the
interactor, the value of the variable will be changed, too.
When the user event is evaluated: After the user has
clicked on a button or hyperlink, one can again get and set the values of
variables by calling the methods variable and
set_variable in the handle callback.
Unless the value is explicitly modified, variables retain their values across
page changes (like many other properties of dialog objects).
For an introduction into the type system, see Data
Level: Dialog structure
<!ENTITY % value-literal "(ui:string-value | ui:enum-value | ui:dyn-enum-value |
<!ELEMENT ui:variable ( %value-literal; )? >
name NMTOKEN #REQUIRED
type NMTOKEN "string"
associative (yes|no) "no"
temporary (yes|no) "no"
protected (yes|no) "no"
There are some restrictions concerning the possible sub elements of
ui:variable, see below.
name: Specifies the name of the variable
type: Specifies the base type of the variable:
Either string, dialog, dynamic-enumerator, or the
name of a declared enumerator (see ui:enumeration). The default is "string".
associative: Whether the variable is associative or not;
the default is
that the variable is not associative.
temporary: Whether the variable is temporary or not. A
temporary variable is reset to its initial value during a page change (unless
the variable is tied to an interactor). This means that you can still set the
variable in the prepare_page method and refer to it from elements; but
in the following handle invocation the variable will be found
reset to its initial value. The intention of this option is to avoid that large
variables are transported from one page to another in hidden HTML fields
although the variables are only needed to generate dynamic contents. Note that
interactor variables (i.e. variables tied to an interactor element) are already
transported by the interactor, and so the temporary declaration has no
The default is that variables are not temporary.
protected: A protected variable cannot be changed by
CGI arguments. Sometimes it is necessary to prevent the users from changing
variables because they contain trusted data. The recommended method to
achieve this requires two steps: First, the variables must be declared with
protected="yes". Second, a session manager must be used that protects
the state from user manipulations (note that the session manager that is
enabled by default does not provide such protection).
The sub element of the ui:variable contains the initial value of the
variable. The initial value is the value the variable is initialized with when
the containing dialog object is created. If no initial value is specified, the
following values apply:
For non-associative string variables: The empty string
For non-associative enumerator variables: The empty enumerator (empty
For non-associative dynamic enumerator variables: The empty enumerator (empty
For non-associative dialog variables: The value None
For associative variables: The empty associative list
If an initial value is specified, the sub element defining the value must
correspond to the type of the variable:
For non-associative string variables: The default value must be
defined by ui:string-value.
For non-associative enumerator variables: The default value must
be defined by ui:enum-value.
For non-associative dynamic enumerator variables:
The default value must
be defined by ui:dyn-enum-value.
For non-associative dialog variables: It is not possible
to define default values for dialog variables.
For associative variables: The default value must
be defined by ui:alist-value.
<ui:dialog name="sample" ...>
My name is <ui:dynamic variable="person"/>.