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 Boolean Methods
        6.5.2 Number Methods
        6.5.3 String Methods
        6.5.4 Miscellaneous Methods
    6.6 Extensibility
        6.6.1 Extension Functions

6 XPath Expressions in XForms

XPath is used within XForms to address instance data nodes, 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.

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. Every XPath expression requires a context against which to be evaluated.

The following context is used for evaluating all binding 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 a binding expression 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:

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

In this example, the group 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 Boolean Methods

boolean boolean-from-string( string )

The boolean-from-string function returns true if the required string parameter is "true", or false if the string parameter is "false". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression.

Editorial note  
We need to specify behavior if the string paramter is some other value.

6.5.2 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.3 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.4 Miscellaneous Methods

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

XForms 1.0 allows extension functions, similar to [XSLT].

This version of XForms does not provide a mechanism for defining implementations of extensions. Therefore, a containing document that must be portable between XForms implementations cannot rely on particular extensions being available. XForms provides mechanisms that allow a containing document to determine whether the XForms processor by which it is being processed has implementations of particular extensions available, and to specify what should happen if those extensions are not available. If a containing document is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still work with any XForms implementation.

6.6.1 Extension Functions

If a FunctionName in a FunctionCall expression is not an NCName (i.e. if it contains a colon), then it is treated as a call to an extension function. The FunctionName is expanded to a name using the namespace declarations from the evaluation context.

If the XForms processor does not have an implementation of an extension function of a particular name available, then the function-available function must return false for that name. If such an extension function occurs in an expression and the extension function is actually called, the XForms processor must signal an error. An XForms processor must not signal an error merely because an expression contains an extension function for which no implementation is available.

If the XForms processor has an implementation of an extension function of a particular name available, then the function-available function must return true for that name. If such an extension is called, then the XForms processor must call the implementation passing it the function call arguments; the result returned by the implementation is returned as the result of the function call.

boolean function-available()

The function-available function returns true if an extension function of a particular name is available, otherwise false.

   
Table of Contents Top