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

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 binding expressions in XForms:

The context node for outermost form control elements is the XPath root (/). A " form control element" is any element other than bind that is explicitly allowed to have a binding expression attribute. A form control element is "outermost" when the node-set returned by the XPath expression ancestor::* includes no form control element nodes.
The context node for non-outermost form control elements is the first node of the binding expression of the immediately enclosing element. An element is "immediately enclosing" when it is the first form control element node in the node-set returned by the XPath expression ancestor::*. This is also referred to as "scoped resolution".
The context node for the ref attribute on bind is the XPath root. The context node for other attributes of 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.
Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

Example: 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:

Example: Sample Instance

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

7.4 Forms 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 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 10.3 Repeating Structures for details on repeat and its associated repeat cursor. If the specified argument does not identify a repeat, this function throws an error.

Example: 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 12 Conformance.

Example: 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).


Table of Contents	Prev	Next	Bottom