Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

XForms - Variables

Contents

  1. 1 Rationale
  2. 2 The variable element
  3. 3 Variables within <xforms:model>
  4. 4 Variables declared by <xforms:bind> elements
  5. 5 Variables outside <xforms:model>
  6. 6 Variables within <xforms:action>
  7. 7 The <xxforms:sequence> element
  8. 8 Scoping of variables in the view
  9. 9 Current limitations

Rationale

Orbeon Forms supports declaring variables which look and behave very much like XSLT variables. Variables are extremely useful, for example to avoid repeating long XPath expressions, or to give an XPath expression unambiguous access to data computed in enclosing <xforms:group> or <xforms:repeat> elements.

The variable element

You define variables with the extension element:
  • <xxforms:variable>
  • or the shorter, experimental form <xxforms:var> [SINCE: 2011-03-30]
The element supports the following attributes: 

 namemandatoryName of the variable.
 asoptional
Type of the variable. This is ignored as of 2011-03, but can be used for documentation purposes.
 modeloptionalContributes to the variable's single-node binding.
 contextoptionalContributes to the variable's single-node binding.
 refoptionalContributes to the variable's single-node binding.
 bindoptionalContributes to the variable's single-node binding.
 select
    or
 value
optionalXPath 2.0 expression determining the value of the variable.

The expression is evaluated in the element's single-node binding if present, otherwise in the context of its parent.

If the attribute is omitted, the text content of the <xxforms:variable> element is used as the value.

NOTE: The value attribute is supported since 2011-03-30.

NOTE: You can also use <exforms:variable> in the eXforms namespace. 

Variables within <xforms:model>

Directly under the <xforms:model> element, the following rules apply:
  • Variables are supported directly under the <xforms:model> element.
  • Model variables are evaluated in the order in which they appear in the model.
  • All model variables are visible to other model elements such as <xforms:bind> or <xforms:submission>.
  • Model variables are also visible from XPath expression outside of models whenever that model is in scope.
<xhtml:head>
    <xforms:model id="my-model">
        <xforms:instance id="my-instance">...</xforms:instance>
        <xxforms:variable name="mine" value="."/>
    </xforms:model>
    <xforms:model id="her-model">
        <xforms:instance id="her-instance">...</xforms:instance>
        <xxforms:variable name="hers" value="instance('her-instance')"/>
    </xforms:model>
</xhtml:head>
<xhtml:body>
    <!-- $mine is visible from here, but not $hers -->
    <xforms:output value="$mine">
        <xforms:label>My stuff:</xforms:label>
    </xforms:output>
    <xforms:group model="her-model">
        <!-- $hers is visible from here, but not $mine -->
        <xforms:output value="$hers">
            <xforms:label>Her stuff:</xforms:label>
        </xforms:output>
    </xforms:group>
</xhtml:body>

Variables declared by <xforms:bind> elements

Bind elements with a name attribute automatically declare a corresponding variable, as if using <xxforms:variable>.

