XForms
2.0
base
__NUMBEREDHEADINGS__
- Document title :
- XForms 2.0
- Editors
- John M. Boyer, IBM
- Erik Bruchez, Orbeon
- Leigh L. Klotz, Jr., Xerox
- Steven Pemberton, CWI
- Nick Van den Bleeken, Inventive Designers
- a declarative model composed of formulae for data calculations and constraints, data type and other property declarations, and data submission parameters
- a view layer composed of intent-based user interface controls
- an imperative controller for orchestrating data manipulations, interactions between the model and view layers, and data submissions.
Thus, XForms accommodates form component reuse, fosters strong data type validation, eliminates unnecessary round-trips to the server, offers device independence and accessibility, and reduces the need for scripting.
Editorial
note:
What
is
XForms
2.0
|
2012-03-29 |
Update
the
|
XForms
1.0
]
by
adding
several
2.0
adds
a
number
of
new
submission
capabilities,
action
handlers,
utility
features
including
dialogs,
custom
functions,
user
interface
improvements,
and
helpful
datatypes
as
well
as
variables,
a
more
powerful
action
processing
facility,
including
conditional,
iterated
pluggable
expression
language
with
extra
functions
(XPath
2.0),
model-based
switch
and
background
execution,
the
ability
to
manipulate
data
arbitrarily
repeat,
Attribute
Value
Templates,
and
to
access
event
context
information.
consuming
and
submitting
JSON
and
CSV
instance
data.
Copyright © 2010 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
About the XForms Specification
Background
Forms
are
an
important
part
of
the
Web,
and
they
continue
to
be
the
primary
means
for
enabling
interactive
Web
applications.
Web
applications
and
electronic
commerce
solutions
have
sparked
the
demand
for
better
Web
forms
with
richer
interactions.
XForms
is
the
response
to
this
demand,
and
provides
a
new
platform-independent
markup
language
for
online
interaction
between
a
person
(through
an
XForms
Processor
)
and
another,
usually
remote,
agent.
XForms
are
is
the
successor
to
HTML
forms,
and
benefit
from
the
lessons
learned
from
HTML
forms.
Further background information on XForms can be found at http://www.w3.org/MarkUp/Forms .
Reading the Specification
This specification has been written with various types of readers in mind, in particular XForms authors and XForms implementors. We hope the specification will provide authors with the tools they need to write efficient, attractive and accessible documents without overexposing them to the XForms implementation details. Implementors, however, should find all they need to build conforming XForms Processors. The specification begins with a general presentation of XForms before specifying the technical details of the various XForms components.
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 and 2
- An introduction to XForms. The introduction outlines the design principles and includes a brief tutorial on XForms.
- Chapters 3 and up
- XForms reference manual. The bulk of the reference manual consists of the specification of XForms. This reference defines XForms and how XForms Processors must interpret the various components in order to claim conformance.
- Appendixes
- Appendixes contain an XML Schema description of XForms, references, examples, and other useful information.
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 XForms )
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 ])
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 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.
- 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 | 2011-08-31 |
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.
Differences between XForms 2.0 and XForms 1.1
Editorial note: Complete list | 2011-08-31 |
Complete list of differences below |
- Custom functions
- Variable support
- repeat over sequences of atomic values and nodes (doesn't need to be in document order, same node can occur multiple times)
- Pluggable expression language (XPath 2.0 module)
- json, csv and other external instance data formats
- @nodeset is deprecated in favour of @ref
- p3ptype is deprecated
- repeat @indexref
- Multiple MIPs of the same property allowed on one node.
- @iterate
- model-based switch : @caseref
- Attribute Value Template support
- script action
- property child of dispatch element
- dialog
- support for typed values in XPath 2 expressions
- @label, @hint, @help, @alert
- @appearance on <alert> (erratum)
Introduction to XForms
XForms was originally designed for handling forms on the web. Forms helped to kick off the web as an interactive medium and for e-commerce, with tasks such as searching, shopping, reading and writing email, editing documents online, configuring hardware, and banking.
XForms
has
been
designed
on
to
improve
the
basis
form-filling
experience,
and
make
production
and
management
of
several
years'
experience
with
HTML
forms.
HTML
forms
have
formed
the
backbone
easier.
Issues
addressed
included
authoring,
reuse,
internationalization,
accessibility,
usability,
data
structuring,
client-side
checking,
device
independence,
support
of
the
e-commerce
revolution,
common
use
cases
and
having
shown
their
worth,
have
also
indicated
numerous
ways
they
could
be
improved.
reduced
reliance
on
scripting.
The
primary
difference
when
comparing
XForms
with
HTML
forms,
apart
from
Properties
of
XForms
being
in
XML,
include:
-
Data
is
the separation of the data being collectedseparated from the markup of thecontrols collecting the individual values. By doing this, itcontrols. This not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since theunderlyingessential part of aFormform is no longer irretrievably bound to the page it is used in.A second major difference is that XForms, while designed to be integrated into XHTML, is no longer restricted only -
Controls
say
what
they
do,
not
how
they
look.
This
gives
the
designer
more
control,
makes
it
easier
to
be a part of that language, but may be integrated into any suitable markup language. XForms has strivendeploy forms toimprove authoring, reuse, internationalization, accessibility, usability,multiple devices, anddevice independence. Here is a summary of the primary benefits of using XForms:aids accessibility. -
Strong typing Submitted data is strongly typed andData can be checkedusing off-the-shelf tools.client-side . This speeds up form filling since it reduces the need for round trips to the server forvalidation. XML submission This obviates the need for customvalidation, and eases server-sidelogicprocessing, since the server does not have tomarshalconstruct new forms with thesubmittederror messages. -
Structured,
typed
data
is
supported
.
This
allows
forms
to
fit
in
existing
data
pipelines
without
the
application back-end. The received XML instance document candata having to bedirectly validated and processed bytransformed first. Although XML is theapplication back-end. Existing schema re-use This obviates duplication,principal format for this, formats like JSON andensures that updating the validation rules as a resultCSV are also supported. -
Declarative
specification
is
used
.
The
details
of
a
change in the underlying business logic does not require re-authoring validation constraints within the XForms application. External schema augmentation This enables the XForms authorform, including calculation, are defined using declarative markup, rather than scripting, making forms smaller, more tractable (through static analysis), and easier togo beyondproduce. Experience has shown that this significantly reduces production times and costs. -
Calculations
are
done
spreadsheet-style
.
So
you
never
have
to
worry
about,
for
instance,
the
basic settotal price ofconstraints available fromgoods being out-of-date, and theback-end. Providing such additional constraintsuser doesn't have to press a 'recalculate' button. -
Data
and
markup
are
fully
integrated
.
For
instance,
as
part oftheXForms Model enhances the overall usability ofuser enters an address it can be displayed in its final form on theresulting Web application. Internationalization Using XML 1.0 for instancepage itself; dataensures thatimported from an external source can be easily displayed; and as thesubmitteddata changes it isinternationalization ready. Enhanced accessibility XForms separates content and presentation. User interface controls encapsulate all relevant metadata such as labels, thereby enhancing accessibility ofupdated on theapplication when usingpage. It also means that it is easy to produce an internationalized version of a form, by importing labels in differentmodalities. XForms user interface controls are generic and suited for device-independence. Multiple device supportlanguages.
The
high-level
nature
original
version
of
the
user
interface
controls,
XForms
was
purely
about
forms,
and
the
consequent
intent-based
authoring
of
the
user
interface
makes
followed
HTML
fairly
strictly
in
what
it
possible
to
re-target
the
user
interaction
to
different
devices.
Less
use
could
do
in
many
cases.
However,
because
of
scripting
By
defining
XML-based
declarative
event
handlers
XForms'
generality,
it
was
quickly
realised
that
cover
common
use
cases,
the
majority
it
was
capable
of
far
more
than
only
forms
if
certain
parts
were
further
generalised.
And
so
was
born
XForms
documents
can
1.1,that
allowed
not
only
forms
to
be
statically
analyzed,
reducing
the
need
for
imperative
scripts
for
event
handlers.
created,
but
certain
types
of
applications
as
well
that
you
would
not
normally
consider
as
being
a
form.
XForms
2.0
continues
this
process
of
generalization.
An Example
In
the
A
form
in
XForms
approach,
forms
are
comprised
of
has
a
section
that
describes
what
the
form
does,
data
being
manipulated,
called
the
XForms
Model
,
which
includes
the
data,
types,
constraints,
and
relationships
with
other
data
values,
and
another
section
that
describes
how
the
form
data
is
to
be
presented.
manipulated.
Consider
a
simple
electronic
commerce
form
that
might
be
rendered
as
follows:
like
this:
It
is
clear
that
we
are
collecting
a
value
that
represents
whether
cash
or
a
credit
card
is
asking
for
the
method
of
payment
being
used,
and
if
a
credit
card,
its
number
and
expiration
date.
This
can
be
represented
in
the
XForms
element,
which
in
XHTML
would
model
<model>
typically
be
contained
within
the
head
<head>
section:
element:
<model><instance> <ecommerce xmlns=""> <method/> <number/> <expiry/> </ecommerce> </instance> <submission action="" method="post" id="submit" includenamespaceprefixes=""/><instance> <payment xmlns=""> <amount/> <method/> <number/> <expiry/> </payment> </instance> <submission action="https://example.com/submit" method="post"/> </model>
This
simply
says
that
we
are
collecting
three
four
pieces
of
information
(note
that
we
have
as
yet
not
said
anything
about
their
types),
and
that
they
will
be
submitted
using
the
URL
in
the
action
attribute.
XForms
defines
a
device-neutral,
platform-independent
device-neutral
set
of
form
controls
suitable
for
general-purpose
use.
The
controls
are
bound
to
the
XForms
Model
via
data
in
the
XForms
binding
mechanism,
in
this
simple
case
model
using
the
ref
attribute
on
the
controls.
In
XHTML,
this
This
markup
would
typically
appear
within
the
body
<body>
section
(note
that
we
have
intentionally
defaulted
the
XForms
namespace
prefix
here):
of
an
XHTML
document:
Please pay: <output ref="amount"/> <select1 ref="method" label="Payment Method"> <item label="Cash" value="cash"/> <item label="Credit" value="cc"/> </select1><input ref="number"> <label>Credit Card Number:</label> </input> <input ref="expiry"> <label>Expiration Date:</label> </input> <submit submission="submit"> <label>Submit</label> </submit><input ref="number" label="Card Number"/> <input ref="expiry" label="Expiration Date"/> <submit label="Submit"/>
Notice
the
following
features
of
this
design:
There
are
some
things
worth
noting
here:
-
The
user
interface
is
not
hard-coded
to
use
radio
buttons.buttons, or any other style of input. Different devices (such as voice browsers) can render the concept of "select one" asappropriate.appropriate, small-screen devices can use drop-down menus, while larger-screen devices can use radio buttons. -
Core formForm controls always have labels directly associated with them as child elements —this isakeyfeature designed to enhance accessibility.There is no need for an enclosing form element, as in HTML. (See Multiple Forms per Document for details on how to author multiple forms per document) Markup for specifying form controls has been simplified in comparison with HTML forms.
The
fact
that
you
can
bind
form
controls
to
the
model
like
this
simplifies
integrating
XForms
into
other
host
languages
,
,
since
any
form
control
markup
may
be
used
to
bind
to
the
model.
Providing
XML
Instance
Submitted
Data
The
XForms
Processor
can
directly
submit
the
data
collected
as
XML.
XML
instance
data.
In
the
example,
the
submitted
data
would
might
look
like
this:
<payment> <amount>99.00</amount> <method>cc</method> <number>1235467789012345</number> <expiry>2017-08</expiry> </payment>
but it is also possible to submit data in URL-encoded style, such as
https://example.com/submit?amount=99.00&method=cc&number=1235467789012345&expiry=2017-08
This
is
done
by
changing
the
method
attribute
on
the
submission
element
to
<submission action="https://example.com/submit" method="get"/>
Instance Data
XForms
processing
keeps
track
of
the
state
of
the
partially
filled
form
through
this
instance
data
.
Initial
values
for
the
instance
data;
this
data
may
can
be
provided
or
left
initially
empty
as
in
the
example.
Element
instance
essentially
holds
a
skeleton
XML
document
example
above,
or
may
be
(partially)
initialized
with
values,
for
instance:
<instance> <payment xmlns=""> <amount>99.99</amount> <method>cc</method> <number/> <expiry/> </payment> </instance>
Data
may
be
also
initialised
from
external
sources.
For
instance,
for
forms
that
gets
updated
as
the
user
fills
out
the
form.
It
gives
the
author
full
include
a
control
on
the
structure
of
the
submitted
XML
data,
including
namespace
information.
When
the
form
is
submitted,
to
fill
in
a
country,
the
instance
data
is
serialized
as
an
XML
document.
Here
is
an
alternative
version
for
the
countries
of
the
earlier
example:
world
can
be
obtained
from
an
external
resource:
<instance id="c" src="countries.xml"/>
In
this
case
If
the
submitted
countries
data
would
look
looks
like
this:
<countries xml:lang="en"> <country code="AF">Afghanistan</country> <country code="AX">Åland Islands</country> <country code="AL">Albania</country> <country code="DZ">Algeria</country> <country code="AS">American Samoa</country> ...
This
design
has
features
worth
calling
out:
There
is
complete
flexibility
in
the
structure
of
the
XML
instance
data,
including
the
use
of
attributes.
Notice
that
XML
namespaces
are
used,
and
that
then
a
wrapper
element
of
the
author's
choosing
contains
the
instance
data.
Empty
elements
number
and
expiry
serve
as
place-holders
in
the
XML
structure,
and
will
be
filled
in
with
form
data
provided
by
the
user.
An
initial
value
(
suitable
"cc"
select1
)
for
the
form
control
is
provided
through
the
instance
data,
in
this
case
an
attribute
method
.
In
the
submitted
XML,
this
initial
value
will
be
replaced
by
the
user
input,
if
the
user
changes
the
form
control
displaying
that
data.
To
connect
could
use
this
instance
data
with
form
controls,
the
ref
attributes
on
the
form
controls
need
to
be
changed
to
point
to
the
proper
part
of
the
instance
data,
using
binding
expressions
:
as
follows:
<select1 ref="land"> <label>Country</label> <itemset ref="instance('c')/country"> <label ref="."/> <value ref="@code"/> </itemset> </select1>
This means that the country data is no longer hard-wired into forms, but can be sourced from a single file for the whole site, and is easily updated when necessary.
Binding
expressions
are
based
on
XPath
in
XForms
use
[
XPath
1.0
],
including
the
use
of
the
@
character
to
refer
to
attributes,
as
seen
here.
Note
that
for
illustrative
purposes,
Calculating Values
XForms
allows
values
to
be
calculated
dynamically
from
the
first
two
expressions
make
use
of
values
in
the
XPath
context
node,
which
defaults
model
as
they
change.
For
instance,
if
we
add
to
the
top-level
element
(here
my:payment
).
The
third
expression
shows
example
above
two
values
for
the
unit
price
of
an
absolute
path.
item,
and
how
many
are
being
ordered:
<payment xmlns=""> <unitprice>99.99</unitprice> <howmany/> <amount/> <method/> <number/> <expiry/> </payment>
then we can add a calculation to calculate the total amount from these two:
<bind ref="amount" calculate="../unitprice * ../howmany" />
Whenever either of those two values is changed, the total amount is automatically updated.
Constraining Values
XForms
allows
data
to
be
checked
for
validity
as
the
form
is
being
filled.
In
the
absence
of
specific
information
about
the
types
of
values
being
collected,
all
values
are
returned
as
strings,
but
it
is
possible
to
assign
types
to
values
in
the
instance.
For
instance
data.
In
this
in
the
example,
number
should
accept
digits
only,
there
are
datatypes
that
represents
an
integer,
and
should
have
a
decimal
type
for
representing
monetary
values:
<bind ref="howmany" type="integer"/> <bind ref="amount" type="decimal"/>
but
there
is
also
a
data
type
that
represents
a
credit
card,
accepting
between
14
and
18
digits
digits:
<bind ref="number" type="card-number"/>
It is possible to add dynamic constraints to a value. For instance, if you want to restrict how many items are bought:
<bind ref="howmany" constraint=". lt 10" />
which would prevent more than 9 items being ordered. There is also a function for checking that a credit card number is valid:
<bind ref="number" constraint="is-card-number(.)"/>
The
data
cannot
be
submitted
until
all
constraints
are
met,
and
expiry
input
controls
bound
to
data
not
matching
their
constraints
are
typically
marked
specially
(how
they
are
marked
is
controllable
by
stylesheets).
You
can
also
include
a
message
to
be
displayed
should
accept
only
valid
month/date
combinations.
the
constraints
not
be
met:
<input ref="howmany"> <label>Number</label> <alert>Must be a whole number less than 10</alert> </input>
Relevance and Required Values
Furthermore,
In
the
credit
card
information
form
example,
the
input
controls
for
number
and
expiry
are
only
relevant
if
the
"cc"
credit
card
option
is
chosen
for
method
,
but
are
required
in
that
case.
By
specifying
an
additional
component,
model
item
properties
,
authors
can
include
rich
declarative
validation
information
in
forms.
Such
information
can
be
taken
from
XML
Schemas
as
well
as
XForms-specific
additions,
such
as
relevant
.
Such
properties
appear
on
bind
elements,
while
Schema
constraints
are
This
is
expressed
in
an
XML
Schema
fragment,
either
inline
or
external.
For
example:
as
follows:
<bind ref="number" type="card-number" relevant="../method='cc'" required="true()"/> <bind ref="expiry" relevant="../method='cc'" required="true()"/>
XForms processors have the option of graying out controls bound to non-relevant values, or of making them non-visible.
Putting it all together, the model would look like this:
<model> <instance> <payment xmlns=""> <unitprice>99.99</unitprice> <howmany/> <amount/> <method/> <number/> <expiry/> </payment> </instance> <bind ref="howmany" type="integer" constraint=". lt 10"/> <bind ref="amount" type="decimal" calculate="../unitprice * ../howmany" /> <bind ref="number" type="card-number" relevant="../method='cc'" required="true()" constraint="is-card-number(.)"/> <bind ref="expiry" relevant="../method='cc'" required="true()"/> <submission action="https://example.com/submit" method="post"/> </model>
Note:
Attribute
Values
In
XForms
has
the
above
example,
ability
to
output
values
into
the
presentation
of
a
form
using
the
relevant
output
expression
uses
absolute
XPath
notation
(beginning
element,
but
a
new
feature
of
XForms
2.0
is
the
ability
to
output
into
attributes
as
well,
with
/
)
because
a
feature
known
as
attribute
value
templates
(AVTs).
For instance, with
<output class="{if (total ge 0) then 'positive' else 'negative'}" ref="total"/>
the
evaluation
context
nodes
CSS
style
sheet
can
then
have
two
rules,
one
for
computed
expressions
are
determined
by
the
binding
expression
(see
Evaluation
Context
),
and
so
any
relative
node
path
in
the
first
bind
class
,
and
one
for
relevant
above
would
be
relative
to
positive
,
for
instance
coloring
the
output
red
if
it
is
negative:
/my:payment/my:number
negative
.positive {color: black} .negative {color: red}
All attributes support AVTs, with the exception of attributes that are already XPath expressions, and a small number of structural attributes. These are marked in the descriptions of the attributes.
Multiple Forms per Document
XForms
processing
places
no
limits
on
the
number
of
individual
forms
that
can
be
placed
in
a
single
containing
document
.
When
a
single
document
contains
multiple
forms,
each
form
needs
a
separate
model
element,
each
with
element.
The
first
model
element
may
omit
a
unique
id
attribute
(as
have
all
the
examples
above),
but
subsequent
model
elements
require
an
id
attribute
so
that
they
can
be
referenced
from
elsewhere
in
the
containing
document.
elsewhere.
In
addition,
form
controls
should
need
to
specify
which
model
element
contains
the
instance
data
to
which
they
bind.
This
is
accomplished
through
a
model
attribute
that
is
part
of
alongside
the
binding
attributes.
If
no
model
ref
attribute
is
specified
on
the
binding
element,
attribute.
The
default
for
the
nearest
ancestor
binding
element's
model
attribute
is
used,
and
failing
that,
the
first
XForms
Model
model
element
in
document
order
is
used.
This
technique
is
called
'scoped
resolution',
and
is
used
frequently
in
XForms.
order.
The
next
example
adds
an
opinion
poll
to
our
electronic
commerce
the
form.
<model><instance> ...payment instance data... </instance> <submission action="" method="post"/><instance> ...payment instance data... </instance> <submission action="https://example.com/submit" method="post"/> </model><model id="poll"> <instance> <helpful xmlns=""/> </instance> <submission id="pollsubmit" .../>
<model id="poll"> <instance> <data xmlns=""> <helpful/> </data> </instance> <submission id="pollsubmit" action="..."/> </model>
Additionally, the following markup would appear in the body section of the document:
<select1 ref="helpful" model="poll"> <label>How useful is this page to you?</label> <item> <label>Not at all helpful</label> <value>0</value> </item> <item> <label>Barely helpful</label> <value>1</value> </item> <item> <label>Somewhat helpful</label> <value>2</value> </item> <item> <label>Very helpful</label> <value>3</value> </item> </select1><submit submission="pollsubmit"> <label>Submit</label>
<submit submission="pollsubmit"> <label>Submit</label> </submit>
The
main
difference
here
is
the
use
of
model="poll"
,
which
identifies
the
instance.
Note
that
submit
refers
to
the
submission
element
by
ID
and
does
not
require
binding
attributes.
More
XForms
examples
can
be
found
in
Complete
XForms
Examples
.
Document Structure
XForms is an application of XML [ XML 1.0 ] and has been designed for use within other XML vocabularies, in particular within versions of XHTML [ XHTML 1.0 ]. XForms always requires such a host language . This chapter discusses the structure of XForms that allow XForms to be used with other document types.
Namespace for XForms
The
namespace
URI
for
XForms
is
http://www.w3.org/2002/xforms
.
The
XForms
schema
has
the
target
namespace
specified
and
as
such
is
compatible
with
the
XForms
1.0
definition.
<switch xmlns="http://www.w3.org/2002/xforms"> <case id="in" selected="true"> <input ref="yourname"> <label>Please tell me your name</label> <toggle ev:event="DOMActivate" case="out"/> </input> </case> <case id="out" selected="false"> <html:p>Hello <output ref="yourname" /> <trigger id="editButton"> <label>Edit</label> <toggle ev:event="DOMActivate" case="in"/> </trigger> </html:p> </case> </switch>
(the
prefixes
html
and
ev
are
defined
by
an
ancestor
of
the
switch
element).
The XForms Core Module
The XForms Core Module defines the major structural elements of XForms, intended for inclusion in a containing document. The elements and attributes included in this module are:
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
functions
|
| |
Common
,
src
|
(ANY) | |
Common
,
Model
Item
Properties
,
ref
(
model-binding-expression
),
nodeset
(
model-binding-expression
|
(bind)* | |
function | Common , signature[doesn't support AVT], override? | (var*, result)? |
result | Common , value | EMPTY |
var | Common , name (QName), value (expression) | EMPTY |
submission |
|
( resource [deprecated] | method [deprecated] | header )*, Action * |
Elements
defined
in
the
XForms
Actions
module,
when
that
module
is
included,
are
also
allowed
in
the
content
model
of
model
and
submission
,
as
shown
above.
Within the containing document, these structural elements are typically not rendered.
The XForms Processor must ignore any foreign-namespaced attributes that are unrecognized.
Note that the presence of foreign namespaced elements is subject to the definition of the containing or compound document profile.
The model Element
This
element
represents
a
form
definition
and
is
used
as
a
container
for
elements
that
define
the
XForms
Model.
definition
of
the
data
to
be
used
in
a
form.
No
restriction
is
placed
on
how
many
model
elements
may
exist
within
a
containing
document.
Common Attributes: Common
Special Attributes:
- functions
- Author-optional space-separated list of extension functions (represented by QNames) required by this XForms Model. Guidance on the use of this attribute is at Extension Functions .
- schema
-
Author-optional
list
of
xsd:anyURI
links to XML Schema documents outside thismodel
element. The XForms Processor must process all XML Schemas listed in this attribute. Within each XForms Model, there is a limit of one XML Schema per namespace declaration, including inline and linked XML Schemas.
schema
list
may
include
URI
fragments
referring
to
elements
located
outside
the
current
model
elsewhere
in
the
containing
document;
e.g.
"#myschema"
.
xs:schema
elements
located
inside
the
current
model
need
not
be
listed.
- version
-
Author-optional
attribute
with
a
default
value
of
empty
string
and
legal
values
defined
by
the
datatype
xforms:versionList
.
Examples
are
"1.0"
,"1.1"
and"1.0"1.1 2.0"model
, then an XForms Processor must support at least one of the listed language versions of XForms. Otherwise, the XForms Processormust terminate processing after dispatchingdispatches the eventxforms-version-exceptionxforms-version-error to the defaultmodel
. If the XForms Processor supports more than one language version indicated by the version setting on the defaultmodel
or if the version setting on the defaultmodel
is empty string (whether specified or by default), then the XForms Processor may execute the XForms content using any language conformance level available to it. If any non-defaultmodel
has a version setting that is incompatible with the language version selected by the XFormsProcessor ,Processor, then the XForms Processormust terminate processing after dispatchingdispatches the eventxforms-version-exceptionxforms-version-error to the defaultmodel
.
model
,
with
the
XForms
namespace
defaulted:
<model id="Person" schema="MySchema.xsd"><instance resource="" /><instance resource="https://example.com/cgi-bin/get-instance" /> ... </model>
<model><message level="modal" ev:event="xforms-version-exception"> <output value="event('errorinformation')"/><message level="modal" ev:event="xforms-version-error"> <output value="event('error-message')"/> </message> ... </model> ... <model id="m2" version="2.0"> ... </model>
Since
the
version
attribute
is
not
specified
on
the
model
,
the
XForms
Processor
may
choose
any
language
conformance
level,
which
may
be
incompatible
with
the
version
setting
of
the
second
model
.
Therefore,
the
message
action
occurs
during
initialization
of
the
second
model
due
to
its
version
incompatibility
with
the
default
model
.
<model version="1.0 2.0"> ... </model> ... <model id="m2"> ... </model>
Since
the
version
attribute
is
not
specified
on
the
second
model
,
it
is
compatible
with
any
choice
made
based
on
the
version
setting
on
the
default
model.
The instance Element
This author-optional element contains or references initial instance data.
Common Attributes: Common
Special Attributes:
- src
-
Author-optional
link
to
externally
defined
initial
instance
data.
If
the
link
traversal
fails,
it is treated asanexception (Thexforms-link-exceptionEvent).is dispatched. - resource
-
Author-optional
link
to
externally
defined
initial
instance
data.
If
the
link
is traversed and thetraversal fails,it is treated asanexception (Thexforms-link-exceptionEvent).is dispatched.
If
the
src
attribute
is
given,
then
it
takes
precedence
over
inline
content
and
the
resource
attribute,
and
the
XML
data
for
the
instance
is
obtained
from
the
link.
If
the
src
attribute
is
omitted,
then
the
data
for
the
instance
is
obtained
from
inline
content
if
it
is
given
or
the
resource
attribute
otherwise.
If
both
the
resource
attribute
and
inline
content
are
provided,
the
inline
content
takes
precedence.
Note
that
the
only
difference
between
the
src
and
resource
attributes
is
the
precedence
over
inline
content,
which
is
principally
of
use
in
automatically-generated
forms.
If
the
initial
instance
data
is
given
by
a
link
(from
inline
content,
then
instance
data
is
obtained
as
follows:
-
A
detached
copy
of
the
first
child
element
of
the
srcinstance - If needed, namespace nodes are copied to that detached root element as described below.
Namespace
nodes
for
prefixes
which
are
in
use
by
elements
or
attributes
which
are
descendants
of
the
enclosing
resource
instance
),
then
element
are
copied
to
the
new
root
element.
A prefix is considered to be in use if:
-
it
is
a
prefix
of
a
element
or
attribute
which
is
a
descendant
of
the
instance
elementdata -
and
at
least
one
use
of
that
prefix
is
formednot shadowed bycreatinga nested namespace declaration.
Note:
Previous versions of this specification stated that all "namespaces inherited from the enveloping ancestors" had to be copied to the detached copy of the inline content. The current specification changes this behavior.
The
resulting
XML
document
is
converted
to
an
XPath
data
model
of
associated
with
the
linked
resource.
source
instance
element.
<xh:html xmlns:xh="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms" xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <xh:head> <xf:model> <xf:instance> <form> <first-name/> </form> </xf:instance> </xf:model> </xh:head> </xh:html>
<form> <first-name/> </form>
<xh:html xmlns:xh="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms" xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <xh:head> <xf:model> <xf:instance> <form> <foo:first-name/> <last-name bar:baz=""/> </form> </xf:instance> </xf:model> </xh:head> </xh:html>
<form xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <foo:first-name/> <last-name bar:baz=""/> </form>
<xh:html xmlns:xh="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms" xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <xh:head> <xf:model> <xf:instance> <form> <foo:bar xmlns:foo="http://dummy.org/foo"/> </form> </xf:instance> </xf:model> </xh:head> </xh:html>
<form> <foo:bar xmlns:foo="http://dummy.org/foo"/> </form>
<xh:html xmlns:xh="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms" xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <xh:head> <xf:model> <xf:instance> <form xmlns:baz="http://example.org/baz"> <expression value="foo:a/bar:b/baz:c"/> </form> </xf:instance> </xf:model> </xh:head> </xh:html>
<form xmlns:baz="http://example.org/baz"> <expression value="foo:a/bar:b/baz:c"/> </form>
<xh:html xmlns:xh="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms" xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar"> <xh:head> <xf:model> <xf:instance> <form xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar" xmlns:baz="http://example.org/baz"> <expression value="foo:a/bar:b/baz:c"/> </form> </xf:instance> </xf:model> </xh:head> </xh:html>
<form xmlns:foo="http://example.org/foo" xmlns:bar="http://example.org/bar" xmlns:baz="http://example.org/baz"> <expression value="foo:a/bar:b/baz:c"/> </form>
If
the
initial
instance
data
is
given
by
a
link
(from
src
or
resource
),
and
the
link
cannot
be
traversed,
then
processing
halts
after
dispatching
an
xforms-link-exception
with
a
resource-uri
of
the
link
that
failed.
If
Otherwise
the
initial
instance
data
is
given
by
inline
content,
then
instance
data
is
obtained
formed
by
first
creating
a
detached
copy
of
the
inline
content
(including
namespaces
inherited
from
the
enveloping
ancestors),
then
creating
an
XPath
data
model
over
the
detached
copy.
The
detached
copy
must
consist
of
content
that
would
be
well-formed
XML
if
it
existed
in
a
separate
document.
Note
that
this
restricts
the
element
content
of
linked
resource
as
described
below
under
Creating
instance
to
a
single
child
element.
data
from
external
resources
.
If
creation
of
the
XPath
data
model
for
the
instance
data
fails
due
to
an
XML
error,
fails,
then
processing
halts
after
dispatching
an
xforms-link-exception
with
a
resource-uri
indicating
either
the
URI
for
an
external
instance,
a
fragment
identifier
URI
reference
(including
the
leading
#
mark)
for
an
identified
internal
instance,
or
empty
string
for
an
unidentified
internal
instance.
This
exception
could
happen,
for
example,
if
the
content
had
no
top-level
element
or
more
than
one
top-level
element,
neither
of
which
is
permitted
by
the
grammar
of
XML.
Note:
All data relevant to the XPath data model must be preserved during processing and as input to submission serialization, including processing instructions, comment nodes and all whitespace.
<instance resource="https://example.org/templates/a1.xml" />
<instance> <data xmlns=""> <height>1024</height><width>1920</width> </data> </instance>
Creating instance data from external resources
Although inline instance values are created from XML markup, there is no requirement that external sources be XML, just that they be converted to an XPath Data Model [ XDM ] internally.
If the external resource is an XML format (i.e. with a content type matching any of the specifiers in [ RFC 3023 ]), then an XPath data model is created as defined in [ XDM ].
If the external resource is not an XML format, it should be parsed as if a one-to-one mapping had been applied to the original to produce an equivalent XML document which is then used to produce the XPath Data Model. The one-to-one mapping is defined per format. Two examples are given below, but implementors are encouraged to add others, and report on their experiences.
A requirement on such a mapping is that it should only require simple and obvious XPath expressions to access the data. It is not necessary to be able to map all possible XML onto the external data type, but it is required to be able to map all possible values of the external data to XML, and then back again.
The conversion of external data to an XPath data model is used both for initializing instances, and for processing the data returned by submissions .
For
every
media
type
accepted
for
external
sources
by
the
processor,
the
processor
must
provide
an
equivalent
serialization
using
the
serialization
attribute
of
the
submission
element
.
Note:
External
JSON
values
When
an
XForms
authors
who
need
additional
control
over
Processor
receives
a
JSON
value
[
JSON
],
it
treats
it
as
follows:
-
A
root
element
<json/>
is created whose content is theserializationtransformation ofnamespace nodes can usethe JSON value. -
An
object
is
transformed
by
adding
an
attribute
includenamespaceprefixesobject="true"-
Each
name/value
member
is
encoded
as
an
XML
element
whose
name
is
the
name
of
the
member,
and
whose
content
is
the
transformation
of
the
value
part
of
the
member.
If
any
character
of
the
element
name
is
not
an
allowable
XML
name
character,
or
is
":",
the
character
is
replaced
with
an
underscore
"_";
if
the
first
character
of
the
element
name
is
not
an
allowable
XML
name
start
character,
or
is
":",
then
an
underscore
"_"
is
prepended
to
the
name.
In
either
case,
an
attribute
onname
is added to the element, with the value of the original name of the element. -
If
the
value
part
is
an
array,
then
each
value
in
the
array
is
so
treated,
and
each
such
element
is
given
an
attribute
submissionarray="true"
-
Each
name/value
member
is
encoded
as
an
XML
element
whose
name
is
the
name
of
the
member,
and
whose
content
is
the
transformation
of
the
value
part
of
the
member.
If
any
character
of
the
element
name
is
not
an
allowable
XML
name
character,
or
is
":",
the
character
is
replaced
with
an
underscore
"_";
if
the
first
character
of
the
element
name
is
not
an
allowable
XML
name
start
character,
or
is
":",
then
an
underscore
"_"
is
prepended
to
the
name.
In
either
case,
an
attribute
-
If
a
value
is
an
(anonymous)
array
(either
being
the
top-level
value,
or
itself
an
element
of
an
array),
then
each
element
of
the
transformed
array
is
given
the
name
"_"
and an attributename=""
is added to the element. -
The
content
of
a
string
is
copied
across,
and
an
attribute
type="string"
is added to its containing element. Escaped characters are transformed as necessary; characters and escapes that have no equivalent XML character (\b, \f, and characters of the form \uxxxx less than \u0020) are transformed by adding \uE000 to them. -
A
number
is
copied
across,
and
an
attribute
type="number"
is added to its containing element. -
true
and
false
are
copied
across,
and
an
attribute
type="boolean"
is added to its containing element. -
null
produces
empty
content,
and
an
attribute
type="null"
is added to its containing element.
This
format
can
be
serialized
back
to
JSON
with
a
submission
element
with
a
serialization
attribute
value
of
"application/json".
Elements
not
in
the
default
namespace
and
unknown
attributes
are
ignored
when
serialising
to
JSON.
JSON | Transformation |
---|---|
{"given": "Mark", "family": "Smith"} | <json object="true"><given type="string">Mark</given><family type="string">Smith</family></json> |
{"name": "Mark", "age": 21} | <json object="true"><name type="string">Mark</name><age type="number">21</age></json> |
{"selected": true} | <json object="true"><selected type="boolean">true</selected></json> |
{"cities": ["Amsterdam", "Paris", "London"]} | <json object="true"> <cities array="true" type="string">Amsterdam</cities> <cities array="true" type="string">Paris</cities> <cities array="true" type="string">London</cities> </json> |
{"load": [0.31, 0.33, 0.32]} | <json object="true"> <load array="true" type="number">0.31</load> <load array="true" type="number">0.33</load> <load array="true" type="number">0.32</load> </json> |
{"father": {"given": "Mark", "family": "Smith"}, "mother": {"given": "Mary", "family": "Smith"}} | <json object="true"> <father><given type="string">Mark</given><family type="string">Smith</family></father> <mother><given type="string">Mary</given><family type="string">Smith</family></mother> </json> |
{"p": null} |
<json
object="true">
</json> |
{"p": ""} |
<json
object="true">
</json> |
{"p": []} |
<json
object="true">
</json> |
{"p": {}} |
<json
object="true">
</json> |
{"$v": 0} | <json object="true"><_v name="$v" type="number">0</_v></json> |
{"1": "one"} | <json object="true"><_1 name="1" type="string">one</_1></json> |
3 | <json type="number">3</json> |
"Disconnected" | <json type="string">Disconnected</json> |
["red", "green", "blue"] | <json> <_ name="" array="true" type="string">red</_> <_ name="" array="true" type="string">green</_> <_ name="" array="true" type="string">blue</_> </json> |
{g: [["a", "b", "c"], ["d", "e"]] | <json object="true"> <g array="true"> <_ name="" array="true" type="string">a</_> <_ name="" array="true" type="string">b</_> <_ name="" array="true" type="string">c</_> </g> <g array="true"> <_ name="" array="true" type="string">d</_> <_ name="" array="true" type="string">e</_> </g> </json> |
{} | <json object="true"/> |
[] | <json array="true"/> |
"" | <json type="string"/> |
Note
that
the
mapping
is
designed
to
be
round-trippable,
to
allow
as
natural
as
possible
selectors,
and
to
easily
support
structural
additions
and
deletions;
the
type
attributes
are
only
necessary
to
distinguish
ambiguous
representations
on
serialization,
and
have
no
further
effect
on
processing.
<repeat ref="cities">... <input ref="father/given">... <output ref="cities[1]"/> <output ref="g[1]/_[1]"/>
External CSV values
When an XForms Processor receives a CSV value [ CSV ], it treats it as follows:
-
A
root
element
<csv/>
is created whose content is the transformation of the CSV value. -
If
the
first
row
of
the
external
resource,value contains labels (marked by theheader
parameter of the media type), then that row appears in the transformed content, enclosed by an<h>
element. Each value of the headers row is enclosed by an element: if the value consists only XML name characters, that is the name of the element, otherwise non-matching characters are replaced by the underscore character "_"; if the first character may not start an XML name, an underscore is prepended. -
Each
(subsequent)
row
is
enclosed
in
an
<r>
element. - If the first row of the external value contained labels, then each value of subsequent rows is surrounded by an element consisting of the transformed name from the respective header as defined above.
-
If
the
first
row
of
the
CSV
value
did
not
contain
headers,
then
each
value
is
surrounded
by
a
<v>
element.
This
format
can
be
serialized
back
to
CSV
with
a
submission
element
with
a
serialization
attribute
value
of
"text/csv",
with
optional
charset
and
one
initialized
inline:
header
parameters
[
CSV
].
When
no
header
parameter
is
supplied,
it
has
the
same
effect
as
header=absent
.
CSV | Transformation |
---|---|
Year, Result 2011, 143 2012, 457 |
<csv> <r><Year>2011</Year><Result>143</Result></r> <r><Year>2012</Year><Result>457</Result></r> </csv> |
2011, "Jan, Mar" 2012, "Feb, Apr" | <csv> <r><v>2011</v><v>Jan, Mar</v></r> <r><v>2012</v><v>Feb, Apr</v></r> </csv> |
Name, Hex value Red, #f00 Green, #0f0 Blue, #00f | <csv> <h><Name>Name</Name><Hex_value>Hex value</Hex_value></h> <r><Name>Red</Name><Hex_value>#f00</Hex_value></r> <r><Name>Green</Name><Hex_value>#0f0</Hex_value></r> <r><Name>Blue</Name><Hex_value>#00f</Hex_value></r> </csv> |
<repeat ref="r"><output ref="Name"/></repeat> <output ref="r[1]/Year"/> <input ref="r[1]/v[3]">... <output ref="r[2]/Hex_value"/>
Other External values
No other types of external values are normative defined in this specification; however implementors are encouraged to accept other types of values, and report on experiences for possible future inclusion. Transformations should be chosen to make selectors as natural as possible. As an example, a VCARD:
BEGIN:VCALENDAR METHOD:PUBLISH PRODID:-//Example/ExampleCalendarClient//EN VERSION:2.0 BEGIN:VEVENT ORGANIZER:mailto:a@example.com DTSTART:19970701T200000Z DTSTAMP:19970611T190000Z SUMMARY:ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES UID:0981234-1234234-23@example.com END:VEVENT END:VCALENDAR
could be transformed to
<VCALENDAR> <METHOD>PUBLISH</METHOD> <PRODID>-//Example/ExampleCalendarClient//EN</PRODID> <VERSION>2.0</VERSION> <VEVENT> <ORGANIZER>mailto:a@example.com</ORGANIZER> <DTSTART>19970701T200000Z</DTSTART> <DTSTAMP>19970611T190000Z</DTSTAMP> <SUMMARY>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</SUMMARY> <UID>0981234-1234234-23@example.com</UID> </VEVENT> </VCALENDAR>
The bind Element
Element
bind
selects
a
node-set
sequence
of
items
consisting
of
nodes
from
the
instance
data
and
atomic
values
(such
as
an
integer,
date,
or
string)
with
either
a
model
binding
expression
in
the
attribute
or
the
default
of
the
in-scope
evaluation
context
nodeset
ref
node.
item.
Other
attributes
on
element
bind
encode
model
item
properties
to
be
applied
to
each
node
in
the
node-set.
sequence.
When
bind
has
an
attribute
of
type
xsd:ID
,
the
bind
then
associates
that
identifier
with
the
selected
node-set.
sequence.
Common Attributes: Common , Model Item Properties (author-optional)
If
the
model
attribute
is
expressed
in
a
bind
element,
then
an
(
xforms-binding-error
)
occurs
if
the
identified
model
is
not
the
containing
model
element.
Special Attributes:
-
nodesetref -
An
author-optional
attribute
containing
a
model
binding
expression
that
selects
the
set of nodesitems on which thisbind
operates. If the attribute is omitted, the default is the in-scope evaluation contextnode.item. - nodeset
-
A
deprecated
synonym
for
ref
. It has no meaning if attributeref
is present.
See Model Item Properties for details on model item properties.
See
Evaluation
Context
for
details
on
how
the
evaluation
context
is
determined
for
each
attribute
of
the
bind
element.
<bind ref="height" constraint=". > 0" />
<bind ref="c"><bind calculate="../a + ../b"/></bind>
<bind ref="c"><bind context=".." calculate="a+b"/></bind>
The var element
The
var
element
declares
a
local
variable.
A
variable
is
a
binding
between
a
name
and
a
value.
The
value
of
a
variable
is
any
sequence
of
nodes
and/or
atomic
values,
as
defined
in
XPath
Data
Model
[
XDM
].
Common Attributes: Common
Special Attributes:
- name
-
Required
attribute
containing
the
name
of
the
variable.
The
value
of
the
name
attribute is a QName. The scope of the variable is defined in the Variable Scope section below. - value
- Optional attribute containing an expression to evaluate. The result of the expression is made available as a variable to XPath expressions for which the variable is in scope.
The
value
of
a
variable
can
either
be
specified
by
the
value
attribute
or
as
inline
text.
The
value
attribute
has
precedence
over
the
inline
text
(the
inline
text
is
ignored
if
the
value
attribute
is
specified).
A
variable
can
occur
either
as
a
child
of
an
action
element
or
anywhere
a
control
can
appear.
Variables
under
the
model
element
are
not
supported
except
within
nested
action
elements.
Behavior
for
such
variables
may
be
specified
in
the
future
based
on
implementation
experience.
Variable Evaluation
If
a
variable
is
a
child
of
an
action
element,
its
value
is
updated
after
the
previous
child
action
or
variable
has
been
invoked
or
evaluated,
and
before
the
following
child
action
or
variable
is
invoked
or
evaluated.
Such
a
variable
is
evaluated
exactly
once
for
each
execution
of
the
content
of
the
action
element.
This
means
that
if
the
action
is
repeated
with
the
iterate
or
while
attribute,
the
variable
is
re-evaluated
as
well
during
each
execution.
Variables
outside
of
actions
behave
as
if
they
are
updated
upon
xforms-refresh
in
the
order
they
are
defined.
A
variable
holds
references
to
all
the
nodes
the
value
expression
returns
(if
any).
Deleting
nodes
from
an
instance
with
a
delete
action
does
not
remove
those
nodes
from
the
value
of
the
variable
until
the
variable
is
re-evaluated.
Similarly,
changes
to
predicates
of
the
value
expression
by
actions
don't
update
the
value
of
the
variable.
Variable Scope
For any variable, there is a region (more specifically, a set of element nodes) of the form within which the variable is visible. The set of variables in scope for an XPath expression consists of those variables that are visible at the point in the form where the expression occurs.
Variable
scoping
is
lexical
:
a
variable
defined
by
a
var
element
is
visible
for
all
following
sibling
nodes
and
their
descendants.
The
variable
is
not
visible
for
the
var
element
itself.
Variable shadowing is not allowed: if a variable is declared with a name that is already in scope at the point of the new variable declaration, an ( xforms-binding-error ) event is dispatched.
This is unlike XSLT, which discourages but allows shadowing.
Examples:
<trigger> <label>Show</label> <action ev:event="DOMActivate"> <message ref="$message"/> </action> </trigger>
<trigger> <label>Show</label> <message ev:event="DOMActivate" ref="$message"/> </trigger>
<action iterate="items/item"> <insert context="$current-item" origin="xf:element('label'), xf:element('value')"/> </action>
<input ref="$binding"> <label>Quantity</label> </input>
<select ref="my-item"> <label>Item</label> <itemset ref="$items"> <label ref="name"/> <value ref="value"/> </itemset> </select>
<var name="message">Your document has been saved.</var>
<group> <output value="$page-count"> <label>Number of pages</label> </output> </group>
The function Element
The
function
element
defines
a
custom
function
that
can
be
called
from
any
expression
within
the
XForms
document
that
is
associated
with
the
model
in
which
the
function
is
defined.
Common Attributes: Common
Special Attributes:
- signature
- The signature (name, parameters and return type) of the function.
- override
- Author-optional specifies if this function overrides previously declared functions. The default value is yes.
- type
- Author-optional specifies the implementation language of the function using a valid MIME type. When the attribute is omitted the expression language of the form is used. The supported languages depend on the XForms Processor. The function definition is ignored if the language is not supported by the XForms Processor or if the function element contains mixed content.
A
function
element
can
only
appear
as
a
top-level
element
in
a
model.
Note: The Working Group is considering allowing the definition of custom functions outside of the model in a future version of the specification, but is waiting for implementation experience first.
A custom function is included in the in-scope functions of the static context for all XPath expressions associated with the model that contains the function definition, unless
-
the
override
attribute has the value no and there is already a function with the same name and arity in the in-scope functions. - the custom function tries to override a built-in function.
The
value
of
the
signature
attribute
defines
the
name,
parameters
and
return
type
of
the
function.
See
Function
signature
syntax
for
more
information
about
the
function
signature.
The function that is executed as the result of a function call is identified by searching the in-scope functions of the static context for a function whose name and arity match those of the function call.
Note: Functions are not polymorphic. Although the function call mechanism allows two functions to have the same name and different arity, it does not allow them to be distinguished by the types of their arguments.
The
result
of
a
function
is
a
sequence
of
atomic
values
and/or
nodes.
If
the
result
type
of
the
function
is
specified
with
the
as
attribute,
the
result
value
of
the
function
as
specified
by
the
function
body
is
converted
to
the
required
type
(specified
using
a
SequenceType,
as
defined
in
XPath
2.0
),
using
the
function
conversion
rules.
It
is
a
type
error
/code>
or
if
this
conversion
fails.
If
the
as
attribute
is
omitted,
the
calculated
result
is
used
as
supplied,
and
no
conversion
takes
place.
<function signature="my:sumproduct($p as xs:decimal*, $q as xs:decimal*) as xs:decimal"> sum(for $i in 1 to count($p) return $p[$i]*$q[$i]) </function>
<function signature="my:fibonacci($n as xs:integer) as xs:integer"> <var name="sqrt5" value="math:sqrt(5)" <result value="(math:power(1+$sqrt5, $n) - math:power(1-$sqrt5, $n)) div (math:power(2, $n) * $sqrt5)" /> </function>
<function signature="my:foo($p as xs:decimal*) as xs:decimal" override="no" type="text/javascript"> foo(XForms.var.p); </function>
<function signature="my:foo($p as xs:decimal*) as xs:decimal" override="no"> sum($p) </function>
The
second
definition
of
the
my:foo
function
doesn't
override
the
first
definition
because
the
override
attribute
is
set
to
no
(even
though
the
expanded
QName
and
the
arity
of
the
functions
are
the
same).
Function signature syntax
The
signature
attribute
of
the
function
element
has
the
following
syntax:
CustomFunctionSignature | ::= |
FunctionName
"("
ParamList?
")"
("as"
SequenceType)?
|
FunctionName | ::= |
QNameButNoNCName
|
ParamList | ::= |
Param
(","
Param)*
|
Param | ::= |
"$"
QName
TypeDeclaration?
|
TypeDeclaration | ::= |
"as"
SequenceType
|
The function name is a QName but not an NCName. This means that a form author cannot add functions to the default function namespace.
The parameter list defines the formal arguments to the function. When the function is called using a function call in an expression, the first argument supplied is assigned to the first parameter, the second argument supplied is assigned to the second parameter, and so on.
The type declaration defines the required type of the parameter. The rules for converting the values of the actual arguments supplied in the function call to the types required by each parameter are defined in [XPath 2.0]. The rules that apply are those for the case where XPath 1.0 compatibility mode is set to false.
If the value of a parameter to a custom function cannot be converted to the required type, a type error is signaled.
If the type declaration is omitted, no conversion takes place and any value is accepted.
[ERR] It is a static error if two parameters of a custom function have the same name.
Optional parameters are not allowed.
The following are examples of some function signatures:
Function body
The function body contains the implementation of the function as text content, following the syntax of the function's implementation language.
Alternatively,
when
the
function's
implementation
language
is
the
same
as
the
expression
language
of
the
form,
the
function
body
can
be
specified
with
an
optional
sequence
of
var
elements
followed
by
a
single
result
element
specifying
the
function's
result.
Note: This in particular allows writing more readable custom functions with XPath 1.0 and XPath 2.0, which do not natively support variables.
The implementation of the function should be stable (calling the same function twice within an execution scope with the same arguments returns the same result) and should not change any instance data, nor should it change the internal state of the form (e.g.: should not change the repeat index) or processor.
Function body evaluation context
Within the body of a custom function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error ([err:XPDY0002] as defined in XPath 2.0 )
The variables in scope for the function body include all variables representing the function parameters, as well as all variables that are in scope where the custom function is defined.
Note: Function parameter names can shadow variables that would otherwise be in scope for the function body.
XPath expressions within the function body may refer to instance data through the instance() function.
The result element
The
optional
result
element
is
used
inside
a
function
element
to
produce
the
result
of
the
function.
If
any
var
element
is
present
under
the
function
element,
this
element
is
required.
Otherwise,
it
is
optional.
Common Attributes: Common
Special Attributes:
- value
- Contains the expression which specifies the result of the function.
The submission Element
Details
about
the
submission
element
and
its
processing
are
described
in
The
XForms
Submission
Module
.
XForms Core Attribute Collections
Common Attributes
The Common Attribute Collection applies to every element in the XForms namespace.
- anyAttribute
-
Foreign
attributes
are
allowed
on
all
XForms
elements.
id The author-optional id attribute of type xsd:ID assigns an identity to the containing element.
Note:
Elements
can
be
identified
using
any
attribute
of
type
ID
(such
as
xml:id
),
not
just
the
id
attribute
defined
above.
Note:
The
XML
Events
attributes
are
foreign
attributes
and
therefore
are
allowed
on
any
XForms
element
that
includes
the
Common
attributes.
This
specification
lists
both
Common
and
Events
attributes
on
XForms
actions
for
reading
convenience,
i.e.
since
authors
are
most
likely
to
place
Events
attributes
on
the
actual
event
handler
elements.
- id
-
The
host language may permit a Linking Attributes Collection to be applied to XForms elements as an alternate means of obtaining content related to the element. An example is theauthor-optionalsrcidfrom [ XHTML 1.0 ]. The schedule by which link traversal occurs is defined by the host language. If the link traversal fails, the host language may dispatch xforms-link-exception to the[doesn't support AVT] of typemodelxsd:IDassociated with the in-scope evaluation context node of the element that bears the Linking Attributes Collection forassigns an identity to thefailed link.containing element.
Note:
Section
The
instance
Element
defines
Elements
can
be
identified
using
any
attribute
of
type
ID
(such
as
src
xml:id
for
),
not
just
the
instance
id
element.
Single-Node
Binding
Attributes
The
following
attributes
can
be
used
to
define
a
binding
between
an
XForms
element
such
as
a
form
control
or
an
action
and
an
instance
data
node
attribute
defined
by
an
expression.
above.
-
ref Binding expression interpreted as specified in the expression module . This attribute has no meaning when a bind attribute is present.model -
Author-optional
XForms
Model
selector.selector [doesn't support AVT]. Specifies theID
of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when abind
attribute is present. Rules for determining the context XForms Model are located at Evaluation Context .
-
bindcontext -
Author-optional reference to a bind element. In this specification, when an XForms element is declared to have a Single-Node Binding, then the author must specify the Single-Node Binding unless the element explicitly states that it is author-optional. In some cases,anXForms element may allow a Single-Node Binding, but one or more attributesexpression interpreted as specified in theSingle-Node Bindingexpression module . This author-optional attributegroup are inappropriate for that XForms element. In such cases, the exact attributes are listed for the XForms element, but those attributes still expresshas no meaning when aSingle-Node Binding if they appear in the element. For example, the submission element forbids themodelbindbecause the modelisdefined to be the one containing the submission , so the attributes ref and bind are listed for submission rather than referring topresent. If theSingle-Node Binding attribute group, but if aref or bindmodelused on a submission ,present, then itdoes express a Single-Node Binding. When the Single-Node Bindingisrequired, one of ref or bind is required. When bind is used, the nodeprocessed first as described in Evaluation Context . The expression isdetermined byevaluated in thereferenced bind . See References to Elements within a bind Elementinitial in-scope evaluation contextfor details on selecting an identified bindbefore any other attributes thatis iterated by one or more containing bind elements. When ref is used,contain an expression, and thenode is determined by evaluatingfirst item of theexpression withresult overrides the in-scope evaluation contextdescribed in Section Evaluation Context . First-node rule :item, and the context size and position are changed to 1. Whena Single-Node Bindingthis attributeselects a node-set of size > 1, the first node inis absent, thenode-set, based on document order,in-scope evaluation context isused.not overridden.
It
is
an
exception
error
(
The
xforms-binding-exception
xforms-binding-error
Event
)
if
the
XForms
Processor
encounters
a
model
attribute
IDREF
value
that
refers
to
an
ID
not
on
a
model
element,
or
element.
Linking Attributes
The
host
language
may
permit
a
Linking
Attributes
Collection
to
be
applied
to
XForms
elements
as
an
alternate
means
of
obtaining
content
related
to
the
element.
An
example
is
the
attribute
from
[
XHTML
1.0
].
The
schedule
by
which
link
traversal
occurs
is
defined
by
the
host
language.
If
the
link
traversal
fails,
the
host
language
may
dispatch
xforms-link-exception
to
the
bind
src
IDREF
model
value
associated
with
the
element
that
refers
to
an
bears
the
Linking
Attributes
Collection
for
the
failed
link.
Note:
Section
The
instance
Element
defines
attribute
ID
src
not
on
a
for
the
element.
bind
instance
Node-Set
Binding
Attributes
The
following
These
attributes
define
create
a
binding
between
an
XForms
element
such
as
a
form
control
or
an
action
and
a
node-set
defined
items
returned
by
the
expression.
a
Binding
expression
.
Those
items
can
be
either
nodes
or
atomic
values
(such
as
an
integer,
date,
or
string).
Typically
form
controls
will
bind
to
instance
data
nodes,
but
they
can
bind
to
any
type
of
item.
-
nodesetref -
Binding
expression
interpreted
as
specified
in
the
expression
module
and
evaluated
in
the
in-scope
evaluation
context
.
This
attribute
has
no
meaning
when
a
bind
attribute is present. -
modelnodeset (deprecated) -
Author-optional XForms Model selector. SpecifiesBinding expression interpreted as specified in theID of an XForms Model to be associated with this binding element.expression module and evaluated in the in-scope evaluation context . This author-optional, deprecated attribute has no meaningfor the current binding elementwhen abind
orref
attribute is present.Rules for determiningIs is deprecated in favor of thecontext XForms Model are located at Evaluation Context .ref
attribute. - bind
-
Author-optional
reference
to
a
bind
element.element [doesn't support AVT].
In
this
specification,
when
an
XForms
element
is
declared
to
have
a
Node-Set
Binding,
(item
or
sequence)
binding,
then
the
author
must
specify
the
Node-Set
Binding
binding
unless
the
element
explicitly
states
that
it
is
author-optional.
In
some
cases,
an
XForms
element
may
allow
a
Node-Set
Binding,
but
one
or
more
attributes
in
the
Node-Set
Binding
attribute
group
are
inappropriate
for
that
XForms
element.
In
such
cases,
the
exact
attributes
are
listed
for
the
XForms
element,
but
those
attributes
still
express
a
Node-Set
Binding
if
they
appear
in
the
element.
For
example,
the
bind
element
only
allows
the
nodeset
attribute.
The
model
and
bind
attributes
are
not
allowed
on
a
bind
element,
but
if
the
nodeset
attribute
appears
on
a
bind
element,
it
does
express
a
Node-Set
Binding.
When
the
Node-Set
Binding
a
binding
is
required,
one
of
or
nodeset
ref
bind
is
required.
When
a
bind
attribute
is
used,
the
node-set
item
is
determined
by
the
referenced
bind
element.
See
References
to
Elements
within
a
bind
Element
for
details
on
selecting
an
identified
.
bind
that
is
iterated
by
one
or
more
containing
bind
elements.
When
is
used,
the
nodeset
ref
node-set
item
is
determined
by
evaluating
the
expression
with
the
evaluation
context
described
in
Section
Evaluation
Context
.
It
is
an
exception
(
The
xforms-binding-exception
Event
)
if
the
In
XForms
Processor
encounters
a
2.0,
the
attribute
model
nodeset
attribute
is
a
synonym
for
,
but
deprecated.
Should
both
IDREF
ref
nodeset
value
that
refers
to
an
and
ID
ref
not
be
on
a
an
element,
model
nodeset
element,
or
is
ignored.
If
the
XForms
Processor
encounters
a
bind
attribute
IDREF
value
that
refers
to
an
ID
not
on
a
bind
element.
element,
an
(
xforms-binding-error
is
dispatched.
When a binding is defined as a Single Item Binding then the First-item rule is applied: When a binding selects a sequence of size greater than 1, the first item in the sequence is used.
Model Item Property Attributes
This collection contains one attribute for each model item property, with an attribute name exactly matching the name of the model item property, as defined in Model Item Property Definitions .
The XForms Extension Module
There are many different ways a host language might include XForms. One approach uses only well-formed processing, disregarding validation. Another case uses strict validation, for example XHTML 1.0, in which only predefined elements are allowed. Another common approach is to allow unregulated content in a few select places. A host language that chooses this option can use the Extension module.
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
ANY |
The extension Element
Author-optional
element
extension
is
a
container
for
application-specific
extension
elements
from
any
namespace
other
than
the
XForms
namespace.
This
specification
does
not
define
the
processing
of
this
element.
Common Attributes: Common
<input ref="dataset/user/email" id="email-input"> <label>Enter your email address</label> <extension> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> <rdf:Description rdf:about="#email-input"> <my:addressBook>personal</my:addressBook> </rdf:Description> </rdf:RDF> </extension> </input>
Expressions in XForms
XForms
uses
an
expression
language
expressions
to
address
instance
data
nodes
in
binding
expressions,
to
express
constraints,
and
to
specify
calculations.
The
expression
language
is
Expressions
have
access
to
variables
(see
Variable
Scope
for
more
information
about
variable
scoping)
and
the
focus
(see
next
section
for
more
information
about
the
focus).
Expression
languages
are
pluggable
and
are
defined
in
a
separate
module,
referred
to
as
the
expression
module
.
An
example
of
such
an
expression
module
is
@@todo
make
reference
to
XPath
2.0
module
,
this
module
specifications.
Currently
W3C
defines
an
only
one
expression
language
that
can
be
used
in
XForms
(XPath
which
is
based
on
[
XPath
2.0
]
or
[
defined
in
XForms
2.0:
XPath
1.0
expression
module
].
).
Other
expression
language
modules
might
be
defined
in
the
future.
At
the
time
of
evaluation,
an
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,
an
exception
(
The
xforms-compute-exception
Event
)
error
is
raised,
except
for
binding
expressions,
which
produce
a
different
exception
(
The
xforms-binding-exception
Event
).
Datatypes
Datatypes
are
used
only
in
binding
expressions
and
computed
expressions
;
raised
depending
on
the
actual
supported
data
types
are
defined
in
location
of
the
expression
module
expression:
xforms-expression-error
Event
,
xforms-binding-error
Event
,
or
xforms-action-error
Event
.
Evaluation Context
Within
XForms,
the
default
model
is
the
first
model
Expressions
are
evaluated
in
document
order.
an
evaluation
context.
The
default
instance
evaluation
context
for
a
given
expression
consists
of
any
model
is
all
the
first
child
instance
in
document
order
within
information
that
model
.
Expressions
appearing
in
various
XForms
attributes
are
used
to
reference
instance
data.
Every
expression
requires
an
can
affect
the
result
of
the
expression.
The
evaluation
context
containing
consists
of
at
least
the
focus
(an
(see
following
section
for
details),
the
variables
in
scope
and
the
available
functions.
An
expression
module
language
can
extend
the
evaluation
context
with
add
additional
properties
he
wants).
The
focus
represents
the
place
in
to
the
instance
document
that
is
currently
being
referenced.
evaluation
context.
Maintaining Position: the Focus
The
focus
consists
of
the
context
item
,
position
and
size
and
which
are
determined
according
to
rules
described
below.
A
binding
element
is
any
element
that
is
explicitly
allowed
to
have
a
binding
expression
attribute,
and
a
bound
element
is
any
element
that
explicitly
declares
a
binding
expression
attribute.
A
binding
expression
attribute
contains
an
expression
that
references
zero
or
more
nodes
of
instance
data.
Every
items.
An
expression
requires
may
require
an
evaluation
context.
The
in-scope
evaluation
context
of
a
binding
element
provides
an
evaluation
context
for
the
binding
expression
attribute.
The
following
rules
are
used
in
determining
the
node,
item,
position
and
size
of
the
in-scope
evaluation
context:
-
A
binding
element
is
"
outermost
"
if
the
element
has
no
ancestor
binding
elements.
If
an
outermost
binding
element
is
contained
by
a
model
, then the context item for the outermost binding element is the top-level document element node of the default instance of the containingmodel
element. Otherwise, the context item for outermost binding elements is the top-level document element node of the default instance in the default model. For outermost binding elements, the context size and position are 1. -
The
context
item,
position
and
size
for
non-outermost
binding
elements
is
determined
using
the
binding
expression
attribute
or
in-scope
evaluation
context
of
the
nearest
ancestor
binding
element.
This
is
also
referred
to
as
"scoped
resolution".
For
a
non-outermost
binding
element:
- If the nearest ancestor binding element is not a bound element, then the in-scope evaluation context of the non-outermost binding element is equivalent to the in-scope evaluation context of the nearest ancestor binding element.
-
If
the
nearest
ancestor
binding
element
expresses
a
Single-Node binding,Single Item Binding, then the in-scope evaluation context of the non-outermost binding element has a context size and position of 1 and the context item is the one resulting from theSingle-Node bindingSingle Item Binding of the nearest ancestor binding element. -
If
the
nearest
ancestor
binding
element
expresses
a
Node Set binding,Sequence Binding, then the XFormsprocessorProcessor dynamically generates an occurrence of the non-outermost binding element for each of thenodesitems in theNode SetSequence Binding of the nearest ancestor binding element. The dynamic in-scope evaluation context for each generated occurrence of the non-outermost binding element has a context size equal to the size of thenodesetsequence identified by theNode SetSequence Binding of the nearest ancestor binding element, the context item is thenodeitem for which the occurrence of the non-outermost binding element wasgenerated, and thegenerated. The position is equal to the position of the generatornodeitem in thenodesetsequence identified by theNode SetSequence Binding of the nearest ancestor binding element. -
If
the
nearest
ancestor
binding
element
expresses
a
Node Set binding,Sequence Binding, then the non-outermost binding element has its own in-scope evaluation context separately from those of its dynamically generatedoccurencesoccurrences described above. The in-scope evaluation context has a context position of 1, and the context item and size are set by the firstnodeitem and the size of thenodesetsequence identified by theNode Set bindingSequence Binding of the nearest ancestor binding element.
-
Once
the
context
item
of
the
in-scope
evaluation
context
has
been
determined
according
to
the
rules
above,
if
the
bindingelement expresses amodel
attribute that refers to amodel
other than the one containing the context item (if the context item isn't an instance node, the model is the model specified on the element or the model of its parent if no model attribute is specified on the element), then the context item of the in-scope evaluation context is changed to be the top-level document element node of the default instance of the referencedmodel
, and the context position and size are changed to 1. -
Once
the
context
item
of
the
in-scope
evaluation
context
has
been
determined
according
to
the
rules
above,
if
the
element
expresses
a
context
attribute, then the expression is evaluated in the in-scope evaluation context determined by the rules above, and the first item of the result overrides the in-scope evaluation context item, and the context size and position are changed to 1. When this attribute is absent, the in-scope evaluation context is not modified.
The
in-scope
evaluation
context
of
an
element
that
is
not
a
binding
element
is
the
same
as
if
the
element
were
a
binding
element.
For
example,
the
in-scope
evaluation
context
for
the
setindex
action
element
is
required
to
provide
the
context
for
evaluating
the
index
attribute,
so
it
is
determined
as
if
the
element
could
contain
a
binding
expression
attribute.
Expressions
also
appear
in
model
item
property
attributes
of
the
bind
element
to
define
computed
expressions.
If
the
bind
element
does
not
express
a
Node
Set
binding,
Sequence
Binding,
then
the
in-scope
evaluation
context
for
model
item
property
attributes
of
the
bind
is
equal
to
the
in-scope
evaluation
context
for
the
bind
.
Otherwise,
the
bind
has
a
Node
Set
binding,
Sequence
Binding,
and
computed
expressions
for
each
model
item
property
attribute
are
generated
for
each
node.
For
each
computed
expression
generated,
the
evaluation
context
item,
position
and
size
are
determined
by
the
same
method
as
dynamic
in-scope
evaluation
context
rule
above,
except
the
computed
expression
is
used
in
lieu
of
a
binding
expression
attribute
such
that
the
bind
element
is
the
nearest
ancestor
binding
element.
Expressions
also
appear
in
the
special
attributes
of
several
other
XForms
elements,
such
as
the
value
attribute
on
setvalue
and
output
,
the
at
attribute
of
insert
and
delete
,
or
the
index
attribute
of
setindex
.
Generally,
if
the
containing
element
does
not
express
a
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding,
then
the
special
attribute
is
evaluated
using
the
in-scope
evaluation
context.
Special
attributes
may
be
evaluated
using
the
in-scope
evaluation
context
even
if
the
containing
element
expresses
a
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding.
However,
for
some
special
attributes,
the
evaluation
context
item,
position
and
size
are
based
on
the
result
of
the
Single
Node
Item
Binding
or
Node
set
Sequence
Binding.
Each
special
attribute
that
contains
an
expression
describes
how
its
evaluation
context
item,
position
and
size
are
determined.
In
the
following
example
(we
use
XPath
as
an
expression
language
in
this
sample),
the
group
has
a
binding
expression
of
level2/level3
.
According
to
the
rules
above,
this
outermost
element
node
would
have
a
context
item
of
/level1
,
which
is
the
document
element
node
of
the
instance
data.
The
select1
form
control
then
inherits
a
context
item
from
the
parent
group.
<level1> <level2> <level3 attr="xyz"/> </level2> </level1>
<group ref="level2/level3"> <select1 ref="@attr" ... > <label>...</label> </select1> </group>
This
section
describes
how
the
in-scope
evaluation
context
of
an
element
is
determined,
not
whether
the
in-scope
evaluation
will
be
used.
The
Single-Node
Single
Item
Binding
or
Node
Set
Sequence
Binding
of
a
non-outermost
binding
element
is
not
evaluated
if
the
in-scope
evaluation
context
does
not
contain
a
context
item.
This
can
occur
if
the
Single-Node
Single
Item
Binding
or
Node
Set
Sequence
Binding
of
the
nearest
ancestor
bound
element
produces
an
empty
nodeset.
sequence.
Also,
if
the
Single-Node
Single
Item
Binding
or
Node
Set
Sequence
Binding
of
an
element
is
expressed
with
the
bind
attribute,
then
the
resulting
node
item
or
nodeset
sequence
is
obtained
from
the
referenced
bind
element.
The
ref
(or
deprecated
nodeset
)
attribute
of
a
bind
element
is
evaluated
using
the
in-scope
evaluation
of
the
bind
element,
not
the
in-scope
evaluation
context
of
an
element
that
references
it
with
a
bind
attribute.
References, Dependencies, and Dynamic Dependencies
An expression references a node of instance data if the node is selected during the evaluation of the expression. The selection mechanism is defined in the expression module . The reference list of an expression is the set of instance nodes that it references, including the nodes that were referenced while evaluating the expression but were subsequently excluded from further participation in the expression evaluation (for example by a filter expression).
Given the following default instance:
<instance><data xmlns=""> <a attr="X"> <b attr="Y"> <c/> </b> <d/> </a> <a attr="Z"> <b attr="Z"> <c/> </b> <d/> </a></data> </instance>
and the following XPath expression:
a[@attr='X']/b[@attr='X']/c
Both
nodes
named
a
are
referenced
since
both
are
matched
by
a
NameTest.
The
attr
attribute
in
each
element
a
is
referenced
during
the
evaluation
of
the
filter
expression.
The
filter
expression
rejects
the
second
element
a
,
but
that
element
is
still
considered
to
have
been
referenced
because
it
was
selected
for
further
processing
during
the
expression
evaluation.
The
element
named
b
in
the
first
element
a
is
referenced,
but
element
b
in
the
second
a
is
not
referenced
because
the
expression
evaluation
did
not
proceed
beyond
the
filter
expression
that
rejected
the
second
a
element.
While
performing
the
NameTest
for
element
b
,
observe
that
an
XPath
expression
evaluator
may
visit
all
the
children
of
the
first
element
a
in
order
to
perform
the
NodeTest.
However,
a
node
is
not
referenced
if
it
is
only
visited
but
fails
the
NodeTest.
In
this
case,
the
NodeTest
is
a
NameTest
for
b
,
which
the
element
d
fails.
Therefore,
d
is
not
referenced.
The
filter
expression
test
on
b
rejects
the
only
element
b
that
has
been
selected
so
far
because
the
attribute
value
of
attr
does
not
match
the
equality
test.
Still,
b
and
its
attribute
attr
have
been
referenced
by
this
expression.
Element
c
is
not
considered
to
be
referenced
by
this
expression
given
this
data.
Although
a
NameTest
for
c
appears
in
the
expression,
the
evaluation
of
the
expression
did
not
proceed
to
perform
the
NameTest
due
to
the
rejection
of
b
by
the
filter
expression.
Finally,
note
that
an
XPath
expression
can
reference
many
nodes
even
if
its
final
result
is
an
empty
nodeset.
sequence.
Note:
Defining
a
reference
in
terms
of
matching
a
NodeTest
was
a
deliberate
design
decision
that
creates
more
references
than
necessary
in
order
to
make
the
computation
system
more
responsive
to
certain
types
of
changes
without
needing
a
rebuild
operation.
When
a
leaf
node
is
filtered
from
an
expression
by
a
predicate,
the
leaf
node
is
still
considered
to
be
referenced
so
that
if
the
condition
changes
such
that
the
leaf
node
would
A
function
can
introduces
additional
dependencies
which
should
be
included
defined
in
the
result
value
of
the
expression,
then
the
expression
will
be
recalculated
without
needing
a
rebuild.
However,
once
a
node
is
rejected
from
an
expression,
further
location
steps
are
not
evaluated
relative
to
the
rejected
node,
so
references
for
module
that
location
step
are
only
created
based
on
its
execution
relative
to
accepted
nodes.
For
example,
if
the
above
expression
were
in
a
calculate
,
and
if
the
attribute
of
either
b
element
changes
to
the
value
X
,
makes
the
expression
would
be
recalculated
but
it
still
does
not
record
a
reference
function
available
to
any
c
elements
until
the
references
are
obtained
in
the
next
rebuild
operation.
Moreover,
the
excess
references
created
by
the
definition
may
cause
some
recalculation
constructs
to
cease
operation
due
to
circular
references
that
would
not
be
created
with
a
stricter
definition
of
a
reference.
A
future
version
of
XForms
may
use
a
stricter
version
of
referencing
for
recalculation
and
a
less
strict
definition
of
referencing
for
the
purpose
of
detecting
and
performing
automatic
rebuild
operations.
The
referencing
of
a
repeat
index
by
the
index()
function
engine.
It
is
handled
as
a
special
case.
Implementations
must
behave
recommended
to
define
additional
dependencies
as
if
each
occurrence
of
a
repeat
is
associated
with
an
it
they
were
dependencies
to
implicitly
managed
instance
data
node
containing
the
repeat
index.
nodes.
If
an
expression
other
than
a
repeat
identified
as
R1
contains
a
repeat
identified
as
R2
,
then
a
repeat
index
computed
expression
references
an
instance
node
is
managed
for
each
occurrence
of
R2
that
is
generated
by
R1
.
An
invocation
of
node,
then
the
function
index()
in
an
expression
is
considered
to
reference
dependent
on
the
repeat
index
instance
node
corresponding
to
the
repeat
index
value
that
it
returns.
node.
If
an
a
computed
expression
references
an
instance
node,
node
and
uses
its
character
content
(rather
than
just
referencing
for
navigation),
then
the
computed
expression
result
is
dependent
on
the
instance
node.
A
dependency
list
for
an
instance
node
is
the
list
of
expressions
of
a
given
category
that
are
dependent
upon
the
instance
node.
For
example,
in
Section
The
xforms-recalculate
Event
,
the
dependency
list
of
computed
expressions
for
each
instance
node
helps
establish
the
recalculation
order
for
the
computed
expressions
when
the
values
of
instance
data
nodes
are
changed.
The
references
of
an
expression
may
be
altered
by
insertion
of
instance
nodes
since
the
new
nodes
may
be
referenced
by
the
expression
if
it
is
re-evaluated.
Similarly,
the
references
of
an
expression
may
be
altered
by
deletion
of
instance
nodes
that
are
being
referenced
by
the
expression.
An
expression
is
dynamically
dependent
on
an
instance
node
if
its
reference
list
is
altered
by
inserting,
deleting
or
changing
the
value
of
the
instance
node.
An
instance
node
is
a
dynamic
dependency
for
an
expression
if
the
expression
is
dynamically
dependent
on
the
instance
node.
If
an
expression
contains
a
dynamic
dependency
and
the
XForms
processor
Processor
is
maintaining
dependency
lists
for
the
category
of
the
expression,
then
changing
the
dynamic
dependency
implies
a
change
to
the
dependency
lists
of
instance
nodes
referenced
by
the
expression.
The
computational
dependency
data
structure
described
in
Section
The
xforms-recalculate
Event
essentially
stores
the
dependency
lists
of
instance
nodes
corresponding
to
all
the
references
made
by
computed
expressions
(see
Appendix
Recalculation
Sequence
Algorithm
for
details).
The
computational
dependency
data
structure
is
not
reconstructed
in
response
to
a
dynamic
dependency
change.
Instead,
the
form
author
may
request
a
rebuild
of
the
computational
dependency
data
structures
using
the
rebuild
action.
Additionally,
the
insert
and
delete
actions
set
a
rebuild
flag
so
that
computational
dependency
data
structures
will
be
rebuild
at
the
end
of
an
action
sequence.
Due
to
the
rebuild
flag
setting
on
insert
and
delete
,
a
form
author
can
use
many
kinds
of
dynamic
dependencies
in
model
binding
expressions
and
computed
expressions
without
ever
explicitly
invoking
the
rebuild
action.
This
includes
the
use
of
functions
such
as
position()
,
last()
,
and
count()
on
element
and
attribute
nodes
because
the
return
values
of
the
functions
in
these
cases
is
fixed
except
when
an
insert
or
delete
occurs.
By
comparison,
functions
such
as
id()
,
instance()
,
and
index()
can
establish
dynamic
dependencies
that
can
necessitate
invoking
a
rebuild
if
they
are
used
in
model
binding
expressions
or
computed
expressions
because
the
results
of
the
functions
are
affected
by
changing
the
values
of
instance
nodes,
not
by
inserting
or
code>modelor
deleting
nodes.
Typed Values
When referencing a node, an expression might require the value of that node. In addition, some expression languages, such as XPath 2.0, support accessing the typed-value of a node in addition to the string-value of a node. The typed-value always consists of a sequence of atomic values.
When
the
expression
language
is
XPath
2.0
or
newer,
and
the
associated
type
is
integer
or
one
of
the
built-in
primitive
datatypes
listed
in
XForms
Datatypes
(either
in
the
XForms
namespace
or
the
XML
Schema
namespace),
the
typed-value
of
nodes
must
be
supplied
to
the
expression
language
based
on
type
information
associated
with
the
node,
either
by
the
type
model
item
property
or
by
xsi:type
.
If the associated type is one of the XForms datatypes allowing empty content , the corresponding XML Schema datatype must be supplied to the expression engine by the implementation.
An implementation may provide additional datatypes.
If the type information is associated by an external or an inline XML Schema, the typed-value of nodes should be supplied to the expression language when possible, following the Typed Value Determination in [ XDM ]. If a node is invalid and the XML Schema validator cannot provide type information, or if the processor for the expression language does not support certain types provided by an XML Schema, the implementation is allowed to omit providing specific type information for the associated nodes.
Editorial note: Type from XML Schema | 2013-09-24 |
Feedback is welcome on the approach proposed here with regard to XML Schema. |
Editorial note: xs:untypedAtomic | 2013-09-24 |
Does anything need to be said about providing xs:untypedAtomic to the expression? |
When another expression language is used, the typed-value of nodes should be supplied when possible.
Note:
The
typed-value
must
in
particular
be
available
to
expressions
running
during
the
default
processing
of
xforms-recalculate
,
even
though
revalidation
via
the
default
processing
of
xforms-revalidate
might
not
have
happened
yet.
Because
XForms
has
a
mutable
model
and
type
information
reflects
the
desired
datatype
of
a
node
rather
than
a
guaranteed
datatype,
the
situation
can
arise
that
the
typed-value
of
a
given
node
cannot
be
obtained
when
requested
by
the
expression.
For
example,
if
the
string-value
of
the
node
is
a
blank
string
or
the
string
acme
,
and
the
datatype
is
xs:decimal
,
it
is
not
possible
to
create
a
value
of
type
xs:decimal
.
When
this
situation
arises,
the
evaluation
of
the
expression
must
be
interrupted.
If the evaluation of an expression is interrupted because of such a type error, the XForms Processor must take the following action:
-
if
the
expression
is
a
calculate
expression, the result of the expression is the empty sequence -
if
the
expression
is
a
constraint
expression, the result of the expression isfalse()
-
if
the
expression
is
another
xf:bind
computed expression, the result of the expression is not applied to the node - if the expression is any other type of expression, the error is considered a dynamic error
The following XPath 2 example shows how type information can be used to simplify expressions by reducing the number of casts:
<model> <instance> <data xmlns=""> <a/> <b/> <c/> <sum1/> <sum2/> </data> </instance> <bind ref="a | b | c | sum2" type="xs:decimal"/> <bind ref="sum1" type="xf:decimal"/> <bind ref="sum1" calculate="sum((../a, ../b, ../c))"/> <bind ref="sum2" calculate="sum((../a, ../b, ../c)[string() castable as xs:decimal], 0.0)"/> </model> <input ref="a"/> <input ref="b"/> <input ref="c"/> <output ref="sum1"><label>Sum only if all values are decimal:</label></output> <output ref="sum2"><label>Sum all decimal values and ignore other values:</label></output>
Also
note
how,
with
XPath
2,
it
is
possible
to
access
the
string
value
of
a
node
with
the
standard
string()
function,
and
to
test
the
type
of
the
node
before
using
it.
Expression Categories
There
are
several
different
categories
of
expressions
used
in
XForms,
and
they
are
processed
at
different
times
depending
on
the
category.
A
binding
expression
is
an
expression
used
to
bind
a
model
item
property
to
one
or
more
instance
nodes,
or
to
bind
a
form
control
to
instance
data,
an
item
(node
or
atomic
value),
or
to
specify
the
node
item
or
node
set
sequence
for
operation
by
an
action.
The
evaluation
schedule
for
binding
expressions
differs
based
on
whether
the
binding
expression
is
a
model
binding
expression,
UI
binding
expression,
or
a
binding
expression
for
an
XForms
action.
Expressions
are
also
used
in
various
other
attributes
of
XForms
binds,
actions,
form
controls,
and
submission
s,
and
their
descendant
elements.
These
expressions
follow
one
of
the
three
schedules
associated
with
binding
expressions
as
described
below.
Model Binding Expressions and Computed Expressions
A
model
binding
expression
is
a
kind
of
binding
expression
that
can
be
used
to
declare
model
item
properties,
and
is
used
in
the
Node-Set
binding
Sequence
Binding
of
the
bind
element.
A
computed
expression
is
an
expression
used
to
determine
the
value
of
a
model
item
property
based
on
instance
data.
Several
of
the
attributes
of
bind
are
computed
expressions,
including
calculate
,
readonly
,
relevant
,
and
required
.
Dynamic dependencies in model binding expressions and computed expressions will require manual rebuilding of dependencies.
Note:
If
the
index()
function
is
being
invoked
from
a
model
binding
expression
or
computed
expression,
it
will
be
necessary
to
invoke
rebuild
manually.
If
the
repeat
index
change
occurs
due
to
an
implicit
behavior
such
as
a
change
to
the
focused
form
control,
then
the
rebuild
(along
with
recalculate,
revalidate
and
refresh)
can
be
invoked
from
a
handler
for
DOMFocusIn
a
ttached
attached
to
the
repeat
or
each
repeat
object.
Expressions in Actions and Submissions
Binding
expressions
on
XForms
actions
and
expressions
appearing
in
other
attributes
of
XForms
actions
are
evaluated
at
the
time
the
XForms
action
is
performed.
In
some
cases,
XForms
actions
have
child
elements
that
allow
the
values
of
some
of
their
attributes
to
be
determined
based
on
instance
data.
In
these
cases,
the
value
attribute
of
the
child
element
is
evaluated
at
the
time
the
corresponding
attribute
is
needed
in
the
processing
model
of
the
containing
XForms
action.
Similarly,
expressions
used
in
the
attributes
of
submission
and
its
child
elements
(other
than
XForms
actions)
are
evaluated
as
needed
within
the
submission
processing
model.
Form authors can use dynamic dependencies in the expressions of XForms Actions and Submissions without invoking any special data structure reconstruction actions because implementations must behave as if these expressions are evaluated as needed.
UI Expressions
A
UI
Binding
Expression
is
a
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding
in
a
form
control.
A
UI
expression
is
a
UI
Binding
Expression
or
an
expression
appearing
in
a
descendant
element
of
a
form
control,
except
for
expressions
in
the
categories
described
above
(such
as
XForms
action
expressions).
These
include
the
Single
Node
Item
Bindings
and
Node
Set
Sequence
Bindings
of
the
additional
elements
that
contribute
to
the
behavior
of
a
form
control
(including
label
,
help
,
hint
and
alert
,
filename
and
mediatype
)
and
the
selection
helper
elements
(
itemset
,
label
,
value
and
copy
).
This
also
includes
the
value
attribute
on
output
and
value
elements.
Form authors can use dynamic dependencies in UI Expressions without invoking any special data structure reconstruction actions because the state of the user interface at the end of processing xforms-refresh is required to reflect the instance data as if all UI Expressions had been re-evaluated.
Note:
Implementations may record UI Expression dependency lists on instance nodes to help streamline detection of the need to re-evaluate a UI Expression at the beginning of processing for xforms-refresh . Such implementations may determine that a UI Expression is stale (needs re-evaluation) when a node on which it depends has been changed. An implementation may also indicate that all UI Expressions are stale if a node of instance data is inserted, deleted or replaced, or the implementation may streamline detection of which UI Expressions may be affected by the insertion, deletion or replacement of an instance data node.
UI Binding in other XML vocabularies
The
XForms
binding
mechanism
allows
other
XML
vocabularies
to
make
single
node
bindings
Single
Item
Bindings
between
custom
user
interface
controls
and
XForms
instance
data.
As
an
example,
XForms
binding
attribute
bind
might
be
used
within
XHTML
1.x
user
interface
controls
as
shown
below.
See
Single-Node
Single
Item
Binding
Attributes
.
<html:input type="text" name="..." xforms:bind="fn"/>
Binding Examples
Consider the following document with the one-and-only XForms model:
<model id="orders"><instance xmlns=""> <orderForm><instance> <orderForm xmlns=""> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </instance><bind nodeset="/orderForm/shipTo/firstName" id="fn" /><bind ref="shipTo/firstName" id="fn" /> </model>
The
following
examples
show
three
ways
of
binding
user
interface
control
input
to
instance
element
firstName
declared
in
the
model
shown
above.
ref
<input ref="shipTo/firstName">...
bind
<input bind="fn">...
<input model="orders" ref="shipTo/firstName">...
The
XForms
Function
Library
Attribute
Value
Templates
The
XForms
Function
Library
In
an
attribute
that
is
defined
designated
as
an
attribute
value
template
(AVT),
an
expression
can
be
used
by
surrounding
the
expression
module
.
with
curly
brackets
({}).
Adding
attribute
value
template
support
to
host
language
attributes
is
recommended,
but
should
be
defined
in
the
host
language
integration
specification.
If
An
attribute
value
template
consists
of
an
alternating
sequence
of
fixed
parts
and
variable
parts.
A
variable
part
consists
of
an
XPath
expression
enclosed
in
curly
brackets
({}).
A
fixed
part
may
contain
any
characters,
except
that
a
left
curly
bracket
must
be
written
as
{{
and
a
right
curly
bracket
must
be
written
as
}}.
Note:
An expression within a variable part may contain an unescaped curly bracket within a StringLiteral or within a comment.
An error ( The xforms-expression-error Event ) must be thrown when one of the following error conditions occur:
- an unescaped left curly bracket appears in a fixed part of an attribute value template without a matching right curly bracket.
-
an
unescaped
right
curly
bracket
occurs
in
a
function, thenfixed part of an attribute value template. - the string contained between matching curly brackets in an attribute value template is not a valid XPath expression, or contains other XPath static errors.
AVT Evaluation
The result of evaluating an attribute value template is referred to as the effective value of the attribute. The effective value is the string obtained by concatenating the expansions of the fixed and variable parts:
- The expansion of a fixed part is obtained by replacing any double curly brackets ({{ or }}) by the corresponding single curly bracket.
- The expansion of a variable part is obtained by evaluating the enclosed XPath expression using the in-scope evaluation context and converting the resulting value to a string.
Curly brackets are not treated specially in an attribute value in an XForms document if the attribute doesn't support attribute value templates or if the content model of the attribute is already an expression.
Attribute value templates are evaluated when necessary. If the attribute is on a UI control, its effective value is calculated on xforms-refresh. If the the attribute is on an XForms action, its effective value is calculated when the action is executed.
All
XForms
attributes
that
aren't
XPath
expressions
and
don't
explicitly
disallow
AVTs
support
AVTs.
The
following
non-normative
list
of
attributes
don't
support
AVTs:
functions
,
schema
and
version
on
model
;
signature
on
function
;
src
and
resource
on
instance
;
type
and
p3ptype
on
bind
;
id
.
resource
attribute
of
load
<load resource="/forms/detail/{instance('document-instance')/document/id}"/>
<load>
is
executed,
the
resource
attribute
is
evaluated.
The
result
is
the
concatenation
of
/forms/detail/
and
of
the
result
of
the
expression
within
brackets.
If
the
id
element
pointed
to
contains
the
string
C72E5,
the
resource
attribute
takes
the
value:
/forms/detail/C72E5
Extension Functions
XForms
documents
may
use
additional
extension
functions
beyond
those
defined
in
the
document
and
added
by
the
expression
language.
A
number
of
useful
community
extensions
are
defined
at
[EXSLT]
.
The
names
of
any
such
extension
functions
should
be
declared
by
authors
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-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
dispatching
an
xforms-expression-error
Event
,
xforms-binding-error
Event
,
or
The
xforms-binding-exception
xforms-action-error
Event
occurs.
during
user
interaction.
Failure
by
authors
to
declare
extension
functions
can
result
in
an
XForms
Processor
halting
processing
during
user
interaction
unless
custom
error
event
handlers
are
in
place.
Datatypes
This chapter defines the datatypes used in defining an XForms Model .
XML Schema Built-in Datatypes
XForms
supports
all
XML
Schema
1.0
datatypes
except
for
xsd:ENTITY
,
xsd:ENTITIES
,
and
xsd:NOTATION
.
Concepts
The
concepts
of
value
space
,
lexical
space
and
constraining
facets
are
as
specified
in
[
XML
Schema
part
2
].
XForms
Processors
must
treat
these
datatypes
as
in-scope
without
requiring
the
inclusion
of
an
XML
Schema.
Note:
The
built-in
datatype
xsd:duration
does
not
support
a
total
ordering.
Form
authors
are
encouraged
to
use
xforms:dayTimeDuration
or
xforms:yearMonthDuration
instead.
XForms Datatypes
XForms
defines
the
following
types
in
the
XForms
namespace.
These
datatypes
can
be
used
in
the
type
model
item
property
without
a
namespace
prefix
when
the
default
namespace
is
the
XForms
namespace.
All
of
these
datatypes
allow
empty
content.
XForms
Processors
must
treat
these
datatypes
as
in-scope
without
requiring
the
inclusion
of
an
XML
Schema.
XForms Datatypes Allowing Empty Content
Many
default
XML
schema
Schema
types
report
empty
content
as
invalid,
which
conflicts
with
the
use
of
the
required
model
item
property.
The
following
XForms
datatypes
are
defined
as
having
a
lexical
space
consisting
of
either
the
empty
string
or
the
lexical
space
of
the
corresponding
XML
schema
datatype.
Schema
datatype,
as
defined
in
XML
Schema
part
2,
or
the
XPath
Data
Model
[XDM].
Although
some
XML
schema
Schema
datatypes
do
allow
empty
string
content,
they
have
also
been
added
to
the
available
XForms
datatypes
for
form
authoring
consistency.
Built-in primitive types (in the XForms namespace):
dateTimestring
timeboolean
decimal
double
float
date
time
dateTime
duration
gYearMonthdayTimeDuration
gYearyearMonthDuration
gMonthDayQName
anyURI
gDay
gMonthDay
gMonth
stringgYearMonth
booleangYear
base64Binary
hexBinary
float decimal double anyURI QName
Built-in derived types (in the XForms namespace):
normalizedString token language Name NCName ID IDREF IDREFS NMTOKEN NMTOKENSinteger
nonPositiveInteger
negativeInteger
long
int
short
byte
nonNegativeInteger
unsignedLong
unsignedInt
unsignedShort
unsignedByte
positiveInteger
normalizedString
token
language
Name
NCName
ID
IDREF
IDREFS
NMTOKEN
NMTOKENS
xforms:listItem
This datatype serves as a base for the listItems datatype. The lexical space for listItem permits one or more characters valid for xsd:string, except white space characters.
xforms:listItems
XForms
includes
form
controls
that
produce
simpleType
list
content.
This
is
facilitated
by
defining
a
derived-by-list
datatype.
The
lexical
space
for
listItems
is
defined
by
list-derivation
from
listItem
.
Note:
In most cases, it is better to use markup to distinguish items in a list. See The itemset Element .
xforms:email
This datatype represents an email address, as defined by [ RFC 2822 ]. Internationalized email addresses are not restricted by XForms beyond the definition in the RFC. For simplicity, some extremely uncommon features of the RFC syntax are not allowed, such as "Obsolete Addressing" from section 4.4, square-bracketed "domain-literal"s, and insignificant whitespace and comments.
The
email
datatype
is
made
available
by
the
XForms
processor
Processor
based
on
the
following
lexical
space
definition:
<xs:simpleType name="email"> <xs:restriction base="xsd:string"><xs:pattern value="([A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~
<xs:pattern value="([A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~ ]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*)?"/></xs:restriction>
</xs:restriction> </xs:simpleType>
editors@example.com ~my_mail+{nospam}$?@sub-domain.example.info
Note:
Whilst
the
string
mailto:editors@example.com
is
a
valid
xsd:anyURI,
it
is
not
a
valid
xforms:email
because
the
colon
separator
for
the
URI
scheme
is
not
allowed
before
the
'@'
symbol.
A
valid
xforms:email
address
does
not
include
a
mailto:
URI
scheme.
xforms:card-number
This
type
defines
the
basic
lexical
properties
of
a
datatype
that
can
be
used
to
represent
various
ID,
debit
and
credit
card
numbers..
numbers.
The
lexical
space
of
the
xforms:card-number
datatype
is
a
pattern
restriction
on
xsd:string
:
it
must
be
zero
or
more
digits
(0
-
9).
Note:
The display representation of this datatype by form controls is not required to match the lexical space of the bound instance data. User agents should apply appropriate conventions to the display and input of values, including separator characters.
<xs:simpleType name="card-number"> <xs:annotation> <xs:documentation> This type defines the basic lexical properties for a datatype that can be used to represent various ID numbers such as for debit and credit cards. This type does not apply the Luhn checksum algorithm. </xs:documentation> </xs:annotation> <xs:restriction base="xsd:string"> <xs:pattern value="[0-9]*"/> </xs:restriction> </xs:simpleType>
The
standard
defines
the
structure
of
the
number
as
well
as
how
to
apply
the
Luhn
formula
to
ensure
a
correct
check
digit.
This
type
only
specifies
the
format
of
the
number.
The
complementary
function
is-card-number()
should
be
used
to
validate
that
the
ID
number
conforms
to
the
specification.
<model xmlns="http://www.w3.org/2002/xforms"> <instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number>4111111111111111</number> <expiry/> </payment> </instance><bind nodeset="number" type="card-number" constraint="is-card-number(.)"/><bind ref="number" type="card-number" constraint="is-card-number(.)"/> </model>
This
example
specifies
that
the
element
number
is
of
the
type
card-number
and
that
to
be
valid
the
is-card-number()
function
must
evaluate
to
true
indicating
that
check
digit
is
valid.
xforms:HTMLFragment
This
type
defines
the
basic
lexical
properties
of
a
datatype
that
can
be
used
to
represent
a
serialized
HTML
fragment.
The
lexical
space
of
the
xforms:HTMLFragment
datatype
is
an
xsd:string
with
no
extra
restrictions.
The HTMLFragment datatype is made available by the XForms Processor based on the following lexical space definition:
<xs:simpleType name="HTMLFragment"> <xs:restriction base="xsd:string"/> </xs:simpleType>
The xforms:HTMLFragment is a tagging datatype that can be used by the UI to provide a convenient means for entry and displaying of HTML fragments ('rich text content').
This is <b>rich</b> text content.
Model Item Properties
This
chapter
defines
infoset
contributions
that
can
be
bound
to
instance
data
nodes
with
element
bind
(see
The
bind
Element
).
The
combination
of
these
contributions
to
an
instance
data
node
is
called
a
model
item
.
Taken
together,
these
contributions
are
called
model
item
properties
,
and
are
defined
in
the
following
section.
.
In
contrast,
the
term
Schema
constraint
refers
only
to
XML
Schema
constraints
from
the
facets
of
a
given
datatype.
It is an error ( The xforms-binding-error Event ) to attach Model Item Properties to atomic values or nodes that don't belong to an instance.
Model Item Property Definitions
Model
item
properties
can
be
distinguished
along
various
axes.
Computed
expressions
vs.
fixed
properties:
certain
axes:
- Fixed properties are static values that the XForms Processor evaluates only once. Such properties consist of literals, and are not subject to evaluation of expressions.
- Computed expressions are expressions that provide a value to the XForms Processor. Such values are recalculated at certain times as specified by the XForms Processing Model (see Processing Model ). These expressions encode dynamic properties, often constraints, such as the dependency among various data items. Computed expressions are not restricted to examining the value of the instance data node to which they apply. Expressions provide the means to traverse the instance data; more complex computations may be encoded as call-outs to external scripts.
Inheritance rules:
Some
model
item
properties
define
inheritance
rules,
in
which
case
the
XForms
Processor
needs
to
keep
track
of
two
separate
values:
1)
the
local
value
,
which
is
applied
from
an
attribute
of
element
bind
,
and
2)
the
inherited
value
,
which
is
determined
by
combining
the
evaluated
local
value
with
the
evaluated
values
from
ancestor
nodes
in
the
instance
data.
Note:
The sample recalculation algorithm defined in Recalculation Sequence Algorithm is defined to operate only on the local values of a model item property. It assumes that an implementation propagates the combined values to a node's descendants.
Assigning local values:
Local
values
are
assigned
by
processing
all
bind
elements
in
an
XForms
Model
in
document
order.
It
For
most
properties
it
is
an
error
allowed
to
attempt
assign
the
same
property
more
than
once
to
set
a
model
item
property
twice
value
using
different
bind
elements
(for
instance
having
two
binds
selecting
the
same
element,
each
specifying
a
constraint).
Depending
on
the
property,
the
additional
bindings
are
either
combined
so
that
all
have
to
be
true,
or
that
at
least
one
has
to
be
true,
according
to
the
following
table:
property | combination |
---|---|
type | all |
constraint | all |
relevant | all |
required | one |
readonly | one |
calculate | (not allowed) |
p3ptype | (not allowed) |
For example,
<bind ref="action" readonly="../status='accepted'" /> <bind ref="action" readonly="../status='rejected'" />
has
the
same
node
(see
effect
as
<bind ref="action" readonly="../status='accepted' or ../status='rejected'" />
See
also
The
xforms-rebuild
Event
for
details)..
details
of
the
properties
being
applied.
The following sections list the model item properties available as part of all model items . For each, the following information is provided:
Description
Computed Expression (yes or no)
Legal Values
Default Value
Inheritance Rules
The type Property
Description:
The
type
model
item
property
[doesn't
support
AVT]
can
be
applied
to
both
elements
and
attributes.
The
type
model
item
property
is
not
applied
to
instance
nodes
that
contain
child
elements.
The
type
model
item
property
associates
a
datatype
(as
defined
in
[
XML
Schema
part
2
])
with
the
string-value
(as
defined
in
[
XPath
1.0
])
of
an
instance
node.
The
datatype
being
associated
can
be
obtained
from
a
simpleType
definition
or
a
simpleContent
definition
from
a
complexType.
If
the
datatype
cannot
be
obtained
as
just
described,
then
the
Default
Value
of
xsd:string
is
used.
This
model
item
property
does
not
prevent
form
controls
and
XForms
actions
from
setting
invalid
values
into
data
nodes.
Computed Expression: No.
Legal
Values:
Any
xsd:QName
representing
a
datatype
definition
in
an
XML
Schema.
The
namespace
context
from
the
parent
bind
of
the
type
attribute
is
used
to
resolve
the
namespace
qualification
of
the
value.
Default
Value:
xsd:string
.
Inheritance Rules: does not inherit.
This model item property contributes to the overall validity assessment of a node; the effect of validity state on bound form controls is described in Section Implementation Requirements Common to All Form Controls .
Note:
In
XML
Schema,
an
element
can
be
made
nillable.
Although
this
means
it
can
have
empty
content,
nillable
is
defined
by
[
XML
Schema
part
1
]
to
be
a
property
of
an
element,
not
a
type.
Therefore,
the
nillable
property
from
XML
Schema
cannot
be
applied
to
instance
nodes
using
the
type
model
item
property.
<model xmlns:my="http://example.org"><xs:schema targetNamespace="">
<xs:schema targetNamespace="http://example.org" xmlns:my="http://example.org"> <xs:simpleType name="Currency"> <xs:restriction base="xsd:string"> <xs:enumeration value="USD"/> <xs:enumeration value="EUR"/> </xs:restriction> </xs:simpleType><xs:complexType name="Price">
<xs:complexType name="Price"> <xs:simpleContent> <xs:extension base="xsd:double"> <xs:attribute name="currency" type="my:Currency" use="optional" default="USD"/> </xs:extension> </xs:simpleContent> </xs:complexType> </xs:schema><instance>
<instance> <data xmlns="http://example.org"> <aString>Hello, world!</aString> <simpleType> <price>100.00</price> <price>abc</price> <price currency="EUR">100.00</price> <price currency="EUR">abc</price> </simpleType> <complexType> <price>100.00</price> <price>abc</price> <price currency="abc">100.00</price> <price currency="EUR">abc</price> </complexType></instance><bind nodeset="my:aString" type="xsd:string"/> <bind nodeset="my:simpleType/my:price" type="xsd:double"/> <bind nodeset="my:complexType/my:price" type="my:Price"/> <bind nodeset="my:complexType/my:price[3]/@currency" type="my:Currency"/> <bind nodeset="/my:data" type="xsd:string"/> </model>
<bind ref="my:aString" type="xsd:string"/> <bind ref="my:simpleType/my:price" type="xsd:double"/> <bind ref="my:complexType/my:price" type="my:Price"/> <bind ref="my:complexType/my:price[3]/@currency" type="my:Currency"/> <bind ref="/my:data" type="xsd:string"/>
</model>
The first bind expresses the default datatype of xsd:string.
The
second
and
third
binds
place
type
model
item
properties
on
each
of
the
four
price
element
children
of
the
elements
simpleType
and
complexType
.
Both
binds
associate
the
datatype
xsd:double
with
the
nodes.
In
both
cases,
the
first
and
third
nodes
are
considered
valid
according
to
the
type
model
item
property
because
their
content
matches
the
xsd:double
datatype
constraint.
For
both
binds,
the
second
and
fourth
price
nodes
are
not
valid
due
to
their
content.
The
fourth
bind
places
a
type
model
item
property
on
the
currency
attribute
of
the
third
price
element.
According
to
this
association,
the
currency
attribute
node
is
not
valid
because
its
content
does
not
match
the
enumeration
given
for
my:Currency
.
Note
that
the
containing
element
price
is
valid
according
to
its
type
model
item
property.
The
fifth
bind
attempts
to
associate
a
datatype
with
the
data
element.
The
association
is
ignored
since
the
data
element
contains
child
elements.
The readonly Property
Description: describes whether the node content is restricted from changing.
Computed Expression: Yes.
Legal
Values:
Any
expression
that
is
convertible
to
a
boolean
as
described
in
the
expression
module
.
Default
Value:
false()
,
unless
a
calculate
is
specified
for
the
value
property,
then
true()
.
Inheritance
Rules:
If
any
ancestor
node
evaluates
to
true
,
this
value
is
treated
as
true
.
Otherwise,
the
local
value
is
used.
Note:
This
is
the
equivalent
of
taking
the
logical
OR
of
the
evaluated
readonly
property
on
the
local
and
every
ancestor
node.
When
true
,
this
model
item
property
indicates
that
the
XForms
Processor
must
not
allow
any
direct
changes
to
the
content
of
the
bound
instance
data
node
from
constructs
other
than
the
model
item
property
system
(i.e.
other
than
a
calculate
).
Instance
mutations
performed
by
submission
,
form
controls,
DOM
interface
access,
and
XForms
actions
must
not
insert
or
copy
a
new
node
into
a
parent
node
that
is
readonly,
delete
or
replace
a
node
whose
parent
is
readonly,
nor
change
the
value
or
content
of
a
readonly
node.
A
node
that
is
readonly
but
whose
parent
is
not
readonly
can
be
entirely
deleted
or
replaced
by
a
submission
even
though
doing
so
indirectly
results
in
deletion
or
replacement
of
readonly
descendant
nodes.
In
addition
to
restricting
value
changes,
the
readonly
model
item
property
provides
information
to
the
XForms
user
interface
about
how
bound
form
controls
should
be
rendered.
Form
controls
bound
to
instance
data
with
the
readonly
model
item
property
that
evaluates
to
true
should
indicate
that
entering
or
changing
the
value
is
not
allowed.
This
specification
does
not
define
any
effect
of
the
readonly
model
item
property
on
visibility,
focus,
or
navigation
order.
<instance> <my:person-name> <my:first-name>Roland</my:first-name> <my:last-name/> </my:person-name> </instance><bind nodeset="/my:person-name/my:first-name" readonly="true()"/><bind ref="my:first-name" readonly="true()"/>
Here,
we
have
associated
a
readonly
property
with
an
element.
The
following
example
illustrates
the
ability
to
override
the
default
readonly
setting
on
calculated
nodes.
<model> <instance> <my:data></my:data> </instance><bind nodeset="/my:data" readonly="false()" calculate="choose(.='', 'default', .)"/><bind ref="/my:data" readonly="false()" calculate="choose(.='', 'default', .)"/> <model> <input ref="/my:data"> ...
The
calculate
on
my:data
is
executed
on
any
recalculate
that
follows
a
rebuild,
including
the
form
initialization,
so
the
user
initially
sees
the
word
'default'.
The
user
may
make
any
change
to
my:data
with
the
input
,
and
the
calculation
will
be
executed
again
as
a
result.
Therefore,
if
the
user
enters
an
empty
value,
then
the
calculate
will
change
my:data
back
to
'default'.
The required Property
Description: describes whether a value is required before the instance data is submitted.
Computed Expression: Yes.
Legal
Values:
Any
expression
that
is
convertible
to
a
boolean
as
described
in
the
expression
module
.
Default
Value:
false()
.
Inheritance Rules: does not inherit.
A
form
may
require
certain
values,
and
this
requirement
may
be
dynamic.
When
evaluating
to
true
,
this
model
item
property
indicates
that
a
non-empty
instance
data
node
is
required
before
a
submission
of
instance
data
can
occur.
Non-empty
is
defined
as:
The
value
of
the
bound
instance
data
node
must
be
convertible
to
string
using
the
string
conversion
function
as
described
in
the
expression
module
with
a
length
greater
than
zero.
Note:
The
XML
Schema
feature
represented
by
nillable
and
xsi:nil
is
unrelated
to
the
XForms
required
model
item
property.
An
element
may
have
the
xsi:nil
attribute
set
to
true
to
indicate
that
its
empty
content
is
schema
valid,
but
if
the
required
model
item
property
for
that
element
node
is
true
,
then
the
element
violates
the
required
constraint
because
a
required
node
must
be
non-empty
as
defined
above.
Except
as
noted
below,
the
required
model
item
property
does
not
provide
a
hint
to
the
XForms
user
interface
regarding
visibility,
focus,
or
navigation
order.
XForms
authors
are
strongly
encouraged
to
make
sure
that
form
controls
that
accept
required
data
are
visible.
An
XForms
Processor
must
provide
an
indication
that
a
form
control
is
required,
and
may
provide
immediate
feedback,
including
limiting
navigation.
This
model
item
property
does
not
prevent
form
controls
and
XForms
actions
from
setting
empty
strings
into
data
nodes.
<instance> <my:person-name> <my:first-name>Roland</my:first-name> <my:last-name /> </my:person-name> </instance><bind nodeset="/my:person-name/my:last-name" required="true()"/><bind ref="my:last-name" required="true()"/>
Here,
we
have
associated
a
required
property
with
element
my:last-name
to
indicate
that
a
value
must
be
supplied.
Note:
XML
Schema
has
a
similarly
named
concept
with
use
=
"required|optional|prohibited"
.
This
is
different
than
the
XForms
Model
item
property,
in
two
ways:
1)
use
applies
only
to
attributes,
while
XForms
required
applies
to
any
node.
2)
use
is
concerned
with
whether
the
entire
attribute
must
be
specified
(without
regard
to
value),
while
required
determines
whether
a
value
is
required
of
the
node
before
submission.
The relevant Property
Description:
indicates
whether
the
model
item
is
currently
relevant
.
Instance
data
nodes
with
this
property
evaluating
to
false
are
unavailable
in
the
user
interface
and
can
be
removed
from
submission
serialization.
Computed Expression: Yes.
Legal
Values:
Any
expression
that
is
convertible
to
a
boolean
as
described
in
the
expression
module
.
Default
Value:
true()
.
Inheritance
Rules:
If
any
ancestor
node
evaluates
to
false
,
this
value
is
treated
as
false
.
Otherwise,
the
local
value
is
used.
Note:
This
is
the
equivalent
of
taking
the
logical
AND
of
the
evaluated
relevant
property
on
the
local
and
every
ancestor
node.
Many forms have data entry sections that depend on other conditions. For example, a form might ask whether the respondent owns a car. It is only appropriate to ask for further information about their car if they have indicated that they own one.
Through
single
node
UI
bindings,
the
relevant
model
item
property
provides
information
to
the
XForms
user
interface
regarding
visibility,
focus,
and
navigation
order.
In
general,
when
true
,
associated
form
controls
should
be
made
available
for
user
interaction.
When
false
,
associated
form
controls
(and
any
children)
and
group
and
switch
elements
(including
content)
must
be
made
unavailable,
removed
from
the
navigation
order,
and
not
allowed
focus.
Typically,
non-relevant
user
interface
content
is
not
presented,
or
it
may
be
styled
as
disabled.
Elements
other
than
form
controls
may
also
use
a
single
node
binding
Single
Item
Binding
that
selects
a
non-relevant
node,
but
such
elements
are
not
made
unavailable
or
non-operable
due
to
the
single
node
binding
Single
Item
Binding
because
it
is
not
a
UI
binding
expression
.
For
example,
actions
such
as
The
setvalue
Element
and
The
message
Element
or
the
The
submission
Element
remain
operable
if
their
single
node
bindings
Single
Item
Bindings
select
a
non-relevant
node.
However,
some
such
elements
may
indirectly
be
affected
by
the
relevant
model
item
property.
For
example,
it
is
possible
for
non-relevant
nodes
to
be
excluded
from
the
data
of
a
submission.
Similarly,
non-relevance
indirectly
affects
the
running
of
actions
because
a
non-relevant
form
control
disables
event
handlers
that
listen
for
events
targeted
at
the
form
control
element.
Note:
A
core
form
control,
group
or
switch
must
express
a
single
node
binding
Single
Item
Binding
in
order
to
be
associated
with
an
instance
node.
Due
to
the
definition
of
repeat
object
,
the
relevant
model
item
property
of
the
node
in
the
associated
repeat
item
affects
the
availability
of
the
repeat
object.
<instance> <my:order> <my:item> <my:amount /> <my:discount>100</my:discount> </my:item> </my:order> </instance><bind nodeset="my:item/my:discount" readonly="true()"<bind ref="my:item/my:discount" readonly="true()" relevant="../my:amount > 1000"/>
Here,
we
have
associated
a
relevant
property
with
element
my:discount
to
indicate
a
discount
is
relevant
when
the
order
amount
is
greater
than
1000.
The calculate Property
Description: supplies an expression used to calculate a string value for the associated instance data node.
Computed Expression: Yes.
Legal Values: Any expression.
Default Value: none.
Inheritance Rules: does not inherit.
An
XForms
Model
may
include
model
items
whose
string
values
are
computed
from
other
values.
For
example,
the
sum
over
line
items
for
quantity
times
unit
price,
or
the
amount
of
tax
to
be
paid
on
an
order.
The
formula
for
such
a
computed
value
can
be
expressed
with
a
calculate
property,
whose
expression
is
evaluated,
converted
to
a
string
with
the
string
conversion
function
as
described
in
the
expression
module
,
and
stored
as
the
value
content
of
the
calculated
data
node.
Chapter
Processing
Model
contains
details
of
when
and
how
the
calculation
is
performed.
<instance> <my:order> <my:item> <my:amount /> <my:discount /> </my:item> </my:order> </instance><bind nodeset="my:item/my:discount" calculate="../my:amount * 0.1"<bind ref="my:item/my:discount" calculate="../my:amount * 0.1" relevant="../my:amount > 1000"/>
Here,
we
have
associated
a
relevant
property
with
element
my:discount
to
indicate
a
discount
of
10%
is
relevant
when
the
order
amount
is
greater
than
1000.
The constraint Property
Description: specifies a predicate that needs to be satisfied for the associated instance data node to be considered valid.
Computed Expression: Yes.
Legal
Values:
Any
expression
that
is
convertible
to
a
boolean
as
described
in
the
expression
module
.
Default
Value:
true()
.
Inheritance Rules: does not inherit.
When
evaluating
to
false
,
the
associated
model
item
is
not
valid;
the
converse
is
not
necessarily
true.
This
model
item
property
does
not
prevent
form
controls
and
XForms
actions
from
setting
invalid
values
into
data
nodes.
Chapter
Processing
Model
contains
details
of
when
and
how
the
constraint
is
calculated
as
well
as
when
validation
is
performed.
This
model
item
property
contributes
to
the
overall
validity
assessment
of
a
node;
the
effect
of
validity
state
on
bound
form
controls
is
described
in
Section
Implementation
Requirements
Common
to
All
Form
Controls
.
<instance> <my:range> <my:from /> <my:to /> </my:range> </instance><bind nodeset="my:to" constraint=". > ../my:from" /><bind ref="my:to" constraint=". > ../my:from" />
Here,
a
constraint
property
associated
with
element
my:to
indicates
that
its
value
must
be
greater
than
that
of
element
my:from
.
Note:
Specifying
minimum
and
maximum
occurrences
for
nodes
in
the
instance
data
can
be
achieved
by
using
the
count()
function
within
a
constraint
property.
The p3ptype Property (deprecated)
The p3ptype property is deprecated.
Description: Attaches a P3P data element to an instance data node, indicating the specific kind of data collected there. The attribute doesn't support AVT.
Computed Expression: No.
Legal
Values:
xsd:string
.
Default Value: none
Inheritance Rules: does not inherit.
This model item property holds a description of the kind of data collected by the associated instance data node, based on the P3P datatype system [ P3P 1.0 ]. This information may be used to enhance the form-fill experience, for example by supplying previously-known data.
<instance> <my:person-name> <my:first-name /> <my:last-name /> </my:person-name> </instance><bind type="my:nonEmptyString" nodeset="my:first-name"<bind type="my:nonEmptyString" ref="my:first-name" p3ptype="user.name.given"/>
Here,
we
have
attached
both
XML
Schema
and
P3P
type
information
to
element
first-name
via
element
bind
.
Schema Constraints
Chapter
Datatypes
described
how
XForms
uses
the
XML
Schema
datatype
system
to
constrain
the
value
space
of
data
values
collected
by
an
XForms
Model.
Such
datatype
constraints
can
be
provided
via
an
XML
Schema.
Alternatively,
this
section
lists
various
mechanisms
for
attaching
type
constraints
to
instance
data.
Attributes
xsi:schemaLocation
and
xsi:noNamespaceSchemaLocation
are
ignored
for
purposes
for
locating
a
an
XML
Schema.
Atomic Datatype
The XForms Processing Model applies XML Schema facets as part of the validation process. At the simplest level, it is necessary to associate a set of facets (through an XML Schema datatype) with a model item. This has the effect of restricting the allowable values of the associated instance data node to valid representations of the lexical space of the datatype.
The set of facets associated with a model item must be determined by the following list, as if it were processed in the given order. When multiple datatype restrictions apply to the same model item, the combination of all given restrictions must apply. Note that it is possible to produce a combination of restrictions that is impossible to satisfy; authors are encouraged to avoid this practice.
-
Applicable
XML
schemaSchema definitions (including those associated an external or an inlineschema,XML Schema, or byxsi:type
) -
An
XForms
type
constraint associated with the instance data node using XForms binding . -
If
no
type
constraint
is
provided,
the
instance
data
node
defaults
to
type="xsd:string"
(default to string rule).
The
following
declares
a
datatype
based
on
xsd:string
with
an
additional
constraining
facet.
<xs:simpleType name="nonEmptyString"> <xs:restriction base="xsd:string"> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType>
This new datatype would then be associated with one or more model items through one of the methods outlined here.
<my:first-name xsi:type="my:nonEmptyString"/>
This
defines
element
first-name
to
be
of
type
my:nonEmptyString
.
<instance> <my:first-name /> </instance><bind type="my:nonEmptyString" nodeset="/my:first-name"/><bind type="my:nonEmptyString" ref="/my:first-name"/>
Here,
we
have
attached
type
information
to
element
first-name
via
element
bind
.
Thus
the
XForms
author
can
extend
external
schemas
XML
Schemas
without
having
the
ability
to
change
them.
The XForms Submission Module
XForms is designed to gather instance data , serialize it into an external representation, and submit it with a protocol. XForms defines a set of options for serialization and submission. The following sections define the processing of instance data for submission, and the behavior for the serialization and submission options.
The submission Element
The
submission
element
represents
declarative
instructions
on
what
to
submit,
how
to
submit
it,
and
how.
what
to
do
with
the
result.
Element | Overview of Attributes and Their Content (after AVT evaluation) | Overview of Content Model |
---|---|---|
submission |
|
Below is a more detailed decription of each attribute whose name and datatype information appears above.
Common Attributes: Common
Special Attributes:
What to submit:
- ref
- Author-optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission. The default value is "/".
- bind
-
Author-optional
reference
to
a
bind
element.When present, the binding reference on thisThis attributeis used in preference to any binding reference fromtakes precedence over theref
attribute. - relevant
-
Author-optional
boolean
attribute
that
indicates
whether
or
not
the
relevance
pruning
of
the
submission
is
performed.
The
default
value
is
"false"
if
the
value
of
serialization
is "none" and "true" otherwise. - validate
-
Author-optional
boolean
attribute
that
indicates
whether
or
not
the
data
validation
checks
of
the
submission
are
performed.
The
default
value
is
"false"
if
the
value
of
serialization
is "none" and "true" otherwise.
How to submit it:
- resource
-
Attribute
indicating
the
destination
URI
for
submitting
instance
data.
This
attribute
is
not
author-optional
unless
the
destination
URI
is
provided
by
the
resource
element, which can dynamically specify the URI based on instance data, or theaction
attribute. This attribute should be used in place of theaction
attribute. Behavior of relative URIs in links is determined by the host language, although [ XML Base ] processing is strongly recommended. - action
-
Deprecated
author-optional
attribute
indicating
the
destination
URI
for
submitting
instance
data.
Behavior
of
relative
URIs
in
links
is
determined
by
the
host
language,
although
[
XML
Base
]
processing
is
strongly
recommended.
Due
to
the
addition
of
the
resource
attribute, this attribute is deprecated and optional. However, the destination URI must be specified by this attribute or by either theresource
attribute or theresource
element. - mode
-
Author-optional
attribute
defaulting
to
"asynchronous"
and
with
legal
values
of
"synchronous"
and
"asynchronous".
This
attribute
controls
whether
or
not
the
submission
response
processing
is
performed
as
part
of
the
default
processing
of
event
xforms-submit
. An asynchronous submission can complete default processing for this event before the submission response is received; in this case, submission response is processed once it is completely received asynchronously. For a "synchronous" submission, the submission response is received and processed during the default processing of eventxforms-submit
. - method
-
Author-optional
attribute
specifying
the
protocol
operation
to
be
used
to
transmit
the
serialized
instance
data.
There
is
no
default
value becausevalue; either the attributemethod
or the elementmethod
must be specified. See Section Submission Options for information on how this attribute affects the default serialization of instance data and the HTTP method [ RFC 2616 ]. - serialization
-
Author-optional
attribute
that
controls
how
and
whether
to
serialize
instance
data
as
part
of
the
submission.
The
format
is
type/subtype,
or
the
single
word
"none".
Allowable
values
are
"application/xml",
"application/x-www-form-urlencoded",
"multipart/related",
"multipart/form-data",
or
any
of
the
values
allowed
in
the
section
Creating
instance
data
from
external
resources
.
The
default
value
of
this
attribute
is
based
on
the
submission
method
as described in Section Submission Options . If the attribute value is "none", then instance data is not serialized as part of the submission. This can be useful for requests that either require no data or that have the data already gathered in the URI.Note: Settingserialization
to "none" will also have the default effect of preventing relevance pruning and validation. However, the author is free to override this by settingrelevant
and/orvalidate
attributes to "true". - mediatype
-
Author-optional
attribute
specifying
the
mediatype
for XML serializationofinstance data. Authors shouldthe serialization, to be used in theContent-type
header of HTTP, or similar, according to the format specified in [ RFC 2119 ]. It is the author's responsibility to ensure that the type specified is compatible with thedata being submitted,serialization used, such asapplication/xmlapplication/xhtml+xml"application/xml".serialization-dependent, but is "application/xml" for XML serialization.Note: This attribute does not affect serialization andcannot be used todoes not override theserialization
attribute. It is only used to provide additional information about the submission dataserialization when the serialization is application/xml .serialized. For example, this attribute could be used to indicate that the content type ofthean XML serialization istext/xmlapplication/xhtml+xml - encoding
-
Author-optional
attribute
specifying
anthe character encoding to be used for serialization. The default is "UTF-8".
What to do with the result:
- replace
-
Author-optional
attribute
specifying
how
the
information
returned
after
submit
should
be
applied.
In the absence of this attribute, "all" is assumed.The legal values are "all", "instance", "text" and"none"."none", with a default of "all". See Processing the Response from a Submission . - instance
-
Author-optional
attribute
specifying
the
instance
to
replace
when
the
replace
attribute value is "instance". When the attribute is absent, then the default is the instance that contains the submission data.An xforms-binding-exception ( The xforms-binding-exception Event ) occurs if this attribute does not indicate an instance in the same model as the submission. - targetref
-
Author-optional
attribute
containing
an
expression
that
indicates
the
target
node
for
data
replacement.
The
in-scope
evaluation
context
of
the
submission
element is used to evaluate the expression. Ifreplace
is "instance", then the target node is replaced by the submission result. Ifreplace
is "text", then the content of the target node is replaced by the submission result. For other values of thereplace
attribute, this attribute is ignored. By default, the target node is the document element of the instance indicated by theinstance
attribute. - target
-
Author-optional
presentation
context
name
or
keyword
when
the
replace
attribute value is "all". Behavior is defined for values "_self" and "_blank". In addition, an implementation-dependent presentation context name can be specified. If this attribute is missing a default value of "_self" is assumed. The following are the possible values for thetarget
attribute and the corresponding processing behaviors: - _self
- The document is loaded into the current presentation context. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.
- _blank
- The document is loaded into a new presentation context, e.g., a new window or tab. Form processing in the original window or tab continues.
- Any other value
-
The
behavior
is
implementation-dependent.
Note:
If the host language is HTML, the implementation is encouraged to handle the
target
attribute as defined in HTML for theform
element. In particular, values of "_self", "_blank", "_parent", "_top", as well as browsing context names should be supported.
If the data is serialized as application/x-www-form-urlencoded, the following attribute also applies:
- separator
-
Author-optional
attribute
specifying
the
separator
character
between
name/value
pairs
in
urlencoding.
The
default
value
is
'&'.
To
express
the
default,
character
entity
encoding
is
used:
separator='&'
.
If the data is serialized as XML, the following attributes also apply:
- version
-
Author-optional
attribute
specifying
the
version
of XML to be serialized. The default is "1.0". - indent
- Author-optional attribute specifying whether the serializer should add extra white space nodes for readability. The default is "false".
- omit-xml-declaration
- Author-optional attribute specifying whether to omit the XML declaration on the serialized instance data. The default value is "false".
- standalone
-
Author-optional
attribute
specifying
whether
to
include
a
standalone
declaration
in
the
serialized
XML.
If
the
omit-xml-declaration
attribute has the valuetrue
, then this attribute is ignored. Otherwise, if this attribute is omitted, then the XML declaration does not include a standalone document declaration, and if this attribute is specified, then the XML declaration includes a standalone document declaration with the same value as this attribute. - cdata-section-elements
- Author-optional attribute specifying element names to be serialized with CDATA sections. The default is empty string.
- includenamespaceprefixes
-
Author-optional
attribute
providing
control
over
namespace
serialization.
If
absent,
all
namespace
nodes
present
in
the
instance
data
are
considered
for
serialization.
If
present,
specifies
list
of
namespace
prefixes
to
consider
for
serialization,
in
addition
to
those
visibly
utilized.
As
in
Exc-C14N
[
Exc-C14N
],
the
special
value
#default
specifies the default namespace.
The
following
examples
show
how
various
options
on
element
submission
can
affect
serialization
as
application/xml
.
Given
the
following
XForms
fragment:
<model xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:my="http://ns.example.org/2003"> <instance> <qname xmlns="">my:sample</qname> </instance> <submission method="post" resource="..."/> </model>
Note
that
the
includenamespaceprefixes
attribute
is
not
present,
which
causes
all
namespace
nodes
to
be
serialized,
resulting
in
the
following
serialized
instance
data:
<qname xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:my="http://ns.example.org/2003">my:sample</qname>
In
particular,
note
that
the
XForms
namespace
has
been
serialized.
To
prevent
this
example
from
including
the
unneeded
XForms
namespace
while
maintaining
the
needed
my
prefix,
includenamespaceprefixes="my"
must
be
added
to
the
submission
element.
When
this
attribute
is
present,
the
author
takes
responsibility
to
list
all
namespace
prefixes
not
visibly
utilized
by
the
submitted
instance
data.
The
following
attributes
correspond
(in
spelling,
processing,
and
default
values)
to
attributes
on
the
output
element
of
[
XSLT
1.0
],
with
the
exception
of
using
xsd:boolean
to
replace
"yes"|"no"
:
version
indent
encoding
omit-xml-declaration
cdata-section-elements
Note:
The following XSLT attributes have no counterpart in XForms:
doctype-system
doctype-public
The
table
below
provides
an
overview
of
the
child
elements
of
the
XForms
submission
element,
including
their
attributes
and
content
models.
Elements
defined
in
the
XForms
Actions
module
are
also
allowed
in
the
content
model
of
submission
.
Element | Overview of Attributes and Their Content (after AVT evaluation) | Overview of Content Model |
---|---|---|
resource | value (string Expression) | PCDATA |
method | value (string Expression) | PCDATA |
header |
ref
(node-sequence
Expression),
nodeset
|
name, value+ |
various | various |
The xforms-submit Event
Target:
submission
Bubbles: Yes
Cancelable: Yes
Context Info: None
Under
no
circumstances
can
For
brevity
in
the
following,
the
text
"submission
succeeds"
means
"submission
processing
concludes
after
dispatching
xforms-submit-done
with
appropriate
context
information",
and
the
text
"submission
fails
with
error-code
"
means
"the
submission
processing
concludes
after
dispatching
xforms-submit-error
with
appropriate
context
information,
including
an
error-type
of
error-code
".
Additionally,
"and
an
error-message
of
(some
value)"
means
that
the
context
information
also
includes
an
entry
called
error-message
with
that
value.
No
more
than
a
single
concurrent
submit
process
can
be
under
way
at
any
time
for
a
particular
XForms
submission.
From
the
start
of
the
default
action
of
xforms-submit
for
a
submission
,
until
immediately
before
xforms-submit-done
or
xforms-submit-error
is
dispatched
to
that
submission
,
the
default
action
for
subsequent
xforms-submit
events
dispatched
to
that
submission
is
to
dispatch
xforms-submit-error
to
that
submission
with
context
information
containing
an
error-type
of
submission-in-progress
.
Otherwise, the default action for this event results in the following steps:
-
The
data
model
is
updated
based
on
some
of
the
flags
defined
for
deferred
updates
... Specifically, if the deferred updaterebuild
flag is set for themodel
containing thissubmission
, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred updaterecalculate
flag is set for themodel
containing thissubmission
, then the recalculate operation is performed without dispatching an event to invoke the operation. This sequence of operations affects the deferred update behavior by clearing the deferred update flags associated with the operations performed. -
If
the
binding
attributes
of
submission
indicate an emptynodesetsequence ora nodean item other than an element or an instance document root node, then submissionprocessing is stopped after dispatching event xforms-submit-errorfails withcontext information containing an error-type ofno-data
. Otherwise, the binding attributes ofsubmission
indicate a node of instance data. -
The
indicated
node
and
all
nodes
for
which
it
is
an
ancestor
are
selected.
If
the
attribute
relevant
istrue
, whether by default or declaration, then any selected node which is not relevant as defined in The relevant Property is deselected (pruned). If all instance nodes are deselected, then submissionprocessing is stopped after dispatching event xforms-submit-errorfails withcontext information containing anerror-type of no-datano-relevant-data -
If
the
attribute
validate
istrue
, whether by default or declaration, then all selected instance data nodes are checked for validity according to the definition in The xforms-revalidate Event (no notification events are marked for dispatching due to this operation).,whetherAnyIf any selected instance data nodethatis found to beinvalid stopsinvalid, submissionprocessing after dispatching event xforms-submit-errorfails withcontext information containing an error-type ofvalidation-error
. - The submission method is determined.
-
The
submission
resource
is
determined.
If
the
resource
is
not
specified,
then
submission
processing stops after dispatching even xforms-submit-errorfails withcontext information containing an error-type ofresource-error
. -
If
the
serialization
attribute value is"none"
, then the submission data serialization is the empty string. Otherwise, thesubmission data serialization is determined as follows. Theeventxforms-submit-serialize
isdispatched. Ifdispatched; if thesubmission-body
property of the event is changed from the initial value of empty string, then the content of thesubmission-body
property string is used as thesubmission data serialization
. Otherwise, thesubmission data serialization
consists of a serialization of the selected instance data according to the rules stated inSubmission OptionsSerialization . -
The
submission headers
are determined using the header entries produced by theheader
element(s) in the submission and themediatype
attribute or its default. -
The
submission
is
performed
based
on
the
submission headers
, submission method , submission resource , andsubmission data serialization
. The exact rules of submission are based on the URI scheme and the submission method , as defined in Submission Options .
If
the
mode
of
the
submission
is
asynchronous
,
then
default
processing
for
this
event
ends
after
the
above
steps,
and
submission
processing
is
resumed
once
the
response
from
the
submission
is
returned.
In
the
same
manner
used
to
handle
user-generated
events
or
the
dispatch
and
processing
of
delayed
events,
the
processing
of
the
asynchronous
submission
response
is
done
without
interrupting
the
processing
of
any
other
event
and
its
event
handlers.
If
the
mode
of
the
submission
is
synchronous
,
then
the
XForms
processor
Processor
suspends
user
interaction
with
all
form
controls
of
the
document
and
action
processing
is
blocked
within
the
default
processing
for
this
event
until
the
response
from
the
submission
is
returned.
The
response
returned
from
the
A
submission
with
no
resource
specification
can
be
used
to
test
validity
of
data.
If
the
selected
data
is
applied
as
follows:
invalid,
then
the
xforms-submit-error
has
an
error-type
of
validation-error
.
If
the
selected
data
is
valid,
then
the
xforms-submit-error
has
an
error-type
of
resource-error
.
For
Processing
the
Response
from
a
Submission
For
success
responses,
if
the
response
including
does
not
include
a
body,
when
submission
succeeds;
otherwise,
processing
depends
on
the
value
of
the
replace
attribute
on
element
submission
:
is
"
-
none
: submission succeeds. -
all
: the event",xforms-submit-done
may be dispatched with appropriate context information, and submit processing concludes with the entire containing document being replaced with the returned body. -
For a success response including ainstance
: If the body is not ofan XML mediaa type(as definedaccepted by thecontent type specifiersprocessor, as specified in Creating instance data from external resources , nothing in[ RFC 3023 ]), when the value ofthereplace attribute on element submissiondocument is"replaced and submission fails withinstance ",result-media-typeresponseunacceptable media type. Otherwise the body is parsedas XML.to give an XPath Data Model according to Creating instance data from external resources . If the parse fails, then submissionprocessing concludes after dispatching xforms-submit-errorfails withappropriate context information, including an error-type ofparse-error
.However, ifIf theXMLparse succeeds, then instance data replacement is performed according tothe rules specified inReplacing Data with the Submission Response .This operation may fail for a number of reasons, including if processing of the targetref attribute yields a readonly node (if replace="text" ) or a node that either has a readonly parent or is not an element (if replace="instance" ). InIf thiscase,operation succeeds, submissionends after dispatching event xforms-submit-error with appropriate context information, including an error-type of target-error . Otherwise, the instance data replacementsucceeds.Submission processing then concludes after dispatching xforms-submit-done with appropriate context information. For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [ RFC 3023 ]), when the value of the replace attribute on element submission is " instance ", nothing in the document is replaced and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error . -
For a success response including a body of an XML media type (as defined by the content type specifiers in [ RFC 3023 ]) or a text media type (as defined by a content type of text/* ), when the value of the replace attribute on element submission is "text
: If the", the response is encoded as text. Then, the content replacement is performed according to the rules specified in Replacing Data with the Submission Response .processing of the targetref attribute (including its default) fails, then the submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of target-error . Otherwise, submission processing then concludes after dispatching xforms-submit-done with appropriate context information. For a success response including abodythatisboth a non-XMLneither an XML media type (i.e. with a content type not matching any of the specifiers in [ RFC 3023 ])andnor anon-texttext type (i.e. with a content type not matchingtext/*
),when the value of the replace attribute on element submission is " text ",nothing in the document is replaced and submissionprocessing concludes after dispatching xforms-submit-errorfails withappropriate context information, including anerror-typeresult-text-media-typeresource-error . For a success response including a body, whenthevalue ofunacceptable media type. Otherwise thereplace attribute on element submissioncontent replacement is" none ", submission processing concludes after dispatching xforms-submit-done with appropriate context information. For a success response not including a body, submission processing concludes after dispatching xforms-submit-doneperformed according to Replacing Data withappropriate context information. Behaviors of other possible values for attribute replace are not defined inthe Submission Response . If thisspecification.operation succeeds, submission succeeds.
For
an
error
response,
when
responses,
processing
depends
on
the
value
of
the
replace
attribute
on
element
submission
:
is
"
-
all
: either the document is replaced with an implementation-specific indication of an",errorerror, or submissionprocessing concludes after dispatching xforms-submit-errorfails withappropriate context information, including anerror-type of resource-errorresult-error-response -
For an error response, when the value of the replace attribute on element submission is not " all ",any other value: nothing in the document is replaced, and submissionprocessing concludes after dispatching xforms-submit-errorfails withappropriate context information, including anerror-type of resource-errorresult-error-response
(Further details of the failure are available in the context information).
Behaviors
of
other
possible
values
for
attribute
replace
are
not
defined
in
this
specification.
In
addition
to
initiating
a
submission
with
its
default
processing,
XForms
actions
can
also
provide
handlers
for
the
xforms-submit
event
to
peform
perform
tasks
such
as
data
preparation.
Example:
<submission resource="http://example.com/searchDoctors" method="post" ref="instance('doctorSearchParams')" replace="instance" targetref="instance('doctorList')" > <action ev:event="xforms-submit"> <setvalue ref="diagnosis" value="instance('patientRecord')/malady"/> <setvalue ref="city" value="instance('patientRecord')/city"/> </action> </submission>
The schema for the doctor search service requires certain portions of the patient record in order to provide a list of specialists who could treat the patient. The server-side module may perform database searches for doctors with the required specialties as well as implement business rules such as providing doctors that are within an acceptable distance of the given city. The resulting list is provided to a separate instance so it can be presented to the user for selection or used in subsequent availability searches.
Replacing Data with the Submission Response
First, the replacement target node is determined:
-
if
the
submission
element has neither aninstance
attribute nor atargetref
attribute, the replacement target node is the document element node of the default instance of the model;
-
if
the
submission
element has aninstance
attribute but notargetref
attribute, the replacement target node is the document element node of the instance identified by theinstance
attribute;
-
if
the
submission
element has atargetref
attribute, the attribute value is interpreted as a binding expression to which the first-item rule is applied to obtain the replacement target node. The evaluation context for this attribute is the in-scope evaluation context for thesubmission
element, except the context item is modified to be the document element of the instance identified by theinstance
attribute if present.
Then the target is checked for correctness:
-
if
the
instance
attribute does not indicate an instance in the same model as the submission, submission fails withtarget-model-error
; -
if
the
replacement
target
node
is
an
empty
sequence,
submission
fails
with
target-empty
; -
if
replace="text"
and the replacement target node is a readonly node, or, ifreplace="instance"
and the replacement target node is a node whose parent is readonly, submission fails withtarget-readonly
; -
if
replace="instance"
and the replacement target node is a non-element, submission fails withtarget-non-element
.
Then
the
replacement
is
done
according
to
the
value
of
the
replace
attribute:
text
: the response data is treated as text, regardless of its media type, and used to replace the content of the replacement target node using the XForms Actionsetvalue
( The setvalue Element ).
instance
: the XPath Data Model obtained from the submission response is used to replace the target node. This data may have comment and processing instruction nodes before and after the document element. These nodes are discarded if the replacement target node is not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructions and comments that previously appeared outside of the document element of the instance being replaced. The replacement is performed by an XForms action that performs some combination of node insertion and deletion operations that are performed by theinsert
action ( The insert Element ) and thedelete
action ( The delete Element ).
If
the
submission
has
a
mode
of
"
asynchronous
",
then
the
text
replacement
action
or
the
instance
node
replacement
action
is
an
outermost
action
handler,
so
the
deferred
update
behavior
occurs
at
the
end
of
the
action.
If
the
mode
is
"
synchronous
",
then
the
text
replacement
action
or
the
instance
node
replacement
action
is
not
outermost
since
it
occurs
during
the
default
processing
of
xforms-submit
,
so
the
appropriate
deferred
update
flags
are
set
based
on
whether
the
action
was
a
setvalue
or
whether
it
performed
a
series
of
insert
and
delete
actions.
For
backwards
compatibility
with
earlier
versions
of
this
specification,
the
processor
may
treat
an
attribute
named
target
as
equivalent
to
targetref
as
long
as
there
is
no
targetref
attribute
present.
In
an
asynchronous
submission,
the
deferred
update
behavior
ensures
that
the
user
interface
is
up
to
date
with
the
latest
calculated
values
before
the
xforms-submit-done
event
is
dispatched.
In
a
synchronous
submission,
the
calculated
values
dependent
on
replaced
text
or
data
nodes
can
be
made
available
to
actions
in
the
xforms-submit-done
handler
by
first
invoking
the
recalculate
action.
A
sequence
of
synchronous
submissions
performed
with
successive
send
actions
can
avoid
refreshing
the
user
interface
until
after
the
completion
of
the
last
send
action.
Examples:
<submission resource="http://example.com/jsp/prefill" method="post" ref="name" replace="instance" targetref="address"/>
This
submission
would
be
invoked
after
the
user
enters
a
value
for
name
.
Based
on
the
name
given,
a
simple
server-side
database
lookup
is
performed
to
get
a
last
known
address.
The
address
element
is
replaced
with
the
result,
prefilling
part
of
the
form
for
the
user.
<submission resource="http://example.com/postalCodeSearch" method="get" ref="address" replace="text" targetref="address/postalCode"/>
The
address
information
is
passed
to
a
postal
code
search
service
that
returns
a
textual
result,
which
is
placed
into
the
postalCode
element.
<model> <instance> <data xmlns=""> <name> <first-name>John</first-name> <last-name>Doe</last-name> </name> <address> <street>123 Main St.</street> <city>Smallville</city> </address> </data> </instance> <bind ref="name" readonly="true()"/> <bind ref="address/street" readonly="true()"/> <submission id="S1" targetref="name" replace="instance" method="post" resource="..."/> <submission id="S2" targetref="name/first-name" replace="instance" method="post" resource="..."/> <submission id="S3" targetref="name/first-name" replace="text" method="post" resource="..."/> <submission id="S4" targetref="address/street" replace="text" method="post" resource="..."/> </model>
Submission
S1
succeeds
because
a
readonly
node
(
name
)
can
be
replaced
if
its
parent
is
not
readonly.
Submission
S2
fails
because
a
node
(
first-name
)
cannot
be
replaced
if
its
parent
is
readonly.
Submission
S3
fails
because
the
content
of
a
readonly
node
cannot
be
replaced,
even
if
it
is
readonly
due
to
inheritance.
Submission
S4
fails
because
the
content
of
a
readonly
node
cannot
be
replaced,
even
if
the
node's
parent
is
not
readonly.
The xforms-submit-serialize Event
Dispatched
at
the
beginning
of
submission
serialization
(see
The
xforms-submit
Event
).
Target:
submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
submission-body |
|
A
document
element
node
with
a
QName
of
submission-body
.
The
node
initially
contains
an
empty
string.
Event
handlers
can
write
data
into
the
node.
If
the
string
value
of
this
node
is
non-empty,
then
the
string
value
is
used
in
the
submission
in
lieu
of
the
default
instance
data
serialization.
|
Note:
The
submission-body
property
is
a
string,
but
the
event()
function
encapsulates
the
string
in
a
text
node
so
that
the
string
can
be
modified
by
the
setvalue
action,
which
sets
a
value
into
a
node
determined
by
its
Single
Node
Item
Binding.
Note:
Since
the
submission-body
is
a
string,
this
feature
may
be
used
to
submit
non-XML
data.
Default
Action:
If
the
event
context
submission-body
property
string
is
empty,
then
no
operation
is
performed
so
that
the
submission
will
use
the
normal
serialization
data
(see
The
xforms-submit
Event
).
Otherwise,
if
the
event
context
submission-body
property
string
is
non-empty,
then
the
serialization
data
for
the
submission
is
set
to
be
the
content
of
the
submission-body
string.
Example:
<submission resource="http://example.com/greeter" method="post" mediatype="text/plain"> <setvalue ev:event="xforms-submit-serialize" ref="event('submission-body')" value="my/text"/> </submission>
The
string
value
of
the
element
my/text
is
placed
into
the
node
representing
the
submission
body,
so
that
is
the
text
posted
by
the
submission.
In
this
example,
the
result
returned
by
the
submission
replaces
the
document.
This
feature
could
be
used
to
submit
plain
text,
but
it
could
also
be
used
to
allow
a
document
to
submit
its
serialization
rather
than
just
submitting
instance
data.
The xforms-submit-done Event
Dispatched
as
an
indication
of:
of
successful
completion
of
a
submission
process
Target:
submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
resource-uri | string | The submission resource URI that succeeded (xsd:anyURI) |
response-status-code | number |
The
protocol
return
code
of
the
success
response,
or
NaN
if
the
submission
did
not
receive
a
success
response.
|
response-headers |
|
Zero
or
more
elements,
each
one
representing
a
content
header
in
the
success
response
received
by
the
submission.
The
returned
header
with
no
namespace
URI
and
two
child
elements,
name
and
value
,
whose
string
contents
are
the
name
and
value
of
the
header,
respectively.
|
response-reason-phrase | string | The protocol response reason phrase of the success response. The string is empty if the submission did not receive a response or if the response did not contain a reason phrase. |
Default Action: None; notification event only.
Example:
<submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record"> <send ev:event="xforms-submit-done" submission="chargeForRecord"/> </submission> <submission id="chargeForRecord" resource="https://example.com/chargeForRecord" method="get" serialization="none" replace="none"/>
The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.
The xforms-submit-error Event
Dispatched
as
an
indication
of:
of
failure
of
a
submission
process
Target:
submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error-type | string |
One
of
the
following:
submission-in-progress
,
no-data
,
no-relevant-data
,
validation-error
,
parse-error
,
resource-error
,
,
result-text-media-type
,
result-error-response
,
target-model-error
,
target-empty
,
target-readonly
,
target-non-element
.
|
error-message | string | A message containing further details of the error. |
resource-uri | string | The submission resource URI that failed (xsd:anyURI) |
response-status-code | number |
The
protocol
return
code
of
the
error
response,
or
NaN
if
the
failed
submission
did
not
receive
an
error
response.
|
response-headers |
|
Zero
or
more
elements,
each
one
representing
a
content
header
in
the
error
response
received
by
a
failed
submission.
The
returned
header
with
no
namespace
URI
and
two
child
elements,
name
and
value
,
whose
string
contents
are
the
name
and
value
of
the
header,
respectively.
|
response-reason-phrase | string | The protocol response reason phrase of the error response. The string is empty if the failed submission did not receive an error response or if the error response did not contain a reason phrase. |
response-body |
object
(string
or
|
When
the
error
response
specifies
an
XML
media
type
as
defined
by
[
RFC
3023
],
the
response
body
is
parsed
into
an
XML
document
and
the
root
element
of
the
document
is
returned.
If
the
parse
fails,
or
if
the
error
response
specifies
a
text
media
type
(starting
with
|
Default Action: None; notification event only.
Example:
<submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record"> <message ev:event="xforms-submit-error">A submission error (<output value="event('error-type')"/>) occurred.</message> </submission>
The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.
The Submission Resource
The
submission
resource
is
the
URI
for
the
submission.
It
is
of
type
xsd:anyURI
.
In
XForms
1.0,
the
URI
for
submission
was
provided
by
the
action
attribute.
For
consistency,
form
authors
should
now
use
the
attribute
resource
of
type
xsd:anyURI
,
which
deprecates
the
action
attribute.
If
both
action
and
resource
are
present,
then
the
resource
attribute
takes
precedence.
The
resource
element
provides
the
submission
URI,
overriding
the
resource
attribute
and
the
action
attribute.
If
a
submission
has
more
than
one
resource
child
element,
the
first
resource
element
child
must
be
selected
for
use.
Individually,
the
resource
element,
the
resource
attribute
and
the
action
attribute
are
not
required.
However,
one
of
the
three
is
mandatory
as
there
is
no
default
submission
resource.
The resource Element
The
resource
element
(deprecated
in
favor
of
using
an
AVT
in
the
resource
attribute)
allows
the
URI
used
for
a
submission
to
be
dynamically
calculated
based
on
instance
data.
Common
Attributes:
None
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
URI,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
URI
to
be
used
by
the
submission
can
be
specified
with
either
the
value
attribute
or
the
string
content
of
the
resource
element.
If
both
are
specified,
then
the
value
attribute
takes
precedence.
If
the
submission
does
not
have
a
resource
child
element,
then
the
submission
URI
is
obtained
from
the
resource
attribute
or
the
action
attribute.
Example:
<submission method="post"> <resource value="instance('params')/anyURI"/> </submission>
This is now deprecated in favour of the equivalent:
<submission method="post" resource="{instance('params')/anyURI}"/>
The Submission Method
The
submission
method
indicates
the
submission
protocol
operation
to
be
performed.
The
submission
method
may
be
specified
by
the
method
attribute.
The
submission
element
can
have
a
child
element
named
method
,
which
overrides
the
submission
method
setting
obtained
from
the
method
attribute
if
both
are
specified.
If
more
than
one
method
element
is
given,
the
first
occurrence
in
document
order
must
be
selected
for
use.
Individually,
the
method
element
and
the
method
attribute
are
not
required.
However,
one
of
the
two
is
mandatory
as
there
is
no
default
submission
method.
The method Element
The
method
element
(deprecated
in
favor
of
using
an
AVT
in
the
method
attribute)
allows
the
submission
method
to
be
dynamically
calculated
based
on
instance
data.
Common
Attributes:
None
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
method,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
method
to
be
used
by
the
submission
can
be
specified
with
either
the
value
attribute
or
the
string
content
of
the
method
element.
If
both
are
specified,
then
the
value
attribute
takes
precedence.
If
the
submission
does
not
have
a
method
child
element,
then
the
submission
method
is
obtained
from
the
method
attribute.
The header Element
The
header
element
can
be
used
to
contribute
information
to
the
preamble
of
a
submission
in
a
manner
appropriate
to
the
protocol.
The
submission
element
can
contain
zero
or
more
header
child
elements.
Each
produces
zero
or
more
header
entries
containing
a
name,
a
value,
and
a
combination.
The
entries
are
provided
to
the
submission
protocol
in
the
specified
order.
It
is
the
responsibility
of
the
submission
protocol
implementation
to
combine
the
entries
and
to
serialize
the
result
into
submission
protocol
headers.
Accordingly,
entries
may
be
re-ordered,
combined,
or
otherwise
altered
in
accordance
with
the
specific
protocol
implementation
requirements.
Common
Attributes:
None
Common
Special Attributes:
-
nodesetref -
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
One
or
more
header
entries
are
generated
for
each
nodeitem selected by this attribute. - nodeset
-
Deprecated
synonym
for
attribute
ref
. Ifref
is present,nodeset
has no meaning. - name
-
Author-optional
string;
this
attribute
overrides
the
name
child element if present. - value
-
Author-optional
string;
this
attribute
overrides
all
value
child elements present; - combine
-
Author-optional
attribute
defaulting
to
"append"
and
with
legal
values
of
"append",
"prepend",
and
"replace".
This
attribute
controls
the
method
of
combination
for
entries
produced
by
this
element
headerhea/code> attribute but no derheader
elements. This attribute and its default also provide information for the protocol implementation, which may use some or all of the information to combine XForms submission headers with headers provided by the user agent.
Content:
(
name
,
value
+)
|
(
value
+,
name
)
-
If
the
header
elementdoes not containcontains anodesetnamethen one header entryit iscreatedused foreachname of the headers being produced; otherwise there must be avaluenameelement.child element, which is used instead. If the name evaluates to the empty string, no header is produced.
-
If
the
header
element contains aref
(or deprecatednodeset
) attribute, then for each selectednode, oneitem, the values are evaluated; otherwise the values are evaluated once.
-
The
values
are
evaluated
as
follows:
if
the
header
entry is created for eachelement has avalue
element. Theattribute, one header is produced using the nameand valueof the headerentry are obtained from the required child elements name ( The name Element )being produced, and the evaluated content of thevalue
( The value Element ). If the name obtained from theattribute; otherwise there must be one or morenamevalueelement is the empty string, then thechild elements, and one headerentryisomitted.produced pervalue
child element.
The header entry order is determined as follows:
-
document
order
of
header
elements -
nodeitem order ofnodesitems inref
(or deprecatednodeset
) attribute -
document
order
of
value
elements
The application of this order information to header serialization is determined by the submission protocol.
If
a
header
element
defines
the
Content-type
header,
then
this
setting
overrides
a
Content-type
set
by
the
mediatype
attribute.
In the case of a multipart submission, the header entries are combined with those for the first part of the submission.
Example:
In
the
example
below,
the
submission
request
uses
the
header
element
to
replace
the
user
agent's
existing
value
of
the
HTTP
Accept
header
with
application/sparql-results+xml
.
<submission id="loadConcepts" resource="http://example.com/taxonomy/concepts" method="get" ref="instance('conceptsList')" replace="instance"> <header combine="replace"> <name>Accept</name> <value>application/sparql-results+xml</value> </header> </submission>
Example:
This example produces 2 headers:
Content-Type: application/xml Accept: application/xml,text/json
<instance id="headers"> <my-headers> <my-header><name>Content-Type</name><value>application/xml</value></my-header> <my-header><name>Accept</name><value>application/xml,text/json</value></my-header> </my-headers> </instance> <submission ...> <header ref="instance('headers')/my-header" name="{name}" value="value"/> </submission>
The name Element
When
the
name
element
appears
as
a
child
of
element
header
,
it
is
used
to
specify
the
name
of
a
header
entry
to
be
provided
to
the
submission
protocol.
Common
Attributes:
None
Common
If
the
model
attribute
is
expressed
in
a
name
child
element
of
a
header
element,
then
an
(
xforms-binding-error
)
occurs
if
the
identified
model
is
not
the
containing
model
element.
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
header
name,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
The
header
entry
name
may
be
given
by
the
string
content
of
the
name
element,
or
by
the
result
of
the
value
attribute.
If
both
are
given,
the
result
from
the
value
attribute
takes
precedence.
If
the
resulting
name
is
the
empty
string,
then
the
entry
is
considered
to
be
void,
and
it
is
not
supplied
to
the
submission
protocol.
The value Element
When
the
value
element
appears
as
a
child
of
element
header
,
it
is
used
to
specify
the
value
component
of
a
header
entry
to
be
supplied
to
the
submission
protocol
to
be
added
to
the
preamble
of
a
submission.
The
value
element
may
be
used
more
than
once
in
a
given
element
header
,
in
which
case
each
value
produces
a
new
header
entry.
Common
Attributes:
None
Common
If
the
model
attribute
is
expressed
in
a
value
child
element
of
a
header
element,
then
an
(
xforms-binding-error
)
occurs
if
the
identified
model
is
not
the
containing
model
element.
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
header
entry
value,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
The
header
entry
value
may
be
given
by
the
string
content
of
the
value
element,
or
by
the
result
of
the
value
attribute.
If
both
are
given,
the
result
from
the
value
attribute
takes
precedence.
Note:
The
string
conversion
function
as
described
in
the
expression
module
combines
multiple
nodes
items
by
concatenating
them
into
a
string
separated
with
spaces.
As
a
result,
a
header
value
specified
by
a
value
element
nodeset
sequence
containing
multiple
nodes
items
may
not
be
properly
serialized
in
a
submission
protocol
preamble.
To
assure
proper
delivery
of
individual
header
items
to
the
submission
protocol,
restrict
use
of
expressions
producing
nodesets
sequences
for
element
header
with
attribute
ref
(or
deprecated
nodeset
),
where
each
,
node
item
will
produce
its
own
separate
header
entry,
and
use
expressions
resulting
in
only
a
single
node
item
in
element
value
.
Submission Options
The
XForms
Model
specifies
a
submission
element
containing
the
following
attributes
and
child
elements
that
affect
serialization
and
submission.
This
section
summarizes
the
behaviors
for
the
allowable
values
of
these
attributes
and
child
elements,
and
presents
subsections
that
define
the
behavior
for
submission
and
serialization.
- the submission resource
- the submission method
-
the
header
elements
For the submission protocol obtained from the URI scheme in the submission resource , XForms normatively defines a binding to HTTP/1.1 [ RFC 2616 ], and to HTTPS [ RFC 2818 ].
Note:
Other
bindings,
in
particular
to
the
URI
scheme
"mailto:"
may,
and
the
schemes
"https:"
and
scheme
"file:"
should,
be
supported.
Bindings
to
these
schemes
are
not
normatively
defined
in
XForms.
Implementations
that
choose
to
provide
a
binding
to
these
schemes
should
pay
particular
attention
to
privacy
and
security
concerns.
Within
the
"http:"
and
"https:"
schemes,
form
creators
are
encouraged
to
follow
the
finding
of
the
W3C
Technical
Architecture
Group
on
when
to
use
the
GET
method:
[
TAG
Finding
7
]
The submission method determines the default data serialization format, and both the submission method and the URI scheme in the submission resource determine the submission protocol operation, according to the following table:
URI scheme | Default Serialization | Submission Protocol Operation | |
---|---|---|---|
http https mailto | "post" |
application/xml
|
HTTP POST or equivalent |
http https file | "get" |
application/x-www-form-urlencoded
|
HTTP GET or equivalent |
http https file | "delete" |
application/x-www-form-urlencoded
|
HTTP DELETE or equivalent |
http https file | "put" |
application/xml
|
HTTP PUT or equivalent |
http https mailto | "multipart-post" |
multipart/related
|
HTTP POST or equivalent |
http https mailto | "form-data-post" |
multipart/form-data
|
HTTP POST or equivalent |
http https mailto | "urlencoded-post" |
application/x-www-form-urlencoded
|
HTTP POST or equivalent |
(any) |
Any other NCName |
application/xml
|
As given by the Submission Method |
(any) | implementation-defined | implementation-defined |
Note:
Foreign-namespaced attribute values are allowed in the Submission Method , but no behavior is defined by XForms.
The get Submission Method
This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.
This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See [ RFC 2616 ] for recommended uses of HTTP GET.
The URI is constructed as follows:
-
The
submit
URI
is
examined.
If
it
does
not
already
contain
a
?
(question mark) character, one is appended. If it does already contain a question mark character and the serialized form data is non-empty, then a separator character from the attributeseparator
is appended. - The serialized form data, if any, is appended to the URI.
No message body is sent with the request.
Examples:
<submission resource="http://example.com/search" method="get"/>
After
doing
relevance
and
validity
checking
on
the
data,
the
leaf
nodes
of
the
default
instance
are
submitted
asynchronously,
encoded
as
a
URL
(
application/x-www-form-urlencoded
),
to
http://example.com/search
.
The
result
replaces
the
whole
page.
<submission resource="file:data.xml" method="get" serialization="none" replace="instance" instance="data" />
Replaces the instance 'data' with the content of the file data.xml. Serialization, and its associated validity and relevance processing, is not needed. See the corresponding example for saving a file in Section The put Submission Method . The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.
The post, multipart-post, form-data-post, and urlencoded-post Submission Methods
These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.
Examples:
<submission resource="https://example.com/jsp/orders" method="post" ref="/purchaseOrder" />
Submits the XML for a purchase order to a secure server order processing system.
<submission resource="http://example.com/login" method="urlencoded-post"/>
After
doing
relevance
pruning
and
validity
checking
on
the
login
data,
the
leaf
nodes
of
the
default
instance
are
submitted
asynchronously
in
the
posted
data,
encoded
based
on
the
application/x-www-form-urlencoded
serialization,
to
http://example.com/login
.
The
result
replaces
the
whole
page.
The put Submission Method
This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.
Example:
<submission resource="file:data.xml" ref="instance('data')" method="put" validate="false" relevant="false" replace="none" />
Saves the instance 'data' to the file data.xml without validation checking and relevance pruning. See the corresponding example for reading from a local file in Section The get Submission Method . The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.
The delete Submission Method
This submit method represents HTTP DELETE or the equivalent concept (such as deleting a local file). The serialized form data is delivered in the same manner as the get submission method (see The get Submission Method ).
Serialization
Serialization as application/xml
This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is capable of submission of binary content.
The steps for serialization are as follows:
-
An
XML
document
is
produced
following
the
rules
of
the
XML
output
method
defined
in
[
XSLT
1.0
]
section
16
and
16.1,
using
the
values
supplied
as
attributes
of
the
submission
element.-
Handling
of
namespace
nodes:
The
default
behavior
is
that
every
namespace
node
is
serialized
according
to
the
rules
of
the
XML
output
method,
so
that
at
least
one
namespace
declaration
appears
in
the
serialized
XML
for
each
in-scope
namespace.
Additional
inherited
namespaces
are
declared
on
the
root
element
of
the
serialized
XML.
If,
however,
attribute
includenamespaceprefixes
on elementsubmission
is present, then all namespace declarations not visibly utilized in the instance data (as defined in [ Exc-C14N ]) and the default namespace if it is empty are excluded from the root element serialization, unless the corresponding namespace prefix is listed in theincludenamespaceprefixes
attribute. The special value#default
represents the default namespace. -
Mediatype:
By
default,
the
mediatype
of
the
serialized
XML
instance
is
application/xml
, but can be changed to a compatible type using elementsubmission
attributemediatype
. Authors should ensure that the type specified is compatible withapplication/xml
.
-
Handling
of
namespace
nodes:
The
default
behavior
is
that
every
namespace
node
is
serialized
according
to
the
rules
of
the
XML
output
method,
so
that
at
least
one
namespace
declaration
appears
in
the
serialized
XML
for
each
in-scope
namespace.
Additional
inherited
namespaces
are
declared
on
the
root
element
of
the
serialized
XML.
If,
however,
attribute
We are considering adding extra serialization parameters added by http://www.w3.org/TR/xslt-xquery-serialization/ , but are waiting for further implementation experience and user feedback, to decide which serialization parameters to add.
This
format
is
intended
for
integration
of
XForms
into
environments
that
involve
large
amounts
of
binary
data
where
the
inclusion
of
the
data
as
xsd:base64Binary
or
xsd:hexBinary
is
undesirable.
In
this
format,
XML
instance
data
is
serialized
as
one
part
of
the
[
RFC
2387
]
multipart/related
message,
using
the
rules
as
described
in
Serialization
as
application/xml
.
Binary
content
from
xsd:anyURI
instance
nodes
populated
by
the
upload
(see
The
upload
Element
)
control
is
serialized
in
separate
parts
of
the
[
RFC
2387
]
multipart/related
message.
This
format
follows
the
rules
of
multipart/related
MIME
data
streams
for
in
[
RFC
2387
],
with
specific
requirements
of
this
serialization
listed
below:
-
multipart/related
message header requirements:-
Must
contain
a
type
parameter of the mediatype of the serialized XML instance. -
Must
contain
a
start
parameter referring to the Content-ID first body part (root).
-
Must
contain
a
-
First
body
part
(root)
requirements:
-
Must
have
Content-Type
parameter of the type specified by thesubmission
mediatype
attribute. - Content is serialized by the rules at Serialization as application/xml .
-
Must
have
-
Subsequent
part
requirements:
-
One
part
for
each
node
with
a
datatype
of
xsd:anyURI
populated byupload
with:-
A
Content-Type
header that represents the type of the attachment if known, otherwiseapplication/octet-stream
. -
A
Content-Transfer-Encoding
header. -
A
Content-ID
header whose value matches the URI in the associated instance data node. -
The
binary
content
associated
with
the
URI,
serialized
according
to
the
Content-Transfer-Encoding
heading.
-
A
-
One
part
for
each
node
with
a
datatype
of
<submission method="multipart-post" resource="http://example.com/photo" />
Submits
the
instance
data
in
multipart/related
,
along
with
the
selected
file
as
an
attachment.
POST /photo HTTP/1.0 Host: example.comContent-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>"Content-Type: multipart/related; boundary=f93dcbA3; type="application/xml"; start="<980119.X53GGT@example.com>" Content-Length: xxx--f93dcbA3
--f93dcbA3 Content-Type: application/xml; charset=UTF-8 Content-ID: <980119.X53GGT@example.com><?xml version="1.0"?>
<?xml version="1.0"?> <uploadDocument> <title>My Proposal</title> <author>E. X. Ample</author> <summary>A proposal for a new project.</summary> <notes image="cid:980119.X17AXM@example.com">(see handwritten region)</notes> <keywords>project proposal funding</keywords> <readonly>false</readonly> <filename>image.png</filename> <content>cid:980119.X25MNC@example.com</content> </uploadDocument> --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X25MNC@example.com>...Binary data here...
...Binary data here... --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X17AXM@example.com>...Binary data here...
...Binary data here... --f93dcbA3--
Serialization as multipart/form-data
This format is for legacy compatibility to permit the use of XForms clients with [ RFC 2388 ] servers. This method is suitable for the persistence of binary content. Contextual path information, attribute values, namespaces and namespace prefixes are not preserved. As a result, different elements might serialize to the same name.
Note:
Existing
HTML
user
agents
fail
to
encode
special
characters
(such
as
double
quotes)
and
non-ASCII
characters
in
the
Content-Disposition:
form-data
name
and
filename
parameters.
Since
this
serialization
method
is
supported
for
legacy
applications
only,
new
applications
should
use
application/xml
or
multipart/related
.
This
format
follows
the
rules
for
multipart/form-data
MIME
data
streams
in
[
RFC
2388
],
with
specific
requirements
of
this
serialization
listed
below:
-
Each
element
node
is
visited
in
document
order,
except
non-relevant
elements
are
skipped
if
the
relevant
setting of thesubmission
istrue
. - Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node).
-
Element
nodes
selected
for
inclusion
are
encoded
as
Content-Disposition: form-data
MIME parts as defined in [ RFC 2388 ], with thename
parameter being the element local name. -
Element
nodes
of
any
datatype
populated
by
upload
also have aContent-Disposition
filename
parameter, if the filename is available. -
Element
nodes
of
any
datatype
populated
by
upload
are serialized as the specified binary content. In the case ofxsd:anyURI
and derived types, the serialization content is obtained from the URI. Forxsd:base64Binary
,xsd:hexBinary
, and derived types, the serialization content is obtained by decoding the element string value. -
Element
nodes
of
any
datatype
not
populated
by
upload
are serialized as the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children). -
The
Content-Type
must betext/plain
except forxsd:anyURI
,xsd:base64Binary
,xsd:hexBinary
, and derived types, in which case the header represents the media type of the attachment if known, otherwiseapplication/octet-stream
. If a character set is applicable, theContent-Type
may have acharset
parameter.
Example:
<submission method="form-data-post" resource="http://example.com/photo" />
Submits
the
instance
data
in
multipart/form-data
,
along
with
the
selected
file
as
a
part.
POST /photo HTTP/1.0 Host: example.com Content-Type: multipart/form-data; boundary=AaB03x Content-Length: xxx--AaB03x
--AaB03x Content-Disposition: form-data; name="document"; filename="b.txt" Content-Type: text/plain; charset=iso-8859-1 This is a file. It has two lines. --AaB03x Content-Disposition: form-data; name="title" A File --AaB03x Content-Disposition: form-data; name="summary" This is my file file test --AaB03x--
Serialization as application/x-www-form-urlencoded
This
format
represents
an
extension
of
the
[
XHTML
1.0
]
form
content
type
application/x-www-form-urlencoded
with
specific
rules
for
encoding
non-ASCII
and
reserved
characters.
This format is not suitable for the persistence of binary content. Therefore, it is recommended that forms capable of containing binary content use another serialization method.
The steps for serialization are as follows:
-
Each
element
node
is
visited
in
document
order,
except
non-relevant
elements
are
skipped
if
the
relevant
setting of thesubmission
istrue
. Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node). Note that attribute information is not preserved. -
Element
nodes
selected
for
inclusion
are
encoded
as
EltName=value
, where=
is a literal character,EltName
represents the element local name, andvalue
represents the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children). The separator character {sep} from theseparator
attribute onsubmission
is used between pairs of encoded name/value pairs, e.g.EltName1=value1{sep}EltName2=value2{sep}EltName3=value3
. Note that contextual path information is not preserved, nor are namespaces or namespace prefixes. As a result, different elements might serialize to the same name.-
The
encoding
of
EltName
andvalue
are as follows: space characters are replaced by+
, and then non-ASCII and reserved characters (as defined by [ RFC 2396 ] as amended by subsequent documents in the IETF track) are escaped by replacing the character with one or more octets of the UTF-8 representation of the character, with each octet in turn replaced by%HH
, whereHH
represents the uppercase hexadecimal notation for the octet value and%
is a literal character. Line breaks are represented as "CR LF" pairs (i.e.,%0D%0A
).
-
The
encoding
of
- All such encodings are concatenated, maintaining document order.
Example:
GivenName=Ren%C3%A9
This format consists of simple name-value pairs.
<PersonName title="Mr"><GivenName>René</GivenName><GivenName>René</GivenName> </PersonName>
Here is the instance data for the above example. Note that very little of the data is preserved. Authors desiring greater data integrity should select a different serialization format.
Integration with SOAP
This section describes the integration of XForms submission with [ SOAP 1.1 ] and [ SOAP 1.2 ]
Representation of SOAP Envelope
The
single-node
binding
Single
Item
Binding
of
the
submission
element
refers
to
the
XML
data
to
be
submitted.
In
the
case
of
a
SOAP
submission,
the
instance
data
includes
the
SOAP
envelope
and
related
SOAP
tags.
Note:
The
form
author
may
choose
to
store
the
data
payload
in
one
instance
and
copy
the
data
to
the
submission
instance
containing
the
SOAP
envelope
as
part
of
an
xforms-submit
event
handler.
The
form
author
is
responsible
for
declaring
the
appropriate
model
item
properties
on
both
instances
(e.g.
the
relevant
declarations).
Indicating a SOAP submission
For
a
SOAP
submission,
the
mediatype
attribute
of
the
submission
must
be
set
to
the
MIME
type
of
application/soap+xml
.
The
form
author
may
append
charset
and
action
MIME
parameters.
Note:
The
action
MIME
parameter
has
no
effect
unless
the
submission
method
is
"post"
because
the
GET
method
implies
no
SOAP
processing
by
the
receiving
SOAP
node.
Note:
SOAP 1.1 does not support the HTTP GET operation.
SOAP HTTP Binding
The
method
attribute
of
the
submission
must
be
set
to
get
or
post
in
order
to
access
the
SOAP
HTTP
binding.
If
method="get"
,
then
the
SOAP
response
message
exchange
pattern
is
used.
The
HTTP
headers
must
contain
the
Accept
parameter
with
a
value
conforming
to
the
following
properties:
-
must
begin
with
application/soap+xml
-
If
the
submission
mediatype
contains acharset
MIME parameter, then it is appended to theapplication/soap+xml
MIME type. Otherwise, acharset
MIME parameter with same value as theencoding
attribute (or its default) is appended to theapplication/soap+xml
MIME type. -
No
other
MIME
parameters
from
the
mediatype
are copied to theapplication/soap+xml
MIME type -
The
q
MIME parameter must not be specified in theapplication/soap+xml
MIME type so that the default quality of 1 is used.
If
method="post"
,
then
the
SOAP
request-response
message
exchange
pattern
is
used.
For
SOAP
1.2,
the
current
submission
behavior
of
using
the
mediatype
attribute
value
as
the
value
of
the
Content-type
parameter
in
the
HTTP
headers
is
sufficient.
If
the
instance
data
being
submitted
has
as
its
root
element
node
a
SOAP
envelope
in
the
SOAP
1.1
namespace
(
http://schemas.xmlsoap.org/soap/envelope/
),
then:
-
the
Content-type
HTTP header is changed totext/xml
-
the
charset
MIME parameter is appended . The charset parameter value from themediatype
attribute is used if it is specified. Otherwise, the value of theencoding
attribute (or its default) is used. -
if
the
action
MIME parameter appears in themediatype
then a SOAPAction HTTP header is added and given a value equal to the content of theaction
MIME parameter
Note:
XForms
2.0
does
not
support
the
SOAP
email
binding,
so
method="post"
with
a
mailto:
scheme
results
in
an
xforms-submit-error
event
before
any
submit
processing
message
is
dispatched.
Note:
XForms 2.0 does not support the SOAP 1.1 binding to the HTTP Extension Framework.
Example:
<model xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.webservice.net"> <instance id="data"> <city>Victoria</city> <country>Canada</country> <weather>Mostly sunny and cool. High 12C. Low 3C.</weather> </instance><instance id="GetWeatherSoapIn">
<instance id="GetWeatherSoapIn"> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetWeather xmlns="http://www.webservice.net"> <CityName>Victoria</CityName> <CountryName>Canada</CountryName> </GetWeather> </soap:Body> </soap:Envelope> </instance> <instance id="GetWeatherSoapOut"> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <GetWeatherResponse xmlns="http://www.webservice.net"> <GetWeatherResult>Mostly sunny and cool. High 12C. Low 3C.</GetWeatherResult> </GetWeatherResponse> </soap:Body> </soap:Envelope> </instance><submission id="GetWeather" resource="" method="post"
<submission id="GetWeather" resource="http://www.webservice.net/getweather.asmx" method="post" ref="instance('GetWeatherSoapIn')" mediatype="application/soap+xml; action=http://www.webservice.net/GetWeather" replace="instance" instance="GetWeatherSoapOut"> <action ev:event="xforms-submit"> <setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CityName" value="instance('data')/city"/> <setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CountryName" value="instance('data')/country"/> </action> <action ev:event="xforms-submit-done"> <setvalue ref="instance('data')/weather" value="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeatherResponse/tns:GetWeatherResult"/> </action> </submission> </model><input ref="city">
<input ref="city"> <label>City </label> <send ev:event="xforms-value-changed" submission="GetWeather"/> </input> <input ref="country"> <label>Country </label> <send ev:event="xforms-value-changed" submission="GetWeather"/> </input> <output ref="weather"> <label>The weather forecast is </label> </output>
This
form
accepts
input
of
a
city
name
and
country
name
from
the
user.
When
the
user
changes
either
value,
the
'GetWeather'
web
service
is
initiated.
On
xforms-submit
,
the
user
input
is
copied
into
the
request
envelope.
When
the
web
service
submission
result
is
received,
the
xforms-submit-done
handler
copies
the
weather
forecast
from
the
response
envelope
to
the
data
instance.
The submission and the request and response instances correspond to the web service definition below:
<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.webservice.net" targetNamespace="http://www.webservice.net"> <wsdl:types> <xs:schema elementFormDefault="qualified" targetNamespace="http://www.webservice.net"> <xs:element name="GetWeather"> <xs:complexType> <xs:sequence> <xs:element minOccurs="0" maxOccurs="1" name="CityName" type="xs:string" /> <xs:element minOccurs="0" maxOccurs="1" name="CountryName" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="GetWeatherResponse"> <xs:complexType> <xs:sequence> <xs:element minOccurs="0" maxOccurs="1" name="GetWeatherResult" type="xs:string" /> </xs:sequence> </xs:complexType> </xs:element> ... </wsdl:types><wsdl:message name="GetWeatherSoapIn">
<wsdl:message name="GetWeatherSoapIn"> <wsdl:part name="parameters" element="tns:GetWeather" /> </wsdl:message> <wsdl:message name="GetWeatherSoapOut"> <wsdl:part name="parameters" element="tns:GetWeatherResponse" /> </wsdl:message> ... <wsdl:portType name="GetWeatherSoap"> <wsdl:operation name="GetWeather"> <wsdl:input message="tns:GetWeatherSoapIn" /> <wsdl:output message="tns:GetWeatherSoapOut" /> </wsdl:operation> ... </wsdl:portType> ... <wsdl:binding name="GetWeatherSoap" type="tns:GetWeatherSoap"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" /> <wsdl:operation name="GetWeather"> <soap:operation soapAction="http://www.webservice.net/GetWeather" style="document" /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> ... </wsdl:binding><wsdl:service name="GetWeatherService">
<wsdl:service name="GetWeatherService"> <wsdl:port name="GetWeatherSoap" binding="tns:GetWeatherSoap"> <soap:address location="http://www.webservice.net/getweather.asmx" /> </wsdl:port> ... </wsdl:service> </wsdl:definitions>
Handling the SOAP Response
The
XForms
processor
Processor
must
handle
client
authorization
and
redirection.
SOAP
faults
(400
and
500
level
errors)
are
handled
in
the
same
manner
as
underlying
HTTP
errors,
which
is
to
say
that
an
xforms-submit-error
event
is
dispatched.
On
successful
completion,
the
results
are
consumed
according
to
the
XForms
submission
process,
culminating
in
an
xforms-submit-done
event.
The
form
author
may
capture
this
event
and
copy
data
from
the
target
instance
that
receives
the
returned
SOAP
envelope
to
other
instances
that
are
designed
to
carry
only
data.
Core Form Controls
This chapter covers the XForms view layer features for directly interacting with instance data and properties from the XForms Model. This includes features that provide data from the model to the view layer as well as features of the view layer that commit data collected from the user to the model.
The XForms Core Form Controls Module
Form
controls
are
declared
using
markup
elements,
and
their
behavior
refined
via
markup
attributes.
The
core
form
controls
are
described
in
this
module,
including
their
attributes
and
their
content
models
(their
metadata
elements).
models.
A
core
form
control
is
an
element
that
acts
as
a
direct
point
of
user
interaction
and
often
provides
read,
write,
or
read/write
access
to
a
node
of
instance
data.
See
Section
Container
Form
Controls
for
a
description
of
container
form
controls.
Core Form Control Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
|
| |
|
| |
|
| |
Control
Common
,
|
||
|
||
|
| |
|
| |
|
| |
|
| |
|
|
Note:
Unless
bound
to
form
controls,
instance
data
nodes
are
not
presented
to
the
user;
consequently,
there
is
no
need
for
a
form
control
corresponding
to
HTML
input
type="hidden"
.
The following table summarizes additional support elements for form controls.
Support Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
Appearance
,
Single
|
(PCDATA|( UI Content ))* | |
Common
,
Appearance
,
Single
|
(PCDATA|( UI Content ))* | |
Common
,
Appearance
,
Single
|
(PCDATA|( UI Content ))* | |
Common
,
Appearance
,
Single
|
(PCDATA|( UI Content ))* | |
EMPTY | ||
EMPTY | ||
Common
,
Single
|
EMPTY | |
choices (for selection controls) |
Common , label (xsd:string) |
label?, ( List UI Common )+ |
item (for selection controls) |
| |
value (for selection controls) |
Common
,
Single
|
PCDATA |
|
label, (value|copy), ( UI Common )* | |
copy
| Common , Single Item Binding (author-optional) | EMPTY |
Common attribute and content sets
The
following
attributes
and
attribute
sets
are
common
to
many
user-interface
related
XForms
elements,
here
called
the
elements.
- Control Common
Element Attributes and their Content (after AVT evaluation) (various) Common , Appearance , UI Common
attribute group., Single Item Binding
- appearance
Element Attributes and Their Content (after AVT evaluation) (various) appearance ("full"|"compact"|"minimal" | QNameButNotNCName )
- Author-optional attribute to define an appearance hint. If absent, the user agent may freely choose any suitable rendering.
- inputmode
- Author-optional. Used when a control accepts text input, this attribute gives a hint about the sort of text that is expected by the control. See Input Modes for details.
- incremental
-
Author-optional.
By
default,
controls
with
node
bindings
normally
update
the
instance
data
when
the
control
loses
focus.
When
true
, this attribute indicates that the form control will update the instance data more often, thereby generating additionalxforms-value-changed
events. The default value for this attribute isfalse
.
- UI Common
XForms controls may specify values for labels, help, hint, and alert either via attributes, or via child elements. Unless otherwise stated, a control must have either a label attribute or a label child element. All the other values are optional.Element Attributes and their Content (after AVT evaluation) (various) label (xsd:string) | help (xsd:string) | hint (xsd:string) | alert (xsd:string)
<input ref="price" label="Unit Price" alert="Must be greater than 0"/> <input ref="price"><label>Unit Price</label><alert>Must be greater than 0</alert></input> <input ref="price" label="{instance('msg')/price}"/>
Note:
A
host
language
is
expected
to
add
attributes
such
as
xml:lang
as
well
as
an
attribute,
named
class
,
that
holds
a
list
of
strings
that
can
be
matched
by
CSS
class
selectors.
Further,
a
host
language
must
provide
a
way
to
indicate
overall
navigation
order
among
form
controls
and
other
elements
included
in
the
host
language,
as
well
as
keyboard
or
direct
access
navigation
to
specific
elements.
One
such
proposal
is
to
uses
a
pair
of
attributes
named
navindex
and
accesskey
,
defined
as
follows:
- navindex
- This author-optional attribute is a non-negative integer in the range of 0-32767 used to define the navigation sequence. This gives the author control over the sequence in which form controls are traversed. The default navigation order is specified in the chapter Processing Model .
- accesskey
- This author-optional attribute defines a shortcut for moving the input focus directly to a particular form control . The value of this is a single character which when pressed together with a platform specific modifier key (e.g., the alt key) results in the focus being set to this form control .The user agent must provide a means of identifying the accesskeys that can be used in a presentation. This may be accomplished in different ways by different implementations, for example through direct interaction with the application or via the user's guide. The accesskey requested by the author might not be made available by the player (for example it may not exist on the device used, or it may be used by the player itself). Therefore the user agent should make the specified key available, but may map the accesskey to a different interaction behavior.
Additionally,
this
This
module
also
defines
the
following
content
sets:
Content Set | Minimal Content Model |
---|---|
UI Common |
|
List UI Common |
|
Core Form Controls |
|
UI Content |
|
As shown above, the XML Events module adds the Actions content set into the UI Common content set. A host language may add markup to the UI Content set. When the XForms Extension module is present, it too should be included in the UI Common content set.
Implementation Requirements Common to All Form Controls
XForms user interface controls are bound to the underlying instance data using binding attributes as defined in the chapter Model Item Properties .
Form controls enable accessibility by taking a uniform approach to such features as labels, help text, navigation, and keyboard shortcuts. Internationalization issues are addressed by following the same design principles as in XHTML. All form controls are suitable for styling as aural or visual media.
Form
controls
encapsulate
high-level
semantics
without
sacrificing
the
ability
to
deliver
real
implementations.
For
instance,
the
form
control
select
enables
the
user
to
select
items
from
a
set
.
These
form
controls
distinguish
the
functional
aspects
of
the
underlying
control
from
the
presentational
and
behavioral
aspects.
This
separation
enables
the
expression
of
the
intent
underlying
a
particular
form
control
—
see[
see
[
AUI97
]
for
a
definition
of
such
high-level
user
interaction
primitives.
Form controls when rendered display the underlying data values to which they are bound. While the data presented to the user through a form control must directly correspond to the bound instance data, the display representation is not required to match the lexical space value of the bound instance data. For example, user agents should apply appropriate conventions to the display of dates, times, durations and numeric values including separator characters.
All form controls must meet the following implementation requirements:
-
All
form
controls,
including
container
form
controls
,
should
have
an
inline
layout
by
default
(e.g.
for
a
host
language
that
supports
CSS
,
the
default
styling
should
be
display:inline
). By default, repeat items should have a block layout (e.g. a default styling ofdisplay:block
for host languages that support CSS). -
If
a
form
control
violates
its
data
binding
restriction,
an
xforms-binding-exceptionxforms-binding-errorNote: Form controls that read or write simpleContent produce this exception whenever and as soon as they are bound to an element node that has an element child node. -
Form
controls
that
write
simpleContent
to
instance
data
must
do
so
exactly
as
defined
by
the
XForms
Action
setvalue
( The setvalue Element ).Note: If a form control binds to an element node, then regardless of how many child nodes the element has, the result of the form control writing to the bound element node is that it has either a single non-empty text node child, or no children if the simpleContent written is the empty string (which is in accord with the data model of [ XPath 1.0 ]). -
All
form
controls
that
read
simpleContent
instance
data
must
do
so
as
follows:
-
Element
nodes:
If
element
child
nodes
are
present,
then
an
xforms-binding-exceptionxforms-binding-error - Attribute nodes: returns the string-value of the node.
- Text nodes: returns the string-value of the node.
- Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
-
the
XPath
root
node:
an
xforms-binding-exceptionxforms-binding-errorNote: The simpleContent binding restriction is intended to allow controls to bind to attribute and element nodes. This specification does not prevent binding controls directly to text nodes, however doing so can yield undesirable behavior, such as a form control becoming non-relevant if a user enters empty data. This specification also does not prevent implementers supporting binding controls directly to comment or processing instruction nodes, however the resulting behavior is implementation-dependent and may also yield undesirable behavior.
-
Element
nodes:
If
element
child
nodes
are
present,
then
an
-
Form
controls
are
considered
to
be
relevant
if
none
of
the
following
apply
and
non-relevant
if
any
of
the
following
apply:
-
the
Single
NodeItem Binding is expressed and resolves to emptynodeset,sequence, -
the
Single
NodeItem Binding is expressed and resolves to a non-relevant instance node, -
the
form
control
is
contained
by
a
non-relevant
switch
orgroup
(which includes a non-relevantrepeat
item), or -
the
form
control
is
contained
by
a
non-selected
case
element of aswitch
.When a form control becomes non-relevant, it must receive event
xforms-disabled
and then the XForms action handlers that are listening for events on the non-relevant form control must be disabled.When a non-relevant form control changes to being relevant, the XForms action handlers that listen for events on the form control must become enabled and then the form control must be updated to represent the current value(s) and model item properties of the instance node(s) to which it is bound or to which it refers. The following events must be dispatched to the form control:
xforms-enabled
,xforms-value-changed
, one ofxforms-valid
orxforms-invalid
, one ofxforms-readonly
orxforms-readwrite
, one ofxforms-required
orxforms-optional
, and one ofxforms-in-range
orxforms-out-of-range
.
-
the
Single
-
Except
as
noted,
relevant
form
controls
must
distinguish
rendering
between
being
bound
to
a
required
node
versus
a
non-required
node.
Exceptions
are
form
controls
that
do
not
directly
render
the
string
value
of
the
bound
node
(including
trigger
and the container form controls ). Control of this behavior should be made available to stylesheets. - Relevant form controls must distinguish rendering between valid and invalid states. Control of this behavior should be made available to stylesheets.
- Relevant form controls must indicate when the bound instance data contains a value or content that the form control is not capable of rendering. Control of this behavior should be made available to stylesheets.
-
If
a
form
control
binds
to
a
readonly
node,node or an atomic value, then the form control must not allow the user to modify the node value. The relevant form control that is bound to a readonly node or an atomic value should render in a way which indicates that entering or changing the value is not allowed. Control of the render behavior should be made available to stylesheets.
Sections in this chapter define the various form controls by specifying the following:
Description
Common Attributes
Special Attributes
Examples
Data Binding Restrictions
Implementation Requirements
The input Element
Description:
This
form
control
enables
free-form
data
entry
or
a
user
interface
component
appropriate
to
the
datatype
of
the
bound
node..
node.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
Special
Attributes:
inputmode
Author-optional.
This
form
control
accepts
an
input
mode
hint.
Input
Modes
.
,
incremental
Author-optional.
When
true
,
this
form
control
will
generate
additional
xforms-value-changed
events.
The
default
value
for
this
attribute
is
false
.
Data
Binding
Restrictions:
Binds
to
any
simpleContent
(except
xsd:base64Binary
,
xsd:hexBinary
or
any
datatype
derived
from
these).
these)
or
an
atomic
value.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation
Requirements:
Must
allow
entry
of
a
lexical
value
for
the
bound
datatype.
Implementations
should
provide
a
convenient
means
for
entry
of
datatypes
and
take
into
account
localization
and
internationalization
issues
such
as
representation
of
numbers.
For
example,
an
input
bound
to
an
instance
data
node
of
type
xsd:date
might
provide
a
calendar
control
to
enter
dates;
similarly,
an
input
control
bound
to
of
type
boolean
might
be
rendered
as
a
checkbox.
Examples:
<input ref="order/shipTo/street" class="streetAddress"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
In
the
above,
the
class
attribute
can
be
used
by
a
style
sheet
to
specify
the
display
size
of
the
form
control.
Note
that
the
constraints
on
how
much
text
can
be
input
are
obtained
from
the
underlying
XForms
Model
definition
and
not
from
these
display
properties.
A graphical browser might render the above example as follows:
<input ref="order/shipDate"> <label>Ship By</label> <hint>Please specify the ship date for this order.</hint> </input>
A graphical browser might render the above example as follows:
The user can type a date into the text edit box, or press the button to open a calendar:
<input ref="/search/expr"> <label>Search term(s):</label> <send ev:event="DOMActivate" submission="doSearch" /> </input><submit submission="doSearch">
<submit submission="doSearch"> <label>Search</label> </submit>
This
example
shows
the
input
and
submit
form
controls
working
together
to
provide
the
common
user
experience
of
a
simple
search.
The
input
collects
the
search
term(s)
and
then
automatically
initiates
the
submission
identified
by
doSearch
if
the
user
activates
the
input
control.
Alternatively,
the
user
initiate
the
doSearch
submission
by
activating
the
submit
control.
Note:
A
graphical
browser
on
a
desktop
device
might
activate
form
controls
such
as
input
in
response
to
a
special
user
action
such
as
pressing
the
Enter
key
or
either
clicking
or
double-clicking
with
the
mouse
(depending
on
the
type
of
form
control).
The secret Element
Description: This form control is used to provide the user with the ability to supply information to the system in a manner that makes it difficult for someone, other than the user, who may be observing the process to discern the value that is being supplied. A common use is for password entry.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
Special
Attributes:
inputmode
Author-optional.
This
form
control
accepts
an
input
mode
hint.
Input
Modes
.
,
incremental
Author-optional.
When
true
,
this
form
control
will
generate
additional
xforms-value-changed
events.
The
default
value
for
this
attribute
is
false
.
Data
Binding
Restrictions:
Binds
to
any
simpleContent
(except
xsd:base64Binary
,
xsd:hexBinary
or
any
datatype
derived
from
these).
these)
or
an
atomic
value.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation Requirements: Implementations, including accessibility aids, must obscure the value being entered into this form control. One possible approach would be to render a "*" or similar character instead of the actual characters entered. Note that this provides only a casual level of security; truly sensitive information will require additional security measures outside the scope of XForms.
Example:
The textarea Element
Description: This form control enables free-form data entry and is intended for use in entering multiline content, e.g., the body of an email message.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
Special
Attributes:
inputmode
Author-optional.
This
form
control
accepts
an
input
mode
hint.
Input
Modes
.
,
incremental
Author-optional.
When
true
,
this
form
control
will
generate
additional
xforms-value-changed
events.
The
default
value
for
this
attribute
is
false
.
Data
Binding
Restrictions:
Binds
to
any
simpleContent
(except
xsd:base64Binary
,
xsd:hexBinary
or
any
datatype
derived
from
these).
these)
or
an
atomic
value.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation Requirements: Must allow entry of a lexical value for the bound datatype, including multiple lines of text. Implementations should provide a convenient means for entry of datatypes. For example, a textarea bound to an instance data node of type xforms:HTMLFragment might provide a WYSIWYG rich text editor with common word processor features.
Example:
<textarea ref="message/body" class="messageBody"><label>Message Body</label><label>Message Body:</label> <hint>Enter the text of your message here</hint> </textarea>
In
the
above,
the
class
attribute
can
be
used
by
a
style
sheet
to
specify
the
display
size
of
the
form
control.
Note
that
the
constraints
on
how
much
text
can
be
input
are
obtained
from
the
underlying
XForms
Model
definition
and
not
from
these
display
properties.
A graphical browser might render the above example as follows:
The output Element
Description: This form control renders content based in part on instance data, but it provides no means for entering or changing data.
Common
Attributes:
Control
Common
,
Single
Node
Binding
(author-optional)
Most controls must have either a label attribute, or a label child element. On output, label is optional. Similarly most controls must have a single node binding, but output must either have a single-node binding, or a value attribute.
Special Attributes:
-
appearance This form control does not use the UI Common attribute group, but nevertheless still contains an author-optional appearance attribute, as defined above.value -
Author-optional.
An
expression
to
be
evaluated.
The
string
result
of
the
evaluation
is
rendered
by
the
form
control.
If
binding
attributes
are
present
to
select
a
node,
this
attribute
has
no
effect.
The
evaluation
context
is
the
same
as
would
be
applied
to
the
evaluation
of
the
single node binding.Single Item Binding. This expression is re-evaluated whenever there is a change in any node to which the expression refers. An empty string is used if the evaluation fails. - mediatype
-
Author-optional
attribute
used
to
indicate
that
data
obtained
from
the
Single-NodeSingle Item Binding should be rendered (after decoding, if needed) according to a desired media type indicated by the attribute value string, such asimage/*
for image rendition. If the mediatype element appears as a child of theoutput
, then it overrides this attribute. If the media type is not specified by this attribute or by themediatype
element, then the the default is to present the indicated data as plain text (with no decoding according to datatype).
Data
Binding
Restrictions:
Binds
to
any
simpleContent.
simpleContent
or
an
atomic
value.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation Requirements: Must allow display of a value for the bound datatype. Implementations should provide a convenient means for display of datatypes and take into account localization and internationalization issues such as representation of numbers and dates.
Element
output
can
be
used
to
display
the
value
of
a
particular
instance
node
by
using
a
Single-Node
Single
Item
Binding;
it
can
also
be
used
to
display
the
result
of
evaluating
an
expression
by
specifying
the
expression
to
be
evaluated
via
attribute
value
.
Note
that
the
Single-Node
Single
Item
Binding
attributes
and
value
on
element
output
are
mutually
exclusive.
By
default,
the
output
element
simply
renders
the
plain
text
of
the
value
attribute
or
the
node
item
indicated
by
the
Single-Node
Single
Item
Binding.
However,
if
the
Single-Node
Single
Item
Binding
indicates
a
non-empty
data
node,
value,
and
the
media
type
is
specified
based
on
the
mediatype
attribute
or
mediatype
child
element
,
then
the
content
string
value
of
the
data
node
item
must
be
decoded
or
dereferenced
according
to
its
datatype,
and
the
result
should
be
rendered
according
to
the
indicated
media
type
if
it
is
possible
to
do
so
(e.g.
a
voice-only
device
cannot
render
a
digital
image).
Note:
When
the
media
type
is
specified,
implementations
may
handle
the
output
content
as
presentation-only
or
as
interactive
content,
and
interactive
content
may
be
isolated
from
or
capable
of
accessing
the
enclosing
document
that
contains
the
output
.
Further
implementation
experience
and
user
feedback
is
required.
For
example,
if
the
output
content
includes
XForms
user
interface
elements,
it
may
be
desirable
for
them
to
access
a
default
XForms
model
in
the
output
content
or
from
the
enclosing
document.
If
the
Single
Node
Item
Binding
is
absent
or
if
it
does
not
indicate
a
non-empty
instance
node,
value,
then
the
media
type
specification
is
ignored
if
given.
Otherwise,
if
the
Single
Node
Item
Binding
produces
a
non-empty
node,
value,
and
the
media
type
is
specified,
then
decoding
or
dereferencing
of
the
instance
node
item
prior
to
rendition
is
performed
by
datatype
as
follows:
-
If
the
instance nodeitem either is of type or is derived from typexsd:base64Binary
, then the data is base-64 decoded. -
If
the
instance nodeitem either is of type or is derived from typexsd:hexBinary
, then the data is hex-binary decoded. -
If
the
instance nodeitem either is of type or is derived from typexsd:anyURI
, then the data is treated as a URI and dereferenced. -
If
the
instance nodeitem is of any other type, then the data is used without modification.
If
the
output
rendition
is
based
on
the
value
attribute,
then
the
rendition
is
updated
if
the
nodes
referenced
by
the
value
expression
change
or
if
the
content
of
any
of
the
referenced
nodes
changes.
Otherwise,
the
rendition
of
an
output
is
updated
if
the
node
item
referenced
by
the
Single-Node
Single
Item
Binding
changes,
if
the
content
of
the
referenced
node
item
changes,
or
if
the
media
type
changes.
The
media
type
can
change
by
a
change
to
the
mediatype
element's
referenced
node
item
or
its
content
(a
host
language
may
also
allow
DOM
mutation
of
the
content
of
the
mediatype
attribute
or
element).
A
change
to
the
label
associated
with
the
output
causes
an
update
to
the
rendition
of
the
label
(which
may
affect
the
layout
position
of
the
main
output
content).
Failure
to
render
the
content
indicated
by
the
output
element
should
result
in
an
xforms-output-error
,
a
non-fatal
error
that
does
not
halt
XForms
processing.
Failures
can
occur
on
initial
creation
of
the
output
or
during
user
interface
refresh
(see
Section
The
xforms-refresh
Event
).
Failures
can
occur
for
many
reasons,
including
-
Data
to
be
decoded
does
not
conform
to
the
format
of
xsd:base64Binary
orxsd:hexBinary
; -
An
error
dereferencing
the
URI
in
a
nodeitem of or derived from typexsd:anyURI
; -
A
data
format
error
(e.g.
invalid
or
unsupported
image
format)format); -
An
unrecognized
media
type
identifier
stringstring.
The
content
model
for
the
output
element
includes
UI
Common
in
order
to
allow
action
handlers
for
the
xforms-output-error
as
well
as
to
allow
more
comprehensive
behavior
and
information
to
be
provided
for
the
output
,
e.g.
via
the
hint
element.
Examples:
I charged you - <output ref="order/totalPrice"/> - and here is why:
A graphical browser might render an output form control as follows:
<model> <instance><data xmlns=""> <picture/> </data> </instance><bind ref="/data" type="xsd:base64Binary"/><bind ref="picture" type="xsd:base64Binary"/> </model>
Given
the
model
above,
the
following
controls
can
upload
an
image
to
instance
data
and
display
it:
<upload ref="picture" accept="image/*"> <label>Press me to attach a picture</label> </upload><output ref="/data" mediatype="image/*">
<output ref="picture" mediatype="image/*"> <hint>This is the image you attached to the form.</hint> <message ev:event="xforms-output-error">Error attaching image data.</message> </output>
<bind ref="birthdate" type="xsd:date" /> ... <output ref="birthdate"> <label>Lexical: </label> </output> <output ref="birthdate" appearance="full"> <label>Full: </label> </output> <output ref="birthdate" appearance="minimal"> <label>Minimal: </label> </output>
A
graphical
browser
may
should
take
into
account
the
appearance
and
the
localization
information
from
the
host
language
and
present
the
above
output
form
controls
as
follows:
Lexical: 1998-01-19 Full: 19 janvier 1998 Minimal: 19/01/1998
The mediatype Element (for output)
Binding
attributes
on
author-optional
element
mediatype
(deprecated
in
favor
of
using
an
AVT
in
the
mediatype
attribute)
specify
the
location
in
the
instance
of
the
string
that
indicates
the
desired
media
type
rendition
for
the
parent
output
.
If
the
binding
attributes
are
not
used,
the
value
attribute
must
be
used
instead
to
specify
the
desired
media
type
rendition.
Common
Attributes:
Common
,
Single
Node
Item
Binding
Special Attributes:
- value
-
An
expression
to
be
evaluated.
The
string
result
of
the
evaluation
is
used
to
specify
the
desired
media
type
for
output
rendition.
If
a
single node bindingSingle Item Binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of thesingle node binding.Single Item Binding. An empty string is used if the evaluation fails.
The upload Element
Description: This form control enables the common feature found on Web sites to upload a file from the local file system, as well as accepting input from various devices including microphones, pens, and digital cameras.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
incremental
Special Attributes:
-
mediatypeaccept -
Author-optional.
Space-separatedComma-separated list of suggested mediatypes,types and file extensions (including the leading period), used by the XForms Processor to determine the possible sources of data to upload. This attribute must work as described in [HTML5] . -
incrementalmediatype -
Author-optional. When true , this form control will generate additionalDeprecated. Use the equivalentxforms-value-changedacceptevents. The default for this form control is false .instead. Space-separated list of suggested media types, used by the XForms Processor to determine the possible sources of data to upload.
Data
Binding
Restrictions:
This
form
control
can
only
be
bound
to
datatypes
xsd:anyURI
,
xsd:base64Binary
or
xsd:hexBinary
,
or
types
derived
by
restriction
from
these.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation Requirements: For base64Binary or hexBinary data binding:
-
When
bound
to
an
instance
data
node
of
type
xsd:base64binary
,xsd:hexBinary
, or a type derived by restriction thereof, on activationupload
places the binary content in the content of the node with the indicated encoding.
Implementation Requirements: For anyURI data binding:
-
When
bound
to
an
instance
data
node
of
type
xsd:anyURI
(or a type derived by restriction thereof), on activationupload
places a URI in the content of the node.
For security reasons, the XForms Processor must not dereference the URI bound to this form control without explicit user permission.Note: Implementors note thatupload
must associate the binary content, mediatype, and filename with that URI for Serialization as multipart/related and Serialization as multipart/form-data serialization.
-
Implementations
with
a
file
system
should
support
file
upload
—
selecting
a
specific
file.
The
types
of
files
presented
by
default
should
reflect
the
mediatype
specified
by
attribute
mediatypeaccept
Implementation Requirements: For all data bindings:
- Implementations with specific pen/digitizer hardware should (and implementations with other pointing devices may) support scribble — allowing in-place creation of pen-based data.
- Implementations with specific audio recording capabilities should support record audio — in-place recording of an audio clip.
- Implementations with a digital camera, scanner interface or screen capture should support acquire image — in-place upload of images from an attached device.
- Implementations with video recording capability should provide a record video option.
- Implementations with 3d capabilities should provide a 3d interface option.
-
Implementations
may
provide
proprietary
implementations
(for
example,
a
mediatype
of
text/rtf
could invoke an edit window with a proprietary word processing application) - Implementations are encouraged to support other input devices not mentioned here.
- Implementations which cannot support upload for the given mediatype must make this apparent to the user.
See
the
child
elements
filename
(
The
filename
Element
)
and
mediatype
(
The
mediatype
Element
(for
upload)
).
Example:
Examples:
<upload ref="mail/attachment" accept="video/*,image/*,.txt,.pdf"> <label>Select attachment:</label> <filename ref="@filename" /> <mediatype ref="@mediatype" /> </upload>
<upload ref="mail/attachment" accept="image/*"> <label>Select image:</label> <filename ref="@filename" /> <mediatype ref="@mediatype" /> </upload>
A graphical browser might render this form control as follows:
Implementation Requirements:
-
On
activation,
if
child
element
filename
is present and a filename is available,upload
places the filename of the data to upload in the instance at the node indicated by the binding attributes on child elementfilename
. -
On
activation,
if
child
element
mediatype
is present and a mediatype is available,upload
places the mediatype of the data to upload in the instance at the node indicated by the binding attributes on child elementmediatype
.
The filename Element
Binding
attributes
on
author-optional
element
filename
specify
the
location
in
the
instance
for
the
parent
element
upload
,
when
activated,
to
place
the
filename
for
the
chosen
binary
resource.
For
security
reasons,
upload
must
not
take
action
due
to
any
existing
value
of
the
node.
Common
Attributes:
Common
,
Single
Node
Item
Binding
Content: EMPTY
In
the
following
example,
the
user
is
prompted
to
select
an
image.
When
activated,
upload
places
in
mail/attachment
either
the
binary
data
of
the
image
or
a
URI
for
it,
depending
on
the
type
declared
for
the
mail/attachment
.
The
filename,
perhaps
"
me.jpg
",
is
placed
in
the
attribute
node
mail/attachment/@filename
,
and
the
mediatype,
perhaps
"
image/jpeg
"
in
the
attribute
node
mail/attachment/@mediatype
.
Example:
<upload ref="mail/attachment" accept="image/*"> <label>Select an image to attach</label> <filename ref="@filename"/> <mediatype ref="@mediatype"/> </upload>
The mediatype Element (for upload)
Binding
attributes
on
author-optional
element
mediatype
specify
the
location
in
the
instance
for
the
parent
element
upload
,
when
activated,
to
place
the
mediatype
of
the
chosen
binary
resource,
if
available.
Common
Attributes:
Common
,
Single
Node
Item
Binding
Content: EMPTY
The range Element
Description: This form control allows selection from a sequential range of values.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
incremental
Special Attributes:
- start
-
Author-optional
attribute
containing
a
hint
for
the
lexical
starting
bound
for
the
range
—
aa legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model. - end
-
Author-optional
attribute
containing
a
hint
for
the
ending
bound
for
the
range
— a&‐ a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model. - step
-
Author-optional
attribute
containing
a
delta-value
to
use
for
incrementing
or
decrementing
the
value.
Must
be
of
a
type
capable
of
expressing
the
difference
between
two
legal
values
of
the
underlying
data.
incremental Author-optional. When true , this form control will generate additional xforms-value-changed events. The default for this form control is false .
Data
Binding
Restrictions:
Binds
only
the
following
list
of
datatypes,
or
datatypes
derived
by
restriction
from
those
in
the
list:
xsd:duration
,
xsd:date
,
xsd:time
,
xsd:dateTime
,
xsd:gYearMonth
,
xsd:gYear
,
xsd:gMonthDay
,
xsd:gDay
,
xsd:gMonth
,
xsd:float
,
xsd:double
,
and
xsd:decimal
.
Note:
The
above
list
of
datatypes
includes
by
derivation
all
of
the
integer
datatypes
(),
(which
are
derived
by
restriction
from
xsd:decimal
),
all
of
the
XForms
datatypes
defined
in
Section
XForms
Datatypes
that
correspond
to
the
allowed
XML
schema
Schema
datatypes,
and
the
datatypes
defined
in
xforms:dayTimeDuration
and
xforms:yearMonthDuration
.
Note:
This control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation Requirements: Must allow input of a value corresponding to the bound datatype. Implementations should inform the user of the upper and lower bounds, as well as the step size, if any. If the instance data value is outside the upper or lower bounds, this form control must indicate an out-of-range condition. In graphical environments, this form control may be rendered as a "slider" or "rotary control".
In
the
event
of
overlapping
restrictions
between
the
underlying
datatype
and
the
start
and
end
hints,
the
most
restrictive
range
should
be
used.
Notice that the attributes of this element encapsulate sufficient metadata that in conjunction with the type information available from the XForms Model proves sufficient to produce meaningful prompts when using modalities such as speech, e.g., when using an accessibility aid. Thus, in the example below, an aural user agent might speak a prompt of the form Please pick a date in the range January 1, 2001 through December 31, 2001.
Examples:
<range ref="/stats/balance" start="-2.0" end="2.0" step="0.5"> <label>Balance</label> </range>
A graphical browser might render this as follows:
<range ref="/order/shipDate" start="2021-01-01" end="2021-12-31"> <label>Ship Date</label> </range>
‐
The trigger Element
Description:
This
form
control
is
similar
to
the
HTML
element
button
and
allows
for
user-triggered
actions.
This
form
control
may
also
be
used
to
construct
other
custom
form
controls.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
(author-optional)
Most controls must have a single-node binding. On trigger it is optional.
Data
Binding
Restrictions:
Binds
to
any
node.
node
or
an
atomic
value.
This
form
control
does
not
directly
interact
with
form
data,
but
is
affected
by
model
item
properties
of
the
bound
node,
thus
binding
attributes
are
not
required.
Implementation
Requirements:
The
user
agent
must
provide
a
means
to
generate
an
a
DOMActivate
event
on
the
form
control.
Graphical
implementations
might
render
this
form
control
as
a
push-button
with
the
label
on
the
button
face.
Style
sheets
can
be
used
to
style
this
form
control
as
an
image,
hyperlink,
or
other
presentation.
Although
a
trigger
element
receives
events
associated
with
model
item
properties
of
a
bound
node,
such
as
xforms-readonly
and
xforms-invalid
,
the
XForms
processor
Processor
must
not
impart
special
behaviors
on
this
control
for
model
item
properties
other
than
the
model
item
property
relevant
of
a
bound
data
node.
For
example,
the
readonly
model
item
property
of
a
bound
data
node
does
not
affect
whether
or
not
the
trigger
can
be
activated.
Typically,
a
style
sheet
would
be
used
to
determine
the
exact
appearance
of
form
controls,
though
a
means
is
provided
to
suggest
an
appearance
through
attribute
appearance
.
Suggested
renditions
for
the
pre-defined
values
of
this
attribute
are
as
follows:
"full": visually rendered as a standard button control with border.
"compact": visually rendered as a standard button control without border
"minimal": rendered with no border, a transparent background and underline font effect. This rendition hint is meant to be analogous to the typical visual rendition of an XHTML anchor element.
Example:
<trigger label="Click here"> <message ev:event="DOMActivate">Hello!</message> </trigger>
The submit Element
Description: This form control initiates a submission .
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
(author-optional)
Most controls must have a single-node binding. On submit, it is optional.
Special Attributes:
- submission
-
Author-optional
attribute
containing
a
reference
to
elementasubmission
element. If this attribute is given but does not identify a.submission
element, then activating thesubmit
does not result in the dispatch of anxforms-submit
event. If this attribute is omitted, then the firstsubmission
in document order from themodel
associated with the in-scope evaluation context is used.
Data
Binding
Restrictions:
Binds
to
any
node.
node
or
an
atomic
value.
This
form
control
does
not
directly
interact
with
form
data,
but
is
affected
by
model
item
properties
of
the
bound
node,
thus
binding
attributes
are
not
required.
Implementation
Requirements:
The
default
action
for
event
DOMActivate
is
to
dispatch
event
xforms-submit
to
the
submission
element
specified
by
attribute
submission
(or
its
default).
Upon
activation,
this
control
must
become
unavailable
for
further
activations
until
the
submit
process
concludes
with
either
an
xforms-submit-done
or
xforms-submit-error
event.
Typically,
a
style
sheet
would
be
used
to
determine
the
exact
appearance
of
form
controls,
though
a
means
is
provided
to
suggest
an
appearance
through
attribute
appearance
.
Suggested
renditions
for
the
pre-defined
values
of
this
attribute
are
the
same
as
for
trigger
.
Example:
Examples:
<submit label="OK"/> <submit submission="timecard"> <label>Submit Timecard</label> </submit>
The select Element
Description: This form control allows the user to make multiple selections from a set of choices.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
incremental
Special Attributes:
- selection
-
Author-optional
attribute
determining
whether
free
entry
is
allowed
in
the
list.
Default
is
"closed".
incremental Author-optional. When true , this form control will generate additional xforms-value-changed events. The default for this form control is true .
Data
Binding
Restrictions:
any
simpleContent
capable
of
holding
a
sequence.
sequence
or
a
sequence
of
atomic
values.
The
restriction
to
binding
simpleContent
exists
when
the
choices
are
authored
as
part
of
the
user
interface
control
as
shown
in
this
section.
Element
itemset
(described
in
The
itemset
Element
)
creates
dynamic
selection
items
and
allows
the
available
choices
to
be
obtained
from
an
XForms
Model.
When
itemset
uses
the
value
element,
the
restriction
to
binding
simpleContent
remains
in
effect.
However,
the
itemset
also
allows
for
the
selection
and
deselection
of
subtrees
of
instance
data
using
the
copy
element,
and
when
using
that
construct,
the
data
binding
restriction
to
simpleContent
is
relaxed,
but
the
form
control
must
bind
to
an
element
with
no
mixed
content.
content
or
a
sequence
of
atomic
values.
Note:
Except in the case described above where the simpleContent data binding restriction is relaxed, this control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Note:
A
limitation
of
the
XML
Schema
list
datatypes
is
that
white
space
characters
in
the
storage
values
(the
value
element)
are
always
interpreted
as
separators
between
individual
data
values.
Therefore,
authors
should
avoid
using
white
space
characters
within
storage
values
with
list
simpleContent.
<item> <value>United States of America</value> ... </item>
When selected, this item would introduce not one but four additional selection values: "America", "of", "States", and "United".
Implementation
Requirements:
The
label
for
each
choice
must
be
presented,
and
the
control
must
allow
any
number
of
selections,
possibly
none.
When
this
form
control
uses
the
value
element
for
selection,
it
stores
the
values
corresponding
to
the
selected
choices
in
a
space
separated
list
in
the
location
addressed
by
the
binding
attributes.
The
values
to
be
stored
for
selected
items
are
either
directly
specified
as
the
contents
of
element
value
,
or
specified
indirectly
through
binding
attributes
on
element
value
.
When
this
form
control
uses
the
copy
element
for
selection,
it
stores
copies
of
the
subtrees
corresponding
to
the
selected
choices
in
the
location
addressed
by
the
binding
attributes.
The
datatype
bound
to
this
form
control
may
include
a
non-enumerated
value
space,
e.g.,
xsd:string
,
or
a
union
of
a
an
enumeration
and
a
non-enumerated
datatype
(called
an
open
enumeration).
In
this
case,
control
select
may
have
attribute
selection="open"
.
The
form
control
must
then
allow
free
data
entry,
as
described
in
The
input
Element
.
The
form
control
may
permit
multiple
values
to
be
entered
through
free
entry.
For
closed
selections:
If
the
instance
data
matches
the
storage
data
of
one
or
more
of
the
selection
items,
those
items
are
selected.
If
there
is
no
match,
no
items
are
initially
selected.
If
any
of
the
stored
values
or
subtree
copies
do
not
correspond
to
an
item
with
a
matching
storage
value
or
subtree,
the
form
control
must
indicate
an
out-of-range
condition.
If
the
form
control
switches
to
or
from
being
out-of-range,
then
xforms-out-of-range
or
xforms-in-range
must
be
dispatched
to
the
form
control.
For
open
selections:
When
using
dynamic
selections
with
the
itemset
and
copy
elements,
open
selection
has
no
effect.
If
the
instance
data
matches
the
storage
values
specified
by
one
or
more
of
the
selection
items,
then
all
such
matching
items
are
selected.
If
any
instance
data
list
values
do
not
match
the
storage
value
specified
by
one
or
more
of
the
items,
all
such
non-matching
values
are
retained,
as
if
entered
through
free
entry.
Free
entry
text
is
handled
the
same
as
form
control
input
(
The
input
Element
),
possibly
in
multiplicity.
For both closed and open selections, any selection item with an empty storage data subtree or a storage value that is either empty or contains only white space characters must remain deselected.
For
both
closed
and
open
selections,
the
above
rules
describe
which
items
are
considered
to
be
selected
and
deselected
by
the
control.
The
select
form
control
changes
the
states
of
selected
and
deselected
items
on
creation,
refresh,
and
user
selection
or
deselection
of
an
item.
Newly
selected
items
receive
the
event
xforms-select
immediately
after
all
newly
deselected
items
receive
the
event
xforms-deselect
.
The
content
of
the
instance
node
bound
to
the
selection
control
must
only
be
changed
by
the
addition
or
deletion
of
storage
data
associated
with
items
that
have
been
selected
or
deselected.
Content
not
associated
with
selection
items
is
preserved.
For
selection
controls
that
use
the
value
element,
the
net
effect
of
newly
selected
and
deselected
items
is
computed
into
a
string,
preserving
content
not
associated
with
selection
items,
and
the
result
is
then
committed
to
the
bound
instance
node
by
using
the
XForms
Action
The
setvalue
Element
.
For
selection
controls
that
use
the
copy
element,
the
individual
subtrees
associated
with
the
newly
selected
and
deselected
items
are
added
or
removed
individually
by
using
The
insert
Element
and
The
delete
Element
.
Implementation Hints:
For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:
- The content parts (space-separated values or subtree copies) in the bound instance data node are compared with the form control items' storage data (values or subtree copies).
- Each item with storage data (value or subtree copy) equal to an instance data content part becomes selected if it was not already selected.
- Each item with storage data missing from the instance data content becomes deselected if it was not already deselected.
- If there are instance data content parts for which there is no corresponding selection item, the form control indicates an out-of-range condition.
When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:
-
If
the
item's
storage
data
(value
or
subtree
copy)
was
not
present
in
the
bound
instance
data,
the
item's
storage
data
is
inserted
into
the
instance
data
content
list.li/code> and st. The exact location of the insertion is implementation-dependent. Any other item having the same storage data becomes selected as well. - If the item's storage data was already present in the bound instance data, the bound instance data is left unchanged.
When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:
- If the item's storage data was present in the bound instance data, the item's storage data is removed from the instance data content list. Any other item having the same storage data becomes deselected as well.
- If the item's storage data was already absent from the bound instance data, the bound instance data is left unchanged.
For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.
An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.
Typically,
a
style
sheet
would
be
used
to
determine
the
exact
appearance
of
form
controls,
though
a
means
is
provided
to
suggest
an
appearance
through
attribute
appearance
.
The
value
of
the
attribute
consists
of
one
of
the
following
values:
"full": all choices should be rendered at all times.
"compact": a fixed number of choices should be rendered, with scrolling facilities as needed
"minimal": a minimum number of choices should be rendered, with a facility to temporarily render additional choices
Example:
<select ref="flavors" label="Flavors"> <item label="Vanilla" value="v"/> <item label="Strawberry" value="s"/> <item label="Chocolate" value="c"/> </select>
In the above example, more than one flavor can be selected.
A
graphical
browser
might
render
form
control
select
as
any
of
the
following:
appearance="full"
|
appearance="compact"
|
appearance="minimal"
|
---|---|---|
The select1 Element
Description: This form control allows the user to make a single selection from multiple choices.
Common
Attributes:
Common
,
UI
Control
Common
,
Single
Node
Binding
incremental
Special Attributes:
- selection
-
Author-optional
attribute
determining
whether
free
entry
is
allowed
in
the
list.
Default
is
"closed".
incremental Author-optional. When true , this form control will generate additional xforms-value-changed events. The default for this form control is true .
Data
Binding
Restrictions:
Binds
to
any
simpleContent.
simpleContent
or
an
atomic
value.
The
restriction
to
binding
simpleContent
exists
when
the
choices
are
authored
as
part
of
the
user
interface
control
as
shown
in
this
section.
Element
itemset
(described
in
The
itemset
Element
)
creates
dynamic
selection
items
and
allows
the
available
choices
to
be
obtained
from
an
XForms
Model.
When
itemset
uses
the
value
element,
the
restriction
to
binding
simpleContent
remains
in
effect.
However,
the
itemset
also
allows
for
the
selection
and
deselection
of
subtrees
of
instance
data
using
the
copy
element,
and
when
using
that
construct,
the
data
binding
restriction
to
simpleContent
is
relaxed,
but
the
form
control
must
bind
to
an
element
with
no
mixed
content.
content
or
an
atomic
value.
Note:
Except in the case described above where the simpleContent data binding restriction is relaxed, this control cannot bind to element nodes that have element children. See Implementation Requirements Common to All Form Controls for user interface processing rules common to all form controls.
Implementation
Requirements:
The
label
for
each
choice
must
be
presented,
and
the
control
must
allow
at
all
times
exactly
one
selection.
When
this
form
control
uses
the
value
element
for
selection,
it
stores
the
value
corresponding
to
the
selected
choice
in
the
location
addressed
by
the
binding
attributes.
The
value
to
be
stored
is
either
directly
specified
as
the
contents
of
element
value
,
or
specified
indirectly
through
binding
attributes
on
element
value
.
When
this
form
control
uses
the
copy
element
for
selection,
it
stores
a
copy
of
the
subtree
corresponding
to
the
selected
choice
in
the
location
addressed
by
the
binding
attributes.
The
datatype
bound
to
this
form
control
may
include
a
non-enumerated
value
space,
e.g.,
xsd:string
,
or
a
union
of
a
enumeration
and
a
non-enumerated
datatype
(called
an
open
enumeration).
In
this
case,
control
select1
may
have
attribute
selection="open"
.
The
form
control
must
then
allow
free-form
data
entry,
as
described
in
The
input
Element
.
For
closed
selections:
If
the
instance
data
matches
the
storage
data
of
one
of
the
selection
items,
that
item
is
selected.
If
there
is
no
match,
no
items
are
initially
selected.
If
there
is
no
match
and
the
storage
data
is
non-empty,
the
form
control
must
indicate
an
out-of-range
condition.
If
the
form
control
switches
to
or
from
being
out-of-range,
then
xforms-out-of-range
or
xforms-in-range
must
be
dispatched
to
the
form
control.
For
open
selections:
When
using
dynamic
selections
with
the
itemset
and
copy
elements,
open
selection
has
no
effect.
If
the
instance
data
matches
the
storage
value
specified
by
one
of
the
selection
items,
then
the
first
such
matching
item
is
selected.
Otherwise,
no
items
are
selected
and
the
instance
data
value
is
retained,
as
if
entered
through
free
text
entry.
Free
entry
text
is
handled
the
same
as
form
control
input
(
The
input
Element
).
For both closed and open selections, any selection item with a storage value which is empty or which contains only white space characters is deemed to be selected if the bound data node value exactly matches the storage value of the selection item. Furthermore, selecting a selection item with a storage value which is empty or which contains only white space characters places the storage value into the bound data node value.
For
both
closed
and
open
selections,
the
above
rules
describe
which
items
are
considered
to
be
selected
by
the
control.
Items
that
are
not
selected
are
considered
to
be
deselected.
The
select1
form
control
changes
the
states
of
selected
and
deselected
items
on
creation,
refresh,
and
user
selection
or
deselection
of
an
item.
A
newly
selected
item
receives
the
event
xforms-select
immediately
after
all
other
items
receive
the
event
xforms-deselect
.
The
content
of
the
instance
node
bound
to
the
selection
control
must
only
be
changed
by
the
addition
or
deletion
of
storage
data
associated
with
items
that
have
been
selected
or
deselected.
Content
not
associated
with
selection
items
is
preserved.
For
selection
controls
that
use
the
value
element,
the
net
effect
of
newly
selected
and
deselected
items
is
computed
into
a
string,
preserving
content
not
associated
with
selection
items,
and
the
result
is
then
committed
to
the
bound
instance
node
by
using
the
XForms
Action
The
setvalue
Element
.
For
selection
controls
that
use
the
copy
element,
the
individual
subtrees
associated
with
the
newly
selected
and
deselected
items
are
added
or
removed
individually
by
using
The
insert
Element
and
The
delete
Element
.
Implementation Hints:
For closed selections, when the form control is created or refreshed to reflect bound instance data, behavior equivalent to the following steps occurs:
- The bound instance data is compared with the items' storage data (values or subtree copies).
- If no item with storage data (value or subtree copy) in the bound instance data node is selected, then the first item with storage data in the instance data content, if any, becomes selected. Otherwise, if an item with storage data in the bound instance data node is selected, then the first selected item remains selected, and any other items with storage data matching the selected item are deselected.
- If there is a selected item, then all items with storage data not equal to the selected item are deselected, and their representative storage data is removed from the bound instance node content.
- If no item has storage data in the bound instance data node content and the instance data node content is not empty, then the form control indicates an out-of-range condition.
When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:
- All selected items other than the newly selected item are deselected, if any, and the storage data of any deselected items whose storage data does not match the newly selected item are removed from the bound instance node data.
- The newly selected item becomes selected. If its storage data (value or subtree copy) is not present in the bound instance data, then the item's storage data is inserted into the instance data. The exact location of the insertion is implementation-dependent, but the newly inserted data is not accompanied by any other data unless the data does not match any items for the selection control.
When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:
- The item is deselected and its storage data is removed from the bound instance node data.
- If the bound instance data node is not empty, then the form control indicates an out-of-range condition.
For open selections: when the form control is created or refreshed to reflect bound instance data, the behavior is the same as with closed selection, except the form control never indicates an out-of-range condition.
An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.
User
interfaces
may
choose
to
render
this
form
control
as
a
pulldown
list
or
group
of
radio
buttons,
among
other
options.
The
appearance
attribute
offers
a
hint
as
to
which
rendering
might
be
most
appropriate,
although
any
styling
information
(such
as
CSS)
should
take
precedence.
Example:
<select ref="flavors" label="Flavors"> <item label="Vanilla" value="v"/> <item label="Strawberry" value="s"/> <item label="Chocolate" value="c"/> </select>
In
the
above
example,
selecting
one
of
the
choices
will
result
in
the
associated
value
given
by
element
value
on
the
selected
item
being
set
in
the
underlying
instance
data
at
the
location
icecream/flavor
.
A graphical browser might render this form control as any of the following:
appearance="full" | appearance="compact" | appearance="minimal" |
---|---|---|
Common Support Elements
The
child
elements
detailed
below
provide
the
ability
to
attach
metadata
to
many
form
controls
and
other
elements.
Factoring
elements,
all
human
readable
messages
to
of
them
may
either
be
specified
as
a
separate
resource
XML
file.
Using
URIs
into
this
XML
resource
bundle
within
individual
label
elements
Finally,
child
element,
or
as
an
XForms
implementation
could
use
content
negotiation
to
obtain
the
appropriate
XML
resource
bundle,
e.g.,
based
on
the
accept-language
headers
from
the
client,
to
serve
up
attribute
of
the
user
interface
with
messages
localized
to
same
name
(see
the
client's
locale.
UI
Common
attribute
set).
The label Element
This element provides a descriptive label for the containing form control. The descriptive label can be presented visually and made available to accessibility software so the visually-impaired user can obtain a short description of form controls while navigating among them.
Common
Attributes:
Common
,
Appearance
,
Single
Node
Item
Binding
(author-optional)
Special Attributes: None
The
label
specified
can
exist
in
instance
data
or
as
inline
text.
If
more
than
one
source
of
label
is
specified
in
this
element,
the
order
of
precedence
is:
single
node
binding
Single
Item
Binding
attributes,
inline
text.
An accessibility aid might speak the metadata encapsulated here when the containing form control gets focus.
The help Element
The
author-optional
element
help
provides
a
convenient
way
to
attach
help
information
to
a
form
control.
Common
Attributes:
Common
,
Appearance
,
Linking
,
Single
Node
Item
Binding
(author-optional)
Special Attributes: None
The
message
specified
can
exist
in
instance
data
or
as
inline
text.
If
more
than
one
source
of
message
is
specified
in
this
element,
the
order
of
precedence
is:
single
node
binding
Single
Item
Binding
attributes,
inline
text.
An
XForms
Processors
should
choose
an
appropriate
presentation
for
the
help
content,
and
should
allow
styling
if
the
host
language
integration
supports
it,
for
example
of
this
element
is
at
with
CSS.
If
the
host
language
integration
supports
Linking
,
the
help
link
should
be
made
available
through
an
appropriate
presentation
mechanism.
With
appearance="minimal"
,
the
help
link
should
be
associated
with
the
label.
With
no
host-language
styling
and
no
appearance
specified,
a
graphical
browser
should
present
help
as
an
ephemeral
The
message
Element
.
The
following
example
shows
how
such
help
might
be
presented
in
a
graphical
browser:
<secret ref="/login/password"> <label>Password</label> <help>Have you forgotten your password? Simply call 1-900-555-1212 and have a major credit card handy.</help> </secret>
The hint Element
The
author-optional
element
hint
provides
a
convenient
way
to
attach
hint
information
to
a
form
control.
Common
Attributes:
Common
,
Appearance
,
Single
Node
Item
Binding
(author-optional)
Special Attributes: None
The
message
specified
can
exist
in
instance
data
or
as
inline
text.
If
more
than
one
source
of
message
is
specified
in
this
element,
the
order
of
precedence
is:
single
node
binding
Single
Item
Binding
attributes,
inline
text.
An
XForms
Processors
should
choose
an
appropriate
presentation
for
the
hint,
and
should
allow
styling
if
the
host-language
integration
supports
it,
for
example
of
this
element
is
at
The
with
CSS.
With
no
attribute
appearance
and
no
host-language
styling,
a
presentation
should
be
the
same
as
an
ephemeral
message
Element
.
associated
with
the
label,
which
a
graphical
browser
might
render
as
follows:
<input ref="po/address/street1"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
With
appearance="minimal"
,
a
hint
should
be
associated
with
the
value
yet
distinguished
from
actual
values.
<group ref="registration"> <input ref="name"> <label>Name: </label> <hint appearance="minimal">Last, First</hint> </input> <input ref="website"> <label>Website: </label> <hint appearance="minimal">http://</hint> </input> </group>
A graphical browser might render such a a hint as follows:
The alert Element
The
author-optional
element
alert
provides
a
convenient
way
to
attach
alert
or
error
information
to
a
form
control.
Rendering
of
this
element
is
implementation-defined,
and
there
is
no
default
level
such
as
modal
or
ephemeral
for
the
displayed
message.
Common
Attributes:
Common
,
Appearance
,
Single
Node
Item
Binding
(author-optional)
Special Attributes: None
The
message
specified
can
exist
in
instance
data
or
as
inline
text.
If
more
than
one
source
of
message
is
specified
in
this
element,
the
order
of
precedence
is:
single
node
binding
Single
Item
Binding
attributes,
inline
text.
See
XForms
and
Styling
for
examples
to
see
how
this
might
be
presented
to
the
user.
Common Markup for Selection Controls
The choices Element
This
element
is
used
within
selection
form
controls
to
group
available
choices.
This
provides
the
same
functionality
as
element
optgroup
in
HTML.
Common Attributes: Common
The item Element
This
element
specifies
the
storage
value
and
label
to
represent
an
item
in
a
list.
It
is
found
within
elements
select1
and
select
,
or
grouped
in
element
choices
.
Common Attributes: Common , UI Common
Special Attributes:
- value
-
Author-optional.
An
expression
to
be
evaluated.
The
string
result
of
the
evaluation
is
used
as
the
storage
value
of
the
item
when it is selected. If a Single Item Binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the Single Item Binding. An empty string is used if the evaluation fails.
Data
Binding
Restriction:
All
lexical
values
must
be
valid
according
to
the
datatype
bound
to
the
selection
control.
If
the
Single
Item
Binding
attributes
are
used
and
indicate
a
node
in
a
model
other
than
the
bound
node
of
the
containing
selection
control,
then
an
xforms-binding-error
must
occur.
The value Element
This
element
provides
a
storage
value
to
be
used
when
an
item
is
selected.
The
storage
value
is
determined
by
one
of
three
methods,
in
order
of
precedence:
-
the
value
of
a
node
indicated
by
a
single node bindingSingle Item Binding expression, if specified -
the
result
of
evaluating
an
expression
appearing
in
attribute
value
, if specified -
the
inline
content
of
the
value
element (when neither thesingle node bindingSingle Item Binding nor thevalue
attribute are expressed).
Common
Attributes:
Common
,
Single
Node
Item
Binding
(author-optional)
Special Attributes:
- value
-
Author-optional.
An
expression
to
be
evaluated.
The
string
result
of
the
evaluation
is
used
as
the
storage
value
of
the
item
when it is selected. If asingle node bindingSingle Item Binding is expressed, then this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of thesingle node binding.Single Item Binding. An empty string is used if the evaluation fails.
Data
Binding
Restriction:
All
lexical
values
must
be
valid
according
to
the
datatype
bound
to
the
selection
control.
If
the
single
node
binding
Single
Item
Binding
attributes
are
used
and
indicate
a
node
in
a
model
other
than
the
bound
node
of
the
containing
selection
control,
then
an
must
occur.
xforms-binding-exception
xforms-binding-error
The itemset Element
This
element
allows
the
creation
of
dynamic
selections
within
controls
select
and
select1
,
where
the
available
choices
are
determined
at
run-time.
The
sequence
that
holds
the
available
choices
is
specified
via
the
Sequence
Binding.
Child
elements
label
and
value
indirectly
specify
the
label
and
storage
values.
Notice
that
the
run-time
effect
of
itemset
is
the
same
as
using
element
choices
with
child
item
elements
to
statically
author
the
available
choices.
For
each
item
of
the
Sequence
Binding,
an
associated
item
element
is
created.
XForms
Actions
appearing
in
the
content
of
an
itemset
are
created
within
each
item
element,
and
the
in-scope
evaluation
context
for
these
XForms
Actions
is
based
on
the
data
item
for
which
the
item
was
generated
as
described
in
Section
Evaluation
Context
.
Note:
As
with
the
repeat
element,
the
itemset
template
content,
including
XForms
Actions,
is
made
unavailable.
Copies
of
the
itemset
template
content,
including
XForms
Actions,
are
made
available
via
repeated
item
objects.
Common Attributes: Common , UI Common , Sequence Binding
Note:
Whenever
a
refresh
event
is
dispatched
the
ref
is
re-evaluated
to
update
the
list
of
available
choices.
The
following
example
shows
element
itemset
within
control
select
to
specify
a
dynamic
list
of
ice
cream
flavors:
<model id="cone"> <instance> <my:icecream> <my:order/> </my:icecream> </instance> </model> <model id="flavors"> <instance> <my:flavors> <my:flavor type="v"> <my:description>Vanilla</my:description> </my:flavor> <my:flavor type="s"> <my:description>Strawberry</my:description> </my:flavor> <my:flavor type="c"> <my:description>Chocolate</my:description> </my:flavor> </my:flavors> </instance> </model> <select model="cone" ref="my:order"> <label>Flavors</label> <itemset model="flavors" ref="my:flavor"> <label ref="my:description"/> <copy ref="my:description"/> </itemset> </select>
The copy Element
Structurally,
this
element
is
similar
to
The
value
Element
.
It
differs
in
that
it
can
only
be
used
within
itemset
,
and
that
it
works
with
subtrees
of
instance
data
rather
than
simple
values.
Common Attributes: Common , Single Item Binding (author-optional)
If
the
Single
Item
Binding
attributes
indicate
a
node
in
a
model
other
than
the
bound
item
of
the
containing
selection
control,
then
an
error
results
(
The
xforms-binding-error
Event
).
When
a
copy
node
is
selected,
the
following
rules
apply:
- The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an error results ( The xforms-binding-error Event ).
-
The
element
node
associated
with
the
item
, selected by the binding attributes oncopy
, is deep copied as a child of the target node by using aninsert
action ( The insert Element ). - A full computational dependency rebuild is done, followed by recalculate, revalidate, and refresh.
When
a
copy
item
is
deselected,
the
following
rules
apply:
- The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an error results ( The xforms-binding-error Event ).
-
The
child
element
node
associated
with
the
item
, selected by the binding attributes oncopy
, is deleted by using adelete
action ( The delete Element ). - A full computational dependency rebuild, followed by recalculate, revalidate, and refresh.
Note:
If
the
target
node
of
the
select
or
select1
is
readonly,
then
the
insertion
or
deletion
associated
with
the
copy
operation
is
not
performed.
Container Form Controls
This chapter covers XForms view layer features for combining core form controls into user interfaces using container form controls . All core form controls defined in Core Form Controls are treated as individual units for purposes of visual layout e.g., in XHTML processing. A container form control is a form control that provides the ability to combine other form controls in its content into user interfaces.
Aggregation of form controls with markup defined in this chapter provides semantics about the relationship among user interface controls; such knowledge can be useful in delivering a coherent UI to small devices. For example, if the user interface needs to be split up over several screens, controls appearing inside the same aggregation would typically be rendered on the same screen or page.
The XForms Group Module
A
group
element
is
a
container
form
control
that
allows
a
form
author
to
aggregate
other
form
controls
into
a
single,
aggregate
user
interface
component.
The
elements
and
attributes
included
in
this
module
are:
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
Appearance
,
UI
Common
,
Single
|
label?, (( Core Form Controls )|group|switch|repeat| UI Common )* |
The group Element
The
group
element
is
used
as
a
container
for
defining
a
hierarchy
of
form
controls.
Groups
can
be
nested
to
create
complex
hierarchies.
The
author-optional
label
element
has
special
significance
when
it
appears
as
the
first
element
child
of
group
,
representing
a
label
for
the
entire
group.
Common
Attributes:
Common
,
UI
Common
Appearance
,
Single
Node
Item
Binding
(author-optional)
Although
a
group
element
receives
events
associated
with
model
item
properties
of
a
bound
node,
such
as
xforms-readonly
and
xforms-invalid
,
no
special
behavior
is
imparted
by
the
group
onto
the
content
elements
in
the
group
as
a
direct
result
of
any
model
item
property.
The
model
item
property
relevant
of
a
bound
data
node
can
indirectly
affect
the
content
of
the
group
via
its
contribution
to
deciding
whether
the
group
is
relevant
or
non-relevant.
A
group
is
considered
to
be
non-relevant
if
and
only
if:
-
the
Single
NodeItem Binding is expressed and resolves to emptynodeset,sequence, -
the
Single
NodeItem Binding is expressed and resolves to a non-relevant instance node, -
the
group
is contained by a non-relevantswitch
orgroup
(which includes a non-relevantrepeat
object), or -
the
group
is contained by a non-selectedcase
element of aswitch
.
All
content
elements
(e.g.
core
form
controls,
groups,
switches,
repeats
and
host
language
content)
within
a
non-relevant
group
are
handled
as
non-relevant.
When
a
group
becomes
non-relevant,
it
must
receive
event
xforms-disabled
and
then
the
XForms
action
handlers
that
are
listening
for
events
on
the
non-relevant
group
must
be
disabled.
When
a
non-relevant
group
changes
to
being
relevant,
the
XForms
action
handlers
that
listen
for
events
on
the
group
must
become
enabled
and
then
the
group
must
receive
the
event
xforms-enabled
.
Note:
If a group is non-relevant, then the rendering approach used to signify non-relevance is applied to the entire content of the group.
Example:
<group ref="address"> <label>Shipping Address</label> <input ref="line_1"> <label>Address line 1</label> </input> <input ref="line_2"> <label>Address line 2</label> </input> <input ref="postcode"> <label>Postcode</label> </input> </group>
Setting the input focus on a group results in the focus being set to the first form control in the navigation order within that group.
The XForms Switch Module
A
switch
element
is
a
container
form
control
that
allows
the
creation
of
user
interfaces
where
the
user
interface
can
be
varied
based
on
user
actions
and
events.
The
elements
and
attributes
included
in
this
module
are:
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
|
case + | |
Common , selected (xsd:boolean) |
label?, (( Core Form Controls )|group|switch|repeat| Action )* | |
Common , Events , Action Common , case (xsd:IDREF) |
case ? |
The switch Element
This
element
contains
one
or
more
case
elements,
any
one
of
which
is
rendered
at
a
given
time.
When
the
swilabel>Website:
tch
is
created,
the
initially
selected
case
is
governed
by
the
caseref
attribute
if
specified,
and
otherwise
by
the
selected
attributes
of
the
case
s.
The
selected
case
can
then
be
changed
by
the
toggle
action
or
by
any
change
of
the
data
node
indicated
by
the
caseref
attribute,
if
specified.
When
a
new
case
becomes
selected,
any
previously
selected
case
becomes
deselected.
The
selected
and
deselected
case
elements
receive
events
xforms-select
and
xforms-deselect
regardless
of
how
they
are
selected
and
deselected.
Note:
This
The
selection
of
a
case
and
deselection
of
all
other
cases
is
separate
from
XForms
relevant
processing
(see
The
relevant
Property
),
which
is
based
on
the
current
state
of
the
XForms
Model.
As
an
example,
portions
of
a
questionnaire
pertaining
to
the
user's
automobile
may
become
relevant
only
if
the
user
has
answered
in
the
affirmative
to
the
question
'Do
you
own
a
car?'.
By
comparison,
one
use
of
the
case
s
of
a
switch
is
to
guide
a
user
through
a
sequence
of
user
interfaces
that
collect
data,
all
of
which
is
relevant.
Common
Attributes:
Common
,
UI
Common
Appearance
,
Single
Node
Item
Binding
(author-optional)
Although
Special
Attributes:
- caseref
-
Author-optional
XPath
expression
indicating
an
instance
node
with
which
the
identity
of
the
selected
case
is synchronized.
If
the
caseref
attribute
is
specified,
then
it
takes
precedence
over
the
selected
attributes
of
the
case
elements,
whether
or
not
it
indicates
an
existing
instance
node
and
whether
or
not
the
instance
node
contains
a
value
that
matches
the
ID
of
a
case
.
The
caseref
attribute
is
evaluated
relative
to
the
Single
Item
Binding,
if
specified,
or
the
in-scope
evaluation
context
otherwise.
The
result
is
interpreted
as
a
node-sequence,
and
the
first
node
is
obtained,
if
any.
It
is
an
xforms-binding-error
if
the
first
node
obtained
has
a
child
element.
The
caseref
value
is
considered
to
be
the
string
value
of
the
first
node
if
the
expression
result
is
a
non-empty
nodeset,
and
empty
string
if
the
result
is
not
a
node-sequence
or
an
empty
sequence.
The
result
of
the
caseref
expression
is
kept
up
to
date
in
a
manner
consistent
with
user
interface
bindings.
It
is
an
xforms-binding-error
if
the
expression
changes
to
indicating
a
node-sequence
whose
first
node
has
a
child
element.
The
caseref
value
can
change
due
to
a
change
of
the
value
of
the
node
indicated
by
the
caseref
expression,
or
by
the
expression
binding
changing,
either
from
one
node
to
another,
from
not
indicating
a
node
to
indicating
a
node,
or
from
indicating
a
node
to
not
indicating
a
node.
If
the
caseref
value
changes,
then
the
selected
case
of
the
switch
is
changed
to
reflect
the
new
caseref
value.
Whether
initially
selecting
a
case
or
selecting
a
case
due
to
a
caseref
value
change,
the
case
that
is
selected
is
based
on
ID
matching.
If
the
caseref
value
is
a
non-empty
string
that
matches
the
ID
of
a
case
in
the
switch
,
then
the
matched
case
is
selected.
If
the
caseref
value
is
empty
string
or
is
not
equal
to
the
ID
of
a
case
in
the
switch
,
then
the
selected
case
is
the
first
case
child
element
of
the
switch
.
In
this
latter
circumstance,
if
caseref
refers
to
a
node,
the
value
of
the
node
is
not
changed.
If
the
caseref
attribute
is
not
specified,
then
the
initially
selected
case
is
governed
by
the
selected
attributes
of
the
case
elements,
and
changes
to
the
selected
case
can
only
be
made
by
the
toggle
action.
If
the
caseref
attribute
is
specified,
then
changes
to
the
selected
case
can
be
made
by
changes
to
the
caseref
value
as
described
above,
such
as
by
the
setvalue
action.
Changes
to
the
selected
case
can
also
be
performed
by
the
toggle
action,
but
these
are
performed
by
performing
a
setvalue
action
if
the
caseref
attribute
is
specified
and
indicates
a
node.
If
the
node
is
readonly
or
if
the
toggle
action
does
not
indicate
a
case
in
the
switch
,
then
no
value
change
occurs
and
therefore
no
change
of
the
selected
case
occurs.
If
the
switch
element
contains
a
Single
Item
Binding,
then
it
receives
events
associated
with
model
item
properties
of
a
bound
node,
such
as
xforms-readonly
and
xforms-invalid
.
No
special
behavior
is
imparted
by
the
,
no
switch
onto
the
content
elements
in
the
selected
case
as
a
direct
result
of
any
model
item
property.
The
model
item
property
relevant
of
a
bound
data
node
can
indirectly
affect
the
content
of
the
selected
case
via
its
contribution
to
deciding
whether
the
containing
switch
is
relevant
or
non-relevant.
The
non-relevance
of
a
switch
is
determined
in
the
same
way
as
it
is
for
group
and
similarly
applies
to
the
entire
content.
Also,
as
with
group
,
when
a
switch
becomes
non-relevant,
it
must
receive
event
xforms-disabled
and
then
the
XForms
action
handlers
that
are
listening
for
events
on
the
non-relevant
switch
must
be
disabled.
As
well,
when
a
non-relevant
switch
changes
to
being
relevant,
the
XForms
action
handlers
that
listen
for
events
on
the
switch
must
become
enabled
and
then
the
switch
must
receive
the
event
xforms-enabled
.
Example:
<switch> <case id="in" selected="true"> <input ref="yourname"> <label>Please tell me your name</label> <toggle ev:event="DOMActivate" case="out"/> </input> </case> <case id="out" selected="false"> <html:p>Hello <output ref="yourname" /> <trigger id="editButton"> <label>Edit</label> <toggle ev:event="DOMActivate" case="in"/> </trigger> </html:p> </case> </switch>
The
above
results
in
the
portion
of
the
user
interface
contained
in
the
first
case
being
displayed
initially.
This
prompts
for
the
user's
name;
filling
in
a
value
and
activating
the
control
e.g.,
by
pressing
enter
results
switches
to
the
alternate
case,
with
a
read-only
output
rendering.
Activating
the
trigger
labeled
"Edit"
in
turn
switches
back
to
the
original
case.
Example:
<select1 ref="/payment/details/@method">
<label>Select Payment Method</label> <item><label>Credit Card</label><value>creditCard</value></item> <item><label>Bank Account Card</label><value>cashCard</value></item> <item><label>Cash on delivery</label><value>COD</value></item>
</select1>
<switch ref="/payment/details" caseref="@method">
<case id="creditCard"> <label>Credit Card Details</label> ... </case>
<case id="cashCard"> <label>Bank Account Card</label> ... </case>
<case id="COD"> <label>Cash-on-delivery Account Information</label> ... </case>
</switch>
In
this
example,
if
the
payment
method
is
initially
empty,
then
initially
the
credit
card
details
case
will
be
selected.
Once
the
user
chooses
a
payment
method
with
the
select1
,
then
the
case
is
selected
whose
ID
matches
the
selected
item
value.
The case Element
This
element
encloses
markup
to
be
conditionally
rendered.
When
a
case
is
selected,
it
receives
the
event
xforms-select
,
and
its
content
is
rendered.
When
a
case
is
deselected,
it
receives
the
event
xforms-deselect
.
The
content
elements
(e.g.
form
controls,
groups,
switches,
repeats
and
host
language
elements)
within
a
non-selected
case
behave
as
if
they
were
in
a
non-relevant
group
(see
The
group
Element
).
Similarly,
content
elements
in
a
case
that
becomes
selected
behave
as
if
they
were
in
a
group
that
has
become
relevant.
The
If
the
containing
switch
does
not
specify
the
caseref
attribute,
then
the
attribute
selected
determines
the
initial
selected
state.
The
selected
state
of
the
case
,
and
the
toggle
can
be
changed
with
action
is
used
to
change
the
selected
case
.
The
toggle
action,
which
action
uses
a
case
attribute
or
a
case
child
element
to
make
an
ID
reference
to
the
case
of
the
switch
to
select.
Common Attributes: Common
Special Attributes:
- selected
-
Author-optional
initial
selection
status
for
the
case.
The
default
value
is
"false"
. This attribute is ignored if theswitch
specifies thecaseref
attribute.
If
the
containing
switch
does
not
specify
the
caseref
attribute,
then
the
initially
selected
case
within
a
switch
is
the
one
marked
as
selected="true"
.
If
multiple
case
s
within
a
switch
are
marked
as
selected="true"
,
the
first
selected
case
remains
in
document
order
is
initially
selected
and
all
others
are
deselected.
If
none
of
the
case
s
within
a
switch
are
selected,
marked
as
selected="true"
,
the
first
case
in
document
order
becomes
initially
selected.
The XForms Dialog Module
A
dialog
element
is
a
top-level
container
form
control
that
allows
the
definition
of
a
dialog,
which
can
be
shown
or
hidden
at
different
points
in
time.
The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
dialog | Common , Appearance , UI Common , level?, hide(xsd:boolean) | label?, (( Core Form Controls )|group|switch|repeat| UI Common )* |
show | Common , Events , Action Common , dialog(xsd:IDREF) | EMPTY |
hide | Common , Events , Action Common , dialog(xsd:IDREF) | EMPTY |
Example:
<dialog id="my-dialog"> <label>Please enter your information</label> <input ref="first-name"> <label>First Name:</label> </input> <input ref="last-name"> <label>Last Name:</label> </input> <input ref="e-mail"> <label>E-mail:</label> </input> <trigger> <label>Submit</label> <hide ev:event="DOMActivate" dialog="my-dialog"/> </trigger> </dialog>
A
graphical
browser
might
render
the
above
dialog
as
follows:
The dialog Element
Common Attributes: Common , Appearance , UI Common
Special Attributes:
- level
- Author-optional attribute, containing a dialog level identifier, one of ("modeless"|"modal"|QNameButNotNCName). The default is "modal" if the attribute is not specified. This specification does not define behavior for QNameButNotNCName values.
- hide
-
Author-optional,
indicating
if
the
processor
should
provide
a
way
to
hide
the
dialog.
The
default
value
is
true
. On a graphical browser an "x" could be shown in the dialog title bar when hide is set totrue
. If you specifyhide="false"
, then you should provide a way to hide the dialog, for instance by having you own "Close" button inside the dialog. This is typically useful when you want to force users to enter some data before proceeding and you don't want them to cancel the current operation by closing the dialog.
When a modal dialog is shown the user can't interact with any UI control on the page outside of that dialog. A graphical browser could visualize this by shielding the document with a partially transparent mask when a modal dialog is shown.
The dialog generates an implicit group that contains the content elements (e.g. form controls, groups, switches, repeats and host language elements). When the dialog is shown the implicit group is relevant, when the dialog is hidden the implicit group is non-relevant.
Note: It should be possible to show a new dialog from within a modal dialog.
The show Element
This XForms Action begins by invoking the [#action-deferred-update-behavior|deferred update behavior]]. This action then shows the specified dialog by dispatching an xforms-dialog-show event to the dialog that is being shown.
Common Attributes: Common , Events , Action Common
Special Attributes:
- dialog
-
Required
reference
to
a
dialog
element. Thedialog
to select is specified by this attribute.
Note:
This action affects deferred updates by performing deferred update in its initialization.
The hide Element
This XForms Action begins by invoking the [#action-deferred-update-behavior|deferred update behavior]]. This action then hides the specified dialog by dispatching an xforms-dialog-hide event to the dialog that is being hidden.
Common Attributes: Common , Events , Action Common
Special Attributes:
- dialog
-
Required
reference
to
a
dialog
element. Thedialog
to select is specified by this attribute.
Note:
This action affects deferred updates by performing deferred update in its initialization.
The xforms-dialog-show Event
Dispatched in response to a show action executed with an existing dialog id.
Target:
dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Show the dialog if it isn't shown already.
The default action for this event results in the following steps:
- Adjusts the shown state of the dialog.
- Makes the dialog available to the user.
- Dispatches the xforms-dialog-shown event
The xforms-dialog-hide Event
Dispatched in response to a hide action executed with an existing dialog id.
Target:
dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Hide the dialog if it isn't hidden already.
The default action for this event results in the following steps:
- Adjusts the shown state of the dialog.
- Makes the dialog unavailable to the user.
- Dispatches the xforms-dialog-hidden event
The xforms-dialog-shown Event
Dispatched in response to a dialog being shown.
Target:
dialog
Bubbles: Yes
Cancelable: No
Context Info: none
The default action for this event results in the following: None; notification event only.
Dispatched in response to a dialog being hidden.
Target:
dialog
Bubbles: Yes
Cancelable: No
Context Info: none
The default action for this event results in the following: None; notification event only.
The XForms Repeat Module
The
XForms
specification
allows
the
definition
of
repeating
structures
such
as
multiple
items
within
a
purchase
order.
When
defining
the
XForms
Model,
such
higher-level
collections
are
constructed
out
of
basic
building
blocks;
similarly,
this
section
defines
a
container
form
control
called
repeat
that
can
bind
to
data
structures
such
as
lists
and
collections
and
provide
a
user
interface
for
each
node
item
of
the
list
or
collection..
collection.
The
elements
and
attributes
included
in
this
module
are:
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
|
(( Core Form Controls )|group|switch|repeat| Action )* | |
Common , Events , Action Common , repeat (xsd:IDREF), index (number Expression) |
EMPTY | |
|
|
N/A |
The repeat Element
This
element
defines
a
UI
mapping
over
a
node-set
sequence
selected
by
Node
Set
Sequence
Binding
Attributes.
This
node-set
sequence
is
called
a
repeat
collection
.
The
markup
contained
within
the
body
of
element
repeat
specifies
the
template
of
the
user
interface
to
be
generated
for
each
node
item
of
the
repeat
collection.
For
each
node
item
of
the
repeat
collection,
a
repeat
item
is
defined
to
be
the
aggregation
of
the
node,
item,
its
position,
the
size
of
the
repeat
collection,
and
a
repeat
object
.
A
repeat
object
is
an
implicitly
generated
group
element
that
contains
the
set
of
run-time
objects
generated
to
represent
the
repeat
template
content
for
a
single
repeat
item
of
the
repeat
collection.
These
run-time
objects
are
form
controls,
XForms
actions
and
other
host
language
elements
that
correspond
to
markup
content
in
the
repeat
template.
If
a
node
an
item
of
the
repeat
collection
is
non-relevant,
then
the
rendering
approach
used
to
signify
non-relevance
is
applied
to
the
user
interface
controls
of
the
associated
repeat
object.
The
XForms
processor
Processor
associates
with
each
repeat
collection
an
integer
value,
called
a
repeat
index
,
that
is
between
0
and
the
size
of
the
repeat
collection
to
indicate
a
repeat
object
that
may
be
the
focus
of
certain
XForms
processor
Processor
operations.
This
repeat
index
is
accessed
via
XForms
function
index
(see
The
index()
Function
).
Common
Attributes:
Common
,
UI
Common
Appearance
,
Node
Set
Sequence
Binding
Special Attributes:
- indexref
- Author-optional XPath expression indicating an instance node with which the repeat index is synchronized.
- startindex
-
Author-optional
1-based
initial
value
of
the
repeat
index.
The
default
value
is
1.
This
attribute
is
ignored
if
the
indexref
is specified. - number
- Author-optional hint to the XForms Processor as to how many elements from the collection to display.
Example:
<repeat ref="/cart/products/product"> <input ref="." ...> <label>...</label> </input> <html:br/> </repeat>
The
repeat
element
operates
over
a
repeat
collection
by
creating
repeat
objects
and
binding
them
to
the
nodes
items
of
the
collection.
Another
way
to
conceptually
grasp
repeat
processing
(disregarding
special
user
interface
interactions)
is
to
consider
"unrolling"
the
repeat.
The
above
example
is
similar
to
the
following
(given
four
product
elements
in
the
returned
node-set):
sequence):
<input ref="/cart/products/product[1]"><label>...</label></input><html:br/> <input ref="/cart/products/product[2]"><label>...</label></input><html:br/> <input ref="/cart/products/product[3]"><label>...</label></input><html:br/> <input ref="/cart/products/product[4]"><label>...</label></input><html:br/>
The repeat collection can be an arbitrary sequence of items. The items in the repeat collection can be either nodes, atomic values or a mix of them. The nodes in the repeat collection don't have to be in document order, and the same node can occur multiple times in the repeat collection.
<repeat ref="1 to 10"> <output value="." ...> <label>...</label> </input> <html:br/> </repeat>
The
capture
and
bubble
phases
of
events
dispatched
to
the
run-time
objects
behave
as
if
the
repeat
object
were
a
child
of
element
repeat
.
The
repeat
template
content,
including
action
handlers,
is
made
unavailable
to
the
host
language
processor.
Copies
of
the
repeat
template
content,
including
Action
handlers,
are
made
available
via
the
repeat
objects.
Thus,
to
handle
an
event
targeted
at
a
repeat
element,
it
is
necessary
to
place
the
action
handler
outside
of
the
repeat
template,
as
in
this
example:
repeat
Element
<repeat id="X" ... > ... </repeat><action ev:event="xforms-scroll-first" ev:target="X" ev:observer="X">
<action ev:event="xforms-scroll-first" ev:target="X" ev:observer="X"> ... </action>
XForms
Actions
insert
and
delete
(see
XForms
Actions
)
can
be
used
to
directly
operate
on
a
repeat
collection
nodeset,
sequence,
and
the
XPath
function
index
can
be
used
to
help
focus
the
behavior
of
the
actions
at
a
point
of
interest
to
the
user.
For
example:
<model> <instance> <my:lines> <my:line name="a"> <my:price>3.00</my:price> </my:line> <my:line name="b"> <my:price>32.25</my:price> </my:line> <my:line name="c"> <my:price>132.99</my:price> </my:line> </my:lines> </instance> </model> ... <repeat id="lineset" ref="my:line"> <input ref="my:price"> <label>Line Item</label> </input> <input ref="@name"> <label>Name</label> </input> </repeat><trigger>
<trigger> <label>Insert a new Line Item after the current one</label> <action ev:event="DOMActivate"> <insert ref="my:line" at="index('lineset')" position="after"/> <setvalue ref="my:line[index('lineset')]/@name"/> <setvalue ref="my:line[index('lineset')]/price">0.00</setvalue> </action> </trigger><trigger>
<trigger> <label>remove current item</label> <delete ev:event="DOMActivate" ref="my:line" at="index('lineset')"/> </trigger>
If
the
indexref
attribute
is
specified,
then
it
takes
precedence
over
the
startindex
attribute,
whether
or
not
the
indexref
expression
indicates
an
existing
instance
node
and
whether
or
not
the
instance
node
contains
an
integer
value
between
0
and
the
size
of
the
repeat
collection.
The
indexref
attribute
is
evaluated
relative
to
the
in-scope
evaluation
context
of
the
repeat
element.
The
result
is
interpreted
as
a
node-sequence,
and
the
first
node
is
obtained,
if
any.
It
is
an
xforms-binding-error
if
the
first
node
obtained
has
a
child
element.
A
numeric
result
is
calculated.
If
the
indexref
evaluation
does
not
produce
a
first
node,
then
the
numeric
result
is
NaN
.
Otherwise,
the
content
of
the
first
node
is
converted
to
a
number
(possibly
NaN
).
If
the
numeric
result
is
NaN
,
then
the
indexref
value
is
0
if
the
repeat
collection
is
empty
and
1
otherwise.
If
the
numeric
result
is
not
NaN
,
then
the
numeric
result
is
rounded
to
the
nearest
integer,
and
the
indexref
value
is
the
closest
integer
to
the
numeric
result
that
is
in
the
range
0
to
the
size
of
the
repeat
collection.
The
result
of
the
indexref
expression
is
kept
up
to
date
in
a
manner
consistent
with
user
interface
bindings.
It
is
an
xforms-binding-error
if
the
expression
changes
to
indicating
a
node-sequence
whose
first
node
has
a
child
element.
The
indexref
value
can
change
due
to
a
change
of
the
value
of
the
node
indicated
by
the
indexref
expression,
or
by
the
expression
binding
changing,
either
from
one
node
to
another,
from
not
indicating
a
node
to
indicating
a
node,
or
from
indicating
a
node
to
not
indicating
a
node.
If
the
indexref
value
changes,
then
the
repeat
index
associated
with
the
repeat
collection
is
changed.
Whether
during
initialization
or
in
response
to
a
change
of
the
indexref
value,
the
new
setting
for
the
repeat
index
may
not
be
equal
to
the
data
value
in
the
node
indicated
by
indexref
.
This
can
occur
if
the
data
value
was
rounded
or
if
it
was
coerced
to
be
in
the
range
0
to
the
size
of
the
repeat
collection.
In
this
circumstance,
if
the
indexref
expression
indicates
a
node,
the
value
of
the
node
is
not
changed.
If
the
indexref
attribute
is
not
specified,
then
the
repeat
index
is
initialized
to
the
closest
integer
to
the
value
in
the
startindex
attribute,
or
its
default,
that
is
in
the
range
0
to
the
size
of
the
repeat
collection,
and
changes
to
the
repeat
index
can
only
be
made
by
the
setindex
action.
If
the
indexref
attribute
is
specified,
then
changes
to
the
repeat
index
can
be
made
by
changes
to
the
indexref
value
as
described
above,
such
as
by
the
setvalue
action.
Changes
to
the
repeat
index
can
also
be
performed
directly
by
the
setindex
action,
but
these
are
performed
by
performing
a
setvalue
action
if
the
indexref
attribute
is
specified
and
indicates
a
node.
If
the
node
is
readonly,
then
no
value
change
occurs
and
therefore
no
change
of
repeat
index
occurs.
Regardless
of
how
the
repeat
index
value
is
changed,
if
the
new
value
was
greater
than
the
size
of
the
non-empty
repeat
collection,
then
the
event
xforms-scroll-last
is
dispatched
to
the
repeating
element
to
indicate
that
the
repeat
index
value
was
coerced
to
the
size
of
the
repeat
collection.
Similarly,
if
the
new
value
was
increased
to
1,
then
xforms-scroll-first
is
dispatched
to
the
repeat
element.
Nested Repeats
The
form
controls
appearing
inside
repeat
need
to
be
suitable
for
populating
individual
items
of
the
collection.
A
simple
but
powerful
consequence
of
the
above
is
that
if
the
XForms
Model
specifies
nested
collections,
then
a
corresponding
user
interface
can
nest
repeat
elements.
It
is
possible
to
nest
repeat
elements
to
create
more
powerful
user
interface
for
editing
structured
data.
Editing
Hierarchical
Bookmarks
Using
XForms
is
an
example
of
a
form
using
nested
repeats
to
edit
hierarchical
data
consisting
of
bookmarks
within
multiple
sections.
Consider
the
following
insert
statement
that
appears
as
part
of
that
example.
<insert ref="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" position="after"/>
The
above
insert
statement
is
used
in
that
example
to
add
new
bookmark
entries
into
the
currently
selected
section.
The
inner
(nested)
repeat
operates
on
bookmarks
in
this
selected
section;
The
index
—
as
returned
by
XForms
function
index
—
for
this
inner
repeat
starts
at
1
.
Hence,
after
a
new
empty
section
of
bookmarks
is
created
and
becomes
current
,
the
first
insert
bookmark
operation
adds
the
newly
created
bookmark
at
the
front
of
the
list.
Repeat Processing
During
user
interface
initialization
(see
The
xforms-model-construct-done
Event
),
the
following
steps
are
performed
for
repeat
:
-
The
Node SetSequence Binding is evaluated to locate the repeat collection to be operated on by thisrepeat
. -
The
index for this repeating structure is initialized to the value of startindex . If the initial startindex is less than 1 it defaults to 1. If therepeat index isgreater than the initial node-set then it defaults to the size of the node-set.initialized. -
UserRepeat items are generated with repeat objects each having a user interface as specified by the repeatis generatedtemplate for the requisite number of members of the repeat collection as specified by attributes on elementrepeat
.
A
new
repeat
item
is
created
dynamically
at
any
time
in
the
lifecycle
of
the
form
(i.e.
any
time
after
xforms-model-construct-done
)
whenever
a
new
node
item
is
added
to
the
repeat
collection
.
There
are
many
ways
to
add
new
nodes
items
to
a
repeat
collection
,
including
but
not
limited
to
the
following:
-
An
insert
action can add one or more nodes that match the repeatnodeset;sequence; -
The
new
instance
data
subtree
created
by
a
submission
instance replacement may contain nodes that match the repeatnodeset;sequence; -
A
setvalue
action or acalculate
may change a value that causes one or morenodesitems to match the repeatnodeset.sequence.
Any
time
a
new
repeat
item
is
created,
XML
Event
handlers
declared
within
the
corresponding
repeat
object
are
initialized,
and
the
user
interface
form
controls
generated
for
the
repeat
object
are
initialized
in
the
same
manner
as
the
user
interface
initialization
that
is
performed
during
default
processing
of
xforms-model-construct-done
.
For
example,
if
the
repeat
object
contains
an
inner
repeat
run-time
object,
then
it
is
initialized
according
to
the
list
of
steps
at
the
beginning
of
this
section
(
Repeat
Processing
).
If
one
or
more
nodes
items
have
been
added
to
the
repeat
collection
by
for
example
an
insert
action,
then
the
repeat
items
corresponding
to
the
new
nodes
items
must
be
created
and
initialized,
and
the
repeat
index
must
be
updated
to
indicate
the
repeat
item
corresponding
to
the
last
node
item
added
by
the
insert
.
Note:
The
change
of
index
on
a
repeat
does
not
cause
the
index
of
any
repeat
nested
within
it
to
be
re-initialized.
The
repeat
item
generation
and
repeat
index
update
on
insertion
must
behave
as
if
it
occurs
in
response
to
the
xforms-insert
event
dispatched
by
the
insert
action.
The
index
update
must
behave
as
if
it
occurs
when
the
xforms-insert
event
reaches
the
parent
of
the
target
instance
element
in
the
capture
phase.
Note:
An
event
handler
that
listens
for
xforms-insert
on
instance
in
the
default
phase
has
access
to
the
updated
index
value
via
function
index()
.
A
repeat
item
can
also
be
destroyed
dynamically
at
any
time
in
the
lifecycle
of
the
form
whenever
a
node
an
item
is
removed
from
the
repeat
collection
.
When
a
repeat
item
is
destroyed,
the
repeat
object
and
all
of
its
inner
form
controls
are
eliminated,
including
inner
repeats,
switches
and
groups,
and
all
XML
Event
handlers
created
by
the
repeat
object
are
eliminated.
There
are
many
ways
to
remove
repeat
items
from
a
repeat
collection
,
including
but
not
limited
to
the
following:
-
A
delete
action can removenodesitems that matched the repeatnodeset;sequence; -
The
new
instance
data
subtree
created
by
a
submission
instance replacement may replacenodesitems that matched the repeatnodeset;sequence; -
A
setvalue
action or acalculate
may change a value that causes one or morenodesitems to stop matching the repeatnodeset.sequence.
If
one
or
more
nodes
items
have
been
removed
from
the
repeat
collection
by
a
delete
action,
then
the
repeat
items
corresponding
to
the
deleted
nodes
items
must
be
destroyed
and
the
repeat
index
must
be
updated
based
on
the
rules
below.
-
If,
prior
to
nodeitem deletion, the repeat index indicated a repeat item that is still contained in the repeat collection afternodeitem deletion, then the index is adjusted, if necessary, to indicate that same repeat item. - Otherwise, if all repeat items in the collection have been destroyed, the repeat index is set to 0.
- Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is smaller than the index, the index is changed to the new size of the collection.
- Otherwise, if the repeat index was pointing to one of the deleted repeat items, and if the new size of the collection is equal to or greater than the index, the index is not changed.
Note:
The
change
of
index
on
a
repeat
does
not
cause
the
index
of
any
repeat
nested
within
it
to
be
re-initialized.
The
repeat
index
update
on
deletion
behaves
as
if
it
occurs
in
response
to
the
xforms-delete
event
dispatched
by
the
delete
action.
Specifically,
the
index
update
behaves
as
if
it
occurs
when
the
xforms-delete
event
reaches
the
parent
of
the
target
instance
element
in
the
capture
phase.
User Interface Interaction
Element
repeat
enables
the
binding
of
user
interaction
to
a
node-set,
sequence,
referred
to
as
repeat
collection
.
The
number
of
displayed
items
might
be
less
than
the
total
number
available
in
the
collection.
In
this
case,
the
presentation
would
render
only
a
portion
of
the
repeating
items
repeat
objects
at
a
given
time.
For
example,
a
graphical
user
interface
might
present
a
scrolling
table.
The
current
item
indicated
by
the
repeat
index
should
be
made
available
to
the
user
at
all
times,
for
example,
not
allowed
to
scroll
out
of
view.
The
XForms
Actions
enumerated
at
XForms
Actions
may
be
used
within
event
listeners
to
manipulate
the
repeat
collection
being
populated
by
scrolling,
inserting,
and
deleting
entries.
Notice
that
the
markup
encapsulated
by
element
repeat
acts
as
the
template
for
the
user
interface
that
is
presented
to
the
user.
As
a
consequence,
statically
authored
IDREF
attributes
must
be
interpreted
based
on
a
combination
of
repeat
indexes
and
where
the
IDREF
attributes
appear
relative
to
the
element
bearing
the
matching
ID.
Based
on
the
IDREF
resolution
rules
given
in
Resolving
ID
References
in
XForms
,
it
is
possible
to
toggle
the
case
of
a
switch
even
when
it
is
within
one
or
more
repeat
elements.
Similarly,
it
is
possible
to
set
the
focus
to
controls
and
dispatch
events
to
elements
that
are
within
one
or
more
repeat
elements.
If
the
focus
is
transferred
to
a
form
control
within
a
repeat
by
any
means,
such
as
by
an
XForms
action
or
by
user
interaction,
the
index
of
the
repeat
is
updated
to
indicate
the
item
of
the
repeat
collection
that
contains
the
control.
If
the
repeat
item
containing
the
focused
control
contains
any
inner
repeat
objects,
their
indexes
are
not
changed.
However,
the
repeat
index
update
is
recursive
for
all
outer
repeats
that
contain
the
focused
control;
the
index
of
each
outer
containing
repeat
is
adjusted
appropriately.
These
changes
of
repeat
index
occurs
as
if
by
invoking
the
setindex
action.
Creating Repeating Structures Via Attributes
Element
repeat
enables
the
creation
of
user
interfaces
for
populating
repeating
structures.
When
using
XForms
within
host
languages
like
XHTML,
it
is
often
necessary
to
create
repeating
structures
within
constructs
such
as
table
.
Thus,
one
might
wish
to
use
element
repeat
within
a
table
to
create
the
rows
of
a
table,
where
each
row
of
the
table
binds
to
a
distinct
member
of
a
repeat
collection
.
Since
html:table
doesn't
(and
perhaps
never
will)
allow
xforms:repeat
elements
as
children,
another
syntax
is
needed.
<table><repeat nodeset="..."><repeat ref="..."> <tr> <td>...</td> ... </tr> </repeat> </table>
More
generally,
there
is
a
need
to
integrate
repeat
behavior
into
host
languages
at
points
where
the
content
model
of
the
host
language
does
not
or
cannot
provide
the
appropriate
extension
hooks
via
modularization.
To
accommodate
this,
XForms
defines
an
alternative
syntax
that
is
functionally
equivalent
to
the
repeat
element,
using
the
following
global
attributes:
xforms:repeat-model
xforms:repeat-bind
xforms:repeat-ref
xforms:repeat-nodeset
(deprecated)
xforms:repeat-startindex
xforms:repeat-number
xforms:repeat-indexref
The
above
attributes
are
equivalent
to
the
local
repeat
attributes
of
the
same
name,
but
without
except
for
the
namespace
qualifications
and
the
prefix
repeat-
.
A
host
language
can
include
these
attributes
in
the
appropriate
places
to
enable
repeating
constructs.
For
example,
a
version
of
XHTML
might
use:
<table xforms:repeat-ref="..."> <tr> <td><xforms:output ref="..."/></td> </tr> </table>
Which
This
example
could
be
validated
against
an
appropriately
configured
XHTML
Schema
that
includes
the
XForms
Repeat
module.
Note
that
what
gets
repeated
is
the
child
elements
and
descendant
content
of
the
element
with
the
global
repeat-
attributes.
attributes,
i.e.
the
tr
is
repeated,
not
the
table
.
Also
note
that
if
the
table
must
contain
a
thead
,
then
the
repeat-
attributes
could
instead
be
attached
to
a
tbody
to
repeat
its
contained
tr
.
Additionally,
when
using
XForms
Action
setindex
,
attribute
repeat
of
type
idref
can
point
to
any
element
carrying
the
these
global
repeat
attributes.
Similarly,
when
using
function
index
against
a
repeating
structure
created
via
the
repeat-
attributes,
the
id
of
that
element
can
be
used
as
the
argument
to
function
index
.
Processing Model
This chapter defines the XForms Processing Model declaratively by enumerating the various states attained by an XForms Processor and the possible state transitions that exist in each of these states. The chapter enumerates the pre-conditions and post-conditions that must be satisfied in each of these states. XForms Processors may be implemented in any manner, so long as the end results are identical to that described in this chapter.
State transitions are in general initiated by sending events to parts of the XForms tree. The XForms Processing Model consists of events in the following categories:
- Initialization
- Interaction
- Notification
- Error Conditions
Events Overview
XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in [ DOM2 Events ][ XML Events ], with an event capture phase, arrival of the event at its Target, and finally the event bubbling phase.
Event name | Cancelable? | Bubbles? | Target element |
---|---|---|---|
xforms-model-construct | No | Yes |
model
|
xforms-model-construct-done | No | Yes |
model
|
xforms-ready | No | Yes |
model
|
xforms-model-destruct | No | Yes |
model
|
xforms-rebuild | Yes | Yes |
model
|
xforms-recalculate | Yes | Yes |
model
|
xforms-revalidate | Yes | Yes |
model
|
xforms-refresh | Yes | Yes |
model
|
xforms-reset | Yes | Yes |
model
|
xforms-previous | Yes | No | |
xforms-next | Yes | No | |
xforms-focus | Yes | No |
Core
Form
Controls
|
|
xforms-help | Yes | Yes | |
xforms-hint | Yes | Yes | |
xforms-submit | Yes | Yes |
submission
|
xforms-submit-serialize | No | Yes |
submission
|
xforms-insert | No | Yes |
instance
|
xforms-delete | No | Yes |
instance
|
xforms-value-changed | No | Yes | |
xforms-valid | No | Yes |
Core
Form
Controls
|
|
xforms-invalid | No | Yes |
Core
Form
Controls
|
|
xforms-readonly | No | Yes |
Core
Form
Controls
|
|
xforms-readwrite | No | Yes |
Core
Form
Controls
|
|
xforms-required | No | Yes |
Core
Form
Controls
|
|
xforms-optional | No | Yes |
Core
Form
Controls
|
|
xforms-enabled | No | Yes |
Core
Form
Controls
|
|
xforms-disabled | No | Yes |
Core
Form
Controls
|
|
DOMActivate | Yes | Yes | |
DOMFocusIn | No | Yes |
Core
Form
Controls
|
|
DOMFocusOut | No | Yes |
Core
Form
Controls
|
|
xforms-select | No | Yes |
item
or
case
|
xforms-deselect | No | Yes |
item
or
case
|
xforms-in-range | No | Yes | |
xforms-out-of-range | No | Yes | |
xforms-scroll-first | No | Yes |
repeat
|
xforms-scroll-last | No | Yes |
repeat
|
xforms-submit-done | No | Yes |
submission
|
|
| Yes | any element that can contain a binding expression |
xforms-expression-error | Yes | Yes | any element that is not an action element and that can contain an expression which is not a binding expression |
xforms-action-error | Yes | Yes | any element that is an event observer for an action handler |
xforms-compute-exception | No | Yes |
model
|
|
|
Yes |
The
default
model
|
xforms-link-exception | No | Yes |
model
|
xforms-output-error | No | Yes |
output
|
xforms-submit-error | No | Yes |
submission
|
Initialization Events
This
section
defines
the
various
stages
of
the
initialization
phase.
The
processor
begins
initialization
by
dispatching
an
event
xforms-model-construct
to
each
XForms
Model
in
the
containing
document.
How
the
XForms
Processor
itself
is
requested
to
initialize
is
implementation
dependent.
The xforms-model-construct Event
Dispatched
to
each
XForms
model
by
the
XForms
processor.
Processor.
Target:
model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following:
- All XML Schemas are loaded. If an error occurs while attempting to access or process a remote document, processing halts with an exception ( The xforms-link-exception Event ).
-
For
each
instance
element, an XPath data model[ Expressions in XForms ]is constructed from it as described in Section The instance Element . If there are noinstance
elements, the data model is not constructed in this phase, but during user interface construction ( The xforms-model-construct-done Event ). - If applicable, P3P initialization occurs. [ P3P 1.0 ]
-
Perform
the
behaviors
of
xforms-rebuild
,xforms-recalculate
, andxforms-revalidate
in sequence on thismodel
element without dispatching events to invoke the behaviors. The notification event markings for these operations are discarded, and thexforms-refresh
behavior is not performed since the user interface has not yet been initialized.
After
all
XForms
Models
have
been
initialized,
an
xforms-model-construct-done
event
is
dispatched
to
each
model
element.
The xforms-model-construct-done Event
Dispatched
after
the
completion
of
xforms-model-construct
processing.
Target:
model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event happens once, no matter how many XForms Models are present in the containing document, and results in the following, for each form control :
Processing
can
proceed
in
one
of
two
different
ways
depending
on
whether
an
instance
in
a
model
exists
when
the
first
form
control
is
processed.
If
the
instance
referenced
on
the
form
control
existed
when
the
first
form
control
was
processed:
-
The
single node bindingSingle Item Binding expression is evaluated, if it exists on the form control, to ensure that it points toa node that exists.an item. If this is not the case (result of the expression is the empty sequence) then the form control should behave in the same manner as if it had bound to a model item with therelevant
model item property resolved tofalse
. - Otherwise, the user interface for the form control is created and initialized.
If
the
instance
referenced
on
the
form
control
did
not
exist
when
the
first
form
control
for
the
same
instance
was
processed:
-
For
the
first
reference
to
an
instance
a defaultinstance
is created by following the rules described below.-
A
root
instanceData
element is created. -
An
instance
data
element
node
will
be
created
using
the
binding
expression
from
the
user
interface
control
as
the
name
. If thename
is not a valid QName,processing halts with an exception ( The xforms-binding-exception Eventthe xforms-binding-error).event is dispatched to the control and the control is bound to the empty sequence.
-
A
root
-
For
the
second
and
subsequent
references
to
an
instance
which was automatically created the following processing is performed:- If a matching instance data node is found, the user interface control will be connected to that element.
-
If
a
matching
instance
data
node
is
not
found,
an
instance
data
node
will
be
created
using
the
binding
expression
from
the
user
interface
control
as
the
name
. If thename
is not a valid QName,processing halts with an exception ( The xforms-binding-exception Eventthe xforms-binding-error).event is dispatched to the control and the control is bound to the empty sequence.
Note:
No nodes are created when the first item of the result sequence is an atomic value. And the form control is read-only in this case.
The
above
steps
comprise
the
default
processing
of
xforms-model-construct-done
.
After
all
form
controls
have
been
initialized
and
all
xforms-model-construct-done
events
have
been
processed,
an
xforms-ready
event
is
dispatched
to
each
model
element.
The xforms-ready Event
Dispatched
as
part
of
xforms-model-construct-done
processing.
Target:
model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
The xforms-model-destruct Event
Dispatched
by
the
processor
to
advise
of
imminent
shutdown
of
the
XForms
Processor,
which
can
occur
from
user
action,
or
from
the
load
XForms
Action,
or
as
a
result
of
form
submission.
Target:
model
Bubbles: No
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Interaction Events
The xforms-rebuild Event
Dispatched in response to: a request to rebuild the internal data structures that track computational dependencies within a particular XForms Model.
Target:
model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
All
model
item
properties
are
initialized
by
processing
all
bind
elements
in
document
order.
For
each
bind
:
-
If
the
attribute
nodesetrefan XPath node-set.a sequence of items. Otherwise, if thebind
does not have anodesetrefXPath node-setsequence of items consists of the in-scope evaluation context. -
For
each
nodeitem in the selectedXPath node-set,sequence of items, model item properties are applied according to the remaining attributes on thebind
element (for details on the model item properties, see Model Item Properties ).If a node already contains a model item property of the same name due to the processing of prior bind elements, then XForms processing for the containing document halts with an exception ( The xforms-binding-exception Event ). -
For
each
nodeitem in the selectedXPath node-set,sequence of items, any childbind
elements are recursively processed as described in the three points of this list.
After
initial
processing
of
the
bind
elements,
the
computational
dependency
data
structures
are
rebuilt,
and
then
the
change
list
L
is
set
to
contain
references
to
all
instance
nodes
that
have
an
associated
computational
expression
so
that
a
full
recalculation
is
performed
the
next
time
the
behavior
of
xforms-recalculate
is
invoked.
The xforms-recalculate Event
Dispatched in response to: a request to recalculate all calculations associated with a particular XForms Model.
Target:
model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
The values of all instance data items match their associated 'calculate' constraints, if any. All model item properties that can contain computed expressions are resolved. In addition to contributing further node value changes that will cause xforms-value-changed notifications in xforms-refresh, the model item properties that change are marked to help xforms-refresh to determine the notification events to dispatch.
- If the required model item property changes, then either the xforms-required event must be marked for dispatch if required is true or the xforms-optional event must be marked for dispatch if required is false. Marking one of these events for dispatch unmarks the other.
- If the readonly model item property changes, then either the xforms-readonly event must be marked for dispatch if readonly is true or the xforms-readwrite event must be marked for dispatch if readonly is false. Marking one of these events for dispatch unmarks the other.
- If the relevant model item property changes, then either the xforms-enabled event must be marked for dispatch if relevant is true or the xforms-disabled event must be marked for dispatch if relevant is false. Marking one of these events for dispatch unmarks the other.
An
expression
is
bound
either
to
the
value
or
to
a
model
item
property
(e.g.,
required
,
relevant
)
of
one
or
more
instance
nodes.
The
combination
of
an
expression
with
a
single
instance
node's
value
or
model
item
property
is
considered
as
a
single
computational
unit,
a
compute
,
for
the
purposes
of
recalculation.
When
it
is
time
to
recalculate
a
model
item
property,
the
expression
is
evaluated.
The
evaluation
context
is
determined
from
the
model
binding
expression
that
applied
the
model
item
property,
as
defined
for
computed
expressions
in
Evaluation
Context
.
The
expression
may
reference
or
refer
to
another
instance
node,
in
which
case
the
value
of
the
instance
node
is
referenced
.
Each
referenced
instance
node
has
as
dependents
those
computes
which
directly
refer
to
the
instance
node.
References
to
the
current
node's
value
in
calculate
expressions
are
explicitly
ignored,
i.e.,
if
an
expression
associated
with
a
compute
refers
to
the
instance
node
associated
with
the
compute,
then
the
instance
node
does
not
take
itself
as
a
dependent.
A
compute
is
computationally
dependent
on
an
instance
node
(whose
value
may
or
may
not
be
computed)
if
there
is
a
path
of
dependents
leading
from
the
instance
node
through
zero
or
more
other
instance
nodes
to
the
compute.
A
compute
is
part
of
a
circular
dependency
if
it
is
computationally
dependent
on
itself.
Note:
Referring
to
a
node's
value
in
a
calculate
on
the
node,
as
in
the
following
example,
may
have
effects
that
vary
by
implementation:
<bind
.
Model
item
properties
other
than
nodeset="x"
ref="x"
calculate=".+1"/>
calculate
,
such
as
required
or
readonly
are
well-defined
in
the
presence
of
self-references.
Note:
An
example
of
a
calculate
formula
that
contains
a
self-reference
(i.e.
that
refers
to
the
node
it
calculates)
appears
in
Section
The
readonly
Property
.
The
example
enforces
a
default
value
for
a
node
and,
as
mentioned
above,
does
not
create
a
circular
dependency.
An
example
of
a
circular
dependency
is
<bind
.
In
this
example,
node
nodeset="A|B"
ref="A|B"
calculate="../A
+
../B"/>
A
depends
in
part
on
B
,
and
node
B
depends
in
part
on
A
.
When
a
recalculation
event
begins,
there
will
be
a
list
L
of
one
or
more
instance
nodes
whose
values
may
have
been
changed,
e.g.,
by
user
input
being
propagated
to
the
instance
or
by
a
setvalue
action.
- An XForms Processor must recalculate computes for nodes in L , if any, and nodes that are computationally dependent on nodes in L .
- An XForms Processor must perform only a single recalculation of each compute that is computationally dependent on one or more of the elements in L .
- An XForms Processor must recalculate a compute C after recalculating all computes of instance nodes on which C is computationally dependent. (Equivalently, an XForms Processor must recalculate a compute C before recalculating any compute that is computationally dependent on the instance node associated with C .)
-
Finally,
if
a
compute
is
part
of
a
circular
dependency
and
also
computationally
dependent
on
an
element
in
L
,
then
an
XForms
processorProcessor must report an exception ( The xforms-compute-exception Event ).
Recalculation Sequence Algorithm describes one possible method for achieving the required recalculation behavior.
The xforms-revalidate Event
Dispatched in response to: a request to revalidate a particular XForms Model.
Target:
model
Bubbles: Yes
Cancelable: Yes
Context Info: None
An instance node is valid if and only if the following conditions hold:
- the constraint model item property is true
- the value is non-empty if the required model item property is true
-
the
node
satisfies
all
applicable
XML
schemaSchema definitions (including those associated by thetype
model item property, by an external or an inlineschema,XML Schema, or byxsi:type
)
Note:
xsi:type
attributes
on
instance
data
elements
are
processed
even
in
the
absence
of
external
or
inline
schema.
XML
Schema.
Note:
The
applicable
XML
schema
Schema
definitions
are
determined
as
defined
in
Section
The
model
Element
.
The default action for this event results in the following:
All
instance
data
nodes
in
all
instance
elements
in
the
model
are
checked
for
validity
according
to
the
above
definition.
If
the
validity
of
a
node
changes,
then
either
the
xforms-valid
event
must
be
marked
for
dispatch
if
the
node
changes
from
invalid
to
valid
or
the
xforms-invalid
event
must
be
marked
for
dispatch
if
the
node
changes
from
valid
to
invalid.
Marking
one
of
these
events
for
dispatch
unmarks
the
other.
Note:
Since
the
event
sequence
for
xforms-model-construct
excludes
xforms-refresh
and
discards
event
notification
marks,
form
controls
bound
to
invalid
nodes
do
not
receive
an
initial
xforms-invalid
event.
The xforms-refresh Event
Dispatched in response to: a request to update all form controls associated with a particular XForms Model.
Target:
model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
- All UI Expressions are reevaluated (implementations may optimize this operation but must behave as if all UI Expressions are reevaluated).
-
A
node
can
be
changed
by
a
number
of
mechanisms
in
XForms,
including
confirmed
user
input
to
a
form
control,
an
xforms-recalculate
( The xforms-recalculate Event ), and thesetvalue
action ( The setvalue Element ). If the value of an instance data node was changed, then the node must be marked for dispatching the xforms-value-changed event. - If the xforms-value-changed event is marked for dispatching, then all of the appropriate model item property notification events must also be marked for dispatching (xforms-optional or xforms-required, xforms-readwrite or xforms-readonly, and xforms-enabled or xforms-disabled).
-
The
user
interface
reflects
the
state
of
the
model,
which
means
that
all
forms
controls
and
related
UI
elements
reflect
their
corresponding
instance
data,
including:
- current values (for the appropriate form controls and related UI elements)
- validity
-
other
model
item
properties
(
required
,readonly
andrelevant
). - the proper number of and content for repeat objects.
This process includes sending the notification events to the form controls. For each form control, each notification event for which the form control is a legitimate target and that is marked for dispatching on the bound node must be dispatched (xforms-value-changed, xforms-valid, xforms-invalid, xforms-optional, xforms-required, xforms-readwrite, xforms-readonly, and xforms-enabled, xforms-disabled). The notification events xforms-out-of-range or xforms-in-range must also be dispatched as appropriate. This specification does not specify an ordering for the events.
The xforms-reset Event
Dispatched in response to: a user request to reset the model.
Target:
model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
The
instance
data
is
reset
to
the
tree
structure
and
values
it
had
immediately
after
having
processed
the
xforms-ready
event.
Then,
the
events
xforms-rebuild
,
xforms-recalculate
,
xforms-revalidate
and
xforms-refresh
are
dispatched
to
the
model
element
in
sequence.
The xforms-next and xforms-previous Events
Dispatched in response to: user request to navigate to the next or previous Core Form Control .
Target: Core Form Controls
Bubbles: No
Cancelable: Yes
Context Info: None
The
default
action
for
these
events
results
in
the
following:
Navigation
according
to
the
default
navigation
order.
For
example,
on
a
keyboard
interface,
"tab"
might
generate
an
xforms-next
event,
while
"shift+tab"
might
generate
an
xforms-previous
event.
Navigation
is
determined
on
a
containing
document-wide
basis.
The
host
language
is
responsible
for
defining
overall
navigation
order.
The
following
describes
a
possible
technique
based
on
a
navindex
attribute,
using
individual
form
controls
as
a
navigation
unit:
The
<
group
>,
<
repeat
>,
and
<
switch
>
structures
serve
as
container
navigation
units
that,
instead
of
providing
a
single
navigation
point,
create
a
local
navigation
context
for
child
form
controls
(and
possibly
other
substructures).
The
navigation
sequence
is
determined
as
follows:
-
Form
controls
that
have
a
navindex
specified and assign a positive value to it are navigated first.-
Outermost
form
controls
are
navigated
in
increasing
order
of
the
navindex
value. Values need not be sequential nor must they begin with any particular value. Form controls that have identicalnavindex
values are to be navigated in document order. -
Ancestor
form
controls
(<
group
>, <repeat
>, and <switch
>) establish a local navigation sequence. All form controls within a local sequence are navigated, in increasing order of thenavindex
value, before any outside the local sequence are navigated. Form controls that have identicalnavindex
values are navigated in document order.
-
Outermost
form
controls
are
navigated
in
increasing
order
of
the
-
Those
form
controls
that
do
not
specify
navindex
or supply a value of "0" are navigated next. These form controls are navigated in document order. -
Those
form
controls
that
are
disabled,
hidden,
or
not
relevant
are assigned a relative order in the overall sequence but do not participate as navigable controls. - The navigation sequence past the last form control (or before the first) is undefined. XForms Processors may cycle back to the first/last control, remove focus from the form, or other possibilities.
The xforms-focus Event
Dispatched in response to: set focus to a form control.
Target:
Core
Form
Control
|
group
|
switch
|
repeat
|
dialog
Bubbles: No
Cancelable: Yes
Context Info: None
The default action for these events results in the following:
Focus
is
given
to
the
target
form
control
if
the
form
control
is
able
to
accept
focus.
Changing
the
focus
to
a
form
control
within
a
repeat
object
may
cause
one
or
more
repeat
index
values
to
be
changed
as
described
in
Section
User
Interface
Interaction
.
Setting
focus
to
a
repeat
container
form
control
sets
the
focus
to
the
repeat
object
associated
with
the
repeat
index.
Setting
the
focus
to
a
group
,
or
switch
,
or
dialog
container
form
control
set
the
focus
to
the
first
form
control
in
the
container
that
is
able
to
accept
focus.
Any
form
control
is
able
to
accept
the
focus
if
it
is
relevant.
Note:
This
event
is
implicitly
invoked
to
implement
XForms
accessibility
features
such
as
accesskey
and
when
the
user
changes
the
focus.
The xforms-help and xforms-hint Events
Dispatched in response to: a user request for help or hint information.
Target: Core Form Control
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for these events results in the following: If the form control has help/hint elements supplied, these are used to construct a message that is displayed to the user. Otherwise, user agents may provide default help or hint messages, but are not required to.
The xforms-submit Event
See chapter The xforms-submit Event .
The xforms-submit-serialize Event
See chapter The xforms-submit-serialize Event .
The xforms-dialog-show Event
See chapter The xforms-dialog-show Event .
The xforms-dialog-hide Event
See chapter The xforms-dialog-hide Event .
Notification Events
The xforms-insert Event
Dispatched
in
response
to:
Successful
insertion
of
one
or
more
nodes
by
an
XForms
insert
action.
Target:
instance
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
inserted-nodes |
|
The instance data node or nodes inserted. |
origin-nodes |
|
The
instance
data
nodes
referenced
by
the
insert
action's
origin
attribute
if
present,
or
the
empty
nodeset
if
not
present.
|
insert-location-node |
|
The
insert
location
node
as
defined
by
the
insert
action.
|
position | string |
The
insert
position,
before
or
after
.
|
Default Action: None; notification event only.
Note:
Notification
events
are
those
with
no
default
processing
defined.
Although
this
event
is
dispatched
by
insert
processing
as
a
notification,
repeat
processing
associates
behavior
with
the
capture
phase
of
this
event.
The xforms-delete Event
Dispatched
in
response
to:
Successful
deletion
of
one
or
more
nodes
by
an
XForms
delete
action.
Target:
instance
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
deleted-nodes |
|
The instance data node or nodes deleted. Note that these nodes are no longer referenced by their parents. |
delete-location | number |
The
delete
location
as
defined
by
the
delete
action,
or
NaN
if
there
is
no
delete
location.
|
Default Action: None; notification event only.
Note:
Notification
events
are
those
with
no
default
processing
defined.
Although
this
event
is
dispatched
by
delete
processing
as
a
notification,
repeat
processing
associates
behavior
with
the
capture
phase
of
this
event.
The xforms-value-changed Event
Dispatched in response to: a change to an instance data node bound to a core form control.
Target: Core Form Controls
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event due to a change.
Note:
For incremental processing, this specification does not define how often XForms Processors fire these events. Implementations are expected to optimize processing (for instance not flashing the entire screen for each character entered, etc.).
Note:
The change to the instance data associated with this event happens before the event is dispatched.
The xforms-valid Event
Dispatched in response to: an instance data node either changing and being or becoming valid .
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-revalidate Event .
The xforms-invalid Event
Dispatched in response to: an instance data node either changing and being or becoming invalid (not valid ).
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-revalidate Event .
The xforms-readonly Event
Dispatched in response to: an instance data node either changing and being or becoming readonly.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The xforms-readwrite Event
Dispatched in response to: an instance data node either changing and being or becoming read-write.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The xforms-required Event
Dispatched in response to: an instance data node either changing and being or becoming required.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The xforms-optional Event
Dispatched in response to: an instance data node either changing and being or becoming optional.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The xforms-enabled Event
Dispatched in response to: an instance data node either changing and being or becoming enabled.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The xforms-disabled Event
Dispatched in response to: an instance data node either changing and being or becoming disabled.
Target:
Core
Form
Controls
|
group
|
switch
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in The xforms-recalculate Event or The xforms-refresh Event .
The DOMActivate Event
Dispatched in response to: the "default action request" for a core form control, for instance pressing a button or hitting enter.
Target: Core Form Controls
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following: None; notification event only.
The DOMFocusIn Event
Dispatched in response to: a form control receiving focus.
Target:
Core
Form
Controls
|
group
|
switch
|
repeat
|
dialog
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
The DOMFocusOut Event
Dispatched in response to: a form control losing focus.
Target:
Core
Form
Controls
|
group
|
switch
|
repeat
|
dialog
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
The xforms-select and xforms-deselect Events
Dispatched
in
response
to:
an
item
in
a
select
,
select1
,
or
a
case
in
a
switch
becoming
selected
or
deselected.
Target:
item
or
case
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
The xforms-in-range Event
Dispatched
in
response
to:
the
value
of
an
instance
data
node
has
changed
such
that
the
value
can
now
be
represented
by
the
form
control.
Target: Core Form Controls
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This
event
is
dispatched
whenever
the
value
of
an
instance
data
node
that
was
not
possible
to
represent
given
the
constraints
specified
on
a
form
control
has
changed
such
that
the
value
can
now
be
represented
by
the
form
control.
The xforms-out-of-range Event
Dispatched
in
response
to:
the
value
of
an
instance
data
node
has
changed
such
that
the
value
can
not
be
represented
by
the
form
control.
Target: Core Form Controls
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This
event
is
dispatched
whenever
the
value
of
an
instance
data
node
can
not
be
represented
given
the
constraints
specified
on
a
form
control.
The xforms-scroll-first and xforms-scroll-last Events
Dispatched
in
response
to:
a
setindex
action
attempting
to
set
an
a
repeat
index
outside
the
range
of
a
repeat
.
Target:
repeat
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
The xforms-submit-done Event
See chapter The xforms-submit-done Event .
The xforms-dialog-shown Event
See chapter The xforms-dialog-shown Event .
See chapter The xforms-dialog-hidden Event .
Error
Indications
Handling
Error
indications
Errors
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.
console
or
inspector.
This version of the XForms specification enhances error handling with the ability to recover from errors, that is to optionally continue processing after being informed of an error condition.
For
backward
compatibility,
the
default
action
of
error
events
remains
to
halt
processing,
but
event
handlers
attached
to
error
events
can
use
defaultAction="cancel"
to
implement
custom
error
handling
and
stop
the
default
action.
<action ev:event="xforms-expression-error" ev:defaultAction="cancel"> <!-- Custom error handling here --> </action>
The
xforms-binding-exception
Event
Error
Recovery
Outside
Actions
Dispatched
as
The
XForms
Processor,
when
encountering
an
indication
of:
error
with
an
illegal
binding
expression,
expression
or
an
error
with
a
binding,
determines
a
recovery
value
for
the
expression
before
dispatching
an
event.
Specifically:
-
For
control
bindings,
model
bindings,
values,
variables:
-
Upon
expression
errors,
a
default
value
is
chosen:
- the empty sequence for bindings and variable values
- the empty string for string values
xforms-expression-error
is dispatched
-
Upon
binding
errors
with
the
bind
attribute- the binding resolves to the empty sequence
xforms-binding-error
is dispatched
-
Upon
binding
errors
with
the
model
attributethat fails- the model doesn't change, as if the model attribute was missing
-
the
binding
resolves
to
pointthe empty sequence xforms-binding-error
is dispatched
-
Upon
expression
errors,
a
default
value
is
chosen:
-
For
expression
MIP
values:
-
Upon
expression
errors
for
calculate
- the destination value is set to blank
xforms-expression-error
is dispatched
-
Upon
expression
errors
for
other
MIPs
-
the
ID of aMIP is not modified, as if the attribute specifying the property was missing -
modelxforms-expression-errorelement,is dispatched
-
the
-
Upon
binding
errors
with
complex
or
areadonly content (bindcalculateattribute that fails to pointonly)- the instance value is not modified
xforms-binding-error
is dispatched to theIDmodel
-
Upon
expression
errors
for
-
For
the
submission
instance
attribute:-
Upon
incorrect
instance
id
xforms-submit-error
is dispatched, for compatibility with the case of a target error with thetargetref
attribute
-
Upon
incorrect
instance
id
Error Recovery Inside Actions
Any error taking place during action processing stops the outermost action handler. Errors include:
- expression errors
-
binding
errors
with
the
bind
element,orasubmissionmodelthat fails - binding errors with complex or readonly content
- missing mandatory attributes or unsupported attribute values on action elements
The
xforms-action-error
event
is
dispatched
to
point
the
observer
of
the
action.
Observers
include:
controls
and
the
model
,
instance
,
and
submission
elements.
Note:
Some
actions
silently
ignore
error
conditions
and
are
not
subject
to
the
ID
processing
above,
including:
setvalue
pointing to an empty sequence or to an atomic item (such as a string) instead of a node-
submissiondeleteelement,with an empty sequence or an empty overridden context -
instanceinsertattribute onwith an empty or non-element insert context, an empty overridden context, or an empty origin - actions with AVTs evaluating to the empty sequence
-
submissiondispatchsend
,setfocus
,setindex
, andtoggle
when the target element is not found
The xforms-binding-error Event
Dispatched as an indication of any error with a binding not within an action handler, including:
-
a
bind
attributeIDREF
value thatfailsrefers topointanID
not on abind
element -
a
model
attributeIDREF
value that refers to aninstanceIDmodel
elementin -
a
model
attribute which does not refer to thesamecontainingmodel
element, when applicable -
a
static
or
dynamic
error
with
a
binding
expression
expressed
with
the
ref
attribute
Target:
any
element
as
that
can
contain
a
binding
expression
Bubbles: Yes
Cancelable: Yes
Context Info:
Property | Type | Value |
---|---|---|
error-message | string | Optional implementation-dependent error message, or the empty sequence. |
Default Action: Fatal error (halts processing).
Note:
Binding
errors
occurring
within
action
handlers
dispatch
the
event
instead.
submission
.
xforms-action-error
The xforms-expression-error Event
Dispatched as an indication of any error occurring during evaluation of an expression not within an action handler, except for binding expressions, including for:
-
a
bind
computed expression -
a
value
attribute onoutput
andvar
Target: any element that is not an action element and that can contain an expression which is not a binding expression
Bubbles: Yes
Cancelable:
No
Yes
Context
Info:
None
Property | Type | Value |
---|---|---|
error-message | string | Optional implementation-dependent error message, or the empty sequence. |
Default Action: Fatal error (halts processing).
Note:
Expression
errors
occurring
within
action
handlers
dispatch
the
xforms-action-error
event
instead.
The xforms-action-error Event
Dispatched as an indication of any error occurring during the execution of an action handler, including expression and binding errors.
Target: the event observer that caused the action to be executed
Bubbles: Yes
Cancelable: Yes
Context Info:
Property | Type | Value |
---|---|---|
error-type | string |
One
of
the
following:
expression-error
,
binding-error
,
script-error
,
script-language-error
,
other-error
. |
error-message | string | Optional implementation-dependent error message, or the empty sequence. |
Default Action: Fatal error (halts processing).
The xforms-compute-exception Event
Dispatched
as
an
indication
of:
an
a
fatal
error
occurring
with
computing
expressions,
including
if:
-
an
extension
function
is
declared
on
the
functions
attribute but is not implemented by the XForms Processor -
a
circular
dependency
is
detected
during
evaluationxforms-recalculate
processing -
a
computed
expression
violates
a
Binding
Expression
Constraint
during
xforms-recalculate
processing
Editorial note: Should xforms-compute-exception be dispatched during recalculation? | 2011-08-31 |
Currently,
as
with
previous
versions
of
the
specification,
the
recalculation
process
can
dispatch
fatal
xforms-compute-exception
events
when
processing
XPath
expressions
or
when
circular
dependencies
are
found.
We think that this is not desirable, because the improved error handling in XForms 2.0 is predicated on the ability to recover from such errors. Further, while with XPath 1.0 dynamic XPath errors happen rarely, with XPath 2.0 such errors are much more likely, in particular when using type annotations, and should be recoverable.
The
suggested
recalculation
algorithm
in
this
specification
gives
implementors
some
liberty
as
to
how
to
figure
out
dependencies.
However,
we
probably
should
say
something
about
what
happens
if
a
dynamic
error
is
encountered
when
processing
XPath
expressions.
For
example,
we
could
say
that
a
subset
of
dependencies
in
such
cases
remains
unknown
for
the
current
recalculation,
and
that
upon
a
Feedback on this topic is desired. |
Target:
model
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error-message | string | An implementation-specific string that should contain the expression being processed when the exception was detected. |
Default Action: Fatal error (halts processing).
The
xforms-version-exception
xforms-version-error
Event
Dispatched
as
an
indication
of
failure
of
the
version
checks
defined
in
the
description
of
the
version
attribute
in
Section
The
model
Element
.
Target:
the
default
model
>model
Bubbles: Yes
Cancelable:
No
Yes
Context Info:
Property | Type | Value |
---|---|---|
|
string | An implementation-specific error string |
Default Action: Fatal error (halts processing).
Note:
This
exception
occurs
event
can
be
dispatched
early
in
processing.
during
XForms
processors
Processor
initialization.
While
the
default
action
of
this
event
can
be
canceled
by
an
event
handler,
XForms
Processors
are
not
expected
to
product
produce
XForms
user
interface
elements
nor
even
or
execute
further
XForms
action
handlers
(such
as
a
message
action)
in
response
to
this
event.
This
exception
is
mainly
dispatched
for
the
benefit
of
implementation-specific
processing
code
that
may
be
monitoring
the
behavior
of
an
XForms
processor.
Processor.
The xforms-link-exception Event
Dispatched as an indication of: a failure to traverse or process the result of a link in a situation critical to form processing, such as schema or instance initialization.
Target:
model
associated
with
the
in-scope
evaluation
context
node
element
performing
the
link.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
model
attribute
of
the
closest
ancestor
element
performing
is
used.
Otherwise,
the
link
first
model
is
used.
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
resource-uri | string | The URI associated with the failed link (xsd:anyURI) |
Default Action: Fatal error (halts processing).
Note:
This
exception
occurs
early
in
processing.
XForms
processors
Processors
are
not
expected
to
produce
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.
Processor.
The xforms-output-error Event
Dispatched
by
the
processor
immediately
after
the
failure
of
an
output
to
render
or
update
the
rendition
of
content.
Target:
output
Bubbles: Yes
Cancelable: No
Context Info: None.
Default Action: None; notification event only.
Note:
The
output
element
content
can
include
XForms
actions,
so
an
output
element
can
contain
an
event
handler
for
the
xforms-output-error
event.
See
Section
The
output
Element
.
The xforms-submit-error Event
See chapter The xforms-submit-error Event .
Event Sequencing
The previous sections describe processing associated with individual events. This section gives the overall sequence of related events that must occur in several common situations. In the following lists, events that may be fired more than once are prefixed with [n].
For
input
,
secret
,
textarea
,
range
,
or
upload
Controls
-
When
the
form
control
is
interactively
changed,
and
has
the
incremental="true"
setting, the event sequence described at Sequence: Value Change may be initiated at implementation dependent intervals. -
When
the
form
control
is
interactively
changed
and
does
not
have
the
incremental="true"
setting, no events are required to be dispatched, and thus no order is defined. - When the user activates the control and the value has changed, then, after the new value is placed into the bound instance node, the event sequence consists of the events described at Sequence: Value Change followed by dispatching the DOMActivate event. See The input Element for an example.
- When focus changes from the form control and the value has changed, then, after the new value is placed into the bound instance node, the event sequence is as described at Sequence: Value Change .
For output Controls
-
The
implementation
of
an
output
dispatchesxforms-output-error
if it unable to process the output data (such as corrupt image data when the output mediatype indicates it is image data). This event may occur each time theoutput
is given new data (such as a change of data in the bound data node or a change of the bound data node).
For select or select1 Controls
-
When
a
selection
is
interactively
changed,
and
the
form
control
has
the
incremental="true"
setting (which is the default for theselect
orselect1
elements), the event sequence is described at Sequence: Selection Without Value Change , which may be followed immediately by the sequence described at Sequence: Value Change . -
When
a
selection
is
interactively
changed,
and
the
select
orselect1
form control has theincremental="false"
setting, the event sequence is described at Sequence: Selection Without Value Change . - When the user activates the control and the selection has changed, then, after the new value is placed into the bound instance node, the event sequence consists of the events described at Sequence: Value Change followed by dispatching the DOMActivate event. Note that this event sequence will have been preceded by the event sequence described at Sequence: Selection Without Value Change at the moment the selection was changed.
- When focus changes from the form control and the selection has changed, then, after the new value is placed into the bound instance node, the event sequence is as described at Sequence: Value Change . Note that this event sequence will have been preceded by the event sequence described at Sequence: Selection Without Value Change at the moment the selection was changed.
For trigger Controls
- Activating the form control causes the event sequence defined at Sequence: Activating a Trigger .
For submit Controls
- Activating the form control causes the event sequence defined at Sequence: Activating a Trigger , followed immediately by the event sequence defined at Sequence: Submission .
Sequence: Selection Without Value Change
-
xforms-deselect
(for
each
item
deselected by the change, if any) -
xforms-select
(for
each
item
selected by the change, if any)
Sequence: Value Change
- xforms-recalculate
- xforms-revalidate
-
xforms-refresh
performs
reevaluation
of
UI
binding
expressions
then
dispatches
these
events
according
to
value
changes,
model
item
property
changes
and
validity
changes:
- [n] xforms-value-changed
- [n] xforms-valid or xforms-invalid
- [n] xforms-enabled or xforms-disabled
- [n] xforms-optional or xforms-required
- [n] xforms-readonly or xforms-readwrite
-
[n]
xforms-out-of-range
or
xforms-in-range
(The order in which these events are dispatched is not defined).
- Perform further deferred updates as necessary
Sequence: Activating a Trigger
- DOMActivate
Sequence: Submission
- xforms-submit
- xforms-submit-serialize
- xforms-submit-done or xforms-submit-error
Resolving ID References in XForms
The element of a document for which an IDREF must be resolved is called the source element , and the element bearing the matching ID, if there is one, is called the target element . Due to the run-time expansion of repeated content in XForms, it is possible that there will be more than one occurrence of both the source and target elements. This section describes how XForms IDREF resolution works to accommodate such repetition of the originating document's content.
Each run-time occurrence of the source element is called a source object , and each run-time occurrence of the target element is called a target object . It is the source object that performs the IDREF resolution, and the result of the search is either null or a target object.
Whether
or
not
repeated
content
is
involved,
a
null
search
result
for
an
IDREF
resolution
is
handled
differently
depending
on
the
source
object.
If
there
is
a
null
search
result
for
the
target
object
and
the
source
object
is
an
XForms
action
such
as
dispatch
,
send
,
setfocus
,
setindex
or
toggle
,
then
the
action
is
terminated
with
no
effect.
Similarly,
a
submit
form
control
does
not
dispatch
xforms-submit
if
its
submission
attribute
does
not
indicate
an
existing
submission
element.
Likewise,
when
a
function
associated
with
the
source
object
performs
the
IDREF
search
and
a
null
result
is
obtained,
the
function
returns
an
empty
result
such
as
NaN
for
the
index()
function
or
empty
nodeset
sequence
for
the
instance()
function.
However,
an
occurs
if
there
is
a
null
search
result
for
the
target
object
indicated
by
attributes
xforms-binding-exception
xforms-binding-error
bind
,
model
and
instance
.
If the target element is not repeated, then the search for the target object is trivial since there is only one associated with the target element that bears the matching ID. This is true regardless of whether or not the source object is repeated. However, if the target element is repeated, then additional information must be used to help select a target object from among those associated with the identified target element.
References to Elements within a repeat Element
When
the
target
element
that
is
identified
by
the
IDREF
of
a
source
object
has
one
or
more
repeat
elements
as
ancestors,
then
the
set
of
ancestor
repeats
are
partitioned
into
two
subsets,
those
in
common
with
the
source
element
and
those
that
are
not
in
common.
Any
ancestor
repeat
elements
of
the
target
element
not
in
common
with
the
source
element
are
descendants
of
the
repeat
elements
that
the
source
and
target
element
have
in
common,
if
any.
For
the
repeat
elements
that
are
in
common,
the
desired
target
object
exists
in
the
same
set
of
run-time
objects
that
contains
the
source
object.
Then,
for
each
ancestor
repeat
of
the
target
element
that
is
not
in
common
with
the
source
element,
the
current
index
of
the
repeat
determines
the
set
of
run-time
objects
that
contains
the
desired
target
object.
References to Elements within a bind Element
When
a
source
object
expresses
a
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding
with
a
bind
attribute,
the
IDREF
of
the
bind
attribute
is
resolved
to
a
target
bind
object
whose
associated
nodeset
sequence
is
used
by
the
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding.
However,
if
the
target
bind
element
has
one
or
more
bind
element
ancestors,
then
the
identified
bind
may
be
a
target
element
that
is
associated
with
more
than
one
target
bind
object.
If
a
target
bind
element
is
outermost,
or
if
all
of
its
ancestor
bind
elements
have
ref
(or
deprecated
nodeset
)
attributes
that
select
only
one
node,
then
the
target
bind
only
has
one
associated
bind
object,
so
this
is
the
desired
target
bind
object
whose
nodeset
sequence
is
used
in
the
Single
Node
Item
Binding
or
Node
Set
Sequence
Binding.
Otherwise,
the
in-scope
evaluation
context
node
item
of
the
source
object
containing
the
bind
attribute
is
used
to
help
select
the
appropriate
target
bind
object
from
among
those
associated
with
the
target
bind
element.
From
among
the
bind
objects
associated
with
the
target
bind
element,
if
there
exists
a
bind
object
created
with
the
same
in-scope
evaluation
context
node
item
as
the
source
object,
then
that
bind
object
is
the
desired
target
bind
object.
Otherwise,
the
IDREF
resolution
produced
a
null
search
result.
DOM Interface for Access to Instance Data
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.
The IDL for this interface follows:
#include "dom.idl"pragma prefix "w3c.org"module xforms { interface XFormsModelElement : dom::Element { dom::Document getInstanceDocument(in dom::DOMString instanceID) raises(dom::DOMException); void rebuild(); void recalculate(); void revalidate(); void refresh(); }; };
The getInstanceDocument() Method
If
the
instance-id
parameter
is
the
empty
string,
then
the
document
element
of
the
default
instance
is
returned.
Otherwise,
this
method
returns
a
DOM
Document
that
corresponds
to
the
instance
data
associated
with
the
instance
element
containing
an
ID
matching
the
instance-id
parameter.
If
there
is
no
matching
instance
data,
a
DOMException
is
thrown.
The implementation of the DOM interface for the instance document must not permit direct mutations of readonly instance nodes. Specifically, the implementation must not allow insertion of a node whose parent is readonly, direct deletion of a readonly node, nor setting the content of a readonly node. A node that is not readonly can be deleted, including all descendants, even if it has readonly descendants.
The rebuild() Method
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 and raises no exceptions.
The recalculate() Method
This method signals the XForms Processor to perform a full recalculation of this XForms Model. This method takes no parameters and raises no exceptions.
The revalidate() Method
This method signals the XForms Processor to perform a full revalidation of this XForms Model. This method takes no parameters and raises no exceptions.
The refresh() Method
This
method
signals
the
XForms
Processor
to
perform
a
full
refresh
of
form
controls
bound
to
based
on
instance
nodes
within
this
XForms
Model.
This
method
takes
no
parameters
and
raises
no
exceptions.
Feature string for the hasFeature method call
For
this
version
of
the
XForms
specification,
the
feature
string
for
the
[
DOM2
Core
]
DOMImplementation
interface
hasFeature
method
call
is
"org.w3c.xforms.dom"
and
the
version
string
is
"1.0"
.
XForms Actions
This chapter defines the controller layer of XForms, an XML Events-based [ XML Events ] common set of actions that can be invoked in response to events.
Note:
XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.
All form controls as well as other elements defined in this specification have a set of common behaviors that encourage consistent authoring and look and feel for XForms-based applications. This consistency comes from attaching a common set of behaviors to the various form controls. In conjunction with the event binding mechanism provided by XML Events, these handlers provide a flexible means for forms authors to specify event processing at appropriate points within the XForms user interface. XForms Actions are declarative XML event handlers that capture high-level semantics. As a consequence, they significantly enhance the accessibility of XForms-based applications in comparison to previous Web technologies that relied exclusively on scripting.
The elements and attributes included in this module are:
Element | Attributes and Their Content (after AVT evaluation) | Minimal Content Model |
---|---|---|
Common
,
Events
,
Action
Common
,
Single
|
PCDATA | |
Common
,
Events
,
Action
Common
,
|
EMPTY | |
Common
,
Events
,
Action
Common
,
|
EMPTY | |
Common , Events , Action Common , repeat (xsd:IDREF), index (number Expression) |
EMPTY | |
Common , Events , Action Common , case (xsd:IDREF) |
case? [deprecated] | |
Common , Events , Action Common , control (xsd:IDREF) |
control? [deprecated] | |
Common , Events , Action Common , name (xsd:NMTOKEN), targetid (xsd:IDREF), delay (xsd:nonNegativeInteger), bubbles (xsd:boolean), cancelable (xsd:boolean) |
| |
EMPTY | ||
EMPTY | ||
EMPTY | ||
EMPTY | ||
EMPTY | ||
Common
,
Events
,
Action
Common
,
Single
|
resource? [deprecated] | |
Common , Events , Action Common , submission (xsd:IDREF) |
EMPTY | |
Common
,
Events
,
Action
Common
,
Single
|
(PCDATA| UI Inline )* |
This module also defines the content set "Action" , which includes the following elements:
(action|setvalue|insert|delete|setindex|toggle|setfocus|dispatch|rebuild|recalculate|revalidate|refresh|reset|load||send|message)*load|send|message)*
The following group of attributes, here called Action Common , are available to all Action elements:
Element | Attributes and Their Content (after AVT evaluation) |
---|---|
if (boolean Expression), while (boolean Expression) |
- if
- Author-optional attribute defined in Section Conditional Execution of XForms Actions .
- while
-
Author-optional
attribute
defined
in
Section
Iteration of XForms ActionsThe While Attribute . - iterate
- Author-optional attribute defined in Section The Iterate Attribute .
Additionally, this module defines the attribute group "XML Events" , which includes all of the "global" attributes defined in the [ XML Events ] specification.
The following example shows how events can be used:
<trigger> <label>Reset</label> <reset ev:event="DOMActivate" model="thismodel"/> </trigger>
This example recreates the behavior of the HTML reset control, which this specification does not define as an independent form control.
For each built-in XForms Action, this chapter lists the following:
Name
Common Attributes
Special Attributes
Description of behavior
All elements defined in this chapter explicitly allow global attributes from the XML Events namespace, and apply the processing defined in that specification in section 2.3 [ XML Events ].
An
outermost
action
handler
is
an
action
that
is
activated
when
the
XForms
processor
Processor
is
not
executing
any
other
action
handlers.
An
inner
action
handler
is
an
action
that
is
activated
when
the
XForms
processor
Processor
is
executing
the
declared
actions
of
an
outermost
action
handler
.
An
inner
action
handler
may
be
within
the
content
of
the
outermost
action
handler,
or
it
may
be
executed
as
the
response
to
an
event
dispatched
while
performing
all
of
the
actions
initiated
by
the
outermost
action
handler
.
Deferred
Updates
:
Sequences
of
one
or
more
XForms
Actions
have
a
deferred
effect
on
XForms
model
and
user
interface
processing.
Implementations
are
free
to
use
any
strategy
to
accomplish
deferred
updates,
but
the
end
result
must
be
as
follows:
Instance
data
changes
performed
by
a
set
of
actions
do
not
result
in
immediate
computation
dependency
rebuilding,
recalculation,
revalidate
and
form
control
refreshing
until
the
termination
of
the
outermost
action
handler
,
as
described
here.
Each
XForms
model
can
be
thought
of
as
having
a
set
of
deferred
update
Boolean
flags,
initially
false
at
the
start
of
an
outermost
action
handler
,
to
indicate
whether
each
of
the
actions
rebuild
,
recalculate
,
revalidate
,
and
refresh
are
required
for
that
model
upon
termination
of
the
outermost
action
handler
.
By
default,
the
behavior
of
an
action
handler
is
performed
one
time
when
the
action
is
encountered
in
the
execution
sequence.
However,
execution
of
an
action
handler
may
be
conditional
or
iterated,
as
described
in
Conditional
Execution
of
XForms
Actions
,
The
While
Attribute
,
and
Iteration
of
XForms
Actions
The
Iterate
Attribute
.
Execution
of
an
outermost
action
handler
begins
by
setting
the
XForms
processor
Processor
into
the
state
of
executing
an
outermost
action
handler
.
The
outermost
action
handler
is
then
performed,
which
may
include
the
execution
of
inner
action
handlers
.
Finally,
the
XForms
processor
Processor
is
set
into
the
state
of
not
executing
an
outermost
action
handler
and
then
the
deferred
update
is
performed
for
each
model.
The
deferred
update
behavior
for
a
model
consists
of
examining
each
deferred
update
Boolean
flag
in
the
order
of
rebuild
,
recalculate
,
revalidate
,
and
refresh
,
and
for
each
true
flag,
set
the
flag
to
false
and
then
dispatch
the
proper
event
to
the
model
for
that
deferred
update
flag
(i.e.
dispatch
xforms-rebuild
for
a
true
rebuild
flag,
xforms-recalculate
for
a
true
recalculate
flag,
xforms-revalidate
for
a
true
revalidate
flag,
and
xforms-refresh
for
a
true
refresh
flag).
Note:
The
XForms
processor
Processor
is
not
considered
to
be
executing
an
outermost
action
handler
at
the
time
that
it
performs
deferred
update
behavior
for
XForms
models.
Therefore,
event
handlers
for
events
dispatched
to
the
user
interface
during
the
deferred
refresh
behavior
are
considered
to
be
new
outermost
action
handler
.
Actions that manipulate properties of the XForms view layer begin by invoking the deferred update behavior so that the model and all data are up to date prior to performing the action. The XForms Actions in this category are:
setfocus
toggle
setindex
Actions that directly invoke rebuild, recalculate, revalidate, or refresh always have an immediate effect, and clear the corresponding deferred update flag. The XForms Actions in this category are:
rebuild
recalculate
revalidate
refresh
Similarly,
if
the
default
processing
of
any
of
the
events
xforms-rebuild
,
xforms-recalculate
,
xforms-revalidate
,
or
xforms-refresh
are
performed,
then
the
corresponding
deferred
update
flag
is
cleared.
The
XForms
Actions
that
can
dispatch
these
events
are:
reset
dispatch
XForms
Actions
that
change
the
tree
structure
of
instance
data
result
in
setting
all
four
deferred
update
flags
to
true
for
the
model
over
which
they
operate.
The
XForms
Actions
in
this
category
are:
insert
delete
XForms
Actions
that
change
only
the
value
of
an
instance
node
results
in
setting
the
deferred
update
flags
for
recalculate
,
revalidate
,
and
refresh
to
true
and
making
no
change
to
the
deferred
update
flag
for
rebuild
for
the
model
over
which
they
operate.
The
XForms
Actions
in
this
category
are:
setvalue
setindex
Finally,
the
XForms
submission
process
can
affect
deferred
update
behavior.
See
Section
The
xforms-submit
Event
for
details.
XForms
actions
that
are
capable
of
initiating
an
XForms
submission
are:
send
dispatch
The action Element
This action causes its child actions to be invoked in the order that they are specified in the document.
Common Attributes: Common , Events , Action Common
<trigger> <label>Click me</label> <action ev:event="DOMActivate"> <reset model="thismodel"/> <setvalue ref="."/> </action> </trigger>
The setvalue Element
This
action
explicitly
sets
the
value
of
the
specified
instance
data
node.
This
action
has
no
effect
if
the
Single
Node
Item
Binding
does
not
select
an
instance
data
node
or
if
a
readonly
instance
data
node
is
selected.
An
xforms-binding-exception
xforms-action-error
Event
occurs
if
the
Single
Node
Item
Binding
indicates
a
node
whose
content
is
not
simpleContent
(i.e.,
a
node
that
has
element
children).
Common
Attributes:
Common
,
Events
,
Action
Common
,
Single
Node
Item
Binding
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate,
with
the
result
stored
in
the
selected
instance
data
node.
The
evaluation
context
for
this
expression
is
the
result
from
the
Single
NodeItem Binding. Toobtaincode>insertobtain the value, the result of theexpressione/code>, and xpression is processed as if by call to thestring
conversion function as described in the expression module . An empty string is used if the evaluation fails.
The
element
content
of
setvalue
specifies
the
literal
value
to
set;
this
is
an
alternative
to
specifying
a
computed
value
via
attribute
value
.
If
neither
a
value
attribute
nor
text
content
are
present,
the
effect
is
to
set
the
value
of
the
selected
node
to
the
empty
string
("").
If
both
are
present,
the
value
attribute
is
used.
The
following
examples
contrast
these
approaches:
<setvalue bind="put-here" value="a/b/c"/>
This
causes
the
string
value
at
a/b/c
in
the
instance
data
to
be
placed
on
the
single
node
selected
by
the
bind
element
with
id="put-here"
.
<setvalue bind="put-here">literal string</setvalue>
This
causes
the
value
"literal
string"
to
be
placed
on
the
single
node
selected
by
the
bind
element
with
id="put-here"
.
Note:
See
Section
The
context()
Function
for
an
example
in
which
the
Expression
language
modules
are
encouraged
to
add
a
context()
function
is
that
returns
the
in-scope
evaluation
context
item,
which
can
be
used
to
provide
the
same
initial
evaluation
context
node
item
to
both
the
ref
and
value
attributes.
See
Appendix
Patterns
for
Data
Mutations
for
numerous
further
usage
patterns
for
sevalue
,
insert
and
delete
.
All strings are inserted into the instance data as follows:
-
Element
nodes:
If
element
child
nodes
are
present,
then
an
xforms-binding-exceptionxforms-action-error Event occurs. Otherwise, regardless of how many child nodes the element has, the result is that the string becomes the new content of the element. In accord with the data model of [ XPath 1.0 ], the element will have either a single non-empty text node child, or no children string was empty. - Attribute nodes: The string-value of the attribute is replaced with a string corresponding to the new value.
- Text nodes: The text node is replaced with a new one corresponding to the new value, or the text node is eliminated if the new value is the empty string.
- Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
-
the
XPath
root
node:
an
xforms-binding-exceptionxforms-action-error Event occurs.
Note:
This action affects deferred updates by setting the deferred update flags for recalculate, revalidate and refresh.
The insert Element
The
insert
action
is
used
to
create
one
or
more
nodes
of
instance
data
by
cloning
one
or
more
existing
instance
nodes.
Attributes
of
the
insert
action
specify
the
node
or
nodes
to
be
cloned
and
the
location
within
instance
data
where
the
clones
will
appear.
The
clones
are
deep
copies
of
the
original
nodes
except
the
contents
of
nodes
of
type
xsd:ID
are
modified
to
remain
as
unique
values
in
the
instance
data
after
the
clones
are
inserted.
Common
Attributes:
Common
,
Events
,
Action
Common
,
Node
Set
Sequence
Binding
(author-optional)
Special Attributes:
-
context Author-optional attribute containing an expression evaluated using the in-scope evaluation context. If the model attribute is present, then it is processed as described in Evaluation Context before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the insert action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the subsequent evaluation of many other attributes that can appear on insert , including if , while , nodeset and origin .origin -
Author-optional
attribute
containing
an
expression
evaluated
using
the
in-scope
evaluation
context
,
which
may
have
been
amended
by
the
context
attribute. Theorigin
is thenode-setnode-sequencesetsequence of one or more nodes to be cloned by theinsert
action. If this attribute is present and resolves to a non-emptynodeset,sequence, then the result overrides the default setting of theorigin
as described below in the processing of thenode-setnode-sequenceinsert
action. - at
-
Author-optional
attribute
containing
an
expression
evaluated
using
the
Node SetSequence Bindingnode-setnode-sequence to help determine theinsert location node
. This attribute is ignored if theNode SetSequence Binding is not specified or specifies an emptynode-set.sequence. Theinsert location node
is a node within theNode SetSequence Bindingnode-setnode-sequence that is used to help determine where in the instance to insert each node cloned by theinsert
. If this attribute is present, then its result is used to override the default setting of theinsert location node
as described below in the processing of theinsert
action. - position
-
Author-optional
selector
that
indicates
where
to
put
the
cloned
node
or
nodes
relative
to
the
insert location node
. Valid values arebefore
andafter
, and the latter is the default. This attribute is ignored if theNode SetSequence Bindingnode-setnode-sequence is not specified or empty. If the node at theinsert location node
within theNode SetSequence Bindingnode-setnode-sequence is the document element of an instance, then this attribute is ignored.
Processing
for
the
insert
action
is
as
follows:
-
The
insert context
is determined. If thecontext
attribute is not given, theinsert context
is the in-scope evaluation context. Otherwise, the expression provided by thecontext
attribute is evaluated using the in-scope evaluation context, and thefirst nodefirst-item rule is applied to obtain theinsert context
. Theinsert
action is terminated with no effect if theinsert context
is the emptynode-set.sequence. -
The
Node SetSequence Bindingnode-setnode-sequence is determined. If abind
attribute is present, it directly determines theNode SetSequence Bindingnode-set.node-sequence. If aref
(or deprecatednodeset
) attribute is present, it is evaluated within theinsert context
to determine theNode SetSequence Bindingnode-set.node-sequence. If theNode SetSequence Binding attributes are not present, then theNode SetSequence Bindingnode-setnode-sequence is the emptynode-set.sequence. Theinsert
action is terminated with no effect if any of the following conditions is true:-
The
context
attribute is not given and theNode SetSequence Bindingnode-setnode-sequence is the emptynode-set.sequence. -
The
context
attribute is given, theinsert context
does not evaluate to an element node and theNode SetSequence Bindingnode-setnode-sequence is the emptynode-set.sequence.
-
The
-
The
origin
is determined. If thenode-setnode-sequenceorigin
attribute is not given and theNode SetSequence Bindingnode-setsequence is empty, then theorigin
is the emptynode-setnode-sequencenode-set.sequence. Otherwise, if theorigin
attribute is not given, then theorigin
consists of the last node of thenode-setnode-sequenceNode SetSequence Bindingnode-set.node-sequence. If theorigin
attribute is given, theorigin
is the result of the evaluation of thenode-setnode-sequenceorigin
attribute in theinsert context
.Namespace nodes and rootRoot nodes (parents of document elements) are removed from theorigin
. An implementation may choose not to include namespace nodes in thenode-setnode-sequenceorigin node-sequence
, in particular if the namespace axis is not supported by the XPath processor or if inserting the namespace node would make the data model inconsistent. Theinsert
action is terminated with no effect if theorigin
is the emptynode-setnode-sequencenode-set.sequence. -
The
insert location node
is determined. If theNode SetSequence Bindingnode-setnode-sequence is not specified or empty, theinsert location node
is theinsert context
node. Otherwise, if theat
attribute is not given, then theinsert location node
is the last node of theNode SetSequence Bindingnode-set.sequence. Otherwise, aninsert location node
is determined from theat
attribute as follows:-
The
evaluation
context
node
is
the
first
node
in
document
order
from
the
Node SetSequence Bindingnode-set,node-sequence, the context size is the size of theNode SetSequence Bindingnode-set,node-sequence, and the context position is1
. -
The
return
value
is
processed
according
to
the
rules
of
the
XPath
function
round()
. For example, the literal1.5
becomes2
, and the literal'string'
becomesNaN
. -
If
the
result
is
in
the
range
1
to
the
Node SetSequence Bindingnode-setnode-sequence size, then theinsert location
is equal to the result. If the result is non-positive, then theinsert location
is1
. Otherwise, the result isNaN
or exceeds theNode SetSequence Bindingnode-setsequence size, so theinsert location
is theNode SetSequence Bindingnode-setsequence size. -
The
insert location node
is the node in theNode SetSequence Bindingnode-setsequence at the position given by theinsert location
.
-
The
evaluation
context
node
is
the
first
node
in
document
order
from
the
-
The
insert
action is terminated with no effect if the insertion will create nodes whose parent is readonly. This occurs if theinsert location node
is readonly and theNode SetSequence Bindingnode-setsequence is not specified or empty, or otherwise if the parent of theinsert location node
is readonly. -
Each
node
in
the
origin
is cloned in the order it appears in thenode-setnode-sequenceorigin
.node-setnode-sequence -
The
target location
of each of the cloned nodes is determined as follows:-
If
the
Node SetSequence Bindingnode-setnode-sequence is not specified or empty, then theinsert location node
provided by thecontext
attribute is intended to be the parent of the cloned node. Thetarget location
is dependent on the types of the cloned node and theinsert location node
as follows:-
If
the
insert location node
is not an element node or root node, then it cannot be the parent of the cloned node, so thetarget location
is undefined. -
If
the
insert location node
is the root node of an instance (which is the parent of the root element), and the cloned node is an element, then thetarget location
is the root element of the instance. -
If
the
insert location node
is the root node of an instance (which is the parent of the root element), and the cloned node is not an element, then thetarget location
is before the first child of theinsert location node
. -
If
the
insert location node
is an element, and the cloned node is an attribute, then thetarget location
is the attribute list of theinsert location node
. -
If
the
insert location node
is an element, and the cloned node is not an attribute, then thetarget location
is before the first child of theinsert location node
, or the child list of theinsert location node
if it is empty.
-
If
the
-
Otherwise,
the
Node SetSequence Bindingnode-setnode-sequence is specified and non-empty, so theinsert location node
provided by theNode SetSequence Binding and author-optionalat
attribute is intended to be the sibling of the cloned node. If theinsert location node
is an attribute or root node, then thetarget location
is undefined. If theinsert location node
is not an attribute or root node, then thetarget location
is immediately before or after theinsert location node
, based on theposition
attribute setting or its default.
-
If
the
-
The
cloned
node
or
nodes
are
inserted
in
the
order
they
were
cloned
into
their
target locations
depending on their node type. If the parent node of the target location is the instance root node (which is the parent of the root document element of the instance), and if the cloned node is an element, then the instance root element is deleted before the cloned node is inserted at the target location. If the cloned node is a duplicate of another attribute in its parent element, then either the duplicate attribute is first removed or the existing attribute value is updated. If a cloned node cannot be placed at thetarget location
due to a node type conflict or because thetarget location
is undefined, then the insertion for that particular cloned node is ignored. Each cloned node that is inserted is added to theinserted-nodes
list that will be provided in thexforms-insert
event context information. For each cloned node used to update an existing attribute node, the existing attribute node is added to the list ofinserted-nodes
.Note: A node type conflict is a mismatch between the XPath node type and thetarget location
. For example, an attribute cannot be inserted as a sibling before or after an element. -
If
the
list
of
inserted-nodes
is empty, then theinsert
action is terminated with no effect. - The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
-
The
insert
action is successfully completed by dispatching thexforms-insert
event with appropriate context information.Note: Arepeat
updates its index in response to this event if its repeat collection changes size as a result of the insertion. See Section Repeat Processing for details.
Note:
This action affects deferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.
Examples:
repeat
,
whether
or
not
it
is
empty
When
the
repeat
is
empty,
the
at
index
is
zero
so
a
new
item
is
prepended
to
the
child
elements
of
purchaseOrder
.
When
the
repeat
is
non-empty,
the
new
item
is
added
after
the
node
currently
indexed
by
repeat
R
.
... <instance> <purchaseOrder xmlns=""> <subtotal/> <tax/> <total/> </purchaseOrder> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> ... <item> <product/> <quantity/> <unitcost/> <price/> </item> ... </prototypes> </instance> ...<repeat nodeset="/purchaseOrder/item" id="R"><repeat ref="/purchaseOrder/item" id="R"> ... </repeat> ... <trigger> <label>Add to purchase order</label> <action ev:event="DOMActivate"><insert context="/purchaseOrder" nodeset="item" at="index('R')" origin="instance('prototypes')/item"/><insert context="/purchaseOrder" ref="item" at="index('R')" origin="instance('prototypes')/item"/> <setfocus control="R"/> </action> </trigger>
<model xmlns:my="http://example.org"> <instance> <my:data> <my:name> <my:first-name>John</my:first-name> <my:last-name>Doe</my:last-name> </my:name> <my:address> <my:street>123 Main St.</my:street> <my:city>Smallville</my:city> </my:address> </my:data> </instance><bind nodeset="/my:data/my:name/" readonly="true()"/> <bind nodeset="/my:data/my:address/my:street" readonly="true()"/> <action ev:event="xforms-model-construct-done"> <insert id="I1" nodeset="my:name/*" ... /> <insert id="I2" nodeset="my:address/my:street" at="1" >
<bind ref="my:name" readonly="true()"/> <bind ref="my:address/my:street" readonly="true()"/>
<action ev:event="xforms-model-construct-done"> <insert id="I1" ref="my:name/*" ... /> <insert id="I2" ref="my:address/my:street" at="1" > </action> </model>
Insert
I1
fails
because
it
attempts
to
insert
into
the
content
of
a
readonly
node
(
my:name
).
Insert
I2
succeeds
even
though
the
insert
location
is
a
readonly
node
because
the
new
node
is
placed
as
a
sibling
into
the
content
of
the
parent,
which
is
not
readonly.
See
The
delete
Element
for
an
example
that
uses
insert
and
delete
to
make
a
repeat
that
always
shows
at
least
one
repeat
item.
See
Appendix
Patterns
for
Data
Mutations
for
numerous
further
usage
patterns
for
sevalue
,
insert
and
delete
.
The delete Element
This action deletes one or more nodes from instance data.
Common
Attributes:
Common
,
Events
,
Action
Common
,
Node
Set
Sequence
Binding
Special Attributes:
-
context Author-optional attribute containing an expression evaluated using the in-scope evaluation context. If the model attribute is present, then it is processed as described in Evaluation Context before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the delete action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the evaluation of subsequent attributes that may appear on delete , including if , while , and nodeset .at -
Author-optional
attribute
containing
an
expression
evaluated
using
the
Node SetSequence Bindingnode-setto determine thedelete location
. If theNode SetSequence Bindingnode-setis empty, then this attribute is ignored.
Processing
for
the
delete
action
is
as
follows:
-
The
delete context
is determined.-
It
is
set
to
the
in-scope
evaluation
context,
possibly
overridden
by
the
context
attribute if that attribute is present. -
The
delete
action is terminated with no effect if thedelete context
is the emptynode-set.sequence.
-
It
is
set
to
the
in-scope
evaluation
context,
possibly
overridden
by
the
-
The
Node SetSequence Bindingnode-setis determined.-
If
a
bind
attribute is present, it directly determines theNode Set Binding node-set.Sequence Binding. -
If
a
ref
(or deprecatednodeset
) attribute is present, it is evaluated within thedelete context
to determine theNode Set Binding node-set. The behavior of the delete action is undefined if the Node Set Binding node-set contains nodes from more than one instance .Sequence Binding. -
The
delete
action is terminated with no effect if theNode SetSequence Binding is expressed and theNode SetSequence Bindingnode-setis the emptynode-set.sequence. -
Otherwise,
the
Node SetSequence Binding is not expressed,soand theNode SetSequence Bindingnode-setis setequalto the delete contextnodeitem with a position and size of 1.Note:Not expressing the Sequence Binding is deprecated in this version of the specification.
-
If
a
-
The
delete location
is determined. If theat
attribute is not specified, there is nodelete location
. Otherwise, thedelete location
is determined by evaluating the expression specified by theat
attribute as follows:-
The
evaluation
context
node
is
the
first
node
in
document
order
from
the
Node Set Binding node-set,Sequence Binding, the context size is the size of theNode Set Binding node-set,Sequence Binding, and the context position is1
. -
The
return
value
is
processed
according
to
the
rules
of
the
XPath
function
round()
. For example, the literal1.5
becomes2
, and the literal'string'
becomesNaN
. -
If
the
result
is
in
the
range
1
to
the
Node SetSequence Bindingnode-setsize, then thedelete location
is equal to the result. If the result is non-positive, then thedelete location
is1
. Otherwise, if the result isNaN
or exceeds theNode SetSequence Bindingnode-setsize, thedelete location
is theNode SetSequence Bindingnode-setsize.
-
The
evaluation
context
node
is
the
first
node
in
document
order
from
the
-
Nodes
are
then
deleted
as
follows
-
If
there
is
no
delete location
, each node in theNode SetSequence Bindingnode-setis deleted, except if the node is a readonly node, anamespace node, aroot node, or the root document element of an instance, then that particular node is not deleted. Similarly, atomic values in the Sequence Binding are ignored since they cannot be deleted. If the Sequence Binding contains nodes from more than one document, the nodes are deleted from their respective document. -
Otherwise,
if
there
is
a
delete location
, thenodeitem at thedelete location
in theNode SetSequence Bindingnode-setisdeleted,deleted if it is a node, except if the node is a readonly node, a root node, or the root document element of aninstance or has a readonly parent node,instance, then that node is not deleted. If the item at thedelete location
is an atomic value, it is ignored as it cannot be deleted.
-
If
there
is
no
-
The
delete
action
is
terminated
with
no
effect
if
no
node
is
deleted.deleted in the preceding processing step. - The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
-
The
delete
action is successfully completed by dispatching thexforms-delete
event with appropriate context information.
An implementation may choose not to delete namespace nodes, in particular if the namespace axis is not supported by the XPath processor or if deleting a namespace node would make the data model inconsistent.
This action affects deferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.
When a node is deleted from an instance it will no longer have a parent (if you are using XPath as an expression language the parent aces of the delete node will return the empty sequence)
When a deleted node provides the evaluation context for an action, it will keep providing that context as long as the action is running.
Examples:
delete
and
insert
to
Maintain
a
Non-empty
repeat
repeat
In
this
example,
the
trigger
is
not
in
the
repeat
.
When
it
is
activated,
the
indexed
item
in
the
repeat
is
first
deleted.
Next,
if
that
was
the
last
item
,
then
a
new
prototypical
item
is
inserted
so
that
the
repeat
does
not
become
empty.
The
focus
is
then
sent
back
to
the
repeat
from
the
trigger
.
... <trigger> <label>Delete from purchase order</label> <action ev:event="DOMActivate"><delete context="/purchaseOrder" nodeset="item" at="index('R')"/><delete context="/purchaseOrder" ref="item" at="index('R')"/> <insert context="/purchaseOrder" if="not(item)"nodeset="item" origin="instance('prototypes')/item"/>ref="item" origin="instance('prototypes')/item"/> <setfocus control="R"/> </action> </trigger>
nodeset="/purchaseOrder/item"
ref="/purchaseOrder/item"
in
the
delete
action,
but
the
context
attribute
was
added
for
consistency
with
the
insert
action.
<model xmlns:my="http://example.org"> <instance> <my:data> <my:name> <my:first-name>John</my:first-name> <my:last-name>Doe</my:last-name> </my:name> <my:address> <my:street>123 Main St.</my:street> <my:city>Smallville</my:city> </my:address> </my:data> </instance><bind nodeset="/my:data/my:name/" readonly="true()"/> <bind nodeset="/my:data/my:address/my:street" readonly="true()"/> <action ev:event="xforms-model-construct-done"> <delete id="D1" nodeset="my:name/*" ... /> <delete id="D2" nodeset="my:address/my:street" at="1" > <delete id="D3" nodeset="my:address" at="1" >
<bind ref="my:name" readonly="true()"/> <bind ref="my:address/my:street" readonly="true()"/>
<action ev:event="xforms-model-construct-done"> <delete id="D1" ref="my:name/*" ... /> <delete id="D2" ref="my:address/my:street" at="1" > <delete id="D3" ref="my:address" at="1" > </action> </model>
Delete
D1
fails
because
it
attempts
to
delete
from
the
content
of
a
readonly
node
(
my:name
).
Delete
D2
succeeds
even
though
the
node
to
delete
is
readonly
because
the
node
is
not
being
changed,
but
rather
removed
from
the
content
of
the
parent,
which
is
not
readonly.
Delete
D3
succeeds
even
though
it
contains
a
readonly
node
because
a
node
can
be
deleted
if
its
parent
is
not
readonly,
and
node
deletion
includes
deletion
of
its
attributes
and
content,
regardless
of
whether
or
not
the
attributes
or
content
nodes
are
readonly.
See
Appendix
Patterns
for
Data
Mutations
for
numerous
further
usage
patterns
for
sevalue
,
insert
and
delete
.
The setindex Element
This XForms Action begins by invoking the deferred update behavior . This action then marks a specific item as current in a repeating sequence (within The repeat Element ).
Common Attributes: Common , Events , Action Common
Special Attributes:
- repeat
- Required reference to a repeating element.
- index
-
Required
expression
that
evaluates
to
a
1-based
offset
into
the
sequence.
The
evaluation
context
is
determined
in
the
same
manner
as
the
evaluation
context
for
a
Single-NodeSingle Item Binding (see Evaluation Context ).
If
the
selected
index
value
evaluates
to
NaN
,
this
action
has
no
effect.
Otherwise,
the
selected
index
is
adjusted
by
rounding
to
the
nearest
integer.
If
the
repeat
collection
is
non-empty
and
the
selected
index
less
than
1,
then
the
new
index
will
be
1.
If
the
selected
index
is
greater
than
the
size
of
the
repeat
collection,
then
the
new
index
will
be
the
size
of
the
repeat
index.
If
the
repeating
element
has
an
indexref
expression
that
indicates
an
instance
node,
then
the
new
index
is
placed
into
the
node
by
a
setvalue
action.
If
the
node
is
readonly,
then
the
setvalue
is
not
performed
and
this
action
has
no
effect.
The
repeat
index
for
the
repeat
collection
is
changed
to
the
new
index.
If
the
rounded
selected
index
is
0
or
less,
less
and
the
repeat
collection
is
non-empty,
an
xforms-scroll-first
event
is
dispatched
and
the
index
is
set
to
1.
If
the
rounded
selected
index
is
greater
than
the
index
of
the
last
repeat
item,
item
and
the
repeat
collection
is
non-empty,
an
xforms-scroll-last
event
is
dispatched
and
the
index
is
set
to
that
of
the
last
item.
If
the
index
evaluates
to
NaN
the
action
has
no
effect.
dispatched.
Note:
The
IDREF
from
the
repeat
attribute
may
not
uniquely
identify
the
desired
repeat
if
the
repeat
element
bearing
the
matching
ID
resides
within
the
content
of
another
repeat
.
The
general
method
described
in
Resolving
ID
References
in
XForms
is
used
to
determine
the
desired
run-time
repeat
object.
Note:
This
action
affects
deferred
updates
by
performing
deferred
update
in
its
initialization
and
by
setting
the
deferred
update
flags
for
recalculate,
revalidate
and
refresh.
refresh
(because
the
implicit
instance
node
for
the
repeat
index
is
modified).
The toggle Element
This
XForms
Action
begins
by
invoking
the
deferred
update
behavior
.
This
action
then
selects
one
possible
case
from
an
exclusive
list
of
alternatives
in
a
switch
.
This action performs the following:
-
Dispatches
an
xforms-deselect
event to the currently selectedcase
in theswitch
containing the identifiedcase
. -
Adjusts
the
selected
states (not the attribute values) on the affected cases to reflect the new state of theswitch
containing the identifiedcase
. -
Dispatches
an
xform-select
event to thecase
just selected.
Common Attributes: Common , Events , Action Common
Special Attributes:
- case
-
Author-optional
reference
to
a
case
element. The case to select is specified by this attribute or by the child element case .
The
case
to
be
selected
by
the
switch
is
identified
by
IDREF
either
by
the
attribute
case
or
by
a
child
case
element.
If
no
case
element
contains
the
given
identifier,
then
this
action
has
no
effect.
Note:
Whether
the
IDREF
is
obtained
from
the
case
attribute
or
element,
the
IDREF
may
not
uniquely
identify
the
desired
case
if
the
case
element
bearing
the
matching
ID
resides
in
a
repeating
construct
such
as
element
repeat
.
The
general
method
described
in
Resolving
ID
References
in
XForms
is
used
to
determine
the
desired
run-time
case
object.
If
the
switch
that
contains
the
identified
case
specifies
the
caseref
attribute,
then
the
behavior
of
this
action
is
associated
with
the
ability
to
successfully
perform
a
setvalue
on
the
node
indicated
by
the
caseref
.
If
the
caseref
does
not
indicate
a
node
or
if
the
node
is
readonly,
then
this
action
has
no
effect.
Otherwise,
the
node
value
is
changed
to
the
IDREF
value
obtained
above,
which
then
results
in
the
three
toggle
steps
described
above.
Note:
This
action
affects
deferred
updates
by
performing
.
If
this
action
has
an
effect,
then
deferred
update
is
performed
in
its
initialization.
Also,
if
this
action
performs
a
setvalue
,
then
this
action
sets
the
deferred
update
flags
for
recalculate,
revalidate
and
refresh.
The case Element Child of the toggle Element
This
section
defines
a
child
element
of
toggle
named
case
(deprecated
in
favor
of
using
an
AVT
in
the
case
attribute)
that
is
an
alternate
means
of
providing
the
identity
of
a
case
element
to
select
with
a
switch
.
Element:
case
Common
attributes:
None
Attributes:
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
case
identity,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
case
to
be
selected
by
the
toggle
action
is
given
by
the
case
attribute
or
the
case
element.
If
both
are
given,
the
element
takes
precedence.
Due
to
the
addition
of
the
element,
the
case
attribute
is
no
longer
required,
but
either
the
case
attribute
or
the
case
element
must
appear.
The
case
element
can
provide
the
identity
of
a
case
with
either
its
string
content
or
the
value
attribute.
If
both
are
given,
then
the
value
attribute
takes
precedence.
<toggle> <case value="concat('case_', ../addressBlockType)"/> </toggle>
The setfocus Element
This
XForms
Action
begins
by
invoking
the
deferred
update
behavior
.
This
action
then
dispatches
an
xforms-focus
event
(
The
xforms-focus
Event
)
to
the
element
identified
by
attribute
control
or
child
element
control
.
Common Attributes: Common , Events , Action Common
Special Attributes:
- control
- Author-optional reference to a form control . The form control is specified by this attribute or by the child element control .
The
identity
of
the
element
to
which
the
setfocus
action
dispatches
xforms-focus
is
given
by
the
control
attribute
or
the
control
element.
If
no
such
element
contains
the
given
identifier,
then
this
action
has
no
effect.
Note:
Whether
the
IDREF
is
obtained
from
the
control
attribute
or
element,
the
IDREF
may
not
uniquely
identify
the
desired
form
control
if
the
element
bearing
the
matching
ID
resides
in
a
repeating
construct
such
as
element
repeat
.
The
general
method
described
in
Resolving
ID
References
in
XForms
is
used
to
determine
the
desired
form
control.
Note:
Changing the focus to a form control within a repeat object may cause one or more repeat index values to be changed as described in Section User Interface Interaction .
The control Element Child of the setfocus Element
This
section
defines
a
child
element
of
setfocus
named
control
(deprecated
in
favor
of
using
an
AVT
in
the
control
attribute)
that
is
an
alternate
means
of
providing
the
element
that
receives
the
xforms-focus
event.
Element:
control
Common
attributes:
None
Attributes:
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
desired
element
identifier,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
identity
of
the
element
to
which
the
setfocus
action
dispatches
xforms-focus
is
given
by
the
control
attribute
or
the
control
element.
If
both
are
given,
the
element
takes
precedence.
Due
to
the
addition
of
the
element,
the
control
attribute
is
no
longer
required,
but
either
the
control
attribute
or
the
control
element
must
appear.
The
control
element
can
provide
the
desired
element
identifier
with
either
its
string
content
or
the
value
attribute.
If
both
are
given,
then
the
value
attribute
takes
precedence.
<setfocus> <control value="concat('input_', ../paymentType)"/> </setfocus>
The dispatch Element
This action dispatches an XML Event to a specific target element. Two kinds of event can be dispatched:
-
Predefined
XForms
events
(i.e.,
xforms-
event-name
),
in
which
case
the
bubbles
andcancelable
attributes are ignored and the standard semantics as defined in Processing Model apply. - An event created by the XForms author with no predefined XForms semantics and as such not handled by default by the XForms Processor.
Common Attributes: Common , Events , Action Common
Special Attributes:
- name
- Author-optional attribute for specifying the name of the event to dispatch.
- targetid
- Author-optional attribute for specifying the reference to the event target.
- delay
- Author-optional attribute that indicates the minimum number of milliseconds to delay dispatching of the event to the target. The default is the empty string, which indicates no delay.
- bubbles
-
Author-optional
attribute
containing
a
boolean
indicating
if
this
event
bubbles
—
as
defined
in
[
DOM2
Events
].
The
default
value
is
true
for a custom event. For predefined events, this attribute has no effect. - cancelable
-
Author-optional
attribute
containing
a
boolean
indicating
if
this
event
is
cancelable
—
as
defined
in
[
DOM2
Events
].
The
default
value
is
true
for a custom event. For predefined events, this attribute has no effect.
The
event
to
be
dispatched
is
given
by
the
name
attribute
or
the
name
child
element.
Due
to
the
addition
of
the
name
element,
the
name
attribute
is
not
required,
but
either
the
name
attribute
or
the
name
element
must
appear.
If
the
event
name
is
not
specified
or
empty
string,
then
this
action
has
no
effect.
The
element
to
which
the
event
is
to
be
dispatched
is
identified
by
the
targetid
attribute
or
the
targetid
child
element.
Due
to
the
addition
of
the
targetid
element,
the
targetid
attribute
is
not
required,
but
this
action
has
no
effect
unless
the
target
identifier
is
specified
by
the
element
or
attribute.
For
backwards
compatibility
with
documents
created
for
earlier
versions
of
the
specification,
the
processor
of
the
dispatch
element
may
allow
the
attribute
named
target
and
the
child
element
target
to
be
used.
The
attribute
and
element
named
target
provide
exactly
the
same
behaviors
as
the
targetid
attribute
and
element,
except
that
the
target
attribute
and
element
are
ignored
if
the
dispatch
element
also
bears
a
targetid
attribute
or
contains
a
targetid
child
element.
Note:
Whether
the
IDREF
is
obtained
from
the
targetid
attribute
or
targetid
element,
the
IDREF
may
not
uniquely
identify
the
desired
target
object
if
the
element
bearing
the
matching
ID
resides
in
a
repeating
construct
such
as
element
repeat
.
The
general
method
described
in
Resolving
ID
References
in
XForms
is
used
to
determine
the
desired
target
object.
The
event
may
be
dispatched
immediately
or
after
a
specified
non-negative
number
of
milliseconds
of
delay.
The
event
delay
is
specified
the
delay
attribute
or
by
the
child
element
delay
.
If
the
delay
is
not
specified
or
if
the
given
value
does
not
conform
to
xsd:nonNegativeInteger
,
then
the
event
is
dispatched
immediately
as
the
result
of
the
dispatch
action.
Otherwise,
the
specified
event
is
added
to
the
delayed
event
queue
unless
an
event
with
the
same
name
and
target
element
already
exists
on
the
delayed
event
queue.
The
dispatch
action
has
no
effect
if
the
event
delay
is
a
non-negative
integer
and
the
specified
event
is
already
in
the
delayed
event
queue.
Note:
Since an element bearing a particular ID may be repeated, the delayed event queue may contain more than one event with the same name and target IDREF. It is the name and the target run-time element that must be unique.
If
a
run-time
element
is
destroyed,
then
any
delayed
events
targeted
at
that
element
are
removed
from
the
delayed
event
queue.
A
run-time
element
may
be
destroyed
for
a
number
of
reasons,
including
shutdown
of
the
form
or
removal
of
form
controls
associated
by
a
repeat
with
an
instance
data
node
that
is
destroyed.
As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and then dispatched. In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing of delayed events is done without interrupting the processing of another event and its event handlers.
Note:
Because
the
delayed
event
is
first
removed
from
the
delayed
event
queue
and
then
dispatched,
a
handler
for
a
given
event
may
dispatch
the
event
again
with
a
delay.
This
can
be
used
to
perform
simple
polling
and
asynchronous
looping
operations.
Moreover,
the
if
attribute
can
be
applied
to
the
dispatch
action
to
decide
when
to
discontinue
the
polling
or
looping
based
on
a
setting
in
instance
data.
The name Child Element
This
section
defines
a
new
child
element
of
dispatch
(deprecated
in
favor
of
using
an
AVT
in
the
name
attribute)
that
provides
an
alternate
means
of
specifying
the
name
of
the
event
to
dispatch.
Element:
name
Common
attributes:
None
Attributes:
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
event
name,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
event
name
of
the
dispatch
action
is
given
by
the
name
attribute
or
the
name
element.
If
both
are
given,
the
element
takes
precedence.
The
name
element
can
provide
the
event
name
with
either
its
string
content
or
the
value
attribute.
If
both
are
given,
then
the
value
attribute
takes
precedence.
The targetid Child Element
This
section
defines
a
new
child
element
of
dispatch
(deprecated
in
favor
of
using
an
AVT
in
the
targetid
attribute)
that
provides
an
alternate
means
of
specifying
the
target
of
the
event
to
be
dispatched.
Element:
targetid
Common
attributes:
None
Attributes:
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
event
target,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
event
target
of
the
dispatch
action
is
given
by
the
targetid
attribute
or
the
targetid
element.
If
both
are
given,
the
element
takes
precedence.
The
targetid
element
can
provide
an
IDREF
for
the
event
target
with
either
its
string
content
or
the
value
attribute.
If
both
are
given,
then
the
value
attribute
takes
precedence.
The delay Child Element
This
section
defines
a
new
child
element
of
dispatch
(deprecated
in
favor
of
using
an
AVT
in
the
delay
attribute)
that
provides
an
alternate
means
of
specifying
the
delay
imposed
on
the
event
to
be
dispatched.
Element:
delay
Common
attributes:
None
Attributes:
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
event
delay,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . If the result does not conform lexically toxsd:nonNegativeInteger
, then the result of empty string is used. An empty string is used if the evaluation fails.
Content: PCDATA
The
event
delay
of
the
dispatch
action
is
given
by
the
delay
attribute
or
the
delay
element.
If
both
are
given,
the
element
takes
precedence.
The
delay
element
can
provide
the
delay
with
either
its
string
content
or
the
value
attribute.
If
both
are
given,
then
the
value
attribute
takes
precedence.
The property Child Element
An
event
can
have
extra
context
information.
The
property
element
offers
the
ability
to
add
extra
context
information
to
a
newly
dispatched
event.
Common Attributes: Common
Special Attributes:
- name
- The name attribute specifies the name of the context information to pass.
- value
-
The
optional
value
attribute specifies an XPath expression returning the context information to pass. The value can be any sequence of items.
The
value
of
the
extra
context
information
can
either
be
specified
by
the
value
attribute
or
as
inline
text.
The
value
attribute
has
precedence
over
the
inline
context
(i.e.:
if
the
value
attribute
is
specified,
the
result
of
evaluating
the
expression
specified
by
the
value,
is
used
as
the
value
for
the
variable).
<dispatch name="update-person" target="my-model"> <property name="person" value="instance('person')"/> <property name="min-age" value="21"/> <property name="new-first-name">Michelle</property> </dispatch>
Using the information:
<action ev:event="update-person"> <insert context="..." origin="event('person')"/> <setvalue ref="..." value="event('min-age')"/> <setvalue ref="..." value="event('new-first-name')"/> </action>
The rebuild Element
This
action
causes
the
default
processing
of
xforms-rebuild
to
happen,
bypassing
occur
on
the
model
associated
with
the
rebuild
element.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
model
attribute
of
the
closest
ancestor
element
is
used.
Otherwise,
the
first
model
is
used.
This
action
bypasses
the
normal
event
flow
(i.e.
flow,
i.e.
the
behavior
occurs
without
dispatching
the
xforms-rebuild
event).
event.
This
action
results
in
the
XForms
Processor
rebuilding
any
internal
data
structures
used
to
track
computational
dependencies
among
instance
data
nodes
—
see
The
xforms-rebuild
Event
.
Common
Attributes:
Common
,
Events
,
Action
Common
Special
Attributes:
Note:
This action affects deferred updates .
The recalculate Element
This
action
causes
the
default
processing
of
xforms-recalculate
to
happen,
bypassing
occur
on
the
model
associated
with
the
recalculate
element.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
model
attribute
of
the
closest
ancestor
element
is
used.
Otherwise,
the
first
model
is
used.
This
action
bypasses
the
normal
event
flow
(i.e.
flow,
i.e.
the
behavior
occurs
without
dispatching
the
xforms-recalculate
event).
event.
As
a
result,
instance
data
nodes
whose
values
need
to
be
recalculated
are
updated
as
specified
in
the
processing
model
—
see
The
xforms-recalculate
Event
.
Common
Attributes:
Common
,
Events
,
Action
Common
Special
Attributes:
Note:
This action affects deferred updates .
The revalidate Element
This
action
causes
the
default
processing
of
xforms-revalidate
to
happen,
bypassing
occur
on
the
model
associated
with
the
revalidate
element.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
model
attribute
of
the
closest
ancestor
element
is
used.
Otherwise,
the
first
model
is
used.
This
action
bypasses
the
normal
event
flow
(i.e.
flow,
i.e.
the
behavior
occurs
without
dispatching
the
xforms-revalidate
event).
event.
This
results
in
the
instance
data
being
revalidated
as
specified
by
the
processing
model
—
see
The
xforms-revalidate
Event
.
Common
Attributes:
Common
,
Events
,
Action
Common
Special
Attributes:
Note:
This action affects deferred updates .
The refresh Element
This
action
causes
the
default
processing
of
xforms-refresh
to
happen,
bypassing
occur
on
the
model
associated
with
the
refresh
element.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
model
attribute
of
the
closest
ancestor
element
is
used.
Otherwise,
the
first
model
is
used.
This
action
bypasses
the
normal
event
flow
(i.e.
flow,
i.e.
the
behavior
occurs
without
dispatching
the
xforms-refresh
event).
event.
This
action
results
in
the
XForms
user
interface
being
refreshed
,
and
the
presentation
of
user
interface
controls
being
updated
to
reflect
the
state
of
the
underlying
instance
data
—
see
The
xforms-refresh
Event
.
Common
Attributes:
Common
,
Events
,
Action
Common
Special
Attributes:
Note:
This action affects deferred updates .
The reset Element
This
action
initiates
reset
processing
by
dispatching
an
xforms-reset
event
to
the
specified
model
associated
with
the
reset
element.
If
the
element
has
a
model
attribute,
that
model
is
used.
Otherwise,
the
.
model
attribute
of
the
closest
ancestor
element
is
used.
Otherwise,
the
first
model
is
used.
Processing
of
event
xforms-reset
is
defined
in
the
processing
model
—
see
The
xforms-reset
Event
.
Common
Attributes:
Common
,
Events
,
Action
Common
Special
Attributes:
Note:
This action affects deferred updates .
The load Element
This action traverses the specified link.
Common
Attributes:
Common
,
Events
,
Action
Common
,
Single-Node
Single
Item
Binding
(author-optional)
Special Attributes:
- resource
- Author-optional attribute. Link to an external resource to load.
- target
-
Author-optional
presentation
context
name
or
keyword.
Behavior
is
defined
for
values
"_self"
and
"_blank".
In
addition,
an
implementation-dependent
presentation
name
can
be
specified.
If
this
attribute
is
missing
and
show
is specified, then the behavior is defined by theshow
attribute. Otherwise ifshow
is not specified a default value of "_self" is assumed. - show [deprecated]
-
Author-optional
link
behavior
specifier.
The
allowed
values
are
"replace" and"replace", "new". If this attribute is missing, a default value of "replace" is assumed.
The
URI
specifying
the
link
to
traverse
may
be
pointed
to
by
the
Single
Node
Item
Binding
attributes,
if
given,
or
by
the
resource
attribute
or
the
resource
child
element.
Individually,
the
Single
Node
Item
Binding,
resource
element
and
resource
attribute
are
not
required.
If
none
are
given,
the
action
has
no
effect.
If
the
Single
Node
Item
Binding
is
present
and
does
not
select
an
instance
data
node,
then
this
action
has
no
effect.
If
the
Single
Node
Item
Binding
is
given
in
addition
to
one
of
the
resource
attribute
or
resource
element,
then
the
action
has
no
effect.
The
URI
obtained
in
this
manner
is
treated
as
a
link
to
an
external
resource,
defined
as
an
[
XLink
1.0
]
link
between
the
load
element
and
the
remote
resource
indicated.
No
XLink
actuate
value
is
defined,
since
control
of
actuation
is
defined
by
XML
Events.
The
XLink
show
value
depends
on
the
show
attribute.
The
link
indidicated
indicated
by
the
URI
obtained
above
is
traversed.
If
the
link
traversal
fails,
then
an
implementation-specific
means
of
conveying
the
link
traversal
failure
occurs.
Otherwise,
processing
for
the
document
(or
portion
of
the
document)
reached
by
traversing
the
link
is
specified
by
the
target
or
show
attribute.
The
following
are
the
possible
values
for
the
attribute
and
the
corresponding
processing
behaviors:
show
target
- _self
- The document is loaded into the current presentation context. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.
- _blank
-
The
document
is
loaded
into
a
new
presentation
context,
e.g.,
a
new
window.window or tab. Form processing in the original window or tab continues. - Any other value
-
The
behavior
is
implementation-dependent.
Note:
If the host language is HTML, the implementation is encouraged to handle the
target
attribute as defined in HTML for thea
element. In particular, values of "_blank", "_self", "_parent", "_top", as well as browsing context names should be supported.
The
following
are
the
possible
values
for
the
show
attribute
and
the
corresponding
processing
behaviors:
- replace
-
The
document
is
loaded
into
the
current
window.presentation context. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document. - new
- The document is loaded into a new presentation context, e.g., a new window or tab. Form processing in the original window or tab continues.
The resource Element child of load
The
resource
child
element
of
load
is
deprecated
in
favor
of
using
an
AVT
in
the
resource
attribute.
When
it
appears
as
the
first
child
element
of
load
,
the
resource
element
provides
the
URI
of
the
link,
overriding
the
resource
attribute.
As
stated
above,
the
load
action
has
no
effect
if
both
a
resource
and
a
Single
Node
Item
Binding
are
given.
This
element
allows
the
URI
used
by
the
load
to
be
dynamically
calculated
based
on
instance
data.
Common
Attributes:
None
Common
Special Attributes:
- value
-
Author-optional
attribute
containing
an
expression
to
evaluate
using
the
in-scope
evaluation
context.
To
obtain
the
URI,
the
result
of
the
expression
is
processed
as
if
by
call
to
the
string
conversion function as described in the expression module . An empty string is used if the evaluation fails.
Content: PCDATA
The
URI
to
be
used
by
the
load
can
be
specified
with
either
the
value
attribute
or
the
string
content
of
the
resource
element.
If
both
are
specified,
then
the
value
attribute
takes
precedence.
If
the
load
does
not
have
a
resource
element
as
its
first
child,
then
the
URI
is
obtained
from
the
resource
attribute
or
the
Single
Node
Item
Binding,
if
given.
The send Element
This
action
initiates
submit
processing
by
dispatching
an
xforms-submit
event.
Processing
of
event
xforms-submit
is
defined
in
the
processing
model
—
see
The
xforms-submit
Event
.
Common Attributes: Common , Events , Action Common
Special Attributes:
- submission
-
Author-optional
attribute
containing
a
reference
to
a
submission
element. If this attribute is given but does not identify asubmission
element, then thesend
action has no effect. If this attribute is omitted, then the firstsubmission
in document order from themodel
associated with the in-scope evaluation context is used.
The message Element
This action encapsulates a message to be displayed to the to the user.
Common
Attributes:
Common
,
Events
,
Action
Common
,
Single
Node
Item
Binding
(author-optional)
Special Attributes:
- level
- Author-optional attribute containing a message level identifier, one of ("ephemeral"|"modeless"|"modal"| QNameButNotNCName ). The default is "modal" if the attribute is not specified. This specification does not define behavior for QNameButNotNCName values.
The
message
specified
can
exist
in
instance
data
or
as
inline
text.
If
more
than
one
source
of
message
is
specified
in
this
element,
the
order
of
precedence
is:
single
node
binding
Single
Item
Binding
attributes,
inline
text.
The
user
interface
for
the
message
action
is
considered
to
be
created
at
the
time
the
action
occurs.
If
the
message
is
obtained
from
the
inline
content
of
the
message
action,
then
the
output
of
any
output
controls
in
the
message
content
is
determined
based
on
the
instance
data
available
when
the
message
action
occurs.
For
example,
the
following
example
displays
the
message
Hello,
world!
as
the
form
starts
up:
<model> <instance> <name>John</name> </instance><action ev:event="xforms-ready">
<action ev:event="xforms-ready"> <setvalue ref="name">world</setvalue> <message level="modal">Hello, <output ref="name"/>!</message> ...</action> </model>
In
this
example,
the
message
includes
the
latest
user
input
even
though
other
form
controls
not
in
the
message
action
are
not
guaranteed
to
be
updated
until
the
end
of
the
xforms-refresh
event
processing:
<input ref="birthday"> <label>Enter birthday:</label> <message ev:event="xforms-invalid"><output ref="."/> isn't a valid birthday</message> </input>
Note:
Due
to
deferred
update
behavior,
if
a
message
action
is
preceded
in
an
action
sequence
by
other
actions
that
change
instance
nodes,
and
the
message
references
nodes
that
are
computationally
dependent
on
the
changed
nodes,
then
the
form
author
should
invoke
the
recalculate
action
before
the
message
action.
Moreover,
if
the
computational
dependencies
involved
nodes
that
were
inserted
or
deleted,
then
the
form
author
should
invoke
rebuild
prior
to
the
recalculate
.
Modal messages
With
level="modal"
,
further
user
interface
operations
are
blocked
until
the
message
is
explicitly
dismissed
by
the
user.
An XForms Processor should support styling of modal messages in the host language integration.
A graphical browser might render a modal message as follows:
<model> <message level="modal" ev:event="xforms-ready">This is not a drill!</message> ... </model>
Modeless messages
A
modeless
message
is
presented
until
explicitly
dismissed,
but
does
not
inhibit
other
user
interface
operations.
An
XForms
Processor
should
support
styling
of
ephemeral
messages
in
the
foundation
for
displaying
a
help
message,
which
a
host
language
integration.
In this example, the message suggests user action, but does not require it, so interrupting other user interface operations would be obtrusive.
A graphical browser might render a modeless message as follows:
<secret ref="/login/password"><label>Password</label> <help>Have you forgotten your password? Simply call 1-900-555-1212 and have a major credit card handy.</help><label>Password:</label> <message level="modeless" ev:event="xforms-value-changed" if="length(.) > 3 and matches(., '[A-Z]+$') and not(matches(., '[a-z]+'))"> Is your caps-lock key on? </message> </secret>
Ephemeral messages
An
ephemeral
message
is
presented
only
briefly,
and
need
not
be
explicitly
dismissed.
An
XForms
Processor
should
support
styling
of
ephemeral
messages
in
the
foundation
for
displaying
a
hint
message,
which
host
language
integration.
In this example, the message appears briefly when a submit control is activated, offering an encouraging message.
<group> <label>Change of Address:</label> <input ref="name"> <label>Name: </label> <hint appearance="minimal">Last, First</hint> </input> <input ref="website"> <label>Website: </label> <hint appearance="minimal">http://</hint> </input> <submit submission="apply"> <label>Apple</label> <message level="ephemeral" ev:event="DOMActivate">Don't forget to write!</message> </submit> </group>
A
graphical
browser
might
render
an
ephemeral
message
as
follows:
<input ref="po/address/street1">
<label>Street</label>
<hint>Please enter the number and street name</hint>
</input>
The script Element
This
action
is
used
to
execute
a
script,
either
embedded
inline
or
from
an
external
URL
using
the
src
attribute.
Common Attributes: Common , Events , Action Common
Special Attributes:
- type
-
This
attribute
specifies
the
language
of
the
script.
Its
value
must
be
a
valid
MIME
type.
The
supported
languages
depend
on
the
XForms
Processor
and
an
implementation
may
choose
to
support
no
languages
at
all.
It
is
an
xforms-action-error
with
error-type
set toscript-language-error
if the action is executed and the languages is not supported. Theerror-message
context information may contain a more specific error message.
- src
- This author-optional attribute identifies an external resource that provides the script implementation. If the link traversal fails, it is treated as an exception ( The xforms-link-exception Event ).
- charset
-
This
author-optional
attribute
specifies
the
encoding
of
the
remote
resource
identified
by
the
src
attribute.
If
the
src
attribute
is
given,
then
it
takes
precedence
over
inline
content,
and
the
script
implementation
for
the
script
is
obtained
from
the
link.
If
the
src
attribute
is
omitted,
then
the
script
implementation
for
the
script
is
obtained
from
inline
content.
It
is
an
xforms-action-error
with
error-type
set
to
script-error
if
the
action
is
executed
and
any
error
occurs
during
the
execution
of
the
script.
The
error-message
context
information
may
contain
a
more
specific
error
message.
The in-scope variables, the current context item, position and size are made available to the script as variables following the best practices for the specific scripting language. For example, in JavaScript they should be made available as namespaced variables using the following format: XForms.var.{variable-name}, XForms.context.item, XForms.context.position and XForms.context.size.
<script type="text/javascript"> alert('This is a JavaScript alert: ' + XForms.var.message); </script>
Conditional Execution of XForms Actions
The
if
attribute
can
be
added
to
any
XForms
action.
It
contains
an
expression
that
is
evaluated
using
the
in-scope
evaluation
context
before
the
action
is
executed.
The
result
of
the
expression
is
converted
to
a
boolean
as
described
in
the
the
expression
module
.
If
the
converted
result
of
the
expression
evaluates
to
false
,
then
the
action
is
not
performed.
If
the
converted
result
is
true
,
then
the
action
is
performed.
If
this
attribute
is
applied
to
an
XForms
action
element
and
the
converted
result
of
evaluation
is
false
,
then
all
of
the
actions
within
the
action
element
are
omitted
from
the
execution
of
the
XForms
action
sequence
that
invoked
the
action
element.
If
the
result
is
true
,
then
the
contained
actions
are
performed
according
to
the
normal
processing
rules
such
as
deferred
update
behavior
and
applicability
of
conditional
and
iterative
attributes.
Note:
In
actions
insert
and
delete
,
the
attribute
context
is
evaluated
before
the
if
attribute.
The
setfocus
action
in
each
input
control
is
executed
only
if
the
node
bound
to
the
control
is
a
number
of
a
particular
length.
The
exacting
form
author
could
perform
further
validity
tests.
... <input ref="areaCode" id="AreaCodeControl" incremental="true"> <label>Area Code</label><setfocus ev:event="xforms-value-changed" control="ExchangeControl"<setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/> </input> <input ref="exchange" id="ExchangeControl" incremental="true"> <label>Exchange</label><setfocus ev:event="xforms-value-changed" control="LocalControl"<setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/> </input> <input ref="local" id="LocalControl" incremental="true"> <label>Local</label><setfocus ev:event="xforms-value-changed" control="ExtensionControl"<setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/> </input> ...
The
trigger
that
performs
a
delete
conditionally
sets
the
focus
to
a
control
outside
of
the
repeat
if
the
repeat
becomes
empty
due
to
the
deletion.
The
setfocus
is
called
first
because
the
delete
removes
the
context
node.
... <trigger id="InsertControl"> <label>Insert Row</label> <action ev:event="DOMActivate"><insert context="purchaseOrder/lines" nodeset="line"<insert context="purchaseOrder/lines" ref="line" at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/> <setfocus control="PurchaseOrderRepeat"/> </action> </trigger><repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat"><repeat ref="purchaseOrder/lines/line" id="PurchaseOrderRepeat"> ... <trigger> <label>Delete Row</label> <action ev:event="DOMActivate"> <setfocus control="InsertControl" if="last()=1"/><delete nodeset="../line" at="index('PurchaseOrderRepeat')"/><delete ref="../line" at="index('PurchaseOrderRepeat')"/> </action> </trigger> ... </repeat>
Iteration
of
XForms
Actions
The
while
attribute
The
while
attribute
can
be
added
to
any
XForms
action.
It
contains
an
expression
that
is
evaluated
using
the
in-scope
evaluation
context
before
the
action
is
executed.
The
result
of
the
expression
is
converted
to
a
boolean
as
described
in
the
expression
module
.
If
the
converted
result
of
the
expression
is
true
,
then
the
XForms
action
is
performed
and
then
the
expression
is
re-evaluated.
The
XForms
action
is
executed
repeatedly
until
the
converted
result
of
the
expression
evaluates
to
false
.
If
this
attribute
is
applied
to
an
XForms
action
element,
then
the
sequence
of
XForms
actions
in
its
content
are
executed
repeatedly
once
for
each
time
the
immediately
preceding
evaluation
of
the
expression
yields
a
result
of
true
.
When XForms actions are iteratively executed, they are still subject to the normal action processing rules such as deferred update and applicability of conditional and iterative attributes.
An
XForms
action
may
be
executed
zero
times
due
to
this
attribute.
Furthermore,
if
an
action
bears
this
attribute
and
the
if
attribute,
then
the
expressions
of
both
attributes
must
evaluate
to
true
before
each
iterative
execution
of
the
action.
Note:
In
actions
insert
and
delete
,
the
attribute
context
is
evaluated
before
the
while
attribute.
Therefore,
context
is
re-evaluated
before
each
iteration
of
the
actions
controlled
by
the
while
attribute.
Counter and accumlator variables are created in instance data to sum a selection of values chosen by the user
<trigger> <label>Get Sum</label> <action ev:event="DOMActivate"> <setvalue ref="instance('temps')/counter" value="1"/> <setvalue ref="instance('temps')/accumulator" value="0"/> <action while="instance('temps')/counter <= count(/some/nodes)"> <setvalue ref="instance('temps')/accumulator" value=". + instance('default')/some/nodes[number(instance('temps')/counter)]" if="boolean-from-string(/some/nodes[number(instance('temps')/counter)]/@selected)"/> <setvalue ref="instance('temps')/counter" value=". + 1"/> </action> </action> </trigger>
The
iterate
attribute
The
iterate
attribute
can
be
added
to
any
XForms
action.
It
contains
an
expression
that
is
evaluated
once
using
the
in-scope
evaluation
context
before
the
action
is
executed,
which
will
result
in
a
sequence
of
items.
The
action
will
be
executed
with
each
item
in
the
sequence
as
its
context.
This
context
replaces
the
default
in
scope
evaluation
context.
<delete ref="." at="1" iterate="node[@selected='true']"/>
Notice
that
the
iterate
changes
the
evaluation
context
for
if
and
while
attributes.
Also
notice
the
iterate
attribute
is
evaluated
before
any
of
the
two.
Because the iterate expression is evaluated once using the in-scope evaluation context, before the action is executed, the action will be executed for nodes that are deleted, from their instance, by the action or its descendent actions. A deleted node no longer belongs to a document, you can use this characteristic in the if attribute to skip deleted nodes if you want to skip deleted nodes.
Actions from Other Modules
Of the action handlers detailed in this chapter, XForms defines some to be part of the XForms Switch and Repeat modules: The toggle Element and The setindex Element .
Conformance
Conforming XForms Documents
All XForms Containing Documents must conform to the following specifications, except as qualified below:
- [ XML 1.0 ]
- [ XML Names ]
- [ XPath 1.0 ]
- [ XML Events ]
- [ XML Schema part 2 ]
XForms
elements
are
typically
inserted
into
a
containing
document
in
multiple
places.
The
root
element
for
each
individual
fragment
of
XForms
must
be
model
,
a
core
form
control
,
group
,
repeat
,
or
switch
.
Individual
XForms
fragments
are
expected
to
be
schema-valid
according
to
the
XML
Schema
for
XForms
(
Schema
for
XForms
),
except
that
the
host
language
may
add
elements
of
its
own
namespace
to
the
content
models
of
the
following
elements:
group
,
repeat
,
case
,
label
,
help
,
hint
,
alert
and
message
.
.
A host language may introduce additional conformance requirements.
Conforming XForms Generators
XForms generators should generate conforming XForms documents.
Base Technologies for XForms Processors
The following are base technologies for XForms. An XForms Processor therefore must conform to the following specifications, except as qualified below:
- [ XML 1.0 ]
- [ XML Names ]
- [ XPath 1.0 ]
- [ XML Events ] (not all aspects are required )
- [ XML Schema part 2 ]
Conformance Levels
XForms is a generalized XML processing language. Therefore, the XForms specification is intended for implementation on hardware platforms of all sizes, from tiny hand-held devices to high-powered servers. This section describes two main levels of conformance that are useful in varied scenarios.
XForms Model
This
conformance
level
is
distinguished
by
the
processor's
property()
function
returning
a
string
beginning
with
"model"
for
the
conformance-level
property.
An
XForms
model
can
contain
or
reference
XML
schemas,
Schemas,
XForms
instance
elements,
XForms
bind
elements,
XForms
submission
elements,
and
XForms
actions.
XForms
submission
elements
can
also
contain
XForms
actions.
An XForms Model Processor is a reduced functionality XForms Processor with required, recommended and optional features described in this section.
An
XForms
Model
Processor
must
support
all
attributes
of
the
model
element.
The
processor
must
support
the
valid
attributes
and
content
of
the
instance
element,
and
it
should
support
the
notification
events
xforms-insert
and
xforms-delete
.
The
processor
must
support
all
attributes,
content
and
other
aspects
of
bind
elements,
except
p3ptype
support
is
optional
.
The
processor
must
fully
support
[
XPath
1.0
],
including
all
XForms
extension
functions
(though
the
index()
function
may
return
1
if
the
processor
has
no
information
about
the
identified
repeat
element).
The
processor
must
make
available
the
automatic
schema
XML
Schema
datatype
information
defined
by
XForms.
The
processor
must
be
able
to
parse
inline
and
external
declared
XML
schema
Schema
and
consume
their
schema
XML
Schema
datatype
information
[
XML
Schema
part
2
],
and
the
processor
should
consume
all
schema
XML
Schema
information
available
where
appropriate
in
the
XForms
processing
model.
An
XForms
Model
Processor
may
(and
hence
may
not)
support
user
interface
creation
and
refresh
behaviors
described
for
model
processing.
An
XForms
Model
Processor
must
support
action
handlers
for
the
events
xforms-model-construct-done
,
xforms-ready
,
xforms-link-exception
and
.
The
processor
may
support
action
handlers
for
the
xforms-version-exception
xforms-version-error
xforms-refresh
event,
and
it
should
support
all
other
events
targetted
at
model
elements.
The
support
for
attributes
and
elements
of
[
XML
Events
]
is
described
below
in
the
description
of
the
support
for
XForms
Actions.
An
XForms
Model
Processor
should
support
the
XForms
Submission
module
.
If
it
does,
then
all
attributes,
child
elements,
behaviors
and
events
must
be
supported
except
as
follows.
The
support
for
attributes
and
elements
of
[
XML
Events
]
on
action
handlers
for
submission
events
is
described
below
in
the
description
of
the
support
for
XForms
Actions.
All
NCName
submission
methods
should
be
supported,
and
the
following
methods
must
be
supported:
get
,
post
,
put
,
delete
,
and
urlencoded-post
.
The
mode
attribute
should
be
supported;
at
least
one
of
asynchronous
or
synchronous
submission
must
be
supported.
The
http
submission
scheme
must
be
supported.
The
https
and
file
schemes
should
be
supported.
Other
schemes
may
be
supported
such
as
mailto
or
ftp
.
XForms-defined
submission
headers
may
be
combined
with
those
from
the
user
agent
in
the
manner
specified
by
the
combine
attribute.
An
XForms
Model
Processor
must
support
the
following
actions:
action
,
insert
,
delete
,
setvalue
,
reset
,
rebuild
,
recalculate
,
revalidate
,
and
dispatch
.
The
processor
should
support
send
and
load
.
The
processor
may
support
refresh
,
setindex
,
setfocus
,
toggle
,
and
message
.
For
every
supported
action,
the
processor
must
support
all
local
attributes
defined
for
the
action,
including
conditional
and
iteration
attributes.
An
XForms
Model
Processor
must
support
the
attribute
ev:event
so
that
XForms
action
handlers
can
appear
as
children
of
either
the
target
elements
of
the
events
they
handle
or
ancestors
of
those
elements.
The
processor
should
support
the
attribute
ev:target
so
action
handlers
can
identify
the
events
targetted
at
a
particular
descendant
of
the
action
handler's
parent
element
(e.g.
the
xforms-insert
or
xforms-delete
event
on
a
particular
instance
of
the
model
).
The
processor
may
support
all
other
features
of
[
XML
Events
].
XForms Full
This
conformance
level
is
distinguished
by
the
processor's
property()
function
returning
a
string
beginning
with
"full"
for
the
conformance-level
property.
An XForms Full Processor is an XForms Processor consisting of a conforming XForms Model Processor along with the following additional required, recommended and optional features:
-
The
processor
must
support
user
interface
creation
and
refresh
behaviors
described
for
model
processing. - The processor must support all core form controls , including all of their attributes and child elements.
-
The
processor
must
support
the
actions
refresh
,setfocus
, andmessage
. -
The
processor
should
support
the
XForms
Group
Module
.
If the processor does not support this module and a group element is encountered during user interface initialization, then the processor must terminate processing after dispatching xforms-binding-exception . -
The
processor
should
support
the
toggle
action and the XForms Switch Module .If the processor does not support this module and a switch element is encountered during user interface initialization, then the processor must terminate processing after dispatching xforms-binding-exception . -
The
processor
should
support
the
setindex
action and the XForms Repeat Module , except that support of therepeat-*
attributes is optional .If the processor does not support this module and a repeat element is encountered during user interface initialization, then the processor must terminate processing after dispatching xforms-binding-exception . -
The
processor
should
support
all
interaction
and
notification
events
targetted
at
basic
form
controls,
group
,switch
,repeat
, and their descendant elements (e.g.case
anditem
). - The processor may support the Extension module.
Glossary Of Terms
- Binding
-
[Definition:
A
"binding"
connects
an
instance dataitem (either a node or an atomic value (such as an integer, date, or string)) to a form control or to a model item property by using a binding expression as a locator.] - Binding expression
- [Definition: An expression used in a binding. The language used for the expression is defined by the expression module ]
- Compound Document
- A [ CDRF 1.0 ] Compound Document is a document that combines multiple document formats either by reference, by inclusion or both.
- Computed expression
- [Definition: An expression used by model item properties such as relevant and calculate to include dynamic functionality in XForms.]
- Containing document
- [Definition: A specific document, for example an XHTML document, in which one or more <model> elements are found.]
- Datatype
- [Definition: From XML Schema [ XML Schema part 2 ]: A 3-tuple, consisting of a) a set of distinct values, called its value space, b) a set of lexical representations, called its lexical space, and c) a set of facets that characterize properties of the value space, individual values or lexical items.]
- Expression module
- [Definition: A separate specification that defines an expression language that can be used for addressing instance data nodes in binding expressions, to express constraints, and to specify calculations in XForms.]
- Facet
- [Definition: From XML Schema [ XML Schema part 2 ]: A single defining aspect of a value space. Generally speaking, each facet characterizes a value space along independent axes or dimensions.]
-
First nodeFirst-item rule -
[Definition:
When
a
UI
Single-NodeSingle Item Bindingattributeselects anode-setsequence of size > 1, the firstnodeitem in thenode-setsequence is used.] - Form control
- [Definition: An XForms user interface control that serves as a point of user interaction (a core form control ) or as a container for other form controls (a container form control ).]
- Host language
- [Definition: An XML vocabulary, such as XHTML, into which XForms is embedded.]
- Instance data
- [Definition: An internal tree representation of the values and state of all the instance data nodes associated with a particular form.]
- Instance data node
- [Definition: An [ XPath 1.0 ] node from the instance data.]
- Item
- [Definition: An item is either a node or an atomic value (such as an integer, date, or string).]
- Lax schema processing
- [Definition: From XML Schema [ XML Schema part 1 ]: For an element or attributes Schema validity to be assessed, then the applicable schema must provide a definition of the item. If not, Schema validation makes no contribution to the validity test for the item.]
- Lexical space
- [Definition: From XML Schema [ XML Schema part 2 ]: A lexical space is the set of valid literals for a datatype.] The XML serialization that may occur during submission expresses the instance data using lexical space literals.
- Model Binding expression
-
[Definition:
An
expression
used
in
the
ref
(or deprecatednodeset
) attribute of abind
element in an XForms model. Often, abind
also declares computed expressions for model item properties of the nodes. ] - Model item
- [Definition: An instance data node with associated constraints.]
- Model item property
- [Definition: An XForms-specific annotation to an instance data node.]
- Node
- [Definition: The definition as used in the XPath Data Model.]
- Non-relevant Form Control
- [Definition: A form control satisfying at least one of the form control non-relevance conditions .]
- QNameButNotNCName
- [Definition: A QName that is not an NCName . In 2006, the W3C named this a PrefixedName . ]
- Relevant Form Control
- [Definition: A form control satisfying none of the form control non-relevance conditions .]
- Schema constraint
- [Definition: A restriction, applied to form data, based on XML Schema datatypes.]
- Strict schema processing
- [Definition: From XML Schema [ XML Schema part 1 ]: If the applicable schema does not provide a definition for an element or attribute, then Schema validation marks the item as invalid.]
- UI Binding Expression
- [Definition: An expression used in binding a form control to the instance.]
- Valid node
-
[Definition:
An
instance
data
node
is
valid
if
and
only
if
the
constraint
model
item
property
is
true,
the
value
is
non-empty
if
the
required
model
item
property
is
true,
and
the
node
satisfies
all
applicable
XML
Schema
definitions
(including
those
associated
by
the
type
model item property, byxsi:type
or by an external or inline schema).] - Value space
- [Definition: From XML Schema [ XML Schema part 2 ]: A set of values for a given datatype. Each value in the value space of a datatype is denoted by one or more literals in its lexical space.]
- versionList
- [Definition: A list ([ XML Schema part 2 ]) with an atomic datatype ([ XML Schema part 2 ]) of versionNumber .]
- versionNumber
-
[Definition:
A
string
consisting
of
a
non-zero
digit
(1
to
9)
followed
by
zero
or
more
digits
(0
to
9),
then
a
period
character
(.),
and
then
one
or
more
digits
(0-9).
A
version
number
is
derived
from
string
by
restriction
based
on
the
following
pattern
value
(excluding
the
quote
marks):
"[1-9]\d*\.\d+"
.] - XForms Model
- [Definition: The non-visible definition of an XML form as specified by XForms. The XForms Model defines the individual model items and constraints and other run-time aspects of XForms.]
- XForms Processor
- [Definition: A software application or program that implements and conforms to the XForms specification.]
References
Normative References
- Exc-C14N
- Exclusive XML Canonicalization Version 1.0 , J. Boyer, D. Eastlake 3rd, J. Reagle, 2002. W3C Recommendation available at http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/ .
- 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
- HTML5
- HTML5 , 2012. W3C Candidate Recommendation available at: http://www.w3.org/TR/html5/forms.html .
- 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
- RFC 2046
- RFC 2046: Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types , N. Freed, N. Borenstein, 1996. Available at http://www.ietf.org/rfc/rfc2046.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 .
- RFC 2387
- RFC 2387: The MIME Multipart/Related Content-type , E. Levinson, 1998. Available at: http://www.ietf.org/rfc/rfc2387.txt .
- RFC 2388
- RFC 2388: Returning Values from Forms: multipart/form-data , L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2388.txt .
- RFC 2396
- RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax , T. Berners-Lee, R. Fielding, L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2396.txt .
- RFC 2616
- RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1 , R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee,1999. Available at: http://www.ietf.org/rfc/rfc2616.txt .
- RFC 2822
- RFC 2822: Internet Message Format , P. Resnick, 2001. Available at: http://www.ietf.org/rfc/rfc2822.txt .
- RFC 2818
- RFC 2818: HTTP Over TLS , E. Rescorla, 2000. Available at: http://www.ietf.org/rfc/rfc2818.txt .
- RFC 3023
- RFC 3023: XML Media Types , M Murata, S. St. Laurent, D. Kohn, 2001. Available at: http://www.ietf.org/rfc/rfc3023.txt .
- SHA2
- SECURE HASH STANDARD. FIPS PUB 180-2 , August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
- SOAP 1.1
- Simple Object Access Protocol (SOAP) 1.1 , D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. F. Nielsen, S. Thatte, D. Winer, 2000. Available at: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ .
- SOAP 1.2
- SOAP Version 1.2 Part 1: Messaging Framework , M. Gudgin, M. Hadley, N. Mendelsohn, J.-J. Moreau, H. F. Nielsen, A. Karmarkar, Y. Lafon, 2007. Available at: http://www.w3.org/TR/2007/REC-soap12-part1-20070427/ .
- Unicode Collation Algorithm
- Unicode Technical Standard #10, Unicode Collation Algorithm , Available at: http://www.unicode.org/unicode/reports/tr10/ .
- 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 .
- XML Base
- XML Base (Second Edition) , J. Marsh, R. Tobin, 2009. W3C Recommendation available at: http://www.w3.org/TR/2009/REC-xmlbase-20090128/ .
- 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/ .
- XML 1.0
- Extensible Markup Language (XML) 1.0 (Fourth Edition) , Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-20060816/
- XML Names
- Namespaces in XML (Second Edition) , Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-names-20060816/ .
- 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 .
- XPath 2.0
- XML Path Language (XPath) 2.0 , Anders Berglund et al. , 2010. W3C Recommendation available at: http://www.w3.org/TR/2010/REC-xpath20-20101214/ .
- XPath Data Model
- XQuery 1.0 and XPath 2.0 Data Model , Anders Berglund et al. , 2010. W3C Recommendation available at: http://www.w3.org/TR/2010/REC-xpath-datamodel-20101214/ .
- 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/ .
- XSLT 1.0
- > or by an external or inline schema).slt-19991116 XSL Transformations (XSLT) Version 1.0 , James Clark, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xslt-19991116 .
- XPath and XQuery Functions and Operators 3.0
- XPath and XQuery Functions and Operators 3.0 , Michael Kay, 2013. W3C Candidate Recommendation available at: http://www.w3.org/TR/xpath-functions-30/ .
- XSLT and XQuery Serialization 3.0
- XSLT and XQuery Serialization 3.0 , Henry Zongaro, 2013. W3C Candidate Recommendation available at: http://www.w3.org/TR/xslt-xquery-serialization-30/ .
Informative References
- Algorithms
- The Art of Computer Programming: Volume 1 Fundamental Algorithms , D. E. Knuth, Addison-Wesley, Reading, MA. 1968. Third edition, 1997. ISBN:0-2018-9683-4.
- AUI97
- Auditory User Interfaces--Toward The Speaking Computer , T. V. Raman, Kluwer Academic Publishers, 1997. ISBN:0-7923-9984-6.
- CDRF 1.0
- Compound Document by Reference Framework 1.0 , Timur Mehrvarz, Lasse Pajunen, Julien Quint, and Daniel Applequist, 2007. W3C Candidate Recommendation available at: http://www.w3.org/TR/2007/CR-CDR-20070718/ .
- CSS2
- Cascading Style Sheets, level 2 (CSS2) Specification , Bert Bos, HÃ¥kon Wium Lie, Chris Lilley, Ian Jacobs, 1998. W3C Recommendation available at: http://www.w3.org/TR/1998/REC-CSS2-19980512/ .
- CSV
- Common Format and MIME Type for Comma-Separated Values (CSV) Files , Y. Shafranovich, 2005, available at http://tools.ietf.org/html/rfc4180 .
- DDJ-ArrayDoubling
- Resizable Arrays, Heaps and Hash Tables , John Boyer, Doctor Dobb's Journal, CMP Media LLC, January 1998 Issue.
- DOM2 Core
- Document Object Model (DOM) Level 2 Core Specification , Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/ .
- DOM2 Events
- Document Object Model (DOM) Level 2 Events Specification , Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/ .
- EXSLT
- EXSLT Web site . Available at http://www.exslt.org .
- JSON
- The application/json Media Type for JavaScript Object Notation (JSON) , D. Crockford, 2006, available at http://www.ietf.org/rfc/rfc4627.txt .
- ODF 1.1
- NOTREF Open Document Format for Office Applications (OpenDocument) v1.1 , Patrick Durusau, Michael Brauer, and Lars Oppermann (editors), 2007. OASIS Standard available at: http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1-html/OpenDocument-v1.1.html .
- P3P 1.0
- The Platform for Privacy Preferences 1.0 (P3P1.0) Specification , Lorrie Cranor, Marc Langheinrich, Massimo Marchiori, Martin Presler-Marshall, Joseph Reagle, 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-P3P-20020416/ .
- RELAXNG
- RELAXNG Specification , James Clark, MURATO Makoto, 2001. OASIS Committee Specification available at: http://www.relaxng.org/spec-20011203.html .
- RELAXNG Compact
- RELAXNG Compact Syntax , James Clark, 2002. OASIS Committee Specification available at: http://www.relaxng.org/compact-20021121.html .
- SVG 1.1
- SVG 1.1 , Jon Ferraiolo, FUJISAWA Jun, Dean Jackson, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-SVG11-20030114/ .
- TAG Finding 7
- TAG Finding: URIs, Addressability, and the use of HTTP GET , Ian Jacobs, 2004. Available at: http://www.w3.org/2001/tag/doc/whenToUseGet-20040321
- Unicode Script Names
- ISO 15924: Codes for the representation of names of scripts , Available at: http://unicode.org/iso15924/iso15924-codes.html .
- UAAG 1.0
- User Agent Accessibility Guidelines 1.0 , Ian Jacobs, Jon Gunderson, Eric Hansen, 2002. Working Draft available at http://www.w3.org/TR/UAAG10/ .
- Unicode Scripts
- Script Names , Mark Davis, 2001. Unicode Technical Report #24 available at http://www.unicode.org/unicode/reports/tr24/ .
- XForms 1.0
- XForms 1.0 Third Edition , John Boyer, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xforms-20071029/ .
- XLink 1.0
- XML Linking Language (XLink) Version 1.0 , Steve DeRose, Eve Maler, David Orchard, 2001. W3C Recommendation available at: http://www.w3.org/TR/2001/REC-xlink-20010627/ .
-
XPath 2.0 XML Path Language (XPath) 2.0 , Anders Berglund, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, Jérôme Siméon, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xpath20-20070123/ .XML Schema part 0 - XML Schema Part 0: Primer Second Edition , David C. Fallside and Priscilla Walmsley, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/ .
Patterns for Data Mutations
This
appendix
provides
several
usage
patterns
for
the
setvalue
,
insert
and
delete
actions
that
perform
various
kinds
of
mutations
of
instance
data
elements
and
attributes.
Prepend Element Copy
Pattern: <insert context=" parent of new element " origin=" element to copy "/>
Note:
The
context
attribute
is
used
so
that
this
pattern
will
work
whether
or
not
the
parent
element
is
empty.
Operation
:
Prepend
a
new,
empty
person
element
into
a
list
of
people
<insert context="people" origin="instance('prototypes')/person"/>
Data Before Operation
<instance> <people> <person> <name>Jane Doe</name> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <people> <person><name/ </person> <person> <name>Jane Doe</name> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Append Element Copy
Pattern:
<insert
context="
parent
of
new
element
"
nodeset="*"
ref="*"
origin="
element
to
copy
"/>
Note:
The
context
attribute
is
used
so
that
this
pattern
will
work
whether
or
not
the
parent
element
is
empty.
Operation
:
Append
a
new,
empty
person
element
into
a
list
of
people
<insert context="people" ref="person" origin="instance('prototypes')/person"/>
Data Before Operation
<instance> <people> <person> <name>Jane Doe</name> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <people> <person> <name>Jane Doe</name> </person> <person> <name/> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Duplicate Element
Pattern:
<insert
nodeset="
ref="
exact
element
to
duplicate
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
an
exact
element
to
duplicate,
so
is
used.
If
the
element
does
not
exist,
the
operation
will
have
no
effect.
nodeset
ref
Operation : Duplicate the selected element and place it as a following sibling
<insert ref="paragraph[2]"/>
Data Before Operation
<instance> <document xmlns=""> <header>Lorem ipsum</header> <paragraph>Lorem ipsum verterem voluptaria ...</paragraph> <paragraph>Primis abhorreant delicatissimi ..</paragraph> <header>Lorem ipsum</header> <header>Lorem ipsum</header> </document> </instance>
Data After Operation
<instance> <document xmlns=""> <header>Lorem ipsum</header> <paragraph>Lorem ipsum verterem voluptaria ...</paragraph> <paragraph>Primis abhorreant delicatissimi ...</paragraph> <paragraph>Primis abhorreant delicatissimi ...</paragraph> <header>Lorem ipsum</header> <header>Lorem ipsum</header> </document> </instance>
Set Attribute
Pattern: <insert context=" container element receiving attribute " origin=" attribute to copy "/>
Note:
The
attribute
is
not
used
because
this
pattern
cannot
indicate
an
exact
attribute
sibling
of
the
attribute
being
inserted.
This
is
true
not
only
because
attribute
order
is
not
guaranteed
but
also
because
the
attribute
being
inserted
may
already
exist,
in
which
case
the
existing
attribute
is
replaced.
The
nodeset
ref
context
attribute
is
used
when
it
is
necessary
to
indicate
the
parent
of
the
node
being
inserted.
Operation : Create or replace an attribute with a copy of a given attribute
<insert context="item[2]" origin="../item[1]/@rating"/> <insert context="item[3]" origin="../item[1]/@rating"/>
Data Before Operation
<instance> <items xmlns=""> <item key="23" rating="classified"/> <item key="42"/> <item key="68" rating="unknown"/> </items> </instance>
Data After Operation
<instance> <items xmlns=""> <item key="23" rating="classified"/> <item key="42" rating="classified"/> <item key="68" rating="classified"/> </items> </instance>
Remove Element
Pattern:
<delete
nodeset="
ref="
exact
element
to
remove
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
an
exact
element
to
remove,
so
is
used.
If
the
element
does
not
exist,
the
operation
will
have
no
effect.
nodeset
ref
Operation
:
Remove
item
element
in
case
it
exists
<delete ref="item[2]"/>
Data Before Operation
<instance> <shoppingcart xmlns=""> <item> <product>SKU-0815</product> <quantity>1</quantity> <unitcost>29.99</unitcost> <price>29.99</price> </item> <item> <product>SKU-4711</product> <quantity>3</quantity> <unitcost>7.49</unitcost> <price>22.47</price> </item> </shoppingcart> </instance>
Data After Operation
<instance> <shoppingcart xmlns=""> <item> <product>SKU-0815</product> <quantity>1</quantity> <unitcost>29.99</unitcost> <price>29.99</price> </item> </shoppingcart> </instance>
Remove Attribute
Pattern:
<delete
nodeset="
ref="
exact
attribute
to
remove
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
an
exact
attribute
to
remove,
so
is
used.
If
the
attribute
does
not
exist,
the
operation
will
have
no
effect.
nodeset
ref
Operation
:
Remove
rating
attribute
in
case
it
exists
<delete ref="item/@rating"/>
Data Before Operation
<instance> <items xmlns=""> <item key="23" rating="classified"/> </items> </instance>
Data After Operation
<instance> <items xmlns=""> <item key="23"/> </items> </instance>
Remove Nodeset
Pattern:
<delete
nodeset="
ref="
nodeset
to
remove
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
a
nodeset
to
remove,
so
is
used.
If
the
nodeset
does
not
exist,
the
operation
will
have
no
effect.
nodeset
ref
Operation
:
Remove
track
nodeset
in
case
it
exists
<delete ref="track"/>
Data Before Operation
<instance> <playlist xmlns=""> <name>Music for Airports</name> <track id="382"/> <track id="461"/> <track id="629"/> </playlist> </instance>
Data After Operation
<instance> <playlist xmlns=""> <name>Music for Airports</name> </playlist> </instance>
Copy Nodeset
Pattern:
<insert
context="
parent
of
new
nodeset
"
nodeset="*"
ref="*"
origin="
nodeset
to
copy
"/>
Note:
The
context
attribute
is
used
so
that
this
pattern
will
work
whether
or
not
the
parent
element
is
empty.
Operation
:
Append
a
person
nodeset
into
a
list
of
people
<insert context="people" ref="person" origin="instance('prototypes')/person"/>
Data Before Operation
<instance> <people/> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name>Jane Doe</name> </person> <person> <name>John Doe</name> </person> <person> <name>Joe Sixpack</name> </person> </prototypes> </instance>
Data After Operation
<instance> <people> <person> <name>Jane Doe</name> </person> <person> <name>John Doe</name> </person> <person> <name>Joe Sixpack</name> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name>Jane Doe</name> </person> <person> <name>John Doe</name> </person> <person> <name>Joe Sixpack</name> </person> </prototypes> </instance>
Copy Attribute List
Pattern: <insert context=" exact element receiving attribute list " origin=" attribute list to copy "/>
Operation
:
Copy
attribute
list
from
one
item
to
another
<insert context="item[2]" origin="../item[1]/@*"/>
Data Before Operation
<instance> <items xmlns=""> <item key="0" rating="classified"/> <item/> </items> </instance>
Data After Operation
<instance> <items xmlns=""> <item key="0" rating="classified"/> <item key="0" rating="classified"/> </prototypes> </instance>
Replace Element
Pattern:
<insert
nodeset="
ref="
exact
element
to
replace
"
origin="
element
to
copy
"/>
<delete
nodeset="
ref="
exact
element
to
replace
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
an
exact
element
to
replace,
so
is
used.
If
the
element
does
not
exist,
both
insert
and
delete
operation
will
have
no
effect.
nodeset
ref
Operation
:
Replace
a
person
element
by
copying
a
new
one
and
removing
the
old
one
<insert ref="person[1]" origin="instance('prototypes')/person"/> <delete ref="person[1]"/>
Data Before Operation
<instance> <people xmlns=""> <person> <name>John Doe</name> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <people xmlns=""> <person> <name/> </person> </people> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Replace Attribute
Pattern: <setvalue ref=" exact attribute to replace " value=" attribute to copy "/>
Note:
If the attribute does not exist, the operation will have no effect.
Operation : Replace an attribute with the copy of a given attribute
<setvalue ref="item[2]/@key" value="../../item[1]/@key"/>
Data Before Operation
<instance > <items xmlns=""> <item key="0"/> <item key="4711"/> </items> </instance>
Data After Operation
<instance > <items xmlns=""> <item key="0"/> <item key="0"/> </items> </instance>
Replace Instance with Insert
Pattern:
<insert
nodeset="
ref="
root
node
of
instance
to
replace
"
origin="
element
to
copy
"/>
Note:
The
context
attribute
is
not
used
because
this
pattern
assumes
the
ability
to
indicate
an
instance
root
node
to
replace,
so
is
used.
Since
an
instance
cannot
be
empty,
nodeset
ref
will
always
be
non-empty.
Insert
implements
special
handling
for
instance
root
nodes,
thus
a
delete
operation
is
not
necessary.
nodeset
ref
Operation
:
Replace
instance
root
node
with
an
empty
shoppingcart
element
<insert ref="." origin="instance('prototypes')/shoppingcart"/>
Data Before Operation
<instance> <shoppingcart xmlns=""> <item> <product>SKU-0815</product> <quantity>1</quantity> <unitcost>29.99</unitcost> <price>29.99</price> </item> <item> <product>SKU-4711</product> <quantity>3</quantity> <unitcost>7.49</unitcost> <price>22.47</price> </item> </shoppingcart> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <shoppingcart/> </prototypes> </instance>
Data After Operation
<instance> <shoppingcart xmlns=""/> </instance><instance>
<instance> <prototypes xmlns=""> <shoppingcart/> </prototypes> </instance>
Move Element
Pattern:
<insert
context="
new
parent
of
element
"
nodeset="*"
ref="*"
origin="
exact
element
to
move
"/>
<delete
nodeset="
ref="
exact
element
to
move
"/>
Note:
The
context
attribute
is
used
for
insert
so
that
this
pattern
will
work
whether
or
not
the
new
parent
element
is
empty.
For
delete
the
attribute
is
used
instead
because
this
pattern
assumes
the
ability
to
indicate
an
exact
element
to
move.
If
the
element
to
be
moved
does
not
exist,
both
insert
and
delete
operation
will
have
no
effect.
nodeset
ref
Operation : Copy an existing element to a new parent and remove the original
<insert context="playlist[2]" ref="track" origin="../playlist[1]/track[2]"/> <delete ref="playlist[1]/track[2]"/>
Data Before Operation
<instance> <library xmlns=""> <playlist> <name>Music for Airports</name> <track id="382"/> <track id="461"/> <track id="629"/> </playlist> <playlist> <name>Lullabies</name> <track id="251"/> <track id="331"/> </playlist> </library> </instance>
Data After Operation
<instance> <library xmlns=""> <playlist> <name>Music for Airports</name> <track id="382"/> <track id="629"/> </playlist> <playlist> <name>Lullabies</name> <track id="251"/> <track id="331"/> <track id="461"/> </playlist> </library> </instance>
Move Attribute
Pattern:
<insert
context="
exact
element
receiving
attribute
"
origin="
exact
attribute
to
move
"/>
<delete
nodeset="
ref="
exact
attribute
to
move
"/>
Note:
If the attribute to be moved does not exist, both insert and delete operation will have no effect.
Operation : Copy an existing attribute to a new element and remove the original
<insert context="item[2]" origin="../item[1]/@rating"/><delete nodeset="item[1]/@rating"/><delete ref="item[1]/@rating"/>
Data Before Operation
<instance> <items xmlns=""> <item key="23" rating="classified"/> <item key="42"/> </items> </instance>
Data After Operation
<instance> <items xmlns=""> <item key="23"/> <item key="42" rating="classified"/> </items> </instance>
Insert Element into Non-Contiguous, Heterogeneous Nodeset
Pattern:
<insert
nodeset="
ref="
non-contiguous,
heterogeneous
nodeset
"
origin="
element
to
copy
"
at="
insert
location
"/>
Note:
The
context
attribute
is
not
used
because
it
adheres
to
the
first
node
first-item
rule
and
therefore
would
not
allow
to
select
a
non-contiguous
nodeset.
The
attribute
is
used
instead
to
select
a
nodeset
consisting
of
nodes
with
different
names
and
different
parents.
The
parent
of
the
new
node
is
the
same
as
the
parent
of
the
insert
location
node
selected
by
the
combination
of
nodeset
ref
and
nodeset
ref
at
.
Operation : Copy an existing element into a non-contiguous, heterogeneous nodeset at a specified position
<insert ref="chapter/*" origin="instance('prototypes')/paragraph" at="7" position="before"/>
Data Before Operation
<instance> <document xmlns=""> <chapter> <header>Lorem ipsum</header> <paragraph>Lorem ipsum verterem voluptaria ...</paragraph> <diagram>Exemplum 1</diagram> <diagram>Exemplum 2</diagram> <paragraph>Primis abhorreant delicatissimi ...</paragraph> </chapter> <chapter> <header>Lorem ipsum</header> <diagram>Exemplum 3</diagram> </chapter> </document> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <chapter/> <header/> <paragraph/> <diagram/> </prototypes> </instance>
Data After Operation
<instance> <document xmlns=""> <chapter> <header>Lorem ipsum</header> <paragraph>Lorem ipsum verterem voluptaria ...</paragraph> <diagram>Exemplum 1</diagram> <diagram>Exemplum 2</diagram> <paragraph>Primis abhorreant delicatissimi ...</paragraph> </chapter> <chapter> <header>Lorem ipsum</header> <paragraph/> <diagram>Exemplum 3</diagram> </chapter> </document> </instance><instance id="prototypes">
<instance id="prototypes"> <prototypes xmlns=""> <chapter/> <paragraph/> <diagram/> </prototypes> </instance>
Recalculation Sequence Algorithm
XForms Processors are free (and encouraged) to skip or optimize any steps in this algorithm, as long as the end result is the same. The XForms recalculation algorithm considers model items and model item properties to be vertices in a directed graph. Edges between the vertices represent computational dependencies between vertices.
Following
is
the
default
handling
for
a
recalculate
action.
Action
recalculate
is
defined
in
The
recalculate
Element
.
- A master dependency directed graph is created as detailed in Details on Creating the Master Dependency Directed Graph .
- To provide consistent behavior, implementations must reduce the number of vertices to be processed by computing a pertinent dependency subgraph consisting only of vertices and edges that are reachable from nodes that require recomputation. This is detailed in Details on Creating the Pertinent Dependency Subgraph . Note that on a first recomputation (such as on form load), the pertinent dependency subgraph will be the same as the master dependency directed graph.
- A topological sort is performed on the vertices of the pertinent dependency subgraph, resulting in an order of evaluation in which each vertex is evaluated only after those vertices on which it depends and before all vertices which depend on it. The topological sort algorithm is discussed at [ Algorithms ].
-
The
recalculate
process completes.
Details on Creating the Master Dependency Directed Graph
The master dependency directed graph can be considered an array with one record for each vertex, each having the following fields:
InstanceNode : a reference to the associated instance data node
type : indicates the aspect of the instance node represented by the vertex (the text content or a model item property such asreadOnly<code>readOnly</code> orrequired)<code>required</code>)
depList : a list of vertices that refer to this vertex
in-degree : the number of vertices on which this vertex depends
visited : a flag used to ensure vertices are not added to a subgraph multiple times
index : an association between vertices in the master dependency directed graph and a subgraph
The
depList
for
each
vertex
is
assigned
based
on
the
referenced
XML
nodes
of
instance
nodes,
which
are
obtained
by
parsing
the
computed
expression
bound
to
the
node
(e.g.,
by
calculate,
relevant,
readonly,
or
required).
Any
expression
violating
any
Binding
Expression
Constraint
causes
an
exception
(
The
xforms-compute-exception
Event
),
terminating
the
recalculate
process.
Specifically,
the
depList
for
a
vertex
v
is
assigned
to
be
the
vertices
other
than
v
whose
computational
expressions
reference
v
(described
below).
Vertex
v
is
excluded
from
its
own
depList
to
allow
self-references
to
occur
without
causing
a
circular
reference
exception.
A
computational
expression
appearing
in
a
calculate
attribute
controls
the
text
content
(value)
of
one
or
more
instance
nodes.
A
vertex
exists
for
each
instance
node
to
represent
the
expression
in
the
context
of
the
node.
Likewise,
computational
expressions
for
model
item
properties
such
as
readOnly
and
required
are
applied
to
one
or
more
instance
nodes,
and
vertices
are
created
to
represent
such
expressions
in
the
context
of
each
applicable
node.
The
computational
expression
of
each
vertex
must
be
examined
to
determine
the
XML
nodes
to
which
it
refers.
Any
expression
violating
any
Binding
Expression
Constraint
causes
an
exception
(
The
xforms-compute-exception
Event
),
terminating
the
recalculate
process.
A
computation
expression
refers
to
a
vertex
v
if
a
subexpression
indicates
the
InstanceNode
for
v
and
v
represents
the
instance
node
text
content
(its
value).
In
this
version
of
XForms,
model
item
properties
such
as
readOnly
and
required
cannot
be
referenced
in
an
expression.
Details on Creating the Pertinent Dependency Subgraph
If
all
calculations
must
be
performed,
which
is
the
case
on
form
load,
then
the
pertinent
dependency
subgraph
is
simply
a
duplicate
of
the
master
dependency
directed
graph.
If
the
recalculation
algorithm
is
invoked
with
a
list
of
changed
instance
data
nodes
since
the
last
recalculation,
then
the
pertinent
dependency
subgraph
is
obtained
by
exploring
the
paths
of
edges
and
vertices
in
the
computational
dependency
directed
graph
that
are
reachable
from
each
vertex
in
the
change
list.
The
method
of
path
exploration
can
be
depth
first
search,
a
suitable
version
of
which
appears
in
the
pseudo-code
below.
whi/code>
element
into
a
list
of
track
id="382"/>
ch appears in the pseudo-code below.
This
algorithm
creates
a
pertinent
dependency
subgraph
S
from
a
list
of
changed
instance
data
nodes
L
c
.
Variables
such
as
v
and
w
represent
vertices
in
the
master
dependency
directed
graph.
The
same
variables
ending
with
S
indicate
vertices
in
the
pertinent
dependency
subgraph
S
.
// Use depth-first search to explore master digraph subtrees rooted at // each changed vertex. A 'visited' flag is used to stop exploration // at the boundaries of previously explored subtrees (because subtrees // can overlap in directed graphs). for each vertex ''r'' in ''Lc'' if ''r'' is not visited { Push the pair (NIL, ''r'') onto a stack while the stack is not empty { (''v'', ''w'') = pop dependency pair from stack if ''w'' is not visited { Set the visited flag of ''w'' to true Create a vertex ''wS'' in S to represent ''w'' Set the index of ''w'' equal to the array location of ''wS'' Set the index of ''wS'' equal to the array location of ''w'' Set the InstanceNode of ''wS'' equal to the InstanceNode of ''w'' Set the type of ''wS'' equal to the type of ''w'' For each dependency node ''x'' of ''w'' Push the pair (''w'', ''x'') onto the stack } else Obtain ''wS'' from index of ''w'' if ''v'' is not NIL { Obtain ''vS'' from index of ''v'' Add dependency node for ''wS'' to ''vS'' Increment inDegree of ''wS'' } } }// Now clear the visited flags set in the loop above for each vertex ''vS'' in S { Obtain ''v'' from index of ''vS'' Assign false to the visited flag of ''v'' }
Note
that
the
number
of
vertices
and
dependency
nodes
in
the
pertinent
dependency
subgraph
is
not
known
beforehand,
but
a
method
such
as
array
doubling
(see
[
DDJ-ArrayDoubling
])
can
be
used
to
ensure
that
building
the
subgraph
is
performed
in
time
linear
in
the
size
of
S
.
Details on Computing Individual Vertices
The following steps process vertices, resulting in a recalculated form:
- A vertex with inDegree of 0 is selected for evaluation and removed from the pertinent dependency subgraph. In the case where more than one vertex has inDegree zero, no particular ordering is specified. If the pertinent dependency subgraph contains vertices, but none have an inDegree of 0, then the calculation structure of the form has a loop, and an exception ( The xforms-compute-exception Event ) must be thrown, terminating processing.
-
If
the
vertex
corresponds
to
a
computed
item,
computed
expressions
are
evaluated
as
follows:
-
calculate
: If the value of the model item changes, the corresponding instance data is updated and the dirty flag is set. -
relevant
,readonly
,required
,constraint
: If any or all of these computed properties change, the new settings are placed into effect for associated form controls.
-
-
For
each
vertex
in
the
depList
of the removed vertex, decrement the inDegree by 1. - If no vertices remain in the pertinent dependency subgraph, then the calculation has successfully completed. Otherwise, repeat this sequence from step 1.
Example of Calculation Processing
For
example,
consider
six
vertices
a
,
b
,
v
,
w
,
x
,
and
y
.
Let
a
and
b
represent
the
text
content
of
instance
nodes
that
will
be
set
by
a
binding
from
user
input
controls.
Let
v
and
w
be
vertices
representing
the
calculated
value
and
the
validity
property
of
a
third
instance
node
c
.
These
vertices
would
result
from
a
bind
element
B
with
calculate
and
constraint
attributes
and
a
nodeset
attribute
that
indicates
c
.
Suppose
that
the
value
of
c
is
the
product
of
a
and
b
and
that
the
value
is
only
valid
if
it
does
not
exceed
100.
Likewise,
suppose
x
and
y
are
vertices
representing
the
calculated
value
and
the
validity
property
of
a
fourth
instance
node
d
.
Let
the
value
of
d
be
the
sum
of
a
and
b
,
and
let
d
be
valid
if
the
value
does
not
exceed
20.
The
figure
below
depicts
the
dependency
digraph
for
this
example.
Vertices
a
and
b
have
edges
leading
to
v
and
x
because
these
vertices
represent
the
calculate
expressions
of
c
and
d
,
which
reference
a
and
b
to
compute
their
product
and
sum,
respectively.
Similarly,
v
and
x
have
directed
edges
to
w
and
y
,
respectively,
because
w
and
y
represent
the
constraint
expressions
of
c
and
d
,
which
reference
the
values
of
c
and
d
to
compare
them
with
boundary
values.
If
a
and
b
are
initially
equal
to
10,
and
the
user
changes
a
to
11,
then
it
is
necessary
to
first
recalculate
v
(the
value
of
c
)
then
recalculate
w
(the
validity
property
of
the
value
of
c
).
Likewise,
x
(the
value
of
d
)
must
be
recalculated
before
recalculating
y
(the
validity
property
of
the
value
of
d
).
In
both
cases,
the
validity
of
the
value
does
not
change
to
false
until
after
the
new
product
and
sum
are
computed
based
on
the
change
to
a
.
However,
there
are
no
interdependencies
between
v
and
x
,
so
the
product
and
sum
could
be
computed
in
either
order.
The
pertinent
subgraph
excludes
b
and
only
vertex
a
has
in-degree
of
zero.
The
vertex
a
is
processed
first.
It
is
not
a
computed
vertex,
so
no
recalculation
occurs
on
a
,
but
its
removal
causes
v
and
x
to
have
in-degree
zero.
Vertex
v
is
processed
second.
Its
value
changes
to
121,
and
its
removal
drops
the
in-degree
of
vertex
w
to
zero.
Vertex
x
is
processed
next,
changing
value
to
21.
When
x
is
removed,
its
neighbor
y
drops
to
in-degree
zero.
The
fourth
and
fifth
iterations
of
this
process
recalculate
the
validity
of
w
and
y
,
both
of
which
change
to
false.
Privacy Considerations
Using P3P with XForms
P3P privacy policies may be associated with any forms transmitted over HTTP that have URIs associated with them. In the future, mechanisms may be specified for associating P3P policies with content transmitted over other protocols.
P3P allows for policies to be associated with an individual URI or a set of URIs. By associating a separate policy with each URI a site can declare a very precise policy that addresses exactly what data is collected with a particular HTTP request and how that data will be used. However, site management is substantially easier for many sites if they declare a single policy that covers many URIs, or even their entire Web presence.
The P3P specification specifies several methods for referencing a P3P policy reference file, which in turn associates P3P policies with URIs and cookies. XForms can be P3P enabled using any of the methods that are appropriate for the Web site in which they are embedded. Some special considerations regarding forms are addressed in the P3P Specification. [ P3P 1.0 ]
Different P3P policies may be applied to the representation of a form embedded in a containing document to that which is associated with the data submitted via that form. If the form representation is served from a different server than the form is submitted to, it is likely that separate P3P policy reference files and policies will be needed. Typically the form representation causes only clickstream data (as defined in [ P3P 1.0 ] section 5.6.4) to be transferred, while a form submission causes much more data to be transferred.
Input Modes (Non-Normative)
The
attribute
inputmode
provides
a
hint
to
the
user
agent
to
select
an
appropriate
input
mode
for
the
text
input
expected
in
an
associated
form
control.
The
input
mode
may
be
a
keyboard
configuration,
an
input
method
editor
(also
called
front
end
processor)
or
any
other
setting
affecting
input
on
the
device(s)
used.
Using
inputmode
,
the
author
can
give
hints
to
the
agent
that
make
form
input
easier
for
the
user.
Authors
should
provide
inputmode
attributes
wherever
possible,
making
sure
that
the
values
used
cover
a
wide
range
of
devices.
inputmode Attribute Value Syntax
The
value
of
the
inputmode
attribute
is
a
white
space
separated
list
of
tokens.
Tokens
are
either
sequences
of
alphabetic
letters
or
absolute
URIs.
The
later
can
be
distinguished
from
the
former
by
noting
that
absolute
URIs
contain
a
':'.
Tokens
are
case-insensitive.
All
the
tokens
consisting
of
alphabetic
letters
only
are
defined
in
this
specification,
in
List
of
Tokens
(or
a
successor
of
this
specification).
This specification does not define any URIs for use as tokens, but allows others to define such URIs for extensibility. This may become necessary for devices with input modes that cannot be covered by the tokens provided here. The URI should dereference to a human-readable description of the input mode associated with the use of the URI as a token. This description should describe the input mode indicated by this token, and whether and how this token modifies other tokens or is modified by other tokens.
User Agent Behavior
Upon
entering
an
empty
form
control
with
an
inputmode
attribute,
the
user
agent
should
select
the
input
mode
indicated
by
the
inputmode
attribute
value.
User
agents
should
not
use
the
inputmode
attribute
to
set
the
input
mode
when
entering
a
form
control
with
text
already
present.
To
set
the
appropriate
input
mode
when
entering
a
form
control
that
already
contains
text,
user
agents
should
rely
on
platform-specific
conventions.
User agents should make available all the input modes which are supported by the (operating) system/device(s) they run on/have access to, and which are installed for regular use by the user. This is typically only a small subset of the input modes that can be described with the tokens defined here.
Note:
Additional guidelines for user agent implementation are found at [ UAAG 1.0 ].
The
following
simple
algorithm
is
used
to
define
how
user
agents
match
the
values
of
an
inputmode
attribute
to
the
input
modes
they
can
provide.
This
algorithm
does
not
have
to
be
implemented
directly;
user
agents
just
have
to
behave
as
if
they
used
it.
The
algorithm
is
not
designed
to
produce
"obvious"
or
"desirable"
results
for
every
possible
combination
of
tokens,
but
to
produce
correct
behavior
for
frequent
token
combinations
and
predictable
behavior
in
all
cases.
First, each of the input modes available is represented by one or more lists of tokens. An input mode may correspond to more than one list of tokens; as an example, on a system set up for a Greek user, both "greek upperCase" and "user upperCase" would correspond to the same input mode. No two lists will be the same.
Second,
the
inputmode
attribute
is
scanned
from
front
to
back.
For
each
token
t
in
the
inputmode
attribute,
if
in
the
remaining
list
of
tokens
representing
available
input
modes
there
is
any
list
of
tokens
that
contains
t
,
then
all
lists
of
tokens
representing
available
input
modes
that
do
not
contain
t
are
removed.
If
there
is
no
remaining
list
of
tokens
that
contains
t
,
then
t
is
ignored.
Third, if one or more lists of tokens are left, and they all correspond to the same input mode, then this input mode is chosen. If no list is left (meaning that there was none at the start) or if the remaining lists correspond to more than one input mode, then no input mode is chosen.
Example:
Assume
the
list
of
lists
of
tokens
representing
the
available
input
modes
is:
{"cyrillic
upperCase",
"cyrillic
lowerCase",
"cyrillic",
"latin",
"user
upperCase",
"user
lowerCase"},
then
the
following
inputmode
values
select
the
following
input
modes:
"cyrillic
title"
selects
"cyrillic",
"cyrillic
lowerCase"
selects
"cyrillic
lowerCase",
"lowerCase
cyrillic"
selects
"cyrillic
lowerCase",
"latin
upperCase"
selects
"latin",
but
"upperCase
latin"
does
select
"cyrillic
upperCase"
or
"user
upperCase"
if
they
correspond
to
the
same
input
mode,
and
does
not
select
any
input
mode
if
"cyrillic
upperCase"
and
"user
upperCase"
do
not
correspond
to
the
same
input
mode.
List of Tokens
Tokens
defined
in
this
specification
are
separated
into
two
categories:
Script
tokens
and
modifiers
.
In
inputmode
attributes,
script
tokens
should
always
be
listed
before
modifiers.
Script Tokens
Script tokens provide a general indication of the set of characters that is covered by an input mode. In most cases, script tokens correspond directly to [ Unicode Scripts ]. However, this neither means that an input mode has to allow input for all the characters in the script, nor that an input mode is limited to only characters from that specific script. As an example, a "latin" keyboard doesn't cover all the characters in the Latin script, and includes punctuation which is not assigned to the Latin script.
The script tokens that are allowed are listed in [ Unicode Script Names ], "codes for the representations of scripts". The allowable values are those listed in the column "Property Value Alias" with the underscore character (_) removed, and excluding the two values "Common", and "Unknown". At the time of writing, these values are:
-
Arabic
-
Armenian
-
Balinese
-
Bengali
-
Bopomofo
-
Braille
-
Buginese
-
Buhid
-
CanadianAboriginal
-
Carian
-
Cherokee
-
Coptic
-
Cuneiform
-
Cypriot
-
Cyrillic
-
Deseret
-
Devanagari
-
Ethiopic
-
Georgian
-
Glagolitic
-
Gothic
-
Greek
-
Gujarati
-
Gurmukhi
-
Han
-
Hangul
-
Hanunoo
-
Hebrew
-
Hiragana
-
Kannada
-
Katakana
-
KatakanaOrHiragana
-
KayahLi
-
Kharoshthi
-
Khmer
-
Lao
-
Latin
-
Lepcha
-
Limbu
-
LinearB
-
Lycian
-
Lydian
-
Malayalam
-
Mongolian
-
Myanmar
-
NewTaiLue
-
Nko
-
Ogham
-
OlChiki
-
OldItalic
-
OldPersian
-
Oriya
-
Osmanya
-
PhagsPa
-
Phoenician
-
Rejang
-
Runic
-
Saurashtra
-
Shavian
-
Sinhala
-
Sundanese
-
SylotiNagri
-
Syriac
-
Tagalog
-
Tagbanwa
-
TaiLe
-
Tamil
-
Telugu
-
Thaana
-
Thai
-
Tibetan
-
Tifinagh
-
Ugaritic
-
Vai
-
Yi
Seven other values are allowed:
Input Mode Token | Comments |
---|---|
ipa
|
International Phonetic Alphabet |
hanja
|
Subset of 'han' used in writing Korean |
kanji
|
subset of 'han' used in writing Japanese |
math
|
mathematical symbols and related characters, representing the [ Unicode Script Names ] code "Zmth" |
simplifiedHanzi
|
representing the [ Unicode Script Names ] code "Hans" |
traditionalHanzi
|
representing the [ Unicode Script Names ] code "Hant" |
user
|
special value denoting the 'native' input of the user according to the system environment |
Modifier Tokens
Modifier tokens can be added to the scripts they apply in order to more closely specify the kind of characters expected in the form control. Traditional PC keyboards do not need most modifier tokens (indeed, users on such devices would be quite confused if the software decided to change case on its own; CAPS lock for upperCase may be an exception). However, modifier tokens can be very helpful to set input modes for small devices.
Input Mode Token | Comments |
---|---|
lowerCase
|
lowercase (for bicameral scripts) |
upperCase
|
uppercase (for bicameral scripts) |
titleCase
|
title case (for bicameral scripts): words start with an upper case letter |
startUpper
|
start input with one uppercase letter, then continue with lowercase letters |
digits
|
digits of a particular script (e.g. inputmode='thai digits') |
symbols
|
symbols, punctuation (suitable for a particular script) |
predictOn
|
text prediction switched on (e.g. for running text) |
predictOff
|
text prediction switched off (e.g. for passwords) |
halfWidth
|
half-width compatibility forms (e.g. Katakana; deprecated) |
Relationship to XML Schema pattern facets
User
agents
may
use
information
available
in
an
XML
Schema
pattern
facet
to
set
the
input
mode.
Note
that
a
pattern
facet
is
a
hard
restriction
on
the
lexical
value
of
an
instance
data
node,
and
can
specify
different
restrictions
for
different
parts
of
the
data
item.
Attribute
inputmode
is
a
soft
hint
about
the
kinds
of
characters
that
the
user
may
most
probably
start
to
input
into
the
form
control.
Attribute
inputmode
is
provided
in
addition
to
pattern
facets
for
the
following
reasons:
-
The
set
of
allowable
characters
specified
in
a
pattern
may
be
so
wide
that
it
is
not
possible
to
deduce
a
reasonable
input
mode
setting.
Nevertheless,
there
frequently
is
a
kind
of
characters
that
will
be
input
by
the
user
with
high
probability.
In
such
a
case,
inputmode
allows to set the input mode for the user's convenience. -
In
some
cases,
it
would
be
possible
to
derive
the
input
mode
setting
from
the
pattern
because
the
set
of
characters
allowed
in
the
pattern
closely
corresponds
to
a
set
of
characters
covered
by
an
inputmode
attribute value. However, such a derivation would require a lot of data and calculations on the user agent. - Small devices may leave the checking of patterns to the server, but will easily be able to switch to those input modes that they support. Being able to make data entry for the user easier is of particular importance on small devices.
Examples
This is an example of the user interface markup for a form for user input in Japanese. .
<xf:input ref="name" inputmode="kanji"> <xf:label>Family name:</xf:label> </xf:input><xf:input ref="nameKana" inputmode="katakana"> <xf:label>Family name in kana:</xf:label> </xf:input><xf:input ref="given" inputmode="kanji"> <xf:label>Given name:</xf:label> </xf:input><xf:input ref="givenKana" inputmode="katakana"> <xf:label>Given name in kana:</xf:label> </xf:input><xf:input ref="email" inputmode="latin lowerCase"> <xf:label>Email:</xf:label> </xf:input><xf:input ref="phone" inputmode="latin digits"> <xf:label>Telephone:</xf:label> </xf:input><xf:textarea ref="comments" inputmode="user predictOn"> <xf:label>Comments:</xf:label> </xf:textarea><xf:submit submission="sendit"> <xf:label>Send It</xf:label> </xf:submit>
Schema for XForms (Non-Normative)
The
XML
Schema
for
XForms,
which
has
a
target
namespace
http://www.w3.org/2002/xforms
,
is
located
at
http://www.w3.org/MarkUp/Forms/2007/XForms-11-Schema.xsd
.
The
RELAXNG
([
RELAXNG
],
[
RELAXNG
Compact
])
Schema
for
XForms,
which
includes
the
target
namespace
http://www.w3.org/2002/xforms
as
well
as
the
version
suitable
for
import
to
a
host
language
namespace,
is
located
at
http://www.w3.org/MarkUp/Forms/2007/XForms-11-RELAXNG.zip
.
Schema for XML Events
This XML Schema for XML Events is referenced by the XML Schema for XForms, and located at http://www.w3.org/TR/2003/REC-xml-events-20031014/#a_schema_attribs .
XForms and Styling (Non-Normative)
This informative section provides a broad outline of new and existing CSS features needed to style XForms content. A future Recommendation from the CSS Working Group will fully develop the specification of these features.
Pseudo-classes
A CSS pseudo-class is used to select elements for styling based on information that lies outside of the document tree or that cannot be expressed using the other selectors.
Name | Defined in: | Relationship to XForms |
---|---|---|
:enabled
&
:disabled
|
[CSS3] |
Selects any form control that is relevant or non-relevant (respectively). |
:required
&
:optional
|
TBD |
Selects
any
core
form
control
bound
to
a
node
with
the
model
item
property
required
evaluating
to
true
or
false
(respectively).
|
:valid
&
:invalid
|
TBD | Selects any core form control bound to a node that is currently valid or invalid (respectively), as defined by XForms. |
:read-only
&
:read-write
|
TBD |
Selects
any
core
form
control
bound
to
a
node
with
the
model
item
property
readonly
evaluating
to
true
or
false
(respectively).
|
:out-of-range
&
:in-range
|
TBD | Selects any core form control bound to a node that contains a value the form control is not or is capable of rendering, (respectively). |
:value-empty
&
:value-non-empty
|
TBD | Selects any core form control bound to a node whose content is the empty string or not the empty string (respectively). |
This list is not exhaustive; other pseudo-classes may be defined.
Pseudo-elements
Pseudo-elements are abstractions about the document tree beyond those specified by the document language. Pseudo-elements do not appear in the DOM; they are used only for purposes of styling.
Name | Defined in: | Relationship to XForms |
---|---|---|
::value
|
TBD |
Represents
the
"active"
area
of
a
form
control
excluding
the
label;
this
corresponds
in
HTML
to
input
and
other
form
control
elements.
This
pseudo-element
is
a
child
of
the
form
control
element,
and
appears
immediately
after
the
required
label
element.
|
::switch-case
|
TBD |
Represents
the
identity
of
the
selected
case
of
a
switch
. |
::repeat-item
|
TBD |
Represents
a
single
item
from
a
repeating
sequence.
Its
position
is
as
a
parent
to
all
the
elements
in
a
single
repeating
item.
Each
::repeat-item
is
associated
with
a
particular
relevant
')
found
there,
as
the
related
style
properties
will
cascade
to
the
child
elements.
|
::repeat-index
|
TBD |
Represents
the
current
item
of
a
repeating
sequence.
Its
position
is
as
a
parent
of
all
the
elements
in
the
index
repeating
item
(and
as
a
child
to
the
::repeat-item
pseudo-element),
thus
any
style
declarations
applying
to
this
pseudo-element
override
those
on
the
parent
::repeat-item
.
|
This list is not exhaustive; other pseudo-elements may be defined.
Examples
The following examples collects together styling recommendations from this document, expressing them with a CSS notation. Throughout the examples, the following namespace declaration is assumed:
@namespace xf url('http://www.w3.org/2002/xforms');
From Implementation Requirements Common to All Form Controls : "All form controls, including container form controls , should have an inline layout by default... By default, repeat items should have a block layout." Hence, if the display property is not set via CSS, it should default to the following:
xf|input:enabled, xf|secret:enabled, xf|textarea:enabled, xf|output:enabled, xf|upload:enabled, xf|range:enabled, xf|trigger:enabled, xf|submit:enabled, xf|select:enabled, xf|select1:enabled { display: inline; } xf|output:enabled { display: inline; } xf|group:enabled, xf|switch:enabled { display: inline; } xf|repeat:enabled { display: inline; } ::repeat-item:enabled { display:block; }
From The relevant Property : "Typically, non-relevant content is not presented, or it may be styled as disabled." If the display property is not set via CSS, it should default to the following:
xf|input:disabled, xf|secret:disabled, xf|textarea:disabled, xf|output:disabled, xf|upload:disabled, xf|range:disabled, xf|trigger:disabled, xf|submit:disabled, xf|select:disabled, xf|select1:disabled { display: none; }xf|output:disabled { display: none; } xf|group:disabled, xf|switch:disabled { display: none; } ::repeat-item:disabled { display: none; }
Below is an example of how a form author can override the default display:none styling of :disabled. Note that the implementation must also implement the behavior of not accepting user input in the disabled control.
xf|input.authorization:disabled { display: inline; background-color: #bbbbbb }
From Implementation Requirements Common to All Form Controls : "The readonly form control should render in a way which indicates that entering or changing the value is not allowed." Below is an example of one way to indicate this information. CSS does not have a way to provide readonly behavior, so this example merely changes the background color. An implementation could use this style by default, and an author would only need to use styling to override the default.
xf|input:enabled:readonly::value { display: inline; background-color: #888888 }
From Implementation Requirements Common to All Form Controls : "Except as noted, relevant form controls must distinguish rendering between being bound to a required node versus a non-required node. Exceptions are form controls that do not directly render the string value of the bound node (including trigger and the container form controls)." Below is an example styling form controls bound to required nodes with a soft yellow background. An implementation could use this style by default, and an author would only need to use styling to override the default.
xf|input:enabled:required, xf|secret:enabled:required, xf|textarea:enabled:required, xf|output:enabled:required, xf|upload:enabled:required, xf|range:enabled:required, xf|trigger:enabled:required, xf|submit:enabled:required, xf|select:enabled:required, xf|select1:enabled:required { background-color: #FFFFD0 }
From Implementation Requirements Common to All Form Controls : Relevant form controls must distinguish rendering between valid and "invalid states. Control of this behavior should be made available to stylesheets." Below is an example styling input controls bound to non-empty but invalid nodes with a reddish background. An implementation could use this style by default, and an author would only need to use styling to override the default.
xf|input:enabled:invalid:value-non-empty { background-color: #ff8080; }
From Implementation Requirements Common to All Form Controls : "Relevant form controls must indicate when the bound instance data contains a value or content that the form control is not capable of rendering. Control of this behavior should be made available to stylesheets". In this example, select, select1, and range controls bound nodes whose values are not presentable by the controls are styled with in red. An implementation could use this style by default, and an author would only need to use styling to override the default.
xf|select1:enabled:out-of-range, xf|select1:enabled:out-of-range, xf|range:enabled:out-of-range { color: red; }
Complete XForms Examples (Non-Normative)
This section presents complete XForms examples. These and additional examples are maintained at http://www.w3.org/MarkUp/Forms/2002/Examples .
XForms in XHTML
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:my="http://commerce.example.com/payment" xml:lang="en"> <head> <title>XForms in XHTML</title> <model xmlns="http://www.w3.org/2002/xforms" schema="payschema.xsd"> <instance> <my:payment as="credit"> <my:cc /> <my:exp /> </my:payment> </instance> <submission action="http://www.example.com/buy.rb" method="post" id="s00" /><bind nodeset="my:cc" relevant="../@as='credit'" required="true()" /> <bind nodeset="my:exp" relevant="../@as='credit'" required="true()" /><bind ref="my:cc" relevant="../@as='credit'" required="true()" /> <bind ref="my:exp" relevant="../@as='credit'" required="true()" /> </model> </head> <body> ... <group xmlns="http://www.w3.org/2002/xforms"> <select1 ref="@as"> <label>Select Payment Method</label> <item> <label>Cash</label> <value>cash</value> <message level="modeless" ev:event="xforms-select"> Please do not mail cash.</message> </item> <item> <label>Credit</label> <value>credit</value> </item> </select1><input ref="my:cc">
<input ref="my:cc"> <label>Credit Card Number</label> <alert>Please specify a valid credit card number (use spaces or hyphens between digit groups)</alert> </input><input ref="my:exp">
<input ref="my:exp"> <label>Expiration Date</label> </input><submit submission="s00">
<submit submission="s00"> <label>Buy</label> </submit> </group> ... </body> </html>
Schema
file
payschema.xsd
:
<xs:schema xmlns:my="http://commerce.example.com/payment" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://commerce.example.com/payment" elementFormDefault="qualified"><xs:element name="payment">
<xs:element name="payment"> <xs:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"><xs:choice><xs:choice> <xs:element ref="my:cc" /> <xs:element ref="my:exp" /> </xs:choice> </xs:sequence> <xs:attribute name="as" type="my:paymentAs" /> </xs:complexType> </xs:element> <xs:element name="cc" type="my:cc" /> <xs:element name="exp" type="xsd:gYearMonth" /><xs:simpleType name="cc"> <xs:restriction base="xsd:string"> <xs:minLength value="12" /> <xs:maxLength value="19" /> <xs:pattern value="[0-9]+" /> </xs:restriction>
<xs:simpleType name="cc"> <xs:restriction base="xsd:string"> <xs:minLength value="12" /> <xs:maxLength value="19" /> <xs:pattern value="[0-9]+" /> </xs:restriction> </xs:simpleType><xs:simpleType name="paymentAs">
<xs:simpleType name="paymentAs"> <xs:restriction base="xsd:string"> <xs:enumeration value="cash" /> <xs:enumeration value="credit" /> </xs:restriction> </xs:simpleType> </xs:schema>
Editing Hierarchical Bookmarks Using XForms
<html xmlns="http://www.w3.org/2002/06/xhtml2" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:my="http://commerce.example.com/payment" xmlns:ev="http://www.w3.org/2001/xml-events" xml:lang="en"> <head> <style type="text/css"> xforms|input.editField { font-weight:bold; font-size:20px; width:500px } xforms|label.sectionLabel { font-weight:bold; color:white; background-color:blue } xforms|submit { font-family: Arial; font-size: 20px; font-style: bold; color: red } </style> <title>Editing Hierarchical Bookmarks In X-Smiles </title> <model id="bookmarks" version="2.0" xmlns="http://www.w3.org/2002/xforms"> <instance resource="bookmarks.xml" /> <submission id="s01" method="post" action="http://examples.com/" /> </model> </head> <body> <group xmlns="http://www.w3.org/2002/xforms"><repeat nodeset="section" id="repeatSections"><repeat ref="section" id="repeatSections"> <input ref="@name" class="editField"> <label class="sectionLabel">Section</label> </input><repeat nodeset="bookmark" id="repeatBookmarks"><repeat ref="bookmark" id="repeatBookmarks"> <input ref="@name"> <label>Bookmark name</label> </input> <input ref="@href"> <label>URL</label> </input> </repeat> </repeat> <p> <trigger id="insertbutton"> <label>Insert bookmark</label><insert nodeset="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" position="after" ev:event="DOMActivate" /><insert ref="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" position="after" ev:event="DOMActivate" /> </trigger> <trigger id="delete"> <label>Delete bookmark</label><delete nodeset="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" ev:event="DOMActivate" /><delete ref="section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" ev:event="DOMActivate" /> </trigger> </p> <p> <trigger id="insertsectionbutton"> <label>Insert section</label><insert nodeset="section" at="index('repeatSections')" position="after" ev:event="DOMActivate" /><insert ref="section" at="index('repeatSections')" position="after" ev:event="DOMActivate" /> </trigger> <trigger id="deletesectionbutton"> <label>Delete section</label><delete nodeset="section" at="index('repeatSections')" ev:event="DOMActivate" /><delete ref="section" at="index('repeatSections')" ev:event="DOMActivate" /> </trigger> </p> <submit submission="s01"> <label>Save</label> <hint>Click to submit</hint> </submit> </group> </body> </html>
Initial
instance
file
bookmarks.xml
:
<bookmarks> <section name="main"> <bookmark href="http://www.example.com/xforms.xml" name="Main page" /> </section> <section name="demos"> <bookmark href="http://www.example.com/demo/images.fo" name="images" /> <bookmark href="http://www.example.com/demo/xf-ecma.xml" name="ecma" /> <bookmark href="http://www.example.com/demo/sip.fo" name="sip" /> </section> <section name="XForms"> <bookmark href="file:///C/source/xmlevents.xml" name="XML events" /> <bookmark href="file:///C/source/model3.xml" name="model3" /> <bookmark href="file:///C/source/repeat.fo" name="repeat" /> </section> </bookmarks>
Survey Using XForms and SVG
The following example shows one possible way of integrating XForms with [ SVG 1.1 ]. Note that the complete set of rules for integrating XForms and SVG are not fully specified at the time this specification was published. Future versions of the XForms, SVG, or other W3C specifications might define more complete rules for integrating XForms and SVG which might not be compatible with the example below.
Note
that
the
example
below
does
not
use
SVG's
switch
and
requiredExtensions
features,
which
are
commonly
used
in
conjunction
with
foreignObject
.
<svg xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:s="http://example.com/survey" width="700px" height="600px" viewBox="0 0 700 600"> <defs> <polygon id="bullet" points="-30,-30, -10,-10, -20,10" fill="#007138" /><xforms:model id="form1" schema="surveyschema.xsd"> <xforms:instance id="instance1"> <s:survey xmlns=""> <s:drink>none</s:drink> <s:espressoPrefs> <s:numberPerWeek>0</s:numberPerWeek> <s:sugar>0</s:sugar> <s:lemon>Always</s:lemon> </s:espressoPrefs> </s:survey> </xforms:instance> <xforms:submission id="submit1" method="post" action="" /> </xforms:model><model id="form1" schema="surveyschema.xsd" xmlns="http://www.w3.org/2002/xforms"> <instance id="instance1"> <survey xmlns="http://example.com/survey"> <drink>none</drink> <espressoPrefs> <numberPerWeek>0</numberPerWeek> <sugar>0</sugar> <lemon>Always</lemon> </espressoPrefs> </survey> </instance> <submission id="submit1" method="post" action="http://www.example.org/surveyhandler" /> </model> </defs> <title>Espresso survey</title> <desc>Sample SVG and XForms - espresso customer survey</desc> <g> <text x="50" y="70" font-size="40" font-family="Arial Black, sans-serif" font-weight="900">Customer Survey: Espresso</text> <g font-family="Arial, Helvetica, sans-serif" font-size="18"> <foreignObject x="80" y="150" width="250" height="40"><xforms:select1 appearance="minimal" model="form1" ref="s:drink"> <xforms:label> <g transform="translate(80, 140)"> <use xlink:href="#bullet" /> <text>Your usual coffee drink is:</text> </g> </xforms:label> <xforms:item> <xforms:label>Rich, dark espresso</xforms:label> <xforms:value>espresso</xforms:value> </xforms:item> <xforms:item> <xforms:label>Creamy cappuccino</xforms:label> <xforms:value>cappuccino</xforms:value> </xforms:item> <xforms:item> <xforms:label>Long, milky latte</xforms:label> <xforms:value>latte</xforms:value> </xforms:item> <xforms:item> <xforms:label>Don't like coffee!</xforms:label> <xforms:value>none</xforms:value> </xforms:item> </xforms:select1><group xmlns="http://www.w3.org/2002/xforms"> <select1 appearance="minimal" model="form1" ref="s:drink"> <label> <svg:g transform="translate(80, 140)"> <svg:use xlink:href="#bullet" /> <svg:text>Your usual coffee drink is:</svg:text> </svg:g> </label> <item> <label>Rich, dark espresso</label> <value>espresso</value> </item> <item> <label>Creamy cappuccino</label> <value>cappuccino</value> </item> <item> <label>Long, milky latte</label> <value>latte</value> </item> <item> <label>Don't like coffee!</label> <value>none</value> </item> </select1> </group> </foreignObject> <foreignObject x="80" y="240" width="250" height="40"><xforms:range model="form1" start="0" end="30" step="5" ref="s:espressoPrefs/s:numberPerWeek"> <xforms:label> <g transform="translate(80, 230)"> <use xlink:href="#bullet" /> <text>Shots of espresso per week:</text> </g> </xforms:label> </xforms:range><group xmlns="http://www.w3.org/2002/xforms"> <range model="form1" start="0" end="30" step="5" ref="s:espressoPrefs/s:numberPerWeek"> <label> <svg:g transform="translate(80, 230)"> <svg:use xlink:href="#bullet" /> <svg:text>Shots of espresso per week:</svg:text> </svg:g> </label> </range> </group> </foreignObject> <foreignObject x="80" y="350" width="250" height="40"><xforms:select model="form1" ref="s:espressoPrefs/s:sugar"> <xforms:label> <g transform="translate(80, 340)"> <use xlink:href="#bullet" /> <text>Sugar?</text> </g> </xforms:label> <xforms:item> <xforms:label>Yes</xforms:label> <xforms:value>X</xforms:value> </xforms:item> </xforms:select><group xmlns:xforms="http://www.w3.org/2002/xforms"> <select model="form1" ref="s:espressoPrefs/s:sugar"> <label> <svg:g transform="translate(80, 340)"> <svg:use xlink:href="#bullet" /> <svg:text>Sugar?</svg:text> </svg:g> </label> <item> <label>Yes</label> <value>X</value> </item> </select> </group> </foreignObject> <foreignObject x="80" y="420" width="250" height="90"><xforms:select1 appearance="full" model="form1" ref="s:espressoPrefs/s:lemon"> <xforms:label> <g transform="translate(80, 410)"> <use xlink:href="#bullet" /> <text>Lemon?</text> </g> </xforms:label> <xforms:item> <xforms:label>Required for the full experience</xforms:label> <xforms:value>Always</xforms:value> </xforms:item> <xforms:item> <xforms:label>Whatever</xforms:label> <xforms:value>Indifferent</xforms:value> </xforms:item> <xforms:item> <xforms:label>Keep that citrus to yourself</xforms:label> <xforms:value>Never</xforms:value> </xforms:item> </xforms:select1><group xmlns="http://www.w3.org/2002/xforms"> <select1 appearance="full" model="form1" ref="s:espressoPrefs/s:lemon"> <label> <svg:g transform="translate(80, 410)"> <svg:use xlink:href="#bullet" /> <svg:text>Lemon?</svg:text> </svg:g> </label> <item> <label>Required for the full experience</label> <value>Always</value> </item> <item> <label>Whatever</label> <value>Indifferent</value> </item> <item> <label>Keep that citrus to yourself</label> <value>Never</value> </item> </select1> </group> </foreignObject> </g> <use xlink:href="#bullet" x="101" y="64" transform="scale(7,3)" /> <foreignObject y="150" x="500" height="60" width="100"><xforms:submit model="form1"> <xforms:label>Send survey</xforms:label> </xforms:submit><submit model="form1" xmlns="http://www.w3.org/2002/xforms"> <label>Send survey</label> </submit> </foreignObject> <image xlink:href="espresso.svg" x="400" y="230" width="280" height="270" /> </g> </svg>
Acknowledgements (Non-Normative)
This document was produced with the participation of Forms Working Group participants, including:
- John M. Boyer, IBM (Editor, Chair until March 2010)
- Erik Bruchez, Orbeon
- Kurt Cagle, Invited expert
- Alain Couthures, Invited expert
- Philip Fennell, MarkLogic
- Leigh L. Klotz, Jr., Xerox Corporation (Editor until March 2012, Co-chair until March 2012)
- Ulrich Nicolas Lissé, DreamLab
- Dan McCreary, Invited expert
- Steven Pemberton, CWI (Chair)
- T.V. Raman, Google
- Sebastian Schnitzenbaumer
- Nick Van den Bleeken, Inventive Designers n.v. (Editor)
- Alessandro Vernet, Orbeon
- Charles Wiecha, IBM
Production Notes (Non-Normative)
This document was created using an instance of MediaWiki. The sources were transformed to W3C format using a modified version of Sandro Hawke's revdoc.