XPath Expressions in XForms

7 XPath Expressions in XForms

XForms uses XPath to address instance data nodes in binding expressions, to express constraints, and to specify calculations.

7.1 XPath Datatypes

XPath data types are used only in Binding expressions and computed expressions. XForms uses XPath datatypes boolean, string, number and node-set. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.

7.2 Instance Data

For each model element, the XForms processor maintains the state in an internal structure called instance data that conforms to the XPath Data Model [XPath 1.0]. Elements and attributes in the instance data may have namespace information associated with them, as defined in the XPath Data Model. Unless otherwise specified, all instance data elements and attributes are unqualified. In addition, XForms processors must provide DOM access to this instance data via the interface defined below.

interface XFormsModelElement : org.w3c.dom.Element

The method getInstanceDocument returns a DOM Document that corresponds to the instance data associated with this XForms Model.

Return value: org.w3c.dom.Document

raises (DOMException); if there is no model with the specified model-id.

If the instance data is multiply rooted, the returned document has unqualified element instanceData as the documentElement, with the content of the XForms Model as children.

7.3 Evaluation Context

Within XForms, XPath expressions reference abstract instance data (using the "path" portion of XPath), instead of a concrete XML document. This reference is called a binding expression in this specification. Every XPath expression requires an evaluation context. The following rules are used in determining evaluation context when evaluating elements containing binding expressions in XForms:

The context node for outermost binding elements is the XPath root (/). A " binding element" is any element that is explicitly allowed to have a binding expression attribute. A binding element is "outermost" when the node-set returned by the XPath expression ancestor::* includes no binding element nodes.
The context node for non-outermost binding elements is the first node of the binding expression of the immediately enclosing element. An element is "immediately enclosing" when it is the first binding element node in the node-set returned by the XPath expression ancestor::*. This is also referred to as "scoped resolution".
The context node for computed expressions (occurring on element bind) is the first node of the node-set returned from the binding expression in the sibling ref attribute.
The context size and position are both exactly 1.
No variable bindings are in place.
The available function library is defined below, plus any function names declared in attribute extensionFunctions on element model.
Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

Binding Expression Context Nodes

<group ref="level1/level2/level3">
  <selectOne ref="elem" ... />
  <selectOne ref="@attr" ... />
</group>

In this example, the group has a binding expression of level1/level2/level3. According to the rules above, this outermost element would have a context node of /, which is the root of the instance data, or the parent to the elem element. Both of the selectOnes then inherit a context node from their parent, the context node being /level1/level2/level3. Based on this, the selectOne binding expressions evaluate respectively to /level1/level2/level3/elem and /level1/level2/level3/@attr. Matching instance data follows:

Sample Instance

<level1>
  <level2>
    <level3 attr="xyz">
      <elem>xyz</elem>
    </level3>
  </level2>
</level1>

7.4 XForms Core Function Library

The XForms Core Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.

This section defines a set of required functions for use within XForms.

7.4.1 Boolean Methods

7.4.1.1 boolean-from-string()

boolean boolean-from-string(string)

Function boolean-from-string returns true if the required parameter string is "true", or false if parameter string is "false". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matches neither "true" nor "false", according to a case-insensitive comparison, processing stops with a fatal error.

7.4.1.2 if()

string if(boolean, string, string)

Function if evaluates the first parameter as boolean, returning the second parameter when true, otherwise the third parameter.

7.4.2 Number Methods

Note:

The XPath number datatype and associated methods and operators use IEEE specified representations. XForms Basic Processors are not required to use IEEE, and thus might yield slightly different results.

7.4.2.1 avg()

number avg(node-set)

Function avg returns the arithmetic average of the result of converting the string-values of each node in the argument node-set to a number. The sum is computed with sum(), and divided with div by the value computed with count().

7.4.2.2 min()

number min(node-set)

Function min returns the minimum value of the result of converting the string-values of each node in argument node-set to a number. "Minimum" is determined with the < operator. If the parameter is an empty node set, the return value is NaN.

7.4.2.3 max()

number max(node-set)

Function max returns the maximum value of the result of converting the string-values of each node in argument node-set to a number. "Maximum" is determined with the < operator. If the parameter is an empty node set, the return value is NaN.

7.4.2.4 count-non-empty()

number count-non-empty(node-set)

Function count-non-empty returns the number of non-empty nodes in argument node-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

7.4.2.5 cursor()

number cursor(string)

Function cursor takes a string argument that is the idref of a repeat and returns the current position of the repeat cursor for the identified repeat—see 9.3 repeat for details on repeat and its associated repeat cursor. If the specified argument does not identify a repeat, this function throws an error.

cursor

<xforms:button>
		  <xforms:caption>Add to Shopping
		  Cart</xforms:caption> <xforms:insert
		  ev:event="ev:activate" position="after"
		  nodeset="items/item"
		  at="cursor('cartUI')"/>
		  </xforms:button>

7.4.3 String Methods

7.4.3.1 `property()`

string property(string)

Function property returns the XForms Property named by the string parameter.

The following properties are available for reading (but not modification).

version: version is defined as the string "1.0" for XForms 1.0
conformance-level: conformance-level strings are defined in 11 Conformance.

property

<xforms:instance>
		  ...  <xforms:bind
		  ref="info/xforms-version"
		  calculate="property('version')"/> ...
		  </xforms:instance>

7.4.3.2 now()

string now()

The now function returns the current system date and time as a string value in the canonical Schema xsd:dateTime format. If time zone information is available, it is included (normalized to UTC).

7.4.4 Extension Functions

XForms documents may use additional XPath extension functions beyond those described here. The names of any such extension functions must be declared in attribute extensionFunctions on element model. Such declarations are used by the XForms processor to check against available extension functions. XForms processors perform this check at the time the document is loaded, and stop processing by signalling a fatal error if the XForms document declares an extension function for which the processor does not have an implementation.