7 XPath Expressions in XForms

XForms uses XPath to address instance data nodes in binding expressions, to express constraints, and to specify calculations. XPath expressions that are not syntactically valid, including attempted calls to undefined functions, result in an exception (4.5.4 The xforms-compute-exception Event), except for binding expressions, which produce a different exception (4.5.1 The xforms-binding-exception Event).

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]. XForms Processors that implement DOM must provide DOM access to this instance data via the interface defined below.

Note:

Instance data always has a single root element, and thus corresponds to a DOM Document.

The IDL for this interface follows:

// Introduced in XForms 1.0:
interface XFormsModelElement : Element {
  Document               getInstanceDocument(in DOMString instance-id)
                                                raises(DOMException);
  void                   rebuild();
  void                   recalculate();
  void                   revalidate();
  void                   refresh();
};

7.2.1 The getInstanceDocument() Method

This method returns a DOM Document that corresponds to the instance data associated with the instance element containing an ID matching the instance-id parameter. If there is no matching instance data, a DOMException is thrown.

7.2.2 The rebuild() Method

This method signals the XForms processor to rebuild any internal data structures used to track computational dependencies within this XForms Model. This method takes no parameters and raises no exceptions.

7.2.3 The recalculate() Method

This method signals the XForms processor to perform a full recalculation of this XForms Model. This method takes no parameters and raises no exceptions.

Note:

Script invocation of recalculate() is not necessarily equivalent to performing the recalculate action handler. Though the script is assumed to have modified instance data prior to invoking recalculate(), the DOM mutations are not cached. Thus, a full recalculation is necessary to ensure the proper changes are effected throughout the XForms model.

7.2.4 The revalidate() Method

This method signals the XForms processor to perform a full revalidation of this XForms Model. This method takes no parameters and raises no exceptions.

7.2.5 The refresh() Method

This method signals the XForms processor to perform a full refresh of form controls bound to instance nodes within this XForms Model. This method takes no parameters and raises no exceptions.

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 XPath expressions as part of XForms:

  1. The context node for outermost binding elements is the top-level element node, or the single node returned by /*. 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.

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

  3. The context node always resides within the context model, which is determined choosing the first item that applies from this list:

    1. If a model attribute is present on the binding element, the attribute determines the context model.

    2. If the binding element has an immediately enclosing binding element, the context model of the immediately enclosing binding element is used.

    3. The first model in document order is used.

  4. 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 nodeset attribute on the same element.

  5. The context position is exactly 1. For Single-Node binding expressions, the context size is 1. For Nodeset binding expressions, the context size is the size of the node-set.

  6. No variable bindings are in place.

  7. The available function library is defined below, plus any functions supplied by the implementation. Extension functions required for operation of the form should be declared, as described at 7.11 Extension Functions.

  8. Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

Example: Binding Expression Context Nodes
<group ref="level2/level3">
  <select1 ref="@attr" ... />
</group>

In this example, the group has a binding expression of level2/level3. According to the rules above, this outermost element node would have a context node of /level1, which is the top-level element node of the instance data. The select1 form control then inherits a context node from the parent group. Matching instance data, represented as serialized XML, follows:

Example: Sample Instance
<level1>
  <level2>
    <level3 attr="xyz"/>
  </level2>
</level1>

7.4 Binding Expressions

A binding expression is an XPath LocationPath expression used in binding a model item property to one or more instance nodes, or to bind a form control to the instance, or to specify the node or node set for operation by an action.

Not every possible XPath expression is acceptable as a binding expression. In particular, there are restrictions on binding expressions that create dynamic dependencies, which are defined as follows:

An XPath predicate (in square brackets) is a possibly implicit boolean test. A dynamic dependency exists on any predicate unless all terms in the test are "fixed", where fixed means either a constant, or a value that will not change between operations explicitly defined as rebuilding computational dependencies.

Note:

For purposes of determining dynamic dependencies, the following subexpressions are considered fixed: position(), last(), count(), index(), and property(). This is because the specification mandates a dependency rebuild after any event that could change the values returned by these functions.

Another dynamic dependency is any use of the id() function, unless both the parameter to the function and the matching attribute of type xsd:ID are fixed. In the same way, the instance() function is dynamic unless the parameter to the function is fixed.

XPath variables that change in value from one recalculate to the next would also create dynamic dependencies (though XForms 1.0 defines an empty variable context for all XPath expressions).

Authors that define extension functions are encouraged to follow these rules.

7.4.1 Model Binding Expressions

A model binding expression is a kind of binding expression used in bind that can be used to declare model item properties.

No dynamic dependencies are allowed in model binding expressions. Upon detecting a dynamic dependency in a model binding expression, form processing terminates with an exception (4.5.1 The xforms-binding-exception Event).

7.4.2 UI Binding Expressions

Binding references can be used to bind form controls to the underlying instance data as described here. Different attribute names, ref and nodeset distinguish between a single node and a node-set respectively. See 3.2.3 Single-Node Binding Attributes and 3.2.4 Node-Set Binding Attributes.

Dynamic dependences are allowed in UI binding expressions based on the conformance profile.

7.4.3 UI Binding in other XML vocabularies

The XForms binding mechanism allows other XML vocabularies to bind user interface controls to an XForms Model using any of the techniques shown here. As an example, XForms binding attribute bind might be used within XHTML 1.x user interface controls as shown below. See 3.2.3 Single-Node Binding Attributes and 3.2.4 Node-Set Binding Attributes.

Example: XForms Binding In XHTML 1.x User Interface Controls
<html:input type="text" name="..." xforms:bind="fn"/>

7.4.4 Binding Examples

Consider a document with the following XForms model:

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
  <xforms:bind nodeset="/orderForm/shipTo/firstName" id="fn" />
</xforms:model>

The following examples show three ways of binding user interface control xforms:input to instance element firstName declared in the model shown above.

Example: UI Binding Using Attribute ref
<xforms:input ref="/orderForm/shipTo/firstName">...
Example: UI Binding Using Attribute bind
<xforms:input bind="fn">...
Example: Specifies Model Containing The Instance Explicitly
<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...

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

These following sections define additional required functions for use within XForms.

7.6 Boolean Methods

7.6.1 The boolean-from-string() Function

boolean boolean-from-string(string)

Function boolean-from-string returns true if the required parameter string is "true" or "1", or false if parameter string is "false", or "0". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matches none of the above strings, according to a case-insensitive comparison, processing stops with an exception (4.5.4 The xforms-compute-exception Event).

7.6.2 The if() Function

string if(boolean, string, string)

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

7.7 Number Methods

7.7.1 The avg() Function

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.7.2 The min() Function

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.7.3 The max() Function

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.7.4 The count-non-empty() Function

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.7.5 The index() Function

number index(string)

Function index takes a string argument that is the idref of a repeat and returns the current 1-based position of the repeat index for the identified repeat—see 9.3.1 The repeat Element for details on repeat and its associated repeat index. If the specified argument does not identify a repeat, processing stops with an exception (4.5.4 The xforms-compute-exception Event).

Example: index
<xforms:trigger>
  <xforms:label>Add to Shopping Cart</xforms:label>
  <xforms:insert ev:event="xforms-activate" position="after"
      nodeset="items/item" at="index('cartUI')"/>
</xforms:trigger>

7.8 String Methods

7.8.1 The property() Function

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 nodeset="message"
      calculate="concat( 'created with XForms ', property('version'))"/> ...
</xforms:instance>

7.9 Date and Time Functions

Note:

The following XML Schema datatypes do not have specific functions for manipulation within XForms expressions: xsd:time, xsd:gYearMonth, xsd:gYear, xsd:gMonthDay, xsd:gDay, xsd:gMonth. Extension functions (7.11 Extension Functions) may be used to perform needed operations on these datatypes.

7.9.1 The now() Function

string now()

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

Note:

Attaching a calculation of "now()" to an instance data node would not result in a stream of continuous recalculations of the XForms Model.

7.9.2 The days-from-date() Function

number days-from-date(string)

This function returns a whole number of days, according to the following rules:

If the string parameter represents a legal lexical xsd:date or xsd:dateTime, the return value is equal to the number of days difference between the specified date and 1970-01-01. Hour, minute, and second components are ignored. Any other input parameter causes a return value of NaN.

Examples:

days-from-date("2002-01-01") returns 11688
days-from-date("1969-12-31") returns -1

7.9.3 The seconds-from-dateTime() Function

number seconds-from-dateTime(string)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical xsd:dateTime, the return value is equal to the number of seconds difference between the specified dateTime and 1970-01-01T00:00:00Z. If no time zone is specified, an implementation default is used. Any other input string parameter causes a return value of NaN.

7.9.4 The seconds() Function

number seconds(string)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical xsd:duration, the return value is equal to the number specified in the seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component, plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. If no time zone is specified, an implementation default is used. Year and month components, if present, are ignored. Any other input parameter causes a return value of NaN.

Examples:

seconds("P1Y2M") returns 0
seconds("P3DT10H30M1.5S") returns 297001.5
seconds("3") returns NaN

Note:

Even though this function is defined based on a lexical xsd:duration, it is intended for use only with derived-from-xsd:duration datatypes, specifically xforms:dayTimeDuration.

7.9.5 The months() Function

number months(string)

This function returns a whole number of months, according to the following rules:

If the string parameter represents a legal lexical xsd:duration, the return value is equal to the number specified in the months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration. Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return value of NaN.

Examples:

months("P1Y2M") returns 14
months("-P19M") returns -19

Note:

Even though this function is defined based on a lexical xsd:duration, it is intended for use only with derived-from-xsd:duration datatypes, specifically xforms:yearMonthDuration.

7.10 Node-set Functions

7.10.1 The instance() Function

node-set instance(string)

An XForms Model can contain more that one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node.

The argument is converted to a string as if by a call to the string function. This string is treated as an IDREF, which is matched against instance elements in the containing document. If a match is located, and the matching instance data is associated with the same XForms Model as the current context node, this function returns a node-set containing just the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty node-set is returned.

Example:

For instance data corresponding to this XML:

<xforms:instance xmlns="" id="orderform">
  <orderForm>
    <shipTo>
      <firstName>John</firstName>
    </shipTo>
  </orderForm>
</xforms:instance>

The following expression selects the firstName node. Note that the instance function returns an element node, effectively replacing the leftmost location step from the path:

ref="instance('orderform')/shipTo/firstName"

7.11 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 functions 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 signaling an exception (4.5.4 The xforms-compute-exception Event) if the XForms document declares an extension function for which the processor does not have an implementation.

Note:

Explicitly declaring extension functions enables XForms Processors to detect the use of unimplemented extension functions at document load-time, rather than throwing a fatal error during user interaction. Failure by authors to declare extension functions will result in an XForms Processor potentially halting processing during user interaction with a fatal error.