[TODO: example + describe scoping:
  • when accessed from outside the model
  • when accessed from within the model
  • when accessed from XPath MIPs
See also known issue: [ #315833 ] Variables leading to unexpected result inside an <xforms:bind> "iteration]

Variables outside <xforms:model>

Outside of models, the following rules apply:
  • Variables are supported anywhere XForms controls are allowed.
  • A given variable is visible to any XPath expression on a following sibling element or on a following sibling element's descendant element.
<xhtml:body>
    <!-- Variable pointing to the default instance's root element -->
    <xxforms:variable name="instance" value="."/>
    <!-- variable pointing to all the item children -->
    <!-- It uses the variable declared above -->
    <xxforms:variable name="items" value="$instance/item"/>

    <!-- The code below uses the variables in scope -->
    <xforms:repeat nodeset="$items" id="items-repeat">
        <xxforms:variable name="current-item" value="."/>
        <xxforms:variable name="current-position" value="position()"/>
        <xforms:output id="my-count" ref="$current-item/value">
            <xforms:label value="concat($current-item/label, ':')"/>
            <xforms:setvalue ev:event="my-event" ref="$current-item/value" value="count($items) + $current-position"/>
        </xforms:output>
    </xforms:repeat>
</xhtml:body>

Variables within <xforms:action>

Variables are allowed within <xforms:action> elements, whether those elements are used within models or controls.

<xforms:model>
    <xforms:instance>
        <instance>
            <foo>42</foo>
            <bar>43</bar>
        </instance>
    </xforms:instance>
    <!-- These variables are defined within the model -->
    <xxforms:variable name="foo" value="foo"/>
    <xxforms:variable name="bar" value="bar"/>
</xforms:model>
...
<xforms:group>
    <!-- This variable is defined within the group control and has access to the in-scope model variables -->
    <xxforms:variable name="sum" value="$foo + $bar"/>
    <xforms:group>
        <xforms:action ev:event="my-event">
            <!-- This action has access to all variables in scope -->
            <xforms:setvalue ref="sum" value="$sum"/>
            <!-- This variable is defined within the action and has access to all the variables in scope -->
            <xxforms:variable name="difference" value="$foo - $bar"/>
            <xforms:setvalue ref="difference" value="$difference"/>
        </xforms:action>
    </xforms:group>
</xforms:group>

The <xxforms:sequence> element

Like in XSLT, you can nest an <xxforms:sequence> element within <xxforms:variable>. The element supports the following attributes: 

 modeloptionalContributes to the element's single-node binding.
 contextoptionalContributes to the element's single-node binding.
 refoptionalContributes to the element's single-node binding.
 bindoptionalContributes to the element's single-node binding.
 select
    or
 value		optionalXPath 2.0 expression determining the value of the variable. The expression is evaluated in the element's single-node binding if present, otherwise in the context of its parent <xxforms:variable> element. If the attribute is omitted, the text content of the <xxforms:sequence> element is used as the value.

NOTE: The value attribute is supported since 2011-03-30.

This allows you to decouple the variable definition (name) from its evaluation:

<xxforms:variable name="sum">
    <xxforms:sequence value="$foo + $bar"/>
</xxforms:variable>

This is particularly useful for XBL component implementors, where this can be used in combination with the xxbl:scope attribute:

<xxforms:variable name="result" as="node()?">
    <xxforms:sequence value="." xxbl:scope="outer"/>
</xxforms:variable>

Single-node attributes may be used on the <xxforms:sequence> element.

Scoping of variables in the view

The following guidelines apply when using variables in the view:
  • Only variables in the current XBL scope are visible
  • All preceding view variables are visible even across changes of models (with model="...")
  • Finally, the current model's variables are visible
  • Variable hiding applies
Example:

<xhtml:html>
    <xhtml:head>
        <xforms:model id="model1">
            <xforms:instance>
                <instance>
                    <foo>42</foo>
                </instance>
            </xforms:instance>
            <xxforms:variable name="foo" value="foo"/>
        </xforms:model>
        <xforms:model id="model2">
            <xforms:instance>
                <instance>
                    <foo>44</foo>
                </instance>
            </xforms:instance>
            <xxforms:variable name="foo" value="foo"/>
        </xforms:model>
    </xhtml:head>
    <xhtml:body>
        <!-- Top-level -->
        <!-- model1 is the default model: $foo from model1 is visible -->
        <xxforms:variable name="gaga" value="41"/>
        <!-- $gaga is visible because preceding in the view -->
        <xforms:group model="model2">
            <!-- model2 is the current model: $foo from model2 is visible -->
            <xxforms:variable name="toto" value="43"/>
            <!-- $gaga and $toto are visible because they are preceding in the view -->
            <xforms:group model="model1">
                <!-- model1 is the current model: $foo from model1 is visible, and $gaga is visible  -->
                <!-- $gaga and $toto are visible because they are preceding in the view -->
            </xforms:group>
        </xforms:group>
    </xhtml:body>
</xhtml:html>

Current limitations

As of 2011-03, the implementation has the following limitations:
  • <xxforms:variable> element:
    • The as attribute is ignored but can be used for documentation purposes.
    • Cannot be used within XForms leaf controls such as <xforms:input>, including within nested items or itemsets (except within <xforms:action> elements, where they are allowed).
    • Cannot be used within nested model elements, including <xforms:bind> or <xforms:submission> (except within <xforms:action> elements, where they are allowed).
  • <xxforms:sequence> element:
    • Only one <xxforms:sequence> element is currently allowed as child of <xxforms:variable>.
    • When used, single-node attributes may not be used on the parent <xxforms:variable> element.

Sign in  |  Recent Site Activity  |  Revision History  |  Terms  |  Report Abuse  |  Print page  |  Powered by Google Sites