The presentation of this document has been augmented to identify changes from a
previous version. Three kinds of changes are highlighted: new,
added text, changed text, and deleted text.
Copyright © 2012 W3C ® ( MIT , ERCIM , Keio ), All Rights Reserved. W3C liability , trademark and document use rules apply.
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 new submission
capabilities, action handlers, utility 2.0 adds support
for defining 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,
consuming and to access event context
information. submitting JSON and CSV instance data,
amongst other things.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is intended to encourage discussion and should not be considered complete. Within the document there are Editorial notes. These notes reflect areas that need particular attention. Feedback on these areas is particularly appreciated.
The Forms Working Group seeks public feedback on this First Public Working Draft. Please send your comments to www-forms-editor@w3.org ( public archive ). If possible, please offer specific changes to the text that would address your concern. You may also wish to check the Wiki Version of this document and see if the relevant text has already been updated.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy . W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy .
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 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 .
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.
The specification is organized into the following chapters:
Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:
xforms: The XForms namespace, e.g.http://www.w3.org/2002/xforms
(see Namespace for XForms )
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.
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.
Editorial note: Complete list | 2011-08-31 |
Complete list of differences below |
XForms has been designed on the basis of several years' experience with HTML forms. HTML forms have formed the backbone of the e-commerce revolution, and having shown their worth, have also indicated numerous ways they could be improved.
The primary difference when comparing XForms with HTML forms, apart from XForms being in XML, is the separation of the data being collected from the markup of the controls collecting the individual values. By doing this, it not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since the underlying essential part of a Form 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 to be a part of that language, but may be integrated into any suitable markup language.
XForms has striven to improve authoring, reuse, internationalization, accessibility, usability, and device independence. Here is a summary of the primary benefits of using XForms:
In the XForms approach, forms are comprised of a section that describes what the form does, called the XForms Model , and another section that describes how the form is to be presented.
Consider a simple electronic commerce form that might be rendered as follows:
It is clear that we are collecting a value that represents whether cash or a credit card is being used, and if a credit card, its number and expiration date.
This can be represented in the XForms model
element, which in
XHTML would typically be contained within the head
section:
<model> <instance> <ecommerce xmlns=""> <method/> <number/> <expiry/> </ecommerce> </instance> <submission action="http://example.com/submit" method="post" id="submit" includenamespaceprefixes=""/> </model>
This simply says that we are collecting three 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 set of form controls suitable for general-purpose
use. The controls are bound to the XForms Model via the XForms binding
mechanism, in this simple case using the ref
attribute on the
controls. In XHTML, this markup would typically appear within the
body
section (note that we have intentionally defaulted the XForms
namespace prefix here):
<select1 ref="method"> <label>Select Payment Method:</label> <item> <label>Cash</label> <value>cash</value> </item> <item> <label>Credit</label> <value>cc</value> </item> </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>
Notice the following features of this design:
form
element, as in HTML.
(See Multiple Forms per
Document for details on how to author multiple forms per document)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.
The XForms Processor can directly submit the data collected as XML. In the example, the submitted data would look like this:
<ecommerce> <method>cc</method> <number>1235467789012345</number> <expiry>2001-08</expiry> </ecommerce>
XForms processing keeps track of the state of the partially filled form
through this instance data . Initial
values for the instance data may be provided or left empty as in the example.
Element instance
essentially holds a skeleton XML document that
gets updated as the user fills out the form. It gives the author full control
on the structure of the submitted XML data, including namespace information.
When the form is submitted, the instance data is serialized as an XML document.
Here is an alternative version of the earlier example:
<model> <instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number/> <expiry/> </payment> </instance> <submission action="http://example.com/submit" method="post" includenamespaceprefixes="#default"/> </model>
In this case the submitted data would look like this:
<payment method="cc" xmlns="http://commerce.example.com/payment"> <number>1235467789012345</number> <expiry>2001-08</expiry> </payment>
This design has features worth calling out:
number
and expiry
serve as
place-holders in the XML structure, and will be filled in with form data
provided by the user."cc"
) 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 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 :
ref
... xmlns:my="http://commerce.example.com/payment" ... <select1 ref="@method">...</select1> ... <input ref="my:number">...</input> ... <input ref="/my:payment/my:expiry">...</input>
Binding expressions are based on XPath [ XPath 1.0 ], including the use of the @
character to refer
to attributes, as seen here. Note that for illustrative purposes, the first two
expressions make use of the XPath context node, which defaults to the top-level
element (here my:payment
). The third expression shows an absolute
path.
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 data. In this example, number
should accept digits only, and should have between 14 and 18 digits and
expiry
should accept only valid month/date combinations.
Furthermore, the credit card information form controls for
number
and expiry
are only relevant if the
"cc"
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 expressed in an
XML Schema fragment, either inline or external. For example:
... xmlns:my="http://commerce.example.com/payment"... <model> ...<bind nodeset="/my:payment/my:number" relevant="/my:payment/@method = 'cc'" required="true()" type="my:ccnumber"/><bind ref="/my:payment/my:number" relevant="/my:payment/@method = 'cc'" required="true()" type="my:ccnumber"/><bind nodeset="/my:payment/my:expiry" relevant="/my:payment/@method = 'cc'" required="true()" type="xsd:gYearMonth"/><bind ref="/my:payment/my:expiry" relevant="/my:payment/@method = 'cc'" required="true()" type="xsd:gYearMonth"/> <xs:schema ...> ... <xs:simpleType name="ccnumber"> <xs:restriction base="xsd:string"> <xs:pattern value="\d{14,18}"/> </xs:restriction> </xs:simpleType> ... </xs:schema> </model>
Note:
In the above example, the relevant
expression uses absolute
XPath notation (beginning with /
) because the evaluation
context nodes for computed
expressions are determined by the binding expression (see Evaluation Context ), and so any relative node path in the first
bind
relevant
above would be relative to
/my:payment/my:number
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 an
id
attribute so that they can be referenced from elsewhere in the
containing document.
In addition, form controls should specify which model
element
contains the instance data to which they bind. This is accomplished through a
model
attribute that is part of the binding attributes. If no
model
attribute is specified on the binding element, the nearest
ancestor binding element's model
attribute is used, and failing
that, the first XForms Model in document order is used. This technique is
called 'scoped resolution', and is used frequently in XForms.
The next example adds an opinion poll to our electronic commerce form.
poll
model
<model> <instance> ...payment instance data... </instance> <submission action="http://example.com/submit" method="post"/> </model> <model id="poll"> <instance> <helpful xmlns=""/> </instance> <submission id="pollsubmit" .../> </model>
Additionally, the following markup would appear in the body section of the document:
poll
model
<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>
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 .
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.
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 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
|
|
|
function | Common ,signature[doesn't support AVT], override? | param*, var*, (sequence* | script*) |
sequence | Common ,value | EMPTY |
Common , src
|
(ANY) | |
Common , Model Item Properties , ref ( model-binding-expression ), nodeset ( model-binding-expression |
(bind)* | |
var | Common ,name (QName), value (expression) | EMPTY |
submission |
Common |
( 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.
This element represents a form definition and is used as a container for
elements that define the XForms Model. No restriction is placed on how many
model
elements may exist within a containing document.
Common Attributes: Common
Special Attributes:
xsd:anyURI
links to XML Schema
documents outside this model
element. The XForms Processor must process all
Schemas listed in this attribute. Within each XForms Model, there is a
limit of one Schema per namespace declaration, including inline and linked
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.
"1.0"
and "1.0
2.0"
. If one or more versions are indicated by this attribute on
the default model
, then an XForms Processor must support at least one of the listed
language versions of XForms. Otherwise, the XForms Processor must terminate processing after dispatching
the event xforms-version-exception to the default model
. If the
XForms Processor supports more
than one language version indicated by the version setting on the default
model
or if the version setting on the default
model
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-default model
has a version setting that is
incompatible with the language version selected by the XForms Processor , then the XForms Processor must terminate
processing after dispatching the event xforms-version-exception to the default model
.model
, with the XForms namespace
defaulted:
<model id="Person" schema="MySchema.xsd"> <instance resource="http://example.com/cgi-bin/get-instance" /> ... </model>
<model> <message level="modal" ev:event="xforms-version-exception"> <output value="event('errorinformation')"/> </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.
This author-optional element contains or references initial instance data.
Common Attributes: Common
Special Attributes:
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.
If the initial instance data is given by a link
(from src or resource ), then the instance data is formed by creating an
XPath data model of the linked resource. If the link cannot be traversed,
then processing halts after dispatching an xforms-link-exception with a
resource-uri of the link that failed. If the initial instance data is given
by inline content, then instance data is obtained 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 instance
to a single child element.
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. Otherwise the instance data is
formed by creating an XPath data model of the linked resource as described
below under Creating instance 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.
Note:
XForms authors who need additional control over the serialization of
namespace nodes can use the includenamespaceprefixes
attribute
on the submission
element.
<instance resource="http://example.org/templates/a1.xml" />
<instance> <data xmlns=""> <height>1024</height><width>1920</width> </data> </instance>
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
.
When an XForms processor receives a JSON object @@[ref JSON], it maps it as follows:
<json/>
is created
whose content is the transformation of each of the contained members, if
any, of the JSON object.
name
is
added to the element, with the value of the original name of the member.
If the value part is an array, then each value in the array is so
treated, and the first such element is given an attribute
starts="array"
.If the value of the member is not a string, array or object,
an attribute type
is added to the element, with one of the values
"number", "boolean" or "null".
This format can be serialized by the
submission
element with a serialization
attribute value
of "application/json".
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 node. Other attributes on element nodeset refbind
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-exception ) occurs if
the identified model is not the containing model
element.
Special Attributes:
bind
operates. If the
attribute is omitted, the default is the in-scope evaluation context
ref
.It has no meaning if
attribute ref
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 is a local variable-binding element and enables
the declaration of a 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:
The value 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).
Variables can occur either as a child of an action element or somewhere in the document except the model. The value of the variable will be updated when needed. If the variable is a child of an action it means that the value of the variable will be up to date when the action runs, i.e. the value will behave as if it was updated during the execution of the action, in document order relative to other variables and actions. All other variables will behave as if they were updated on xforms-refresh in the order as how they were defined.
Variables in actions are only evaluated once during the execution of an action and will hold a references to all the nodes the expression returns (if any). For example deleting those nodes from an instance with a subsequent delete action will not remove those nodes from the value of the variable. Changes in the predicates of the expression by subsequent actions won't update the value of variable either.
Currently we don't support variables inside the model outside actions, we are waiting for more implementation experience before allowing this.
For any variable-binding element, there is a region (more specifically, a set of element nodes) of the form within which the binding is visible. The set of variable bindings in scope for an expression consists of those bindings that are visible at the point in the form where the expression occurs.
A local variable binding element is visible for all following siblings and their descendants. The binding is not visible for the xf:var element itself.
It is an error to create multiple variable-binding with the same name if they are visible to each other and an ( The xforms-binding-exception Event ) will be dispatched.
Details about the submission
element and its processing are
described in The XForms
Submission Module .
The Common Attribute Collection applies to every element in the XForms namespace.
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
attribute [doesn't support AVT] 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.
ID
of an XForms Model to be
associated with this binding element. This attribute has no meaning for
the current binding element when a bind
attribute is present.
Rules for determining the context XForms Model are located at
Evaluation
Context .
bind
attribute is present.
If the model
attribute is present, then it is processed first as described
in Evaluation Context . The It is an exception ( The
xforms-binding-exception Event attributes
on ) if the actual
event handler elements. XForms Processor encounters a model
attribute IDREF
value that refers to
an ID
not on a model
element.
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 src
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
model
associated with the in-scope evaluation context node of
the element that bears the Linking Attributes Collection for the failed
link.
Note:
Section The instance
Element defines attribute src
for the
instance
element.
The following These attributes can be used to
define create a binding between an XForms
element such as a form control or an action and
items returned by 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 node defined by an expression. nodes,
but they can bind to any type of item.
bind
attribute is present.
bind
or ref
attribute is present. bind
In this specification, when an XForms element is declared to have a
Single-Node Binding, (item
or sequence) binding, then the author must specify the Single-Node Binding binding
unless the element explicitly states that it is author-optional.
In some cases, an XForms element may allow a
Single-Node Binding, but one or more attributes in the Single-Node 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 Single-Node Binding if they appear in the element. For
example, the submission element forbids the model attribute because the model
is defined to be the one containing the submission , so the attributes ref
and bind are listed for submission rather than referring to the Single-Node
Binding attribute group, but if a ref or bind attribute is used on a
submission , it does express a Single-Node Binding.
When the Single-Node Binding a binding is required, one of ref
or
bind
is required. When bind
is used, the
node item is
determined by the referenced bind
. 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 ref
is used, the node item is determined by
evaluating the expression with the evaluation context described in Section
Evaluation Context .
First-node rule : When a Single-Node Binding
In XForms 2.0, the attribute selects nodeset
is a node-set of size >
1, the first node in the node-set, based synonym
for ref
,but deprecated. Should both nodeset
and
ref
be
on document order, an
element, nodeset
is
used. ignored.
It is an exception ( The xforms-binding-exception Event ) if the XForms Processor encounters a
attribute model attribute IDREF value that refers to an ID
not on a model element, or a bindIDREF
value that refers to an ID
not on a bind
element.
The following attributes define When a binding between an XForms
element such as a form control or an action and a node-set is defined by the expression. nodeset
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. Specifies the ID of
an XForms Model to be associated with this binding element. This attribute
has no meaning for the current binding element when a bind attribute is present. Rules for determining the context
XForms Model are located at Evaluation Context . bind Author-optional reference
to a bind element. Single Item
Binding In this specification, when an XForms
element is declared to have a Node-Set Binding, then the
author must specify the Node-Set Binding unless the
element explicitly states that it First-item
rule 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 applied:
When a bind element, it does express
binding selects a Node-Set
Binding. When the Node-Set Binding is required, one sequence of nodeset or bind is
required. When bind is used, the node-set is determined by size > 1, the referenced bind . 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 nodeset is used, first item in the
node-set sequence is
determined by evaluating the expression with the
evaluation context described in Section Evaluation Context .
used.
It is an exception ( The xforms-binding-exception
Event ) if the XForms Processor encounters a model attribute IDREF value that
refers to an ID not on a model element, or a bind attribute IDREF value that
refers to an ID not on a bind element.
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 .
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 |
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>
XForms uses an expression language expressions to address instance data nodes in binding expressions, to express constraints, and to
specify calculations. The expressions will have access to
variables (see Variable Scope for more information
about which variables will be in scope for the expression) and the focus (see
next section for more information about the focus).
The expression language
is 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 [ defined in XForms 2.0: XPath
2.0 expression module
] ), other expression language
modules could be defined in the future by W3C or [
XPath 1.0 ]. other standardization bodies.
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 ) is raised, except for binding expressions, which produce a
different exception ( The xforms-binding-exception Event
).
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.
The focus consists of the context item , position and size and 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 expression requires 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, position and size of the in-scope evaluation context:
model
, then the context item for the outermost binding element is
the top-level document element node of the default instance of the containing
model
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.model
attribute that
refers to a model
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 referenced
model
, and the context position and size are changed to 1.
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. If the first item is a node the context
node is that node. If it is not a node, there will be no context node: that
is, any attempt to reference the context node will result in a fatal
exception ( xforms-bind-exception or
xforms-compute-exception ). 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.
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.
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 A function can introduces
additional dependencies, the leaf node would
additional dependencies 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 the additional dependencies as if
each occurrence of a repeat is associated with an
it 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 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 deleting nodes.
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.
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 to the repeat
or each repeat
object.
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.
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.
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"/>
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">...
In an attribute that is designated as an attribute value template (AVT), an expression can be used by surrounding the expression with curly brackets ({}). Adding attribute value template support to host language attributes is recommended, but should be defined in the host language integration specification.
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 exception ( The xforms-compute-exception Event ) must be thrown when one of the following error conditions occur:
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:
Curly brackets are not treated specially in an attribute
value in an XForms Function Library 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 AVT's 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
<xforms:load resource="/forms/detail/{instance('document-instance')/document/id}"/>
<xforms: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 C728595E0E43A8BF50D8DED9F196A582, the
resource attribute takes the value:
/forms/detail/C728595E0E43A8BF50D8DED9F196A582
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:
A function
element can only appear as a top-level element in a
model.
Editorial
note: Function |
2012-03-08 |
We are considering to to also allow the definition of custom functions outside the model but we are waiting for implementation experience. |
A custom function is defined included in the in-scope functions
of the static context for all XPath expressions associated with the model that
contains the function definition, unless
override
attribute has the value
no and there is already a function with the same name and arity in the in-scope
functions.
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 looking in the in-scope functions of the static context for a function whose name and arity matches the name and number of arguments in 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.
If the result type of the function is specified, the result evaluated by the sequence constructor 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 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"> <sequence value="sum(for $i in 1 to count($p) return $p[$i]*$q[$i])"/> </function>
<function signature="my:foo($p as xs:decimal*) as xs:decimal" override="no"> <script type="text/javascript"> foo(XForms.var.p); </script> </function>
<function signature="my:foo($p as xs:decimal*) as xs:decimal" override="no"> <sequence value="sum($p)"/> </function>
The second definition of the my:foo function won't
override the first one because the override
attribute is set to
no
(even though
the expanded QName and the arity of the functions are the same).
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.
We do not allow optional parameters.
The following are examples of some function signatures:
The function body contains an optional sequence of
variables, followed by a constructor for the return value of the function. The
constructor can either be a sequence of sequence
elements or a sequence
of script
elements.
Both the sequence
and script
elements allow specifying a
return value comprised or atomic values or nodes.
The definition of the function is skipped when the
script
element uses
a language that isn't supported by the XForms implementation. The script
implementation should be stable (calling the same function twice within an
execution scope with the same arguments returns the same
result) and should be side effect free (they should for example not change any
instance data).
Editorial note: Function scoping | 2012-03-15 |
We are considering a lighter syntax, we are thinking of also allow a value attribute on the function element and/or making the expression/script the child contents of the element. |
The implementation of the function should be stable and should not change any instance data, nor should it change the internal state of form (e.g.: should not change the repeat index) or processor.
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
occurs ([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 mask 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 sequence
element is used to
construct a function, then an sequence. The element is used inside a
function
element to
construct the result the function.
Common Attributes: Common
Special Attributes:
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 must be declared in attribute
functions
on
element model
.Such declarations are used by the XForms Processor to check against
available extension functions. XForms Processors perform this check at the time
the document is loaded, and halt processing by signaling an exception (
xforms-compute-exception Event ) if the XForms document
declares an extension function for which the processor does not have an
implementation.
Note:
Explicitly declaring extension functions enables
XForms Processors to detect the use of unimplemented extension functions at
document load-time, rather than throwing a fatal exception ( xforms-bind-exception or The
xforms-binding-exception Event xforms-compute-exception occurs. ) during user interaction.
Failure by authors to declare extension functions will result in an XForms
Processor potentially halting processing during user interaction with a fatal
error.
This chapter defines the datatypes used in defining an XForms Model .
XForms supports all XML Schema 1.0 datatypes except for xsd:ENTITY
, xsd:ENTITIES
, and xsd:NOTATION
. Concepts 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 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.
Many default XML 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. Although some XML 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):
dateTime
time
date
duration
gYearMonth
gYear
gMonthDay
gDay
gMonth
string
boolean
base64Binary
hexBinary
float
decimal
double
anyURI
QName
Built-in derived types (in the XForms namespace):
normalizedString
token
language
Name
NCName
ID
IDREF
IDREFS
NMTOKEN
NMTOKENS
integer
nonPositiveInteger
negativeInteger
long
int
short
byte
nonNegativeInteger
unsignedLong
unsignedInt
unsignedShort
unsignedByte
positiveInteger
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 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 includes a totally ordered duration datatype that can represent a
duration of days, hours, minutes, and fractional seconds. The value space for
this datatype is the set of fractional second values. This datatype is
derived from xsd:duration
.
The dayTimeDuration datatype is made available by the XForms processor based on the following lexical space definition:
<xs:simpleType name="dayTimeDuration"> <xs:restriction base="xsd:string"> <xs:pattern value="([\-]?P([0-9]+D(T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S |\.[0-9]+S)?|(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+ (\.[0-9]*)?S|\.[0-9]+S)?|(\.[0-9]*)?S)|\.[0-9]+S))? |T([0-9]+(H([0-9]+(M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)? |(\.[0-9]*)?S)|(\.[0-9]*)?S)?|M([0-9]+(\.[0-9]*)?S|\.[0-9]+S)? |(\.[0-9]*)?S)|\.[0-9]+S)))?"/> </xs:restriction> </xs:simpleType>
P13D PT47H P3DT2H -PT35.89S P4DT251M
XForms includes a totally ordered duration datatype that can represent a
duration of a whole number of months and years. The value space for this
datatype is the set of integer month values. This datatype is derived from
xsd:duration
.
The yearMonthDuration datatype is made available by the XForms processor based on the following lexical space definition:
<xs:simpleType name="yearMonthDuration"> <xs:restriction base="xsd:string"> <xs:pattern value="([\-]?P[0-9]+(Y([0-9]+M)?|M))?"/> </xs:restriction> </xs:simpleType>
P3Y P36M -P1Y1M
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 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!#-'\*\+\-/=\?\^_`\{-~ ]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*)?"/> </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.
This type defines the basic lexical properties of a datatype that
can be used to represent various ID, debit and credit card 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.
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 exception ( The xforms-binding-exception Event ) to attach Model Item Properties to atomic values or nodes that don't belong to an instance.
Model item properties can be distinguished along various axes.
Computed expressions vs. fixed properties:
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
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="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: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> <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> </data> </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"/><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.
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'.
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.
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.
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.
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 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
.
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 Schema.
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.
xsi:type
)type
constraint associated with the
instance data node using XForms binding .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 without having the ability
to change them.
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 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 |
Common |
Below is a more detailed decription of each attribute whose name and datatype information appears above.
Common Attributes: Common
Special Attributes:
What to submit:
bind
element. When
present, the binding reference on this attribute is used in preference
to any binding reference from the ref
attribute.serialization
is "none" and "true"
otherwise.serialization
is "none"
and "true" otherwise.How to submit it:
resource
element, which can dynamically
specify the URI based on instance data, or the action
attribute. This attribute should be used in place of the
action
attribute. Behavior of relative URIs in links is
determined by the host language, although [ XML Base ] processing is strongly recommended.resource
attribute, this attribute is
deprecated and optional. However, the destination URI must be specified
by this attribute or by either the resource
attribute or
the resource
element.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 event
xforms-submit
.method
or the element
method
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 ].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.
serialization
to "none" will also
have the default effect of preventing relevance pruning and
validation. However, the author is free to override this by setting
relevant
and/or validate
attributes to
"true".
Content-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 the application/xml application/xhtml+xml
for posted XML data.
The default is serialization
attribute. It is only used to provide additional information about
the submission data text/xml
application/xhtml+xml
.
What to do with the result:
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.submission
element is used to evaluate the
expression. If replace
is "instance", then the target node
is replaced by the submission result. If replace
is
"text", then the content of the target node is replaced by the
submission result. For other values of the replace
attribute, this attribute is ignored. By default, the target node is
the document element of the instance indicated by the
instance
attribute.If the data is serialized as application/x-www-form-urlencoded, the following attribute also applies:
separator='&'
.If the data is serialized as XML, the following attributes also apply:
version
of
XML to be serialized. The default is "1.0".omit-xml-declaration
attribute has the value
true
, 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.#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 |
|
name, value+ |
various | various |
Target: submission
Bubbles: Yes
Cancelable: Yes
Context Info: None
Under no circumstances can For brevity in the following, the text "the submission
succeeds" means "submission processing concludes after dispatching
xforms-submit-done
with appropriate context information", and the text "the
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 ".
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:
rebuild
flag is set for the model
containing this submission
, then the rebuild operation is
performed without dispatching an event to invoke the operation. Then,
if the deferred update recalculate
flag is set for the
model
containing this submission
, 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.submission
indicate an
empty no-data
. Otherwise, the binding attributes of
submission
indicate a node of instance data.
relevant
is true
,
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 submission no-data
.
validate
is true ,whether
, 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). validation-error
.
resource-error
.
serialization
attribute value is
"none"
, then the submission data serialization is the
empty string. Otherwise, the xforms-submit-serialize
is submission-body
property of the event is
changed from the initial value of empty string, then the content of the
submission-body
property string is used as the
submission data serialization
. Otherwise, the
submission data serialization
consists of a serialization
of the selected instance data according to the rules stated in
submission headers
are determined using the header
entries produced by the header
element(s) in the
submission and the mediatype
attribute or its
default.submission
headers
, submission
method , submission
resource , and submission 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 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 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.
instance
:If the body is not of
instance ", resource-error
.Otherwise the parse-error
. target-error
. Otherwise, text
:If the body text/*
), text ", the response is encoded as text.
Then, resource-error
.Otherwise the content replacement is
performed according to target-error
. Otherwise, submission
For a success response including a body that is
both a non-XML media type (i.e. with a content type not matching any of
the specifiers in [ RFC 3023 ]) and a non-text type (i.e. with a content
type not matching text/* ), when the value of the replace attribute on
element submission is " text ", nothing in the document is replaced and
submission error responses, 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, when
depends on the value of the
replace
attribute on element submission
: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-done with appropriate context information.
Behaviors of other possible values for attribute replace are not defined
in this specification.
all
",
: either the document is
replaced with an implementation-specific indication of an error or
submission resource-error
.
resource-error
.
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.
First, the replacement target node is determined:
submission
element has
neither an instance
attribute nor a targetref
attribute,
the replacement target node is the document element node of the
default instance of the model;
submission
element has
an instance
attribute but no targetref
attribute,
the replacement target node is the document element node of the
instance identified by the instance
attribute;
submission
element has
a targetref
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 the
submission
element, except the context node is modified to be the
document element of the instance identified by the
instance
attribute if present.
If the replacement target node is any of the following, the processing of the replacement fails:
replace="text"
replace="instance"
replace="instance"
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 Action setvalue
(
The
setvalue Element ).
instance
:the XML obtained from the submission response is used to
replace the target node. The XML in the response 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 the insert
action (
The
insert Element ) and the
delete
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 past to a postal
code search service that returns a textual result, which is placed into
the postalCode
element.
<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 ref="my:name" readonly="true()"/> <bind ref="my:address/my:street" readonly="true()"/> <submission id="S1" targetref="my:name" replace="instance" method="post" resource="..."/> <submission id="S2" targetref="my:name/my:first-name" replace="instance" method="post" resource="..."/> <submission id="S3" targetref="my:name/my:first-name" replace="text" method="post" resource="..."/> <submission id="S4" targetref="my:address/my:street" replace="text" method="post" resource="..."/> </model>
Submission S1 succeeds because a readonly node
( my:name
) can be replaced if its parent is not readonly. Submission
S2 fails because a node ( my: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 failse because the content of a
readonly node cannot be replaced, even if the node's parent is not
readonly.
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.
Dispatched as an indication 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.
Dispatched as an indication 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 ,
validation-error , parse-error ,
resource-error , target-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
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 (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:
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>
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 (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:
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 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:
ref
.If ref
is present, nodeset
has no
meaning.
header
with other entries produced by other
header
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
element does not contain a
ref
(or
deprecated nodeset
)
attribute, then one header entry is created for each value
element. If the header
element contains a ref
(or deprecated
nodeset
) attribute, then for
each selected node, item, one header entry is created for each
value
element. The name and value of the header entry are
obtained from the required child elements name
( The name Element ) and
value
( The value
Element ). If the name obtained from the name
element is
the empty string, then the header entry is omitted.
The header entry order is determined as follows:
header
elementsref
(or
deprecated nodeset
)
attribute
value
elementsThe 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>
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-exception ) occurs if the identified model is not the containing
model
element.
Special Attributes:
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.
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-exception ) occurs if the identified model is not the containing
model
element.
Special Attributes:
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
.
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.
header
elementsFor 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.
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:
?
(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 attribute
separator
is appended.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.
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.
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.
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 ).
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:
submission
element.
includenamespaceprefixes
on element
submission
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 the includenamespaceprefixes
attribute. The special value #default
represents
the default namespace.application/xml
, but can be changed
to a compatible type using element submission
attribute mediatype
. Authors should ensure that
the type specified is compatible with
application/xml
.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:
type
parameter of the mediatype
of the serialized XML instance.start
parameter referring to
the Content-ID first body part (root).Content-Type
parameter of the type
specified by the submission
mediatype
attribute.xsd:anyURI
populated by upload
with:
Content-Type
header that represents the
type of the attachment if known, otherwise
application/octet-stream
.Content-Transfer-Encoding
header.Content-ID
header whose value matches
the URI in the associated instance data node.Content-Transfer-Encoding
heading.<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.com Content-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>" Content-Length: xxx --f93dcbA3 Content-Type: application/xml; charset=UTF-8 Content-ID: <980119.X53GGT@example.com> <?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... --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X17AXM@example.com> ...Binary data here... --f93dcbA3--
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:
relevant
setting of the submission
is true
.Content-Disposition: form-data
MIME parts as defined
in [ RFC 2388 ], with the
name
parameter being the element local name.upload
also have a Content-Disposition
filename
parameter, if the filename is available.upload
are serialized as the specified binary content. In the case of
xsd:anyURI
and derived types, the serialization
content is obtained from the URI. For xsd:base64Binary
, xsd:hexBinary
, and derived types, the serialization
content is obtained by decoding the element string value.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).Content-Type
must be text/plain
except for xsd:anyURI
, xsd:base64Binary
, xsd:hexBinary
, and derived types, in which case the
header represents the media type of the attachment if known,
otherwise application/octet-stream
. If a character
set is applicable, the Content-Type
may have a
charset
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 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--
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:
relevant
setting of the submission
is true
. 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.EltName=value
, where =
is a literal
character, EltName
represents the element local name,
and value
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 the separator
attribute on
submission
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.
EltName
and value
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
, where HH
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
).Example:
GivenName=Ren%C3%A9
This format consists of simple name-value pairs.
<PersonName title="Mr"> <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.
This section describes the integration of XForms submission with [ SOAP 1.1 ] and [ SOAP 1.2 ]
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).
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.
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:
application/soap+xml
mediatype
contains a
charset
MIME parameter, then it is appended to the
application/soap+xml
MIME type. Otherwise, a
charset
MIME parameter with same value as the
encoding
attribute (or its default) is appended to the
application/soap+xml
MIME type.mediatype
are
copied to the application/soap+xml
MIME typeq
MIME parameter must not be specified in the application/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:
Content-type
HTTP header is changed to
text/xml
charset
MIME parameter is appended . The charset
parameter value from the mediatype
attribute is used if
it is specified. Otherwise, the value of the encoding
attribute (or its default) is used.action
MIME parameter appears in the
mediatype
then a SOAPAction HTTP header is added and
given a value equal to the content of the action
MIME
parameterNote:
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"> <data xmlns=""> <city>Victoria</city> <country>Canada</country> <weather>Mostly sunny and cool. High 12C. Low 3C.</weather> </data> </instance> <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="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"> <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: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:port name="GetWeatherSoap" binding="tns:GetWeatherSoap"> <soap:address location="http://www.webservice.net/getweather.asmx" /> </wsdl:port> ... </wsdl:service> </wsdl:definitions>
The XForms 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.
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.
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). 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 |
---|---|---|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
Single
|
||
Common ,
UI Common , Single |
label, filename ?,
mediatype |
|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )*, ( List UI Common )+, ( UI Common )* |
|
Common ,
UI Common , Single |
label, ( UI Common )*, ( List UI Common )+, ( UI 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 ,
Single
|
(PCDATA|( UI Content ))* |
|
Common ,
Single
|
(PCDATA|( UI Content ))* |
|
Common ,
Single
|
(PCDATA|( UI Content ))* |
|
Common ,
Single
|
(PCDATA|( UI Content ))* |
|
EMPTY | ||
EMPTY | ||
Common ,
Single
|
EMPTY | |
label?, ( List UI Common )+ |
||
item (for selection controls) |
label, value, ( UI Common )* |
|
Common ,
Single
|
PCDATA |
See also: The itemset Element (for selection controls) and The copy Element (for selection controls).
The following attributes are common to many user-interface related
XForms elements, here called the UI Common
attribute
group.
Element | Attributes and Their Content (after AVT evaluation) |
---|---|
(various) |
appearance ("full"|"compact"|"minimal" | QNameButNotNCName ) |
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:
Additionally, this module defines the following content sets:
Content Set | Minimal Content Model |
---|---|
UI Common |
(help|hint|alert| Action )* |
List UI Common | (choices|item|itemset)+ |
Core Form Controls | (input|secret|textarea|output|upload|range|trigger|submit|select|select1)* |
UI Content | (output)* |
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.
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:
display:inline
). By default, repeat items should have a block layout (e.g. a default
styling of display:block
for host languages that support
CSS).xforms-binding-exception
must occur.
setvalue
(
The setvalue Element ).
xforms-binding-exception
occurs. Otherwise, return
the string value of the node.xforms-binding-exception
occurs.
switch
or group
(which includes a
non-relevant repeat
item), orcase
element of a switch
.
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 of
xforms-valid
or xforms-invalid
, one
of xforms-readonly
or
xforms-readwrite
, one of
xforms-required
or xforms-optional
,
and one of xforms-in-range
or
xforms-out-of-range
.
trigger
and the container form controls ). Control of this 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
Description: This form control enables free-form data entry or a user interface component appropriate to the datatype of the bound node..
Common Attributes: Common , UI Common ,
Single Node Item Binding
Special Attributes:
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"> <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).
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 Common ,
Single Node Item Binding
Special Attributes:
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:
<secret ref="/login/password"> <label>Password</label> <hint>The password you enter will not be displayed.</hint> </secret>
A graphical browser might render this form control as follows:
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 Common ,
Single Node Item Binding
Special Attributes:
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.
Example:
<textarea ref="message/body" class="messageBody"> <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:
Description: This form control renders content based in part on instance data, but it provides no means for entering or changing data.
Common Attributes: Common , Single
Node Item
Binding (author-optional)
Special Attributes:
appearance
attribute, as defined above.image/*
for image
rendition. If the mediatype element appears as a child of the
output
, then it overrides this attribute. If the
media type is not specified by this attribute or by the
mediatype
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:
xsd:base64Binary
, then the data is base-64 decoded.
xsd:hexBinary
, then the data is hex-binary decoded.
xsd:anyURI
, then the data is treated as a URI and
dereferenced.
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
xsd:base64Binary
or xsd:hexBinary
xsd:anyURI
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=""/> </instance> <bind ref="/data" type="xsd:base64Binary"/> </model>
Given the model
above, the following controls can
upload an image to instance data and display it:
<upload ref="/data" mediatype="image/*"> <label>Press me to attach a picture</label> </upload> <output ref="/data" 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 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
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:
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 Common ,
Single Node Item Binding
Special Attributes:
true
, this form control will
generate additional xforms-value-changed
events. The
default for this form control is false
.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:
xsd:base64binary
, xsd:hexBinary
, or a
type derived by restriction thereof, on activation
upload
places the binary content in the content of the
node with the indicated encoding.Implementation Requirements: For anyURI data binding:
xsd:anyURI
(or a type derived by restriction thereof),
on activation upload
places a URI in the content of the
node.upload
must
associate the binary content, mediatype, and filename with that
URI for Serialization as multipart/related and Serialization
as multipart/form-data serialization.
mediatype
, for example defaulting to only
audio file types in the file dialog when the mediatype is
"audio/*".Implementation Requirements: For all data bindings:
text/rtf
could invoke an edit
window with a proprietary word processing application)See the child elements filename
( The filename Element ) and
mediatype
( The mediatype
Element (for upload) ).
Example:
<upload ref="mail/attachment" mediatype="image/*"> <label>Select image:</label> <filename ref="@filename" /> <mediatype ref="@mediatype" /> </upload>
A graphical browser might render this form control as follows:
Implementation Requirements:
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 element
filename
.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 element
mediatype
.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" mediatype="image/*"> <label>Select an image to attach</label> <filename ref="@filename"/> <mediatype ref="@mediatype"/> </upload>
Binding attributes on author-optional element
mediatype
(deprecated in favor of
using an AVT in the mediatype attribute) 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
Description: This form control allows selection from a sequential range of values.
Common Attributes: Common , UI Common ,
Single Node Item Binding
Special Attributes:
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 (), all of the XForms datatypes defined in Section XForms Datatypes that correspond to the allowed XML 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="2001-01-01" end="2001-12-31"> <label>Ship Date</label> </range>
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 Common ,
Single Node Item Binding
(author-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 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 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</label> </trigger>
Description: This form control initiates a submission .
Common Attributes: Common , UI Common ,
Single Node Item Binding
(author-optional)
Special Attributes:
submission
. If this attribute is given but does not
identify a submission
element, then activating the
submit
does not result in the dispatch of an
xforms-submit
event. If this attribute is omitted, then
the first submission
in document order from the
model
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:
<submit submission="timecard"> <label>Submit Timecard</label> </submit>
Description: This form control allows the user to make multiple selections from a set of choices.
Common Attributes: Common , UI Common ,
Single Node Item Binding
Special Attributes:
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
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:
When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:
When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:
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="my:flavors"> <label>Flavors</label> <choices> <item> <label>Vanilla</label> <value>v</value> </item> <item> <label>Strawberry</label> <value>s</value> </item> <item> <label>Chocolate</label> <value>c</value> </item> </choices> </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" |
---|---|---|
Description: This form control allows the user to make a single selection from multiple choices.
Common Attributes: Common , UI Common ,
Single Node Item Binding
Special Attributes:
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:
When the user selects an item which was previously deselected, behavior equivalent to the following steps occurs:
When the user deselects an item which was previously selected, behavior equivalent to the following steps occurs:
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:
<select1 ref="my:flavor"> <label>Flavor</label> <item> <label>Vanilla</label> <value>v</value> </item> <item> <label>Strawberry</label> <value>s</value> </item> <item> <label>Chocolate</label> <value>c</value> </item> </select1>
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" |
---|---|---|
The child elements detailed below provide the ability to attach metadata to many form controls and other elements.
label
elementsaccept-language
headers from the client, to serve up the
user interface with messages localized to the client's locale.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 , UI Common , 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 author-optional element help
provides a convenient
way to attach help information to a form control.
Common Attributes: Common , UI Common ,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 author-optional element hint
provides a convenient
way to attach hint information to a form control.
Common Attributes: Common , UI Common , 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 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 , 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.
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
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
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:
value
, if specifiedvalue
element (when
neither the value
attribute are expressed).
Common Attributes: Common , Single
Node Item
Binding (author-optional)
Special Attributes:
item
when it is selected. If a 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
xforms-binding-exception
must occur.
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.
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 ,
UI Common , Single |
label?, (( Core Form Controls )|group|switch|repeat| UI Common )* |
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 ,
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:
group
is contained by a non-relevant
switch
or group
(which includes a
non-relevant repeat
object), orgroup
is contained by a non-selected
case
element of a switch
.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.
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 ,
UI Common , Single |
case + | |
Common , selected (xsd:boolean) |
label?, (( Core Form Controls )|group|switch|repeat| Action )* |
|
Common , Events , Action Common , case (xsd:IDREF) |
case ? |
This element contains one or more case
elements, any
one of which is rendered at a given time. When
the switch
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 ,
Single Node Item Binding
(author-optional)
Although Special
Attributes:
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-exception
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-exception
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 , noswitch
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.
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:
"false"
.
This attribute is ignored if the
switch
specifies the caseref
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 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 ,
UI Common , |
(( Core Form Controls )|group|switch|repeat| Action )* |
|
Common , Events , Action Common , repeat (xsd:IDREF), index (number Expression) |
EMPTY | |
label, (value|copy), ( UI Common )* |
||
Common ,
Single
|
EMPTY | |
|
|
N/A |
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 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 operations. This repeat index is
accessed via XForms function index (see The index() Function
).
Common Attributes: Common , UI Common ,
Node
Set Sequence Binding
Special Attributes:
indexref
is specified.
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>
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> <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> <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-exception
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-exception
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.
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.
During user interface initialization (see The
xforms-model-construct-done Event ), the following steps are
performed for repeat
:
repeat
.
repeat
.
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:
insert
action can add one or more nodes that
match the repeat submission
instance replacement may contain nodes that
match the repeat setvalue
action or a calculate
may
change a value that causes one or more 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:
delete
action can remove submission
instance replacement may replace
setvalue
action or a calculate
may
change a value that causes one or more 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.
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.
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.
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 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
.
This element allows the creation of dynamic selections within
controls select
and select1
, where the
available choices are determined at run-time. The node-set sequence that
holds the available choices is specified via the Node Set 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 node item of the Node Set
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 node
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 , Node Set Sequence
Binding
Note:
Whenever a refresh
event is dispatched the
is re-evaluated to update the list of
available choices.nodeset ref
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" nodeset="/my:flavors/my:flavor"><itemset model="flavors" ref="my:flavor"> <label ref="my:description"/> <copy ref="my:description"/> </itemset> </select>
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
Node Item
Binding (author-optional)
If the single node binding Single Item Binding attributes indicate a node in a
model other than the bound node item of the containing selection control, then an
xforms-binding-exception
must occur.. occur. When a
copy
item node is selected, the following rules apply:
item
, selected
by the binding attributes on copy
, is deep copied as a
child of the target node by using an insert
action (
The insert Element ).When a copy
item is deselected, the following rules
apply:
item
,
selected by the binding attributes on copy
, is deleted
by using a delete
action ( The delete Element ).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.
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:
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 |
xforms-binding-exception | No | Yes | any element that can contain a binding expression |
xforms-compute-exception | No | Yes | model |
xforms-version-exception | No | Yes | The default model |
xforms-link-exception | No | Yes | model |
xforms-output-error | No | Yes | output |
xforms-submit-error | No | Yes | submission |
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.
Dispatched to each XForms model by the XForms processor.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following:
instance
element, an XPath data model
instance
elements, the data model is not constructed in
this phase, but during user interface construction ( The
xforms-model-construct-done Event ).
xforms-rebuild
,
xforms-recalculate
, and xforms-revalidate
in
sequence on this model
element without dispatching events
to invoke the behaviors. The notification event markings for these
operations are discarded, and the xforms-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.
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:
relevant
model item property resolved to
false
.
If the instance
referenced on the form control did not
exist when the first form control for the same instance
was
processed:
instance
a default
instance
is created by following the rules described
below.
instanceData
element is created.name
. If the name
is not a valid QName, processing halts
with an exception ( The xforms-binding-exception Event ).instance
which was automatically created the following
processing is performed:
name
. If the
name
is not a valid QName, processing halts with an
exception ( The xforms-binding-exception Event ).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.
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.
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.
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
:
nodeset
ref
is attached to the bind, it is
evaluated to select bind
does not have a nodeset ref
attribute, then the selected bind
element (for details on the model item
properties, see Model Item
Properties ). bind
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.
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.
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.
Recalculation Sequence Algorithm describes one possible method for achieving the required recalculation behavior.
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:
xsi:type
)Note:
xsi:type
attributes on instance data elements are
processed even in the absence of external or inline schema.
Note:
The applicable XML 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.
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:
xforms-recalculate
( The xforms-recalculate
Event ), and the setvalue
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.required
,
readonly
and relevant
).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.
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.
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:
navindex
specified and
assign a positive value to it are navigated first.
navindex
value. Values need not be sequential nor
must they begin with any particular value. Form controls that have
identical navindex
values are to be navigated in
document order.group
>, <
repeat
>, and < switch
>)
establish a local navigation sequence. All form controls within a
local sequence are navigated, in increasing order of the
navindex
value, before any outside the local sequence
are navigated. Form controls that have identical
navindex
values are navigated in document order.navindex
or
supply a value of "0" are navigated next. These form controls are
navigated in document order.relevant
are assigned a relative order in the overall
sequence but do not participate as navigable controls.Dispatched in response to: set focus to a form control.
Target: Core Form Control
| group
| switch
| repeat
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
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.
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.
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.
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.
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.
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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 .
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.
Dispatched in response to: a form control receiving focus.
Target: Core Form Controls
| group
| switch
| repeat
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 form control losing focus.
Target: Core Form Controls
| group
| switch
| repeat
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: 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.
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.
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.
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.
Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.
Dispatched as an indication of: an illegal binding expression, or a
model
attribute that fails to point to the ID of a
model
element, or a bind
attribute that fails
to point to the ID of a bind
element, or a
submission
attribute that fails to point to the ID of a
submission
element, or an instance
attribute on
the submission
element that fails to point to an
instance
element in the same model
element as
the submission
.
Target: any element that can contain a binding expression
Bubbles: Yes
Cancelable: No
Context Info: None
Default Action: Fatal error (halts processing).
Dispatched as an indication of: an error occurring during evaluation for a model item property (see Model Item Properties ).
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).
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
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error-information | string | An implementation-specific error string |
Default Action: Fatal error (halts processing).
Note:
This exception occurs early in processing. XForms processors are not
expected to product XForms user interface elements nor even execute
XForms action handlers (such as a message
action) in
response to this event. This exception is dispatched for the benefit of
implementation-specific processing code that may be monitoring the
behavior of an XForms processor.
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 of the element performing the link
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 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.
Dispatched as an indication of a script language that is not supported.
Target: script
element
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
language | string | The value of the script type attribute |
Default Action: Fatal error (halts processing).
Dispatched as an indication of an error during the execution of a script implementation.
Target: script
element
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error | string | The description of the error that occurred while executing the script implementation. |
Default Action: Fatal error (halts processing).
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 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].
input
, secret
, textarea
,
range
, or upload
Controlsincremental="true"
setting, the event sequence described
at Sequence: Value
Change may be initiated at implementation dependent intervals.incremental="true"
setting, no events are required to
be dispatched, and thus no order is defined.output
dispatches
xforms-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 the output
is given new data (such as a change of data in the bound data node or a
change of the bound data node).incremental="true"
setting (which is the default for
the select
or select1
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 .select
or select1
form control has the
incremental="false"
setting, the event sequence is
described at Sequence: Selection Without Value Change .item
deselected by the
change, if any)item
selected by the change,
if any)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 xforms-binding-exception
occurs if there
is a null search result for the target object indicated by attributes
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.
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.
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.
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(); }; };
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.
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.
This method signals the XForms Processor to perform a full recalculation of this XForms Model. This method takes no parameters and raises no exceptions.
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"
.
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 ,targetid (xsd:IDREF) |
EMPTY | |
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|unload|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) |
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 is not executing any other action handlers.
An inner action handler is an action that is activated when the XForms 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 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 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 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
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>
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
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:
string
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 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:
xforms-binding-exception
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.xforms-binding-exception
occurs.Note:
This action affects deferred updates by setting the deferred update flags for recalculate, revalidate and refresh.
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
attribute. The origin node-set node-sequence
is the insert
action. If this
attribute is present and resolves to a non-empty origin
node-set node-sequence
as described below in the
processing of the insert
action.
insert location node
. This attribute is ignored if the
insert location node
is a
node within the insert
. If this attribute is present, then its result is
used to override the default setting of the insert location
node
as described below in the processing of the
insert
action.
insert location node
. Valid values
are before
and after
, and the latter is the
default. This attribute is ignored if the insert location
node
within the Processing for the insert
action is as follows:
insert context
is determined. If the
context
attribute is not given, the insert
context
is the in-scope evaluation context. Otherwise, the
expression provided by the context
attribute is evaluated
using the in-scope evaluation context, and the insert context
. The insert
action is
terminated with no effect if the insert context
is the empty
bind
attribute is present, it directly determines the
ref
(or deprecated
nodeset
) attribute is present,
it is evaluated within the insert context
to determine the
insert
action is terminated with no effect if any of the
following conditions is true:
context
attribute is not given and the
context
attribute is given, the insert
context
does not evaluate to an element node and the
origin node-set node-sequence
is determined. If the
origin
attribute is not given and the origin node-set
node-sequence
is the empty
origin
attribute is not given, then the origin node-set node-sequence
consists of the last node of the
origin
attribute is given, the origin node-set node-sequence
is the result of the evaluation
of the origin
attribute in the insert context
. Namespace nodes and root nodes (parents of document elements) are
removed from the origin node-set
node-sequence
. The
insert
action is terminated with no effect if the
origin node-set node-sequence
is the empty insert location node
is determined. If the
insert location node
is the insert context
node. Otherwise, if the at
attribute is not given, then the
insert location node
is the last node of the insert location
node
is determined from the at
attribute as follows:
1
.
round()
. For example, the literal
1.5
becomes 2
, and the literal
'string'
becomes NaN
.insert location
is equal to the result.
If the result is non-positive, then the insert location
is 1
. Otherwise, the result is NaN
or
exceeds the insert location
is the insert location node
is the node in the
insert location
.
insert
action is terminated with no effect if the
insertion will create nodes whose parent is readonly. This occurs if the
insert location node
is readonly and the insert
location node
is readonly.
origin node-set
node-sequence
is cloned in the order
it appears in the origin node-set
node-sequence
.target location
of each of the cloned nodes is
determined as follows:
insert location node
provided by the context
attribute is intended to be the
parent of the cloned node. The target location
is
dependent on the types of the cloned node and the insert
location node
as follows:
insert location node
is not an element
node or root node, then it cannot be the parent of the cloned
node, so the target location
is undefined.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 the target location
is the root element of the instance.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 the target
location
is before the first child of the insert
location node
.insert location node
is an element, and
the cloned node is an attribute, then the target
location
is the attribute list of the insert
location node
.insert location node
is an element, and
the cloned node is not an attribute, then the target
location
is before the first child of the insert
location node
, or the child list of the insert
location node
if it is empty.insert location node
provided by the at
attribute is intended to be the sibling of the cloned node. If the
insert location node
is an attribute or root node, then
the target location
is undefined. If the insert
location node
is not an attribute or root node, then the
target location
is immediately before or after the
insert location node
, based on the
position
attribute setting or its default.
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 the target
location
due to a node type conflict or because the target
location
is undefined, then the insertion for that particular
cloned node is ignored. Each cloned node that is inserted is added to the
inserted-nodes
list that will be provided in the
xforms-insert
event context information. For each cloned
node used to update an existing attribute node, the existing attribute
node is added to the list of inserted-nodes
.
target location
. For example, an
attribute cannot be inserted as a sibling before or after an element.
inserted-nodes
is empty, then the
insert
action is terminated with no effect.insert
action is successfully completed by
dispatching the xforms-insert
event with appropriate context
information.
repeat
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"> <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()"/><bind ref="my:name" readonly="true()"/> <bind ref="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" ><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
.
This action deletes one or more nodes from instance data.
Common Attributes: Common
, Events , Action Common , Node Set
Sequence Binding
Special Attributes:
delete
location
. If the Processing for the delete
action is as follows:
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 the
delete context
is the empty bind
attribute is present, it directly determines the
ref
(or deprecated
nodeset
) attribute is present,
it is evaluated within the delete context
to determine the
delete
action is undefined if the instance
. The
delete
action is terminated with no effect if the
delete location
is determined. If the
at
attribute is not specified, there is no delete
location
. Otherwise, the delete location
is
determined by evaluating the expression specified by the at
attribute as follows:
1
.
round()
. For example, the literal
1.5
becomes 2
, and the literal
'string'
becomes NaN
.delete location
is equal to the result.
If the result is non-positive, then the delete location
is 1
. Otherwise, if the result is NaN
or
exceeds the delete location
is the delete location
, each node in the
delete location
, the node at the
delete location
in the delete
action is successfully completed by
dispatching the xforms-delete
event with appropriate context
information.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()"/><bind ref="my:name" readonly="true()"/> <bind ref="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" ><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
.
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:
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).
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:
xforms-deselect
event to the currently
selected case
in the switch
containing the
identified case
.selected
states (not the attribute values)
on the affected cases to reflect the new state of the
switch
containing the identified case
.xform-select
event to the
case
just selected.Common Attributes: Common , Events , Action Common
Special Attributes:
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.
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:
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>
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:
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 .
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:
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>
This action dispatches an XML Event to a specific target element. Two kinds of event can be dispatched:
bubbles
and cancelable
attributes are ignored and the standard semantics as defined in
Processing Model apply.Common Attributes: Common , Events , Action Common
Special Attributes:
true
for a
custom event. For predefined events, this attribute has no effect.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.
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:
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.
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:
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.
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:
string
conversion function as described in the expression module . If the
result does not conform lexically to
xsd: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.
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:
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>
Editorial note: Property child element | 2012-03-15 |
The property child element is still under debate, the syntax will probably change in the future. |
This action causes the default processing of
xforms-rebuild
to happen,
bypassing occur on the model associated with
the in-scope evaluation context node of the rebuild
element. 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
Note:
This action affects deferred updates .
Note:
To rebuild a model other than the one
associated with the in-scope evaluation context node, the
model
attribute from the Common group can be used since it changes the in-scope evaluation
context node.
This action causes the default processing of
xforms-recalculate
to happen,
bypassing occur on the model associated with
the in-scope evaluation context node of the recalculate
element. 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
Note:
This action affects deferred updates .
Note:
To recalculate a model other than the one
associated with the in-scope evaluation context node, the
model
attribute from the Common group can be used since it changes the in-scope evaluation
context node.
This action causes the default processing of
xforms-revalidate
to happen,
bypassing occur on the model associated with
the in-scope evaluation context node of the revalidate
element. 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
Note:
This action affects deferred updates .
Note:
To revalidate a model other than the one
associated with the in-scope evaluation context node, the
model
attribute from the Common group can be used since it changes the in-scope evaluation
context node.
This action causes the default processing of
xforms-refresh
to happen,
bypassing occur on the model associated with
the in-scope evaluation context node of the refresh
element. 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
Note:
This action affects deferred updates .
Note:
To refresh a model other than the one
associated with the in-scope evaluation context node, the
model
attribute from the Common group can be used since it changes the in-scope evaluation
context node.
This action initiates reset processing by dispatching an
xforms-reset
event to the specified model .
associated with the in-scope evaluation context
node of the reset
element. Processing of event
xforms-reset
is defined in the processing model — see
The xforms-reset Event
.
Common Attributes: Common , Events , Action Common
Note:
This action affects deferred updates .
Note:
To reset a model other than the one associated
with the in-scope evaluation context node, the model
attribute from
the Common group can be used
since it changes the in-scope evaluation context node.
This action traverses the specified link.
Common Attributes: Common , Events ,
Action Common , Single-Node Single Item
Binding (author-optional)
Special Attributes:
group
element to be loaded if show="embed"
.This
attribute is required and must indicate a group
element if
show="embed"
.
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 show
attribute. The following are the possible values
for the show
attribute and the corresponding processing
behaviors:
group
and
model
elements from the document resulting from the link
traversal are embedded in the current page, with the
group
set as content of the group
indicated by
attribute targetid
and as new model
elements.
Editorial note: load embedding events | 2012-02-09 |
Need to specify embed event sequence |
In the case of show="embed"
,all
model
elements in the traversed document are added to the current
page and are given the xforms-model-construct event sequence (TBD). The
content of the group
element indicated by attribute
targetid
is replaced with the content of the sole top-level
group
element in the traversed document; xforms-refresh is
dispatched. The loaded group
may specify a
model id
of any model in the resulting page.
Note:
Note that the load action performs no special
processing of id
attributes; therefore authors should pay careful
attention to avoid id
conflicts.
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:
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.
This action reverses the effect of the
load
action with attribute show="embed"
on the
same targetid
.
Common Attributes: Common ,Events ,Action Common
Special Attributes:
group
element to be
unloaded.
If the group
contains content
that was previously loaded by the load
element with
show="embed"
,that content and associated model content is removed. If
not, the unload
action has no effect.
Editorial note: unload event sequence | 2012-02-09 |
Need to specify event sequence |
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
element. If this attribute is given but does
not identify a submission
element, then the
send
action has no effect. If this attribute is omitted,
then the first submission
in document order from the
model
associated with the in-scope evaluation context is
used.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:
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> <data xmlns=""> <name>John</name> </data> </instance> <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
.
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>
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>
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:
This action is used to execute a script, the
script implementation may either be embedded inline or may be imported
from an external file using the src
attribute.
Common Attributes: Common
,Events ,Action Common
Special Attributes:
type
gives the language
of the script, its value must be a valid MIME type. The supported
languages depend on the XForms processor (an implementation may
choose to support no languages at all). It is an xforms-script-language-not-supported-exception
,if the action is executed and the languages is
not supported.
src
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
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-script-exception ,if the action is executed and the script implementation is not confirm the language specification or an exception occurs during the execution of the script.
Editorial note: parameters | 2012-03-08 |
We need a way to access defined variables, the current context item, position and size. Proposal make them available as name spaced variables, for javascript: XForms.var.{variable-name}, XForms.context.item, XForms.context.position, XForms.context.size |
<script type="text/javascript"> foo(); </script>
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" 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" 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" 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>
while
attributeThe 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>
iterate
attributeThe 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.
<xforms:delete nodeset="." 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.
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 .
All XForms Containing Documents must conform to the following specifications, except as qualified below:
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 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.
The following are base technologies for XForms. An XForms Processor therefore must conform to the following specifications, except as qualified below:
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.
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,
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
datatype information defined by XForms. The processor must be able to parse inline and external
declared XML schema and consume their schema datatype information [
XML Schema part 2 ], and the
processor should consume all 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
xforms-version-exception
. The processor may support action handlers for the
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 ].
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:
model
processing.refresh
, setfocus
, and
message
.group
element is encountered during user interface initialization, then the
processor must terminate
processing after dispatching xforms-binding-exception .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 .setindex
action and the XForms Repeat Module , except that support of the
repeat-*
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 .group
, switch
,
repeat
, and their descendant elements (e.g.
case
and item
).ref
(or deprecated
nodeset
) attribute of a
bind
element in an XForms model. Often, a bind
also declares computed
expressions for model item properties of the nodes. ]
xsi:type
or by an external or inline
schema).]"[1-9]\d*\.\d+"
.]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.
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> <data xmlns=""> <people> <person> <name>Jane Doe</name> </person> </people> </data> </instance> <instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <data xmlns=""> <people> <person><name/ </person> <person> <name>Jane Doe</name> </person> </people> </data> </instance> <instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
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> <data xmlns=""> <people> <person> <name>Jane Doe</name> </person> </people> </data> </instance> <instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <data xmlns=""> <people> <person> <name>Jane Doe</name> </person> <person> <name/> </person> </people> </data> </instance> <instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
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>
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 refcontext
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>
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>
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>
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>
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> <data xmlns=""> <people/> </data> </instance> <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> <data xmlns=""> <people> <person> <name>Jane Doe</name> </person> <person> <name>John Doe</name> </person> <person> <name>Joe Sixpack</name> </person> </people> </data> </instance> <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>
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>
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"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
Data After Operation
<instance> <people xmlns=""> <person> <name/> </person> </people> </instance> <instance id="prototypes"> <prototypes xmlns=""> <person> <name/> </person> </prototypes> </instance>
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>
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"> <prototypes xmlns=""> <shoppingcart/> </prototypes> </instance>
Data After Operation
<instance> <shoppingcart xmlns=""/> </instance> <instance> <prototypes xmlns=""> <shoppingcart/> </prototypes> </instance>
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>
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>
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 refat
.
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"> <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"> <prototypes xmlns=""> <chapter/> <paragraph/> <diagram/> </prototypes> </instance>
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 .
recalculate
process completes.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 as readOnly or required)
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.
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.
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
.
The following steps process vertices, resulting in a recalculated form:
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.depList
of the removed vertex,
decrement the inDegree by 1.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.
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.
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.
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.
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.
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 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 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) |
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:
inputmode
allows to set the input mode for the user's
convenience.inputmode
attribute value. However, such a derivation
would require a lot of data and calculations on the user agent.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>
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
.
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 .
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.
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 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.
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; }
This section presents complete XForms examples. These and additional examples are maintained at http://www.w3.org/MarkUp/Forms/2002/Examples .
<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"> <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"> <label>Expiration Date</label> </input> <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:complexType> <xs:sequence minOccurs="0" maxOccurs="unbounded"> <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> <xs:simpleType name="paymentAs"> <xs:restriction base="xsd:string"> <xs:enumeration value="cash" /> <xs:enumeration value="credit" /> </xs:restriction> </xs:simpleType> </xs:schema>
<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>
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:xlink="http://www.w3.org/1999/xlink" xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:ev="http://www.w3.org/2001/xml-events" 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="http://example.com/survey"> <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="http://www.example.org/surveyhandler" /> </xforms: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> </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> </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> </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> </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> </foreignObject> <image xlink:href="espresso.svg" x="400" y="230" width="280" height="270" /> </g> </svg>
This document was produced with the participation of Forms Working Group participants, including:
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.