XPath Expressions Module base
__NUMBEREDHEADINGS__
- Document title:
- XForms 2.0: XPath expression module
- Editor
- Nick Van den Bleeken, Inventive Designers
Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
About the XForms 2.0: XPath expression module
Introduction
Reading the Specification
This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. Implementors, however, should find all they need to add XPath 2.0 support to their XForms Processors. The specification begins with a general presentation of how XPath 2.0 expressions will be used in XForms before specifying the technical details of how to integrate XPath 2.0 in XForms. Finally it defines the XForms Function Library.
The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.
With regard to implementing behaviors defined for XForms content herein, this document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119]. Generally, the elements, attributes, functions and behaviors of XForms content defined in this specification are required to implement unless explicitly specified otherwise. The term author-optional, when applied to a content item such as an element, attribute, or function parameter, indicates to form authors that they may omit the content item and obtain the default behavior. The term author-optional is orthogonal to the conformance status (required, recommended, or optional) of the content item.
How the Specification is Organized
The specification is organized into the following chapters:
- Chapters 1
- An introduction to XPath as an expression language in XForms. The introduction and example usages of XPath expressions in XForms.
- Chapter 2
- Definition of the xpath-version attribute.
- Chapter 3
- Contains all the information on how XPath is integrated into XForms. This section is mostly targeted at XForms implementors.
- Chapter 4
- Defines the XForms Function library which defines additional functions that are useful for creating forms.
Documentation Conventions
Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:
xforms: The XForms namespace, e.g.
http://www.w3.org/2002/xforms
(see Namespace for XFormsXF)
html: An XHTML namespace, e.g.http://www.w3.org/1999/xhtml
(see [XHTML 1.0])
xs: The XML Schema namespacehttp://www.w3.org/2001/XMLSchema
(see [XML Schema part 1])
xsd: The XML Schema namespacehttp://www.w3.org/2001/XMLSchema
(see [XML Schema part 2])
xsi: The XML Schema for instances namespacehttp://www.w3.org/2001/XMLSchema-instance
(see [XML Schema part 1])
ev: The XML Events namespacehttp://www.w3.org/2001/xml-events
(see [XML Events])
fn: The XPath function namespacehttp://www.w3.org/2005/xpath-functions
(see [Functions and Operators])
my: Any user defined namespace
This is only a convention; any namespace prefix may be used in practice.
The following typographical conventions are used to present technical material in this document.
Official terms are defined in the following manner: [Definition: You can find most terms in chapter 6 Glossary Of Terms]. Links to terms may be specially highlighted where necessary.
The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization].
Examples are set off typographically:
Example Item
References to external documents appear as follows: [Sample Reference] with links to the references section of this document.
- Sample Reference
- Reference - linked to from above.
The following typesetting convention is used for additional commentary:
Note:
A gentle explanation to readers.
Editorial note: Editorial Note Name | |
Editorial commentary, not intended for final publication. |
Issue (sample-implementation-issue):
Issue-Name
A specific issue for which input from implementors is requested, for example as part of the Candidate Recommendation phase.
Resolution:
None recorded.
Examples
The following example binds an input control to an instance data node:
<input ref="order/shipTo/street" class="streetAddress"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
The following example outputs the total value of an order by calculating the sum of the price of all line totals in the order. The line total is calculated by multiplying the item price with number of items ordered:
I charged you <output value="sum(for $i in order/order-item return $i/@price * $i/@qty)"/>
XPath Expressions in XForms
This module uses XPath to address instance data node XFs in binding expressions, to express constraints, and to specify calculations. XPath expressions in XForms are based on XPath 1.0. At the time of evaluation, an XPath expression must be syntactically correct. In addition, the namespaces the expression references must be in scope and the functions and variables it references must be defined. If any of these conditions is not satisfied, or a dynamic error or a type error occurs during evaluation, an exception (xforms-compute-exceptionXF) is raised, except for binding expressions, which produce a different exception (xforms-binding-exceptionXF).
Datatypes
This module will use the datatypes defined in the XPath specification as their datatypes. The data types are used only in binding expressionXFs and computed expressionXFs.
Evaluation Context
Initializing the Static Context
Initializing the Dynamic Context
Other components of the XPath Dynamic Context
The XForms Function Library
The XForms Function Library includes the entire XPath 1.0 Core Function Library, including operations on node-sets, strings, numbers, and booleans.
The following sections define additional required functions for use within XForms : 4.1 Boolean Functions, 4.2 Number Functions, 4.3 String Functions, 4.4 Date and Time Functions, 4.5 Node-set Functions , and 4.7 Object Functions.
The function library provided by an XForms processor may also contain other extension functions as described in 4.8 Extension Functions.
If an error occurs in an XPath function, then an xforms-compute-exceptionXF or xforms-bind-exceptionXF occurs.
Boolean Functions
The boolean-from-string() Function
xf:boolean-from-string
($value
as
xs:string
) as
xs:boolean
Function boolean-from-string
returns true
if the required parameter matches "true" or "1" using case-insensitive comparison. Otherwise false
is returned. This function is useful when referencing a Schema xsd:boolean
datatype in an XPath expression.
The is-card-number() Function
xf:is-card-number
($card-nr
as
xs:string?
) as
xs:boolean
If the string parameter conforms to the pattern restriction of the xforms:card-numberXF datatype, then this function applies the Luhn
algorithm described in [Luhn Patent] and returns true if the number satisfies the formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context item.
Examples (see also 5.2.7 xforms:card-numberXF):
xf:is-card-number(.)
returns true
if and only if the string-value of the context item is a string of zero or more digits and satisfies the formula.
xf:is-card-number('4111111111111111')
returns true
. Other examples of string constants that will return true
are : 5431111111111111
, 341111111111111
and 6011601160116611
.
xf:is-card-number('123')
returns false
.
Number Functions
The avg() Function
xf:avg
($arg
as
xs:anyAtomicType*
) as
xs:integer
Function avg
returns the arithmetic average of the result of converting the string-values of each item in the argument sequence to a number. The sum is computed with sum()
, and divided with div
by the value computed with count()
. If the parameter is an empty sequence, or if any of the nodes evaluate to NaN
, the return value is NaN
.
The min() Function
xf:min
($arg
as
xs:anyAtomicType*
) as
xs:integer
Function min
returns the minimum value of the result of converting the string-values of each item in the sequence argument to a number. "Minimum" is determined with the <
operator. If the parameter is an empty sequence, or if any of the nodes evaluate to NaN
, the return value is NaN
.
The max() Function
xf:max
($arg
as
xs:anyAtomicType*
) as
xs:integer
Function max
returns the maximum value of the result of converting the string-values of each item in the sequence argument to a number. "Maximum" is determined with the <
operator. If the parameter is an empty sequence, or if any of the nodes evaluate to NaN
, the return value is NaN
.
The count-non-empty() Function
xf:count-non-empty
($arg
as
node()*
) as
xs:integer
Function count-non-empty
returns the number of non-empty nodes in the first argument. A node is considered non-empty if it is convertible into a string with a greater-than zero length.
The index() Function
xf:index
($repeat-id
as
xs:string
) as
xs:integer
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 ElementXF for details on repeat
and its associated repeat index. If the specified argument does not identify a repeat
, the function returns NaN
.
Note:
The IDREF obtained from the function parameter may not uniquely identify the desired repeat
if the repeat
element bearing the matching ID resides in a repeating construct such as element repeat
. The general method described in 4.7 Resolving ID References in XFormsXF is used to determine the desired run-time repeat object.
The function index
introduces additional dependencies for the computational dependency data structure, see 4.9 Additional dependencies for the computational dependency data structure for details.
<xforms:trigger> <xforms:label>Add to Shopping Cart</xforms:label> <xforms:insert ev:event="DOMActivate" position="after" nodeset="items/item" at="xf:index('cartUI')"/> </xforms:trigger>
The power() Function
xf:power
($base
as
numeric
, $exponent
as
numeric
) as
xs:integer
Raises the first argument to the power of the second argument, returning the result. If the calculation does not result in a real number, then NaN
is returned.
Examples:
xf:power(2, 3)
returns 8
xf:power(-1, 0.5)
returns NaN
.
if (prin>0 and dur>0 and rate>0) then prin*rate/(1-xf:power(1+rate, -dur)) else 0
returns a compounded interest payment value given a non-zero principal (prin
), duration (dur
) and periodic interest rate (rate
).
The random() Function
xf:random
($seed
as
xs:boolean?
) as
numeric
This function generates and returns a uniformly distributed random or pseudorandom number in the range from 0.0 up to but excluding 1.0. This function accepts an author-optional boolean parameter that is false
by default. If true
, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds when random(true)
is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.
Example:
xf:random()
could return 0.14159265358979
The compare() Function
xf:compare
($arg1
as
xs:string
, $arg2
as
xs:string
) as
xs:integer
This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values [Unicode Collation Algorithm].
Example:
xf:compare('apple', 'orange')
returns -1
String Functions
The case() Function
xf:case
($switch-id
as
xs:string
) as
xs:string?
Function case
takes a string argument that is the IDREF
of a switch and returns the ID
of the selected case for the identified switch
—see 9.2.1 The switch ElementXF for details on switch
.
The empty sequence is returned, if the specified argument does not identify a switch
.
Note:
The IDREF obtained from the function parameter may not uniquely identify the desired switch
if the switch
element bearing the matching ID resides in a repeating construct such as element repeat
. The general method described in 4.7 Resolving ID References in XFormsXF is used to determine the desired run-time repeat object.
The function case
introduces additional dependencies for the computational dependency data structure, see 4.9 Additional dependencies for the computational dependency data structure for details.
The property() Function
xf:property
($property-name
as
xs:string
) as
xs:string
This function accepts a string identifying a property name. If the property name is not recognized, empty string is returned. The property definitions for this function are as follows:
Editorial note: Nick Van den Bleeken | 2011-06-26 |
Shouldn't this function return the empty sequence when the property isn't recognized? |
Property | Return Value |
---|---|
version
|
1.1
|
conformance-level
|
full , basic or a string beginning with full or basic
|
Any other NCName |
Reserved. Their use results in an exception (see 4 The XForms Function Library for the exception type) |
An implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned. |
Examples:
xf:property('version')
returns 1.1
xf:property('conformance-level')
may return full
The digest() Function
xf:digest
($data
as
xs:string
, $algo
as
xs:string
, $encoding
as
xs:string?
) as
xs:string
This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:
Keywords | Hash Algorithm | Status |
---|---|---|
MD5
|
The MD5 hash algorithm defined in [MD5] |
|
SHA-1
|
The SHA-1 hash algorithm defined in [SHA2] |
|
SHA-256
|
The SHA-256 hash algorithm defined in [SHA2] |
|
SHA-384
|
The SHA-384 hash algorithm defined in [SHA2] |
|
SHA-512
|
The SHA-512 hash algorithm defined in [SHA2] |
|
Any other NCName |
Reserved. Their use results in an exception (see 4 The XForms Function Library for the exception type) |
|
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 4 The XForms Function Library for the exception type). |
This recommendation defines the values hex
and base64
for the third string parameter that indicates the encoding method. If the parameter is missing, then the default is base64
. The hex
and base64
encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and base64Binary
, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see 4 The XForms Function Library for the exception type).
xf:digest('abc', 'SHA-1', 'hex')
returns a9993e364706816aba3e25717850c26c9cd0d89d
.
xf:digest('abc', 'MD5', 'hex')
returns 900150983cd24fb0d6963f7d28e17f72
.
xf:digest('abc', 'SHA-256', 'hex')
returns ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
The hmac() Function
xf:hmac
($secret
as
xs:string
, $data
as
xs:string
, $algo
as
xs:string
, $encoding
as
xs:string?
) as
xs:string
This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in [HMAC] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.
The following table presents the keywords for the third string parameter and the corresponding hash algorithms:
Keywords | Hash Algorithm | Status |
---|---|---|
MD5
|
The MD5 hash algorithm defined in [MD5] |
|
SHA-1
|
The SHA-1 hash algorithm defined in [SHA2] |
|
SHA-256
|
The SHA-256 hash algorithm defined in [SHA2] |
|
SHA-384
|
The SHA-384 hash algorithm defined in [SHA2] |
|
SHA-512
|
The SHA-512 hash algorithm defined in [SHA2] |
|
Any other NCName |
Reserved. Their use results in an exception (see 4 The XForms Function Library for the exception type) |
|
An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 4 The XForms Function Library for the exception type). |
This recommendation defines the values hex
and base64
for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default is base64
. The hex
and base64
encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and base64Binary
, respectively. For the hexadecimal encoding, the digits 'a' through 'f' are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see 4 The XForms Function Library for the exception type).
xf:hmac('Jefe', 'what do ya want for nothing?', 'SHA-1', 'hex')
returns effcdf6ae5eb2fa2d27416d5f184df9c259a7c79
xf:hmac('Jefe', 'what do ya want for nothing?', 'MD5', 'hex')
returns 750c783e6ab0b503eaa86e310a5db738
xf:hmac('Jefe', 'what do ya want for nothing?', 'SHA-256', 'hex')
returns 5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
Date and Time Functions
Note:
The following XML Schema datatypes do not have specific functions for manipulation within XForms expressions: xsd:gYearMonth
, xsd:gYear
, xsd:gMonthDay
, xsd:gDay
, xsd:gMonth
. Extension functions ( 4.8 Extension Functions) may be used to perform needed operations on these datatypes.
The local-date() Function
xf:local-date
() as
xs:date
This function returns a lexical xsd:date
obtained as if by the following rules: the result of now()
is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result of now()
is returned.
Example:
xf:local-date()
could return 2006-10-13-07:00
xf:substring(local-date(), 1, 10)
could return 2006-10-13
xf:days-to-date(days-from-date(local-date()) + 31)
returns a date that is 31 days from today. For example, if local-date()
returns 2006-10-13-07:00
, then the result is 2006-11-13
.
The local-dateTime() Function
xf:local-dateTime
() as
xs:dateTime
This function returns a lexical xsd:dateTime
obtained as if by the following rules: the result of now()
is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of now()
is returned.
Example:
xf:local-dateTime()
could return 2006-10-13T16:04:17-07:00
xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(local-dateTime()) + 7200))
Adds two hours (7200 seconds) to the local date and time, returning the result in the local time zone. For example, if local-dateTime()
returns 2007-10-02T14:26:43-07:00
, then the above expression returns 2007-10-02T16:26:43-07:00
The now() Function
xf:now
() as
xs:string
The now
function returns the current UTC date and time as a string value in the canonical XML Schema xsd:dateTime
format. If time zone information is available, it is used to convert the date and time to UTC. If no time zone information is available, then the date and time are assumed to be in UTC.
Note:
Attaching a calculation of "now()
" to an instance data node would not result in a stream of continuous recalculations of the XForms Model.
xf:now()
returns 2006-10-14T01:04:17Z
if local-dateTime()
returns 2006-10-13T18:04:17-07:00
xf:seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)
Computes two hours from now, returning the result in UTC time. For example, if now()
returns 2007-10-02T21:26:43Z
, then the above expression returns 2007-10-02T23:26:43Z
The days-from-date() Function
xf:days-from-date
($arg
as
xs:string
) as
xs:integer
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 or dateTime (normalized to UTC) and 1970-01-01
. Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return value of NaN
.
Note:
If an xsd:date
is given as the parameter, the timezone is ignored if provided because there is no way to normalize to the date in the UTC timezone without both the time and timezone.
Examples:
xf:days-from-date("2002-01-01")
returns 11688
xf:days-from-date("2002-01-01-07:00")
returns 11688
xf:days-from-date("1969-12-31")
returns -1
The days-to-date() Function
xf:days-to-date
($arg
as
numeric
) as
xs:date
This function returns an xsd:date
that corresponds to the number of days passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and 1970-01-01
. An input parameter value of NaN
results in output of the empty string.
Examples:
xf:days-to-date(11688)
returns 2002-01-01
xf:days-to-date(-1)
returns 1969-12-31
The seconds-from-dateTime() Function
xf:seconds-from-dateTime
($arg
as
xs:string
) as
xs:decimal
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 (normalized to UTC) and 1970-01-01T00:00:00Z
. If no time zone is specified, UTC is used. Any other input string parameter causes a return value of NaN
. This function does not support leap seconds.
Example:
xf:seconds-from-dateTime('1970-01-01T00:00:00Z')
returns 0
xf:seconds-from-dateTime('1970-01-01T00:00:00-08:00')
returns 28800
The seconds-to-dateTime() Function
xf:seconds-to-dateTime
($arg
as
numeric
) as
xs:xsd:dateTime
This function returns an xsd:dateTime
that corresponds to the number of seconds passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired UTC dateTime and 1970-01-01T00:00:00Z
. An input parameter value of NaN
results in output of the empty string. This function does not support leap seconds.
Examples:
xf:seconds-to-dateTime(0)
returns 1970-01-01T00:00:00Z
xf:seconds-from-dateTime(28800)
returns 1970-01-01T08:00:00Z
xf:seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)
Computes two hours from now, returning the result in UTC time. For example, if now()
returns 2007-10-02T21:26:43Z
, then the above expression returns 2007-10-02T23:26:43Z
xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))
Computes two hours from now, returning the result in the local time zone. For example, if now()
returns 2007-10-02T21:26:43Z
and the local date and time is 2007-10-02T14:26:43-07:00
, then the above expression returns 2007-10-02T16:26:43-07:00
The adjust-dateTime-to-timezone() Function
xf:adjust-dateTime-to-timezone
($arg
as
xs:string
) as
xs:dateTime
This function adjusts a legal lexical xsd:dateTime
received as the parameter to the local time zone of the implementation, and returns the result. "Local" or untimezoned times are presumed to be the time in the local time zone. If the implementation does not have access to time zone information, UTC is used. The result is empty string if the string argument is the empty sequence or not a legal lexical xsd:dateTime
.
Examples:
xf:adjust-dateTime-to-timezone('2007-10-07T02:22:00')
returns 2007-10-07T02:22:00-07:00
in the Pacific time zone since daylight savings time applies.
xf:adjust-dateTime-to-timezone('2007-10-02T21:26:43Z')
returns 2007-10-02T14:26:43-07:00
in the Pacific time zone since daylight savings time applies.
xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))
Computes two hours from now, returning the result in the local time zone. For example, if now()
returns 2007-10-02T21:26:43Z
and the local date and time is 2007-10-02T14:26:43-07:00
, then the above expression returns 2007-10-02T16:26:43-07:00
The seconds() Function
xf:seconds
($arg
as
xs:string
) as
xs:decimal
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. Year and month components, if present, are ignored. Any other input parameter causes a return value of 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
.
Examples:
xf:seconds("P3DT10H30M1.5S")
returns 297001.5
(3 days, 10 hours, 30 minutes, and 1.5 seconds)
xf:seconds("P1Y2M")
returns 0
because the year and month parts of the duration are ignored and the remaining portions are unspecified and default to 0
xf:seconds("3")
returns NaN
because the parameter is not a lexically valid duration
The months() Function
xf:months
($arg
as
xs:string
) as
xs:integer
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
.
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
.
Examples:
Examples:
xf:months("P1Y2M")
returns 14
(1 year and 2 months)
xf:months("-P19M")
returns -19
because the duration is negative and expresses 0 years and 19 months
Node-set Functions
The instance() Function
xf:instance
($id
as
xs:string?
) as
element()?
An XForms Model can contain more than one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node.
If the argument is omitted or is equal to the empty string, then the root element node (also called the document element node) is returned for the default instance of the current model. The current model, is the model that contains the node of the nearest inscope evaluation context that is a node (starting from the evaluation context of the the node containing the XPath expression that invokes this function).
Otherwise, 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 model, this function returns the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty sequence 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="xf:instance('orderform')/shipTo/firstName"
The current() Function
xf:current
() as
item()
Returns the context itemXP used to initialize the evaluation of the containing XPath expression.
Examples:
For the following instance data:
<xforms:instance xmlns=""> <converter> <amount>100</amount> <currency>jpy</currency> <convertedAmount></convertedAmount> </converter> </xforms:instance> <xforms:instance xmlns="" id="convTable"> <convTable date="20040212" currency="cdn"> <rate currency="eur">0.59376</rate> <rate currency="mxn">8.37597</rate> <rate currency="jpy">80.23451</rate> <rate currency="usd">0.76138</rate> </convTable> </xforms:instance>
and the following value calculation bind:
<bind nodeset="convertedAmount" calculate="../amount * xf:instance('convTable')/rate[@currency=xf:current()/../currency]"/>
the content value of /converter/convertedAmount
is the product of /converter/amount
and the conversion table rate given by the rate
element whose currency
attribute value matches the content of /converter/currency
.
For the following instance data:
<xforms:instance xmlns="" id="i1"> <months> <mon>01</mon> <mon>02</mon> <mon>03</mon> </months> </xforms:instance> <xforms:instance xmlns="" id="i2"> <months> <month code="01">Jan</month> <month code="02">Feb</month> <month code="03">Mar</month> </months> </xforms:instance>
and the following repeat structure:
<repeat nodeset="mon"> <output value="xf:instance('i2')/month[@code = xf:current()]/> </repeat>
the output should contain Jan Feb Mar
.
The id() Function
xf:id
($arg
as
xs:string*
, $node
as
node()*?
) as
element()*
xf:id
($arg
as
node()*
, $node
as
node()*?
) as
element()*
The first parameter provides one or more IDREFs. This may be in the form of a string containing a space-separated list of IDREFs or a sequence of nodes, each node of which contains an IDREF. The second parameter provides nodes in one or more instance data documents to be searched. If the second parameter is not given or is empty, then the instance data document to be searched is the one containing the context node of the function call (if the context item isn't a node and second parameter isn't provided or is the empty sequence an error is raised). For each node in the second parameter (or its default), the set of element nodes are collected with IDs that match the IDREFs from the first parameter. The result of this function is a sequence of elements, in document order with duplicates eliminated, containing the union of the collected element nodes from each string. An element node can be assigned an ID by means of an xml:id
attribute or an attribute that is assigned the type ID by a DTD or xsd:ID or any type derived from xsd:ID by an XML schema, or the type
model item property.
Example:
xf:id('X Y', instance('Z'))
Returns nodes identified by X or Y from the instance data document associated with the root element of the instance
identified by Z.
Note:
This function is depricated because it behaves the same as the fn:id() function defined in [Functions and Operators] and we recomend using fn:id().
Note:
When an ID is assigned to a attribute by asigning any type derived from xsd:ID by an XML schema, or the type
model item property that inform the ID type information is provided to the XPath data model. And consequently the is-id accessor will return true
.
The context() Function
xf:context
() as
item()
This function returns the in-scope evaluation context item of the nearest ancestor element of the node containing the XPath expression that invokes this function. The nearest ancestor element may have been created dynamically as part of the run-time expansion of repeated content as described in Section 4.7 Resolving ID References in XFormsXF.
Example:
<setvalue ref="x" value="xf:context()/y"/>
This action sets node x
to the value of node y
, where both nodes are children of the in-scope evaluation context node for the setvalue
element.
Note:
An intended use of this function is in conjunction with the repeat
element (Section 9.3.1 The repeat ElementXF and the setvalue
action element (Section 10.2 The setvalue ElementXF). The intent is to provide form authors with a means of expressing a value
attribute that is relative to the repeat context node when the Single Node Binding result is not.
Object Functions
The choose() Function
xf:choose
($condition
as
xs:boolean
, $choice-true
as
item()*
, $choice-false
as
item()*
) as
item()*
This function provides a conditional test that chooses an object to return based on the boolean parameter. If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. Each of the object parameters can be of any XPath datatype as described in Section 3.1 Datatypes, and this function does no type conversion of the parameter it chooses to return.
Note:
All parameters of an XPath function are evaluated, so the parameter that is not returned by this function is still evaluated, and its result is discarded by this function.
Example:
xf:choose(count(x) > 0, x, y)
Returns the node-set of matching x
if it is non-empty and the node-set matching y
otherwise.
xf:choose(@x, @x, 0)
If the context node of the function contains attribute x
, then the nodeset containing that attribute is returned. Otherwise, the number 0
is returned.
The event() Function
xf:event
($property-name
as
xs:string
) as
item()*
Function event
returns context specific information determined by the string argument. The returned context information is an XPath object whose type and content depends upon the requested property. Each event describes what properties can be accessed by this function and the type and value that will be returned as the result.
The event context properties available for each event are provided in the sections that describe the events.
This function is intended for use in the XPath expressions of XForms actions. If invoked for any other XPath expression, such as a binding expression or model item property expression, this function returns the empty string. If this function is invoked from an XPath expression for an XForms action, then event context information is used from the most recently dispatched event whose action handler contains the XForms action.
Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched. Implementations may also add custom properties. If the event context information does not contain the property indicated by the string argument, then an empty node-set is returned.
Examples:
xf:event('inserted-nodes')
If called from an xforms-insert
event handler, a nodeset is returned containing the instance data node or nodes inserted.
Extension Functions
XForms documents may use additional XPath extension functions beyond those described here. A number of useful community extensions are defined at [EXSLT]. 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 halt processing by signaling an exception (xforms-compute-exceptionXF) 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 exception (xforms-bind-exceptionXF or xforms-compute-exceptionXF) 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.
Editorial note: Nick Van den Bleeken | 2011-06-21 |
We should consider a standard way to embed custom functions in a form (there is a proposal on the table:http://www.w3.org/MarkUp/Forms/wiki/Custom_XPath_functions ) |
Additional dependencies for the computational dependency data structure
The index
( 4.2.5 The index() Function) and case
( 4.3.1 The case() Function) functions introduce additional dependencies for the computational dependency data structure. Beside the normal dependencies introduced by their arguments, these functions also need addtional dependencies to ensure that automatic recalculation happens when respectively the repeat index or selected case changes.
Implementation must behave as if each occurrence of a repeat
is associated with an implicitly managed instance data node containing the repeat index. If a repeat
identified as R1
contains a repeat
identified as R2
, then a repeat index instance node is managed for each occurrence of R2
that is generated by R1
. An invocation of the function index()
in an expression is considered to reference the repeat index instance node corresponding to the repeat index value that it returns. The same strategy should by used for the function case()
(each occurrence of a switch is associated with an implicitly managed instance data node containing the ID of the selected case). An invocation of the function case()
in an expression is considered to reference the switch instance node corresponding to the ID
of the selected case that it returns. Note that if a switch
is embedded in a repeat
a seperate instance node (to track the ID of the selected case of the switch) should be created for every iteration in the repeat.
Error Indications
Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.
The xforms-xpath-version-exception Event
Dispatched as an indication of failure of the XPath version checks defined in the description of the xpath-version
attribute in Section 2 The xpath-version attribute.
Target: the default model
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error-information | string | An implementation-specific error string |
Default Action: Fatal error (halts processing).
Note:
This exception occurs early in processing. XForms processors are not expected to product XForms user interface elements nor even execute XForms action handlers (such as a message
action) in response to this event. This exception is dispatched for the benefit of implementation-specific processing code that may be monitoring the behavior of an XForms processor.
Reserved Namespaces
[Definition: Definition: The XForms namespace, together with certain other namespaces recognized by an XForms processor, are classified as reserved namespaces and must be used only as specified in this and related specifications.] The reserved namespaces are those listed below.
- [Definition: The XForms namespace, described in 3.1 Namespace for XFormsXP, is reserved.]
- [Definition: The xforms function namespace
http://www.w3.org/2002/xforms-functions
is used for xforms extension functions defined in this specification.] - [Definition: The standard function namespace
http://www.w3.org/2005/xpath-functions
is used for functions in the function library defined in [Functions and Operators].]
Glossary Of Terms
- Binding expression
- [Definition: An XPath 1.0 expression used in a binding.]
- QNameButNotNCName
- [Definition: A QName that is not an NCName. In 2006, the W3C named this a PrefixedName. ]
References
Normative References
- HMAC
- RFC 2104 - HMAC: Keyed-Hashing for Message Authentication, H. Krawczyk, M. Bellare, R. Canetti, 1997. Available at http://www.ietf.org/rfc/rfc2104.txt
- RFC 2119
- RFC 2119: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
- SHA2
- SECURE HASH STANDARD. FIPS PUB 180-2, August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
- XML Events
- XML Events - An events syntax for XML, Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-xml-events-20031014/.
- XHTML 1.0
- XHTML 1.0: The Extensible HyperText Markup Language - A Reformulation of HTML 4 in XML 1.0, Steven Pemberton, et al., 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-xhtml1-20020801/.
- XHTML Modularization
- XHTML Modularization 1.1, D. Austin, S. Peruvemba, S. McCarron, M. Ishikawa, M. Birbeck, 2008. W3C Recommendation available at http://www.w3.org/TR/2008/REC-xhtml-modularization-20081008.
- XPath 1.0
- XML Path Language (XPath) Version 1.0, James Clark, Steve DeRose, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xpath-19991116/.
- Luhn Patent
- Computer for Verifying Numbers, H. P. Luhn, U.S. Patent 2,950,048, 1960.
- MD5
- RFC 1321: The MD5 Message-Digest Algorithm, R. Rivest, 1992. Available at http://www.ietf.org/rfc/rfc1321.txt
- XML 1.0
- XML 1.0, Extensible Markup Language (XML) 1.0 (Fourth Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 2008. W3C Recommendation available at: http://www.w3.org/TR/2008/REC-xml-20081126/.
- XML 1.1
- XML 1.1, Extensible Markup Language (XML) 1.1 (Second Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau, John Cowan, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml11-20060816/.
- XML Schema part 1
- XML Schema Part 1: Structures, Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.
- XML Schema part 2
- XML Schema Part 2: Datatypes, Paul V. Biron, Ashok Malhotra, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
- Unicode Collation Algorithm
- Unicode Technical Standard #10, Unicode Collation Algorithm, Available at: http://www.unicode.org/unicode/reports/tr10/.
- QNameButNotNCName
- [Definition: A QName that is not an NCName. In 2006, the W3C named this a PrefixedName. ]
Informative References
- EXSLT
- EXSLT Web site. Available at http://www.exslt.org.
Acknowledgements (Non-Normative)
This document was produced with the participation of Forms Working Group participants, including:
- John M. Boyer, IBM (Chair, Editor)
- Steven Pemberton, W3C/CWI (Activity Lead, W3C Team Contact, Chair until 2007)
- Blake Jones, DAISY Consortium and ViewPlus Technologies
- Ulrich Nicolas Lissé, DreamLab
- Sebastian Schnitzenbaumer, DreamLab (Co-chair until 2003)
- Joern Turner, DreamLab
- T. V. Raman, Google
- Keith Wells, IBM
- Charlie Wiecha, IBM
- Nick Van den Bleeken, Inventive Designers n.v.
- Erik Bruchez, Orbeon
- Mark Seaborne, Origo, PicoForms
- Kenneth Sklander, PicoForms
- Susan Borgrink, Progeny Systems
- Rafael Benito Ruiz de Villa, SATEC
- Rogelio Pérez Cano, SATEC
- Lars Oppermann, Sun Microsystems
- Mark Birbeck, Backplane Ltd. (Invited Expert)
- Leigh L. Klotz, Jr., Xerox Corporation
Production Notes (Non-Normative)
This document was encoded in the XMLspec DTD v2.6. The XML sources were transformed using diffspec and xmlspec stylesheets, version 2.6. The XML Schema portion of the Appendix was rendered into HTML with the xmlverbatim XSLT stylesheet (used with permission). The primary tool used for editing was XMLSpy. The XML was transformed using the XSLT processor in Java 6. The editor(s) use the W3C CVS repository and the W3C IRC server for collaborative authoring.