ui:dynamic

The element ui:dynamic is replaced by the current value of the variable it refers to. The replacement algorithm can quote the value according to several quoting styles; see below.

One task of ui:dynamic is to show the values of variables as constant, immutable texts. For example, the following dialog displays the values of the current data fields in the page show_record:

<ui:dialog name="sample" start-page="show_record">
  <ui:variable name="title"/>
  <ui:variable name="author"/>
  <ui:variable name="isbn"/>
  <ui:variable name="price"/>

  <ui:page name="show_record">
    <html>
      <body>
        <h1>The selected record</h1>
        <dl>
          <dt>Title:</dt>
          <dd><ui:dynamic variable="title"/></dd>
          <dt>Author:</dt>
          <dd><ui:dynamic variable="author"/></dd>
          <dt>ISBN number:</dt>
          <dd><ui:dynamic variable="isbn"/></dd>
          <dt>price:</dt>
          <dd><ui:dynamic variable="price"/></dd>
        </dl>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Of course, one has to load the values into the displayed variables. This can be done in the prepare_page method of the dialog object which is called just before the current page is printed as HTML document.

Another way to apply ui:dynamic is to insert an already generated HTML fragment at the current location into the output stream. In this case, the attribute special must be set to indicate that the variable contains already HTML and that no further quoting is required. A tiny example:

<ui:dialog name="sample" start-page="p">
  <ui:variable name="x">
    <ui:string-value>This is &lt;b&gt;bold&lt;/b&gt; text!</ui:string-value>
  </ui:variable>

  <ui:page name="p">
    <html>
      <body>
        The value of x:
        <ui:dynamic variable="x" special="yes"/>
      </body>
    </html>
  </ui:page>
</ui:dialog>

Here, the variable x is initialized with the value "This is <b>bold</b> text!", and this value is verbatim included into the generated HTML code.

Declaration

Level: Generative element

<!ELEMENT ui:dynamic EMPTY>
<!ATTLIST ui:dynamic
          variable  NMTOKEN  #REQUIRED
          index     CDATA    #IMPLIED
          special   (yes|no) "no"
          enc       NMTOKENS ""
>

Attributes

variable: Specifies the name of the variable to display. This must be a string variable.
index: Specifies the selected index if the variable is an associative string variable. This attribute is required if the variable is associative.
special: This attribute determines if the usual output encoding is applied (special="no") or not (special="yes"). Normally, the characters <, >, &, and " in the generated HTML text are replaced by their corresponding entities, so they are displayed "as they are meant". The attribute special="yes" turns the output encoding off (like the element ui:special for bigger sections of code).
enc: Defines a list of additional output encodings that are applied before the normal HTML output encoding. See Output encodings for a list of encodings. It is recommended to define enc only in conjuction with special="yes" to get full control over the order in which the encodings are applied.

Special case: Using ui:dynamic in parameter values

Or: How to set attributes dynamically

When ui:dynamic occurs in values of template parameters (i.e. within ui:param), the following behaviour can be expected. If the parameter is referred to from character data context, the ui:dynamic element is just passed through to the template expansion text as any other element. For example, if the template definition of t1 is

<ui:template name="t1" from-caller="x">
  The text is: <b>$x</b></ui:template>

and the template is called as in

<ui:use template="t1">
  <ui:param name="x"><ui:dynamic variable="v"/></ui:param>
</ui:use>

the expanded template will be:

The text is: <b><ui:dynamic variable="v"/></b>

This is nothing special. However, it is also possible to use parameters in attribute context. In this case, the ui:dynamic element will be immediately replaced by the (optionally quoted) contents of the called variable; this is different from most other ui: elements which are just ignored in attribute context. If in our example t2 is defined as

<ui:template name="t2" from-caller="x">
  <ui:button name="b_$x" label="Label of: $x"/></ui:template>

and called in the same way as t1, the expansion text will be computed as follows:

<ui:button name="b_<v>" label="Label of: <v>"/>

where <v> is replaced by the current contents of the variable v.

The bracket notation

Or: How to set attributes dynamically in a better way

In pages and templates, the notation $[name] can be used to insert the current value of the named instance variable, just like ui:dynamic does. This notation can also be used inside atttibutes, so the last example can be better written as

<ui:button name="b_$[v]" label="Label of: $[v]"/>

To get the effect of special="yes" you have to put the bracket into a ui:special element:

<ui:special>$[v]</ui:special>

To get the effect of enc, just add the encodings after a slash, and separate them by slashes:

<ui:special>$[v/html/js]</ui:special>

In recent versions of WDialog, the bracket notation has been generalized, and it is now allowed to write more complex expressions inside the brackets. See the chapter about $[expr].