Variable

The variable Element

The variable element introduces a variable to be used in XPath expression in the subtree of the parent to the variable element.

Attributes

name	Required	The name of the variable. This is a xsd:QName.
select	Required	[XPath 1.0] expression which is the value assigned to the variable. The expression is evaluated in the context defined by [XForms 1.0] and by the model attribute on this element.
model	Optional	The xforms model used for scoping which model the attribute correspons to.

For variables in the model they are updated before the processing of the xforms-recalculate event and for variable elements in the UI they are updated before the xforms-refresh event. A variable scope is defined in a model and from the parent of the variable element and the last one with the same name takes precedens. It must be possible to defined identical named variables for different model in the same document scope.

Erik's Notes

Variables must also be defined within actions, wherever these actions take place.
Scoping of variables must be documented. E.g. do you see, from the view, model variables? If so, how does scoping change when you switch models with @model? Etc.

Example of variable in actions (here just using a variable for convenience, you can actually get by with context()):

<xforms:action iterate="a | b | c | d">
  <xforms:variable name="local-name" select="local-name()"/>
  <xforms:setvalue ref="@id" value="concat('id-', $local-name)"/>
</xforms:action>

Example: how to use variable in the UI

<xforms:model>
  <xforms:instance>
    <data xmlns="">
      <a><b><c>value</c></b></a>
    </data>
  </xforms:instance>
</xforms:model>

<xforms:group>
  <xforms:variable name="bvalue" select="a/b"/>
  
  The c value: <xforms:output ref="$bvalue/c"/>
</xforms:group>

Example: how to use variable in the model

<xforms:model>
  <xforms:instance>
    <data xmlns="">
      <a><b><c>value</c></b></a>
    </data>
  </xforms:instance>

  <xforms:variable name="bnode" select="a/b"/>
  <xforms:variable name="boolean" select="$bnode/c = 'value'"/>

  <xforms:bind nodeset="$bnode" relevant="$boolean"/>
</xforms:model>

Proposal (2011-12)

The `var` element

The var element is a local variable-binding element and enables the declaration of a variable. A variable is a binding between a name and a value. The value of a variable is any sequence (of nodes and/or atomic values), as defined in __Data Model__.

Element	Overview of Attributes	Overview of Content Model
var	Common, name (QName), value (expression), model (xsd:IDREF)	EMPTY

Below is a more detailed decription of each attribute whose name and datatype information appears above.

Common Attributes: Common

Special Attributes:

name: Required attribute containing the name of the variable. The value of the name attribute is a QName. The Scope of the variable is defined in the Variable Scope section
value: Required attribute containing an expression to evaluate, the result of the expression will be made available as a variable.
model: Author-optional XForms Model selector. Specifies the ID of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a bind attribute is present. Rules for determining the context XForms Model are located at Evaluation Context.

Variables can occur either as a child of an action element or somewhere in the document except the model. The value of the variable will be updated when needed. If the variable is a child of an action it means that the value of the variable will be up to date when the action runs, i.e. the value will behave as if it was updated during the execution of the action in document order relative to other variables and actions. All other variables will behave as if they were updated on xforms-refresh in the order as how they were defined.

Note:

Variables in actions are only evaluated once during the execution of an action and will hold a references to all the nodes the expression returns (if any). For example deleting those nodes from an instance with a subsequent delete action will not remove those nodes from the value of the variable. Changes in the predicates of the expression by subsequent actions won't update the value of variable either.

Variable Scope

For any variable-binding element, there is a region (more specifically, a set of element nodes) of the form within which the binding is visible. The set of variable bindings in scope for an expression consists of those bindings that are visible at the point in the form where the expression occurs.

A local variable binding element is visible for all following siblings and their descendants. The binding is not visible for the xf:var element itself.

It is an error to create multiple variable-binding with the same name if they are visible to each other and an an xforms-compute-exception or an xforms-binding-exception will be dispatched.

Other edits

add variable to the UIComon list and to Minimal Content Model of action

More of Erik's notes about variables related to the proposed @name attribute

Erik needs to clean this up ;-)

@name is introduced for 2 reasons:
- solve scoping issues with @id
- closer from HTML forms syntax in streamlined syntax in UI
@name should replace/add to @id in model AND view
- model, instance, submission, bind
- controls
@name is scoped by model in model AND view
@name and variable creation
- does NOT automatically create variables
- in streamlined, creates implicit xf:bind AND xf:variable
- so only xf:variable actually create a variable
@name can be used in UI alonside @bind, @ref and @nodeset
- in that case, it does not cause the creation of a variable

   -> RATIONALE: there is already instance data, so no need for creation of a variable to access value