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 following places:

Before the HTML page is generated: In the prepare_page 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 types.

Declaration

Level: Dialog structure

<!ENTITY % value-literal "(ui:string-value | ui:enum-value | ui:dyn-enum-value |
                           ui:alist-value)" >

<!ELEMENT ui:variable ( %value-literal; )? >

<!ATTLIST ui:variable
          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.

Attributes

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 effect.
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).

Sub elements

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 set)
For non-associative dynamic enumerator variables: The empty enumerator (empty set)
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.

Example

<ui:dialog name="sample" ...>
  <ui:variable name="person">
    <ui:string-value>Peter</ui:string-value>
  </ui:variable>
  ...
  <ui:page name="sample">
    <html>
      <body>
        My name is <ui:dynamic variable="person"/>.
      </body>
    </html>
  </ui:page>
</ui:dialog>