PRE-PUBLICATION DRAFT. This document is being prepared for possible publication by the W3C, but it may change, be delayed, be moved, or never be published. This page was produced to help test the publication system and find document errors; it is not a W3C publication.
Copyright
©
2012
2013
W3C
®
(
MIT
,
ERCIM
,
Keio
),
All
Rights
Reserved.
W3C
liability
,
trademark
and
document
use
rules
apply.
This module also defines the XForms Function Library which contains additional functions that are useful for creating forms.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This
document
Since
the
previously
published
draft
of
this
document,
no
changes
other
then
addressing
the
editorial
notes
present
in
the
previous
version
have
been
made.
The
Working
Group
believes
it
has
completed
its
design
work
for
the
technologies
specified
in
this
document,
so
this
is
intended
a
"Last
Call"
draft.
The
design
is
not
expected
to
encourage
discussion
change
significantly
going
forward,
and
should
not
be
considered
complete.
Within
the
document
there
are
Editorial
notes.
These
notes
reflect
areas
that
need
particular
attention.
Feedback
on
these
areas
now
is
particularly
appreciated.
the
key
time
for
external
review,
before
the
implementation
phase.
The
Forms
Working
Group
seeks
public
feedback
on
this
First
Public
Working
Draft.
Please
send
your
comments
to
www-forms-editor@w3.org
(
public
archive
).
If
possible,
please
offer
specific
changes
to
the
text
that
would
address
your
concern.
You
may
also
wish
to
check
the
Wiki
Version
of
this
document
and
see
if
the
relevant
text
has
already
been
updated.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
This document is a module designed to add support for XPath as an expression language in XForms. XPath 2.0 is an expression language to address the nodes of [XML 1.0] or [XML 1.1] trees defined by W3C. It includes over 100 built-in functions, including operations on node-sets, strings, numbers, booleans, dates, and durations.
Besides defining how XPath can be used as an expression language in XForms this document also defines the XForms Function Library. The XForms Function Library contains additional functions that are useful for creating forms.
This
specification
has
been
written
with
various
types
of
readers
in
mind—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.
The specification is organized into the following chapters:
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 XForms XF )
xf: The XForms namespace, e.g.http://www.w3.org/2002/xforms
(see Namespace for XForms XF )
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 term s 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.
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.
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-version
attribute
This
module
adds
the
xpath-version
attribute
to
the
XForms
model
element.
The
xpath-version
attribute
is
used
to
switch
on
or
off
XPath
1.0
backwards
compatibility
mode.
XPath
1.0
backwards
compatibility
mode
ensures
that
nearly
all
XPath
1.0
expressions
continue
to
deliver
the
same
result
with
XPath
2.0.
model
.
If XPath 1.0 compatibility mode is requested, an XForms processor may use either an XPath 1.0 implementation [XPath 1.0] or an XPath 2.0 implementation in XPath 1.0 compatibility mode [XPath 2.0] . Some expressions can't be executed with an XPath 1.0 engine and some functions defined in [Functions and Operators] may be missing if an XPath 1.0 engine is used. If the XPath 1.0 engine can't evaluate the expression an xforms-compute-exception XF or an xforms-binding-exception XF will be dispatched.
Note:
XPath 1.0 only supports atomic values and node sets, and does not support sequences.
If an XPath 1.0 engine is used, the function signature components that accept or return:
This module uses XPath to address instance data node XF s in binding expressions, to express constraints, and to specify calculations. XPath expressions in XForms are based on [XPath 2.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-exception XF ) is raised, except for binding expressions, which produce a different exception ( xforms-binding-exception XF ).
If an xforms-compute-exception XF or an xforms-binding-exception XF is raised the following extra context information is made available to the event:
Property | Type | Value |
---|---|---|
xpath-error | xs:QName | Xpath error that caused the error. |
xpath-error-description | string | Description of the xpath error. |
xpath-error-object | item()* | XPath diagnostic value if available, otherwise the empty sequence. |
This module will use the datatypes defined in the XPath specification as their datatypes. The data types are used only in binding expression XF s and computed expression XF s.
We
are
considering
to
provide
the
type
information
provided
by
schema's
attached
to
the
XForms
model
and
the
type
MIPs
to
the
XPath
data
model.
Erik
is
going
model,
but
are
waiting
for
further
implementation
experience
and
user
feedback,
to
check
if
this
is
possible
(during
form
filling
the
data
isn't
valid
according
decide
wether
and
how
to
the
type
->
anyAtomicType
in
this
case?)
do
this.
This module extends the evaluation context XF , with all the additional properties that are defined in the XPath expression context XP . The expression context has two parts, the static context XP , and the dynamic context XP . The components that make up the expression context are defined in the XPath specification (see Section 2.1 Expression Context XP ). This section describes the way in which these components are initialized when an XPath expression is contained within a Form. The term containing element means in these sections the element within the form that is the parent of the attribute whose value contains the XPath expression in question.
The following two sections describe:
The static context XP of an XPath expression appearing in a form is initialized as follows.
For convenience, the dynamic context is described in two parts: the focus, which represents the place in the instance document that is currently being referenced, and a collection of additional context variables.
A
number
of
functions
specified
in
[Functions
and
Operators]
are
defined
to
be
stable
FO
,
meaning
that
if
they
are
called
twice
during
the
same
execution
scope
FO
,
with
the
same
arguments,
then
they
return
the
same
results
(see
"Section
1.7
Terminology
FO
).
In
XForms,
we
currently
not
rigorously
define
what
the
[TODO]
defines
same
execution
scope
means,
and
leave
it
up
to
the
implementor
to
choose
when
a
new
execution
scope.
scope
starts.
This
means,
for
example,
that
if
the
function
current-dateTime
FO
is
called
repeatedly
during
in
a
transformation,
form,
the
interval
for
which
it
produces
the
same
result
each
time.
By
implication,
the
components
of
the
dynamic
context
on
which
these
functions
depend
are
also
stable
for
[TODO].
Specifically,
the
following
components
defined
in
the
section
Dynamic
Context
XP
must
be
stable:
function
implementations,
current
dateTime,
implicit
timezone,
available
documents,
available
collections,
and
default
collection.
The
values
of
global
variables
are
also
stable
for
the
execution
of
the
form.
is
implementation
defined.
The
focus
is
not
stable.
We
need
to
decide
how
we
will
define
the
'stable'
execution
scope,
currently
we
are
thinking
to
go
waiting
for
between
refreshes.
We
only
need
further
implementation
experience
and
user
feedback
to
think
about
define
what
this
means
when
you
use
those
functions
in
binds
(when
are
the
binding,
calculates,
constraints
updated),
but
this
isn't
a
new
problem.
same
execution
scope
means
for
XForms.
The Core XForms specification explained how the focus for an XPath expression appearing in a Form is initialized. This section explains how the other components of the dynamic context XP of an XPath expression are initialized.
When the result of an expression needs to be converted to a build in atomic type we will use the XPath constructor functions to do the converion:
xs:string
or
xs:string?
,
then
the
argument
is
converted
to
a
string
as
if
by
a
call
to
the
fn:string
function
xs:boolean
or
xs:boolean?
,
then
the
argument
is
converted
to
a
boolean
as
if
by
a
call
to
the
fn:boolean
function
The XForms Function Library defines additional functions that are useful for creating forms. The functions will be made available in the XForms namespace XF . When the XPath version on the model is 1.0 or omitted the functions will be made also available in the default function namespace XP . Additionally all functions defined as built-in function and the operators in [Functions and Operators] are also available in XForms.
For backwards compatibility an implementation may make these additional functions also available in the default function namespace XP when the XPath version on the model is not 1.0. When the additional function is also available in [Functions and Operators] , an implementation should not override that function in the default function namespace XP (e.g.: when xpath version on the model is 2.0 invoking replace() will invoke the replace function defined in [Functions and Operators] ).
In future XForms versions adding the XForms Functions to the default function namespace XP may be deprecated.
The following sections define additional required functions for use within XForms : Boolean Functions , Number Functions , String Functions , Date and Time Functions , Node-set Functions , and Object Functions .
The function library provided by an XForms processor may also contain other extension functions as described in Extension Functions XF .
If an error occurs in an XPath function, then an xforms-compute-exception XF or xforms-bind-exception XF occurs.
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.
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-number
XF
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 xforms:card-number XF ):
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
.
xf:valid()
as
xs:boolean
xf:valid($node
as
node()*)
as
xs:boolean
xf:valid($node
as
node()*,
$relevant
as
xs:boolean)
as
xs:boolean
The
valid()
function
returns
the
validity
of
nodes
of
instance
data.
The function acts as if first selecting nodes in this sequence:
$node
parameter,
if
present,
or
the
expression's
context
node,
if
absent.
$relevant
attribute
is
omitted
or
set
to
true()
,
selected
nodes
which
are
non-relevant
are
deselected.
The
relevance
information
of
an
individual
node
is
obtained
by
looking
at
the
node's
relevant
property
computed
as
per
The
xforms-recalculate
Event
XF
.
If
there
are
no
resulting
selected
nodes,
the
function
returns
true()
.
Otherwise the function computes the logical AND of the validity of all the selected nodes. The validity information of an individual node is obtained by looking at the node validity computed as per The xforms-revalidate Event XF .
If
the
function
is
used
in
a
model
binding
expression
XF
the
XForms
Processor
should
terminate
processing
after
dispatching
the
event
xforms-binding-exception
to
the
model.
If
the
function
is
used
in
a
computed
expression
XF
the
XForms
Processor
should
terminate
processing
after
dispatching
the
event
xforms-compute-exception
to
the
model.
Note:
The
validity
of
a
node
might
appear
to
be
out
of
date
by
the
time
the
valid()
function
is
used
if
changes
have
been
made
to
instance
data
between
the
time
xforms-recalculate
and/or
xforms-revalidate
processing
occur
and
the
time
the
function
is
called.
This
function
must
therefore
used
with
caution.
Examples
of
safe
use
include:
xforms-refresh
has
started.
Similarly,
the
reason
for
discouraging
the
use
of
the
valid()
function
within
binds
is
that
it
can
easily
return
unexpected
results.
For
example
relevant="valid(../value)"
will
usually
fail
to
produce
the
expected
result
as
the
relevant
property
is
computed
before
revalidation
happens.
<model> <instance> <data xmlns=""> <node1/> <node2/> </data> </instance> <bind ref="*" type="xs:integer"/> </model> <repeat ref="*[not(valid())]"> <output value="."> <label>Invalid value:</label> </output> </repeat>
The
repeat
above
generates
an
output
to
show
the
value
of
each
data
node
that
is
not
valid
according
to
XForms
model
validation
processing.
xf:matches
(
$input
as
xs:string?
,
$pattern
as
xs:string
)
as
xs:boolean
xf:matches
(
$input
as
xs:string?
,
$pattern
as
xs:string
,
$flags
as
xs:string
)
as
xs:boolean
The
function
returns
true
if
$input
matches
the
regular
expression
supplied
as
$pattern
as
influenced
by
the
value
of
$flags.
The
function
behavioral
details,
regular
expression
pattern
syntax
and
flags
are
defined
by
XPath
2.0.
This
function
from
XPath
2.0
is
included
in
the
XForms
function
library
for
authoring
ease
and
for
XPath
1.0
expression
compatibility.
Examples:
xf:matches("abracadabra", "bra")
returns
true
.
xf:matches('(123) 456-7890', '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')
returns
true
.
<model> <xf:instance xmlns=""> <data> <phone>abc</phone> </data> </xf:instance> <bind ref="phone" constraint="xf:matches(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')"/> </model>
The
function
returns
false
to
the
constraint
.
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
.
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
.
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
.
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.
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
—see
The
repeat
Element
XF
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
Resolving
ID
References
in
XForms
XF
is
used
to
determine
the
desired
run-time
repeat
object.
The
function
index
introduces
additional
dependencies
for
the
computational
dependency
data
structure,
see
Additional
dependencies
for
the
computational
dependency
data
structure
for
details.
<trigger> <label>Add to Shopping Cart</label> <insert ev:event="DOMActivate" position="after" nodeset="items/item" at="xf:index('cartUI')"/> </trigger>
When
activated,
this
trigger
inserts
a
new
item
element
as
the
successor
of
the
item
element
indicated
by
the
index()
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
).
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
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
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
—see
The
switch
Element
XF
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
Resolving
ID
References
in
XForms
XF
is
used
to
determine
the
desired
run-time
repeat
object.
The
function
case
introduces
additional
dependencies
for
the
computational
dependency
data
structure,
see
Additional
dependencies
for
the
computational
dependency
data
structure
for
details.
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 sequence is returned. The property definitions for this function are as follows:
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
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
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
xf:replace
(
$input
as
xs:string?
,
$pattern
as
xs:string
,
$replacement
as
xs:string
)
as
xs:string
xf:replace
(
$input
as
xs:string?
,
$pattern
as
xs:string
,
$replacement
as
xs:string
,
$flags
as
xs:string
)
as
xs:string
The
function
returns
the
xs:string
that
is
obtained
by
replacing
each
non-overlapping
substring
of
$input
that
matches
the
given
$pattern
(as
influenced
by
the
value
of
$flags)
with
an
occurrence
of
the
$replacement
string.
The
function
behavioral
details,
regular
expression
pattern
syntax,
replacement
string
syntax
and
flags
are
defined
by
XPath
2.0.
This
function
from
XPath
2.0
is
included
in
the
XForms
function
library
for
authoring
ease
and
for
XPath
1.0
expression
compatibility.
Examples:
xf:replace("abcd", "(ab)|(a)", "[1=$1][2=$2]")
returns [1=ab][2=]cd
.
xf:replace('1234567890', '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$', '($1) $2-$3')
returns
(123)
456-7890
.
<model> <xf:instance xmlns=""> <data> <phone></phone> </data> </xf:instance> <bind ref="phone" constraint="xf:matches(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$')"/> </model> <input ref="phone"> <label>Enter phone number:</label> <setvalue ev:event="xforms-value-changed" ref="." value="xf:replace(., '^\(?(\d{3})\)? [-. ]?(\d{3}) [-. ]?(\d{4})$', '($1) $2-$3')"/> </input>
If
the
user
enters
an
input
of
1234567890
,
the
setvalue
uses
the
function
to
change
the
content
of
the
phone
element
to
(123)
456-7890
.
xf:serialize
(
$element
as
element()?
)
as
xs:string
xf:serialize
(
$element
as
element()?
,
$format
as
xs:string
)
as
xs:string
The
function
returns
a
string
containing
the
serialization
of
the
XML
tree
rooted
by
the
given
$element.
If
$element
is
empty,
then
the
empty
string
is
returned.
If
no
$format
is
specified,
then
the
default
is
the
xml
serializer
with
no
relevance
pruning
nor
validation.
The $format is a space-separated list of QNames intended to allow namespace qualified custom extensions as well as NCName values that control various features of serialization such as whether relevance pruning is performed, whether an XML declaration is emitted, and various other options of serialization that are synonymous with XForms submission serialization and the XSLT output element.
Token | Meaning |
---|---|
xml
|
Use the XML 1.0 serializer defined by XForms submission, which is the default if no serializer is specified. |
json
|
Use the JSON data serializer defined by XForms submission |
relevant
|
Serialize relevant nodes only. |
validate
|
If the data to be serialized is not valid, return the empty string. Otherwise, return the serialization according to the other $format tokens. |
omit-xml-declaration
| Specifying whether to omit the XML declaration on the serialized instance data. This $format token is ignored if the serializer is not an xml serializer. |
standalone
| Specifying whether to include a standalone declaration in the serialized XML. This $format token is ignored if the serializer is not an xml serializer or the omit-xml-declaration $format token is specified. |
Any other NCName |
Reserved. Their use results in an exception (see 4 The XForms Function Library for the exception type) |
An implementation-specific serializer or serialization qualifier. A QNameButNotNCName is assumed to provide a serializer only if none of the NCName serializers are specified. If the implementation does not support the serializer, then the empty string is returned. |
Example:
<model> <xf:instance xmlns=""> <data> <node>abc</node> <text><node>abc</node></text> </data> </xf:instance> <bind ref="text" calculate="xf:serialize(../node)"/> </model>
The
function
returns
a
string
containing
the
serialization
of
element
node
,
which
is
placed
into
the
content
of
the
element
text
by
the
calculate
.
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
(
Extension
Functions
XF
)
may
be
used
to
perform
needed
operations
on
these
datatypes.
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
.
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
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.
Examples:
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
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
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
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
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
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
for
the
user
of
the
implementation,
and
returns
the
result.
The
application
of
daylight
savings
time
is
dependent
on
whether
daylight
savings
time
is
in
effect
for
the
local
time
zone
at
the
given
date
and
time.
"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
to
the
date
2007-10-02
in
the
Pacific
time
zone.
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
to
the
date
2007-10-02
in
the
Pacific
time
zone.
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
in
the
Pacific
time
zone,
then
the
above
expression
returns
2007-10-02T16:26:43-07:00
xf:adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime('2007-10-02T14:26:43-07:00') + 61*86400))
Returns
2007-12-02T13:26:43-08:00
,
which
is
the
date
and
time
two
months
(61
days)
from
the
date
2007-10-02T14:26:43-07:00
in
the
Pacific
timezone,
adjusting
the
result
for
the
fact
that
daylight
savings
time
no
longer
applies
to
the
resultant
date
in
the
Pacific
timezone.
Note
that
the
hour
component
is
13
,
not
14
and
the
timezone
offset
is
-08:00
,
not
-07:00
.
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
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:
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
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"
xf:current
()
as
item()
Returns the context item XP 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
.
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
.
xf:context
($id
as
xs:string?)
as
item()
This
function
returns
the
in-scope
evaluation
context
item
of
an
ancestor
element
of
the
node
containing
the
XPath
expression
that
invokes
this
function.
The
ancestor
element
is
determined
using
the
id
parameter,
taking
into
account
Resolving
ID
References
in
XForms
XF
.
When
the
id
parameter
is
omitted,
the
nearest
ancestor
element
is
used
for
determining
the
in-scopre
evaluation
context
item
to
return.
The
ancestor
element
may
have
been
created
dynamically
as
part
of
the
run-time
expansion
of
repeated
content
as
described
in
Section
Resolving
ID
References
in
XForms
XF
.
It is an error to specify a non existing id or an id of an element that isn't an ancestor.
If the resolved element isn't a binding element, see Evaluation Context XF for obtaining the evaluation context for non binding elements.
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.
An
intended
use
of
this
function
is
in
conjunction
with
the
repeat
element
(Section
The
repeat
Element
XF
and
the
setvalue
action
element
(Section
The
setvalue
Element
XF
).
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.
xf:element
(
$qname
as
xs:anyAtomicType
,
$content
as
item()*
)
as
element()
This function returns a new XML element with the qualified name provided. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The content argument is a sequence of items specifying attributes and content for the new element.
Examples:
xf:element('value')
Returns an empty element called "value" (in serialized form the result is <value/>).
xf:element('value', (xf:attribute('id', 'my-value'), 'John'))
Returns an element called "value" with an attribute "id" and text content "John" (in serialized form the result is <value id="my-value">John</value>).
xf:element('value', ('John', xf:attribute('id', 'my-value')))
This example illustrates that the attributes may be specified after the content of the element. The result is the same as the previous example (an element called "value" with an attribute "id" and text content "John").
xf:attribute
(
$qname
as
xs:anyAtomicType
,
$value
as
xs:anyAtomicType?
)
as
attribute()
This function returns a new XML attribute with the qualified name provided as first argument. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The second argument is an optional value for the attribute with the empty string as default.
Example:
xf:attribute('id', 'first-name')
Returns an attribute called "id" with a value of "first-name".
xf:parse
(
$arg
as
xs:string
)
as
element()?
xf:parse
(
$arg
as
xs:string
,
$format
as
xs:string
)
as
element()?
This function takes as input a document represented as a string in $arg, and returns the XML document element node for the parsed document. The default if the $format is not specified, the XML 1.0 parsing is used. If $arg is the empty sequence or is not well-formed according to the $format parsing rules, the function returns the empty sequence.
The $format is a space-separated list of QNames intended to control various features of parsing, such as the grammar and grammatic variations, as well as allowing namespace qualified custom extensions.
Token | Meaning |
---|---|
xml
|
Parse input as XML 1.0 |
json
|
Parse input as JSON data |
Any other NCName |
Reserved. Their use results in an exception (see 4 The XForms Function Library for the exception type) |
An implementation-specific parser. If the implementation does not support the parser, then the empty sequence is returned. |
<insert context="container/node" nodeset="elem" at="last()" position="after" origin="xf:parse('<elem> <a/> <b/> </elem>')"/>
The
function
returns
the
document
element
node
named
elem
,
which
is
then
used
as
the
insert
origin,
i.e.
the
source
node
of
the
copy
operation.
Note:
An important use case for this function is to convert unparsed data received by a form, such as from a submission, into parsed data.
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 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.
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 on each event are:
Property | Type | Value |
---|---|---|
type | xs:string | The name of the event. |
bubbles | xs:boolean | Indicates whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false. |
cancelable | xs:boolean | Indicates whether or not an event can have its default action prevented. If the default action can be prevented the value is true, else the value is false. |
targetid | xs:string? | The id of the target to which the event was originally dispatched. If the target does not have an id an empty sequence is returned. |
current-targetid | xs:string? | The id of the target whose EventListeners are currently being processed. If that target does not have an id an empty sequence is returned. |
event-phase | xs:string | The current event phase: capture, target, or bubbling (When the event arrives at the target, the value is 'target'. Values capture and bubbling are as described in XML events) |
time-stamp | xs:integer? | The time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, an empty sequence will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970. |
The event-specific context properties for each event type 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.
xf:eval
(
$expression
as
xs:string
)
as
item()*
The
function
returns
the
result
of
evaluating
the
$expression
in
the
context
of
the
eval()
function
call.
The
expression
containing
the
eval()
function
invocation
references
the
XPath
nodes
referenced
by
the
$expression,
which
introduces
additional
dependencies
for
the
containing
expression.
<model> <instance xmlns=""> <data> <A>3</A> <B>4</B> <C value="power(../A * ../A + ../B * ../B, 0.5)">5</C> </data> </instance> <bind nodeset="descendant::*[@value]" calculate="xf:eval(@value)"/> </model>
The
model
above
responds
to
changes
of
data
elements
A
and
B
by
recalculating
the
value
of
C
.
For
example,
if
A
and
B
are
changed
to
5
and
12
,
then
element
C
would
be
recalculated
to
the
value
13
.
The
model
below
is
the
same
except
that
the
expression
in
the
value
attribute
is
simplified
due
to
the
context
change
performed
before
the
eval()
function
invocation.
<model> <instance xmlns=""> <data> <A>3</A> <B>4</B> <C value="power(A * A + B * B, 0.5)">5</C> </data> </instance> <bind nodeset="descendant::*[@value]" calculate="../xf:eval(current()/@value)"/> </model>
xf:eval-in-context
(
$expression
as
xs:string
,
$context
as
node()*
)
as
item()*
The
function
returns
the
result
of
evaluating
the
$expression
in
the
$context.
The
expression
containing
the
eval()
function
invocation
references
the
XPath
nodes
referenced
by
the
$expression,
which
introduces
additional
dependencies
for
the
containing
expression.
In
XPath
2.0,
the
eval()
function
can
be
invoked
later
in
an
expression,
after
setting
the
desired
context,
so
this
function
is
included
for
ease
of
authoring
and
XPath
1.0
expression
compatibility.
<model> <instance xmlns=""> <data> <A>3</A> <B>4</B> <C value="power(A * A + B * B, 0.5)">5</C> </data> </instance> <bind nodeset="descendant::*[@value]" calculate="xf:eval-in-context(@value, ..)"/> </model>
The
model
above
responds
to
changes
of
data
elements
A
and
B
by
recalculating
the
value
of
C
.
For
example,
if
A
and
B
are
changed
to
5
and
12
,
then
element
C
would
be
recalculated
to
the
value
13
.
The
expression
in
the
value
attribute
is
simplified,
relative
to
a
normal
calculate
expression,
due
to
the
context
change
provided
by
the
second
parameter.
An XPath node is referenced by an expression if it is selected. A node is selected by matching an XPath NodeTest or by being returned by a function call. For examples, a node can match a name test, a wildcard test, a node type test, or it can be returned by or used as a parameter to a function, or it can appear in a filter expression (where all of the prior examples recursively apply).
The expression parameters of the eval() function and the eval-in-context() function ) make references to XPath nodes and therefore introduce additional dependencies.
The
index
(
The
index()
Function
)
and
case
(
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 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.
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.
[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.
http://www.w3.org/2002/xforms
is
used
for
xforms
extension
functions
defined
in
this
specification.]
http://www.w3.org/2005/xpath-functions
is
used
for
functions
in
the
function
library
defined
in
[Functions
and
Operators]
.]
true
and
false
.
When
the
value
is
set
to
true,
the
semantics
of
function
calls
and
certain
other
operations
are
adjusted
to
give
a
greater
degree
of
backwards
compatibility
between
XPath
2.0
and
XPath
1.0.]
This document was produced with the participation of Forms Working Group participants, including:
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.