Table of Contents | Prev | Next | Bottom |
Quick Table of Contents |
---|
7 XPath Expressions in XForms 7.1 XPath Datatypes 7.2 Instance Data 7.3 Evaluation Context 7.4 Binding Expressions 7.4.1 Model Binding Expressions 7.4.2 UI Binding Expressions 7.4.3 UI Binding in other XML vocabularies 7.4.4 Binding Examples 7.5 XForms Core Function Library 7.6 Boolean Methods 7.6.1 The boolean-from-string() Function 7.6.2 The if() Function 7.7 Number Methods 7.7.1 The avg() Function 7.7.2 The min() Function 7.7.3 The max() Function 7.7.4 The count-non-empty() Function 7.7.5 The index() Function 7.8 String Methods 7.8.1 The property() Function 7.9 Date and Time Functions 7.9.1 The now() Function 7.9.2 The days-from-date() Function 7.9.3 The seconds-from-dateTime() Function 7.9.4 The seconds() Function 7.9.5 The months() Function 7.10 Extension Functions |
XForms uses XPath to address instance data nodes in binding expressions, to express constraints, and to specify calculations. XPath expressions other that are not syntactically valid, including attempted calls to undefined functions, result in an exception (4.5.4 The xforms-compute-exception Event), except for binding expressions, which produce a different exception (4.5.1 The xforms-binding-exception Event).
XPath data types are used only in binding expressions
and computed
expressions. XForms uses XPath datatypes boolean
,
string
, number
, and
node-set
. A future version of XForms is expected to
use XPath 2.0, which includes support for XML Schema datatypes.
For each model
element, the XForms Processor
maintains the state in an internal structure called instance data that
conforms to the XPath Data Model [XPath 1.0]. XForms Processors
that implement DOM must provide DOM access to this instance data
via the interface defined below.
Note:
Instance data always has a single root element, and thus corresponds to a DOM Document.
interface XFormsModelElement : org.w3c.dom.Element
The method getInstanceDocument
returns a DOM
Document that corresponds to the instance data associated with this
XForms Model.
This parameter specifies the ID of an instance
element.
Return value: org.w3c.dom.Document
raises (DOMException); if there is no model with the specified
instance-id
.
This method signals the XForms processor to rebuild any internal data structures used to track computational dependencies within this XForms Model.
This method takes no parameters.
Return value: None
This method raises no exceptions.
This method signals the XForms processor to perform a full recalculation of this XForms Model.
This method takes no parameters.
Return value: None
This method raises no exceptions.
This method signals the XForms processor to perform a full revalidation of this XForms Model.
This method takes no parameters.
Return value: None
This method raises no exceptions.
This method signals the XForms processor to perform a full refresh of form controls bound to instance nodes within this XForms Model.
This method takes no parameters.
Return value: None
This method raises no exceptions.
Note:
Script invocation of recalculate()
is not
necessarily equivalent to performing the recalculate action
handler. Though the script is assumed to have modified instance
data prior to invoking recalculate()
, the DOM
mutations are not cached. Thus, a full recalculation is
necessary to ensure the proper changes are effected throughout the
XForms model.
Within XForms, XPath expressions reference abstract instance data (using the "path" portion of XPath), instead of a concrete XML document. This reference is called a binding expression in this specification. Every XPath expression requires an evaluation context. The following rules are used in determining evaluation context when evaluating elements containing binding expressions in XForms:
The context node for outermost binding elements is the top level
element node, or the single node returned by /*
. A
binding element is any element that is explicitly allowed to
have a binding expression attribute. A binding element is
"outermost" when the node-set returned by the XPath
expression ancestor::*
includes no binding element
nodes.
The context node for non-outermost binding elements is the first
node of the binding expression of the immediately enclosing
element. An element is "immediately enclosing" when it is
the first binding element node in the node-set returned by the
XPath expression ancestor::*
. This is also referred to
as "scoped resolution".
The context node for computed expressions (occurring on element
bind
) is the first node of the node-set returned from
the binding expression in the sibling ref
attribute.
The context size and position are both exactly 1.
No variable bindings are in place.
The available function library is defined below, plus any functions supplied by the implementation. Extension functions required for operation of the form should be declared, as described at 7.10 Extension Functions.
Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.
<group ref="level2/level3"> <select1 ref="@attr" ... /> </group>
In this example, the group
has a binding expression
of level2/level3
. According to the rules above, this
outermost element would have a context node of
/level1
, which is the root element of the instance
data. The select1
form control then inherits a context
node from the parent group. Matching instance data follows:
<level1> <level2> <level3 attr="xyz"/> </level2> </level1>
A binding expression is an XPath LocationPath expression used in binding a model item property to one or more instance nodes, or to bind a form control to the instance, or to specify the a node or node set for operation by an action.
Not every possible XPath expression is acceptable as a binding expression. In particular, there restrictions on binding expressions that create dynamic dependencies, which are defined as follows:
Any XPath predicate expression (in square brackets) is a dynamic dependency unless both sides of the comparison are "fixed", where fixed means either a constant, or a value that will not change between operations explicitly defined as rebuilding computational dependencies.
Note:
A dynamic dependency does not result if either side of the
predicate is one of the following: position()
,
last()
, count()
, or index()
;
the specification mandates a dependency rebuild after any event
that could change the values returned by these functions. Note also
that property()
is also permitted, since it always
returns the same values for the duration of form processing.
Another dynamic dependency is any use of the id()
function, unless both the parameter to the function and the
matching attribute of type xsd:ID
are fixed. In the
same way, the instance()
function is dynamic unless
the parameter to the function is fixed.
XPath variables that change in value from one recalculate to the next would also create dynamic dependencies (though XForms 1.0 defines an empty variable context for all XPath expressions).
Authors that define extension functions are encouraged to follow these rules.
A model binding
expression is a kind of binding expression used in
bind
that can be used to declare model item
properties.
No dynamic dependencies are allowed in model binding expressions. Upon detecting a dynamic dependency in a model binding expression, form processing terminates with an exception (4.5.1 The xforms-binding-exception Event).
Binding references can be used to bind form controls to the
underlying data instance as described here. Different attribute
names, ref
and nodeset
distinguish
between a single node and a node-set respectively. See 3.2.3 Single-Node
Binding Attributes and 3.2.4 Node-Set
Binding Attributes.
Dynamic dependences are allowed in UI binding expressions based on the conformance profile.
The XForms binding mechanism allows other XML vocabularies to
bind user interface controls to an XForms Model using any of the
techniques shown here. As an example, XForms binding attribute
bind
might be used within legacy HTML user interface
controls as shown below. See 3.2.3 Single-Node
Binding Attributes and 3.2.4 Node-Set
Binding Attributes.
<html:input type="text" name="..." xforms:bind="fn"/>
Consider a document with the following XForms model:
<xforms:model id="orders"> <xforms:instance xmlns=""> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </xforms:instance> <xforms:bind nodeset="/orderForm/shipTo/firstName" id="fn" /> </xforms:model>
The following examples show three ways of binding user interface
control xforms:input
to instance element
firstName
declared in the model shown above.
ref
<xforms:input ref="/orderForm/shipTo/firstName">...
bind
<xforms:input bind="fn">...
<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...
The XForms Core Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.
This following sections define additional required functions for use within XForms.
boolean boolean-from-string(string)
Function boolean-from-string
returns
true
if the required parameter string
is
"true" or "1", or false
if parameter
string
is "false", or "0". This is useful when
referencing a Schema xsd:boolean
datatype in an XPath
expression. If the parameter string matches none of the above
strings, according to a case-insensitive comparison, processing
stops with an exception (4.5.4 The
xforms-compute-exception Event).
number avg(node-set)
Function avg
returns the arithmetic average of the
result of converting the string-values of each node in the argument
node-set to a number. The sum is computed with sum()
,
and divided with div
by the value computed with
count()
.
number min(node-set)
Function min
returns the minimum value of the
result of converting the string-values of each node in argument
node-set
to a number. "Minimum" is determined with the
<
operator. If the parameter is an empty node-set,
the return value is NaN.
number max(node-set)
Function max
returns the maximum value of the
result of converting the string-values of each node in argument
node-set
to a number. "Maximum" is determined with the
<
operator. If the parameter is an empty node-set,
the return value is NaN.
number count-non-empty(node-set)
Function count-non-empty
returns the number of
non-empty nodes in argument node-set
. A node is
considered non-empty if it is convertible into a string with a
greater-than zero length.
number index(string)
Function index
takes a string argument that is the
idref
of a repeat
and returns the current
position of the repeat index for the identified
repeat
—see 9.3.1 The repeat Element
for details on repeat
and its associated repeat index.
If the specified argument does not identify a repeat
,
processing stops with an exception (4.5.4 The
xforms-compute-exception Event).
<xforms:button> <xforms:label>Add to Shopping Cart</xforms:label> <xforms:insert ev:event="ev:activate" position="after" nodeset="items/item" at="index('cartUI')"/> </xforms:button>
The
property() Function
string property(string)
Function property
returns the XForms property named
by the string parameter.
The following properties are available for reading (but not modification).
version
is defined as the string "1.0
"
for XForms 1.0
conformance-level
strings are defined in 12 Conformance.
<xforms:instance> ... <xforms:bind ref="info/xforms-version" calculate="property('version')"/> ... </xforms:instance>
Note:
The following XML Schema datatypes do not have specific
functions for manipulation within XForms expressions:
xsd:time
, xsd:gYearMonth
,
xsd:gYear
, xsd:gMonthDay
,
xsd:gDay
, xsd:gMonth
. Extension functions
(7.10 Extension
Functions) may be used to perform needed operations on
these datatypes.
string now()
The now
function returns the current system date
and time as a string value in the canonical XML Schema
xsd:dateTime
format. If time zone information is
available, it is included (normalized to UTC). If no time zone
information is available, an implementation default is used.
Note:
Attaching a calculation of "now()
" to an instance
data node would not result in a stream of continuous recalculations
of the XForms Model.
number days-from-date(string)
This function returns a whole number of days, according to the following rules:
If the string parameter represents a legal lexical
xsd:date
or xsd:dateTime
, the return
value is equal to the number of days difference between the
specified date and 1970-01-01
. Hour, minute, and
second components are ignored. Any other input parameter causes a
return value of NaN
.
Examples:
days-from-date("2002-01-01")
returns11688
days-from-date("1969-12-31")
returns-1
number seconds-from-dateTime(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexical
xsd:dateTime
, the return value is equal to the number
of seconds difference between the specified dateTime and
1970-01-01T00:00:00Z
. If no time zone is specified, an
implementation default is used. Any other input string parameter
causes a return value of NaN
.
number seconds(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexical
xsd:duration
, the return value is equal to the number
specified in the seconds component plus 60 * the number specified
in the minutes component, plus 60 * 60 * the number specified in
the hours component, plus 60 * 60 * 24 * the number specified in
the days component. The sign of the result will match the sign of
the duration. If no time zone is specified, an implementation
default is used. Year and month components, if present, are
ignored. Any other input parameter causes a return value of
NaN
.
Examples:
seconds("P1Y2M")
returns0
seconds("P3DT10H30M1.5S")
returns297001.5
seconds("3")
returnsNaN
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
.
number months(string)
This function returns a whole number of months, according to the following rules:
If the string parameter represents a legal lexical
xsd:duration
, the return value is equal to the number
specified in the months component plus 12 * the number specified in
the years component. The sign of the result will match the sign of
the duration. Day, hour, minute, and second components, if present,
are ignored. Any other input parameter causes a return value of
NaN
.
Examples:
months("P1Y2M")
returns14
months("-P19M")
returns-19
Note:
Even though this function is defined based on a lexical
xsd:duration
, it is intended for use only with
derived-from-xsd:duration
datatypes, specifically
xforms:yearMonthDuration
.
XForms documents may use additional XPath extension functions
beyond those described here. The names of any such extension
functions must be declared in attribute functions
on
element model
. Such declarations are used by the
XForms Processor to check against available extension functions.
XForms Processors perform this check at the time the document is
loaded, and stop processing by signaling an exception (4.5.4 The
xforms-compute-exception Event) if the XForms document
declares an extension function for which the processor does not
have an implementation.
Note:
Explicitly declaring extension functions enables XForms Processors to detect the use of unimplemented extension functions at document load-time, rather than throwing a fatal error during user interaction. Failure by authors to declare extension functions will result in an XForms Processor potentially halting processing during user interaction with a fatal error.
Table of Contents | Top |