Table of Contents | Prev | Next | Bottom |
Quick Table of Contents |
---|
3 Document Structure 3.1 The XForms Namespace 3.2 XForms Core Attribute Collections 3.2.1 Common Attributes 3.2.2 Linking Attributes 3.2.3 Single-Node Binding Attributes 3.2.4 Node-Set Binding Attributes 3.2.5 Model Item Property Attributes 3.3 The XForms Core Module 3.3.1 The model Element 3.3.2 The instance Element 3.3.3 The submission Element 3.3.4 The bind Element 3.4 The XForms MustUnderstand Module 3.5 The XForms Extension Module 3.5.1 The extension Element |
XForms 1.0 is an application of XML [XML 1.0] and has been designed for use within other XML vocabularies—in particular within a future version 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 XForms namespace has the URI: http://www.w3.org/2002/xforms
.
XForms Processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace.
The Common Attribute Collection applies to every element in the XForms namespace.
Foreign attributes are allowed on all XForms elements.
A host language must permit an attribute of type xsd:ID
on each XForms element.
The Linking Attributes Collection applies to XForms elements which include a link to a remote resource.
The src
attribute assigns a URI to be automatically retrieved.
Note:
Since linking attribute URIs are defined in terms of the XML Schema datatype xsd:anyURI
, the same internationalization benefits and white space cautions apply as discussed in [XML Schema part 2].
Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.
Note:
The XForms Working Group is tracking with the HTML Working Group on a method of describing link structures.
The following attributes define a binding between a form control or an action and an instance data node defined by an XPath expression.
Binding expression interpreted as XPath. This attribute has no meaning when a bind
attribute is present.
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 7.4 Evaluation Context.
Reference to a bind
element.
One of ref
or bind
is required. When bind
is used, the node is determined by the referenced bind
.
It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model
IDREF
value that refers to an ID
not on a model
element, or a bind
IDREF
value that refers to an ID
not on a bind
element.
First-node rule: When a Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set, based on document order, is used.
The following attributes define a binding between a form control or an action and a node-set defined by the XPath expression.
Binding expression interpreted as XPath. This attribute has no meaning when a bind
attribute is present.
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 7.4 Evaluation Context.
Reference to a bind
element.
One of nodeset
or bind
is required. When bind
is used, the node-set is determined by the referenced bind
.
It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model
IDREF value that refers to an id not on a model
element, or a bind
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 6.1 Model Item Property Definitions.
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 | Minimal Content Model |
---|---|---|
model | Common, Events, functions (QNameList), schema (list of xsd:anyURI) | (instance|xsd:schema| submission|bind|Action)* |
instance | Common, Linking | (ANY) |
submission | Common, ref (binding-expression), bind (xsd:IDREF), action (xsd:anyURI), method ("post"|"get"|"put"|"form-data-post"|"urlencoded-post"|qname-but-not-ncname), version (xsd:NMTOKEN), indent (xsd:boolean), mediatype (xsd:string), encoding (xsd:string), omit-xml-declaration (xsd:boolean), standalone (xsd:boolean), cdata-section-elements (QNameList), replace ("all"|"instance"|"none"|qname-but-not-ncname), instance (xsd:IDREF), separator (';' | '&'), includenamespaceprefixes (xsd:NMTOKENS) | Action* |
bind | Common, Model Item Properties, nodeset (model-binding-expression) | (bind)* |
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, and must process unrecognized foreign-namespaced elements according to the 3.4 The XForms MustUnderstand Module rules.
Note that the presence of foreign namespaced elements is subject to the definition of the containing 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, Events
Attributes from XML Events are allowed on this element to facilitate creating observers. This element is not an XForms Action, and has no predefined behavior event-based behavior.
Special Attributes:
Optional space-separated list of XPath extension functions (represented by QNames) required by this XForms Model. Guidance on the use of this attribute is at 7.12 Extension Functions.
Optional list of 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.
Note:
The schema
list may include URI fragments referring to elements located elsewhere in the containing document; e.g. "#myschema"
.
This example shows a simple usage of model
, with the XForms namespace defaulted:
<model id="Person" schema="MySchema.xsd"> <instance src="http://example.com/cgi-bin/get-instance" /> ... </model>
This optional element contains or references initial instance data.
Common Attributes: Common
Special Attributes:
Optional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception (4.5.2 The xforms-link-exception Event).
If both an attribute and inline content are provided, the linked version takes precedence as described at 4.2.1 The xforms-model-construct Event.
If the initial instance data is given by a link, then the instance data is formed by creating an XPath data model of the linked resource.
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 creation of the detached copy of the inline instance data fails due to an XML error, then processing should halt with an xforms-link-exception. This could happen, for example, if the inline content had two element nodes, which would imply creating an XML document with two document elements.
Note:
In XForms 1.1, a new exception event will be issued.
Note:
All data relevant to the XPath data model must be preserved during processing and submission, 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.
This element represents declarative instructions on what to submit, and how. Details of submit processing are described at 11 Submit.
Common Attributes: Common
Special Attributes:
Optional reference to a bind
element. When present, the binding reference on this attribute is used in preference to any binding reference from the ref
attribute.
Optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission. The default value is "/".
Required destination URI for submitting instance data. Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.
Required attribute specifying the protocol to be used to transmit the serialized instance data. There is no default value.
Optional attribute specifying the version
of XML to be serialized.
Optional attribute specifying whether the serializer should add extra white space nodes for readability.
Optional attribute specifying the mediatype for XML instance serialization. Authors should ensure that the type specified is compatible with application/xml
.
Optional attribute specifying an encoding for serialization.
Optional attribute specifying whether to omit the XML declaration on the serialized instance data.
Optional attribute specifying whether to include a standalone declaration in the serialized XML.
Optional attribute specifying element names to be serialized with CDATAsections.
Optional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed.
Optional attribute specifying the instance to replace when the replace
attribute value is "instance".
When the attribute is absent, then the default is the instance that contains the submission data.
An xforms-binding-exception (4.5.1 The xforms-binding-exception Event) occurs if this attribute does not
indicate an instance in the same model as the submission.
Optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.
Optional attribute providing control over namespace serialization. If absent, all namespace nodes present in the instance data are considered for serialization. If present, specifies list of namespace prefixes to consider for serialization, in addition to those visibly utilized. As in [Exc-C14N], the special value #default
specifies the default namespace.
The following examples show how various options on element submission
can affect serialization as application/xml
. Given the following XForms fragment:
<xforms:model xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:my="http://ns.example.org/2003"> <xforms:instance> <qname xmlns="">my:sample</qname> </xforms:instance> <xforms:submission method="post" action="..."/> </xforms: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
Elements defined in the XForms Actions module, when that module is included, are also allowed in the content model of submission
.
Element bind
selects a node-set selected from the
instance data with a
model binding expression in the nodeset
attribute. Other attributes on element bind
encode
model item properties to be applied to each node in the
node-set. When bind
has an attribute of type xsd:ID
, the bind
then associates
that identifier with the selected node-set.
Common Attributes: Common, Model Item Properties
Special Attributes:
A model binding expression that selects the set of nodes on which this bind
operates, as defined in 7.5.2 Model Binding Expressions.
When additional nodes are added through action insert
, the newly added nodes are included in any node-sets matched by binding expressions—see action insert
in 9.3.5 The insert Element.
See 7.4 Evaluation Context for details on how binding affects the evaluation context.
Certain elements, such as extension
or foreign namespaced elements defined in a host language might be critical to the operation of a particular form. To indicate this, the MustUnderstand module defines a single attribute that can be used on any element.
Element | Attributes | Minimal Content Model |
---|---|---|
ANY | xforms:mustUnderstand (xsd:boolean) | n/a |
It is a terminating error that must be reported to the user if an element is marked mustUnderstand="true"
, and the XForms Processor does not have an implementation available for processing the element.
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 selected places. A host language that chooses this option can use the Extension module.
Element | Attributes | Minimal Content Model |
---|---|---|
extension | Common | ANY |
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
For example, RDF metadata could be attached to an individual form control as follows:
<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>
Table of Contents | Top |