Table of Contents Prev Next Bottom
Quick Table of Contents
6 XPath Expressions in XForms
    6.1 Datatypes
    6.2 Instance Data
    6.3 Evaluation Context
    6.4 Canonical Binding Expressions
    6.5 Forms Core Function Library
        6.5.1 Number Methods
        6.5.2 String Methods
        6.5.3 Miscellaneous Methods
    6.6 Extensibility

6 XPath Expressions in XForms

XPath is used within XForms to address instance data, as well as to perform basic operations, such as declaratively stating when a form control needs to be filled out, or defining a computation over other values such as unit prices, quantities, discounts, and tax and shipping costs. This chapter describes how XForms uses XPath, and additional XForms functions for use in forms.

6.1 Datatypes

In general, XPath uses a smaller set of datatypes than XML Schema. XForms allows arbitrary Schema datatypes, including those defined in 4 Datatypes, while XPath datatypes are limited to boolean, string, number, and node-set. (For completeness, XPath additionally has external objects and result tree fragments, but there is no special treatment for these types in the XForms specification.)

Note:

Resource-limited XForms Processors may define implementation limits on the maximum size of a node-set.

The XForms specification is defined such that it is always clear whether XPath or XML Schema datatypes are used within a particular context. Binding expressions and computed expressions always use XPath datatypes, while everything else uses XML Schema datatypes.

Note:

A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes, which will make the above distinction moot.

6.2 Instance Data

Every form has a current state, representing the values entered at any particular point in time. Within XForms, for each xform element, the XForms Processor must behave as if it internally maintains an XML data structure modeled as a tree to represent the state of the form. This data structure is called instance data and conforms to the XPath Data Model [XPath 1.0]. Additionally, each node in the tree contains a boolean "dirty" flag, which is referenced elsewhere by the XForms Processing Model. In this context, "dirty" indicates that the data value might need to be refreshed in the presentation.

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. Instance data elements and attributes may not belong to the XForms namespace.

Issue (issue-instance-data-access):

Should there be specified a DOM form of access (perhaps a document fragment), that maps to the instance data? If so, should it be read-only or read-write access? What are possible security implications here?

The rules for defining the root and context nodes of the instance data are found in in the following section.

6.3 Evaluation Context

Applied to XForms, XPath references abstract instance data (using the "path" portion of XPath), instead of a discrete XML document. This reference is called a binding expression in this specification.

The following context is used for evaluating all XPath expressions in XForms:

  1. The context node for outermost binding elements (such as XForms UI elements) is the XPath root (/). A "binding element" is any element that is explicitly allowed to have an xform:ref attribute. An XForms element is "outermost" when the node-set returned by the XPath expression ancestor::* includes no binding element nodes.

    Note:

    The contents of the instance data below the XPath root node (/) are dependent on how the instance data was constructed, which is defined in 11.4.2 Instance Data Construction.

  2. The context node for non-outermost binding elements is determined by evaluating 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 size and position are both exactly 1.

  4. No variable bindings are in place.

  5. The available function library is defined below.

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

Example:

<repeat ref="element1/foo/bar">
  <selectOne ref="element2" ... />
  <selectOne ref="@attr" ... />
</repeat>

In this example, the repeat has a binding expression of element1/foo/bar. 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 element1 element. Both of the selectOnes then inherit a context node from their parent, the context node being /element1/foo/bar. Based on this, the selectOne binding expressions evaluate respectively to /element1/foo/bar/element2 and /element1/foo/bar/@attr. Matching instance data follows: 

<element1>
  <foo>
    <bar attr="xyz">
      <element2>xyz</element2>
    </bar>
  </foo>
</element1>

6.4 Canonical Binding Expressions

As with XPath, it is possible to construct many different binding expressions that end up returning the same node-set. That said, it is often useful to express a binding expression in a standard, compact representation, defined as a canonical binding expression.

Canonical binding expressions are represented as an AbsoluteLocationPath as defined in [XPath 1.0]. Additionally, canonical binding expressions use only default abbreviated axis-specifiers (for elements) or the '@' abbreviation (for attributes). Examples:

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

Issue (xpath-core-lib):

Further input is required on the ability for resource-constrained devices to implement the complete XPath Core Function Library.

6.5.1 Number Methods

number average(node-set)

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

number min(node-set)

The min function returns the minimum value, for each node in the argument node-set, of the result of converting the string-values of the node to a number. "Minimum" is determined with the < operator.

number max(node-set)

The max function returns the maximum value, for each node in the argument node-set, of the result of converting the string-values of the node to a number. "Maximum" is determined with the < operator.

number count-non-empty(node-set)

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

Note:

The following core functions are defined within [XPath 1.0] - number(), sum(), floor(), ceiling(), and round()

Note:

The following useful numeric and boolean operators are defined within [XPath 1.0] - "+", "-", "*", "div", "mod", unary "-" ,"=", "!=", "<", ">", "<=", ">=", "or", "and".

6.5.2 String Methods

string now()

The now function returns the current system time as a string value, in the canonical format defined within the XForms specification. If local time zone information is available, it is included in the string.

Note:

Note: the following are defined within [XPath 1.0] - string(), concat(), starts-with(), contains(), substring-before(), substring-after(), substring(), string-length(), normalize-space(), and translate().

6.5.3 Miscellaneous Methods

boolean submit()

The submit function immediately submits the instance data bound to the node that contains the expression by triggering an xforms-submit event.

boolean reset()

The reset function immediately resets the instance data bound to the node that contains the expression by triggering an xforms-reset event.

string xforms-property(string)

The xforms-property function accesses the XForms Property (defined in 11 Processing Model) named by the string parameter, and returns the value of the property.

6.6 Extensibility

Issue (user-extensions):

This section will be expanded in future revisions, to cover extension functions and methods for calling out to script, perhaps something along the lines of element-available and function-available.

   
Table of Contents Top