Document Structure

3 Document Structure

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.

3.1 The XForms Namespace

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.

3.2 XForms Core Attribute Collections

3.2.1 Common Attributes

The Common Attribute Collection applies to every element in the XForms namespace.

anyAttribute: Foreign attributes are allowed on all XForms elements.

A host language must permit an attribute of type xsd:ID on each XForms element.

3.2.2 Linking Attributes

The Linking Attributes Collection applies to XForms elements which include a link to a remote resource.

src: 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.

3.2.3 Single-Node Binding Attributes

The following attributes define a binding between a form control or an action and an instance data node defined by an XPath expression.

ref: Binding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.
model: 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.
bind: 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.

3.2.4 Node-Set Binding Attributes

The following attributes define a binding between a form control or an action and a node-set defined by the XPath expression.

nodeset: Binding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.
model: 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.
bind: 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.

3.2.5 Model Item Property Attributes

This collection contains one attribute for each model item property, with an attribute name exactly matching the name of the model item property, as defined in 6.1 Model Item Property Definitions.

3.3 The XForms Core Module

The XForms Core Module defines the major structural elements of XForms, intended for inclusion in a containing document. The elements and attributes included in this module are:

Element	Attributes	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.

3.3.1 The model Element

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:

functions: 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.
schema: 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

<model id="Person" schema="MySchema.xsd">
  <instance src="http://example.com/cgi-bin/get-instance" />
  ...
</model>

3.3.2 The instance Element

This optional element contains or references initial instance data.

Common Attributes: Common

Special Attributes:

Linking 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.

3.3.3 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:

bind: 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.
ref: 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 "/".
action: 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.
method: Required attribute specifying the protocol to be used to transmit the serialized instance data. There is no default value.
version: Optional attribute specifying the version of XML to be serialized.
indent: Optional attribute specifying whether the serializer should add extra white space nodes for readability.
mediatype: Optional attribute specifying the mediatype for XML instance serialization. Authors should ensure that the type specified is compatible with application/xml.
encoding: Optional attribute specifying an encoding for serialization.
omit-xml-declaration: Optional attribute specifying whether to omit the XML declaration on the serialized instance data.
standalone: Optional attribute specifying whether to include a standalone declaration in the serialized XML.
cdata-section-elements: Optional attribute specifying element names to be serialized with CDATAsections.
replace: Optional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed.
instance: 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.
separator: Optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.
includenamespaceprefixes: 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.

3.3.4 The bind Element

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:

nodeset: 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.

3.4 The XForms MustUnderstand Module

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.

3.5 The XForms Extension Module

There are many different ways a host language might include XForms. One approach uses only well-formed processing, disregarding validation. Another case uses strict validation, for example XHTML 1.0, in which only predefined elements are allowed. Another common approach is to allow unregulated content in a few selected places. A host language that chooses this option can use the Extension module.

Element	Attributes	Minimal Content Model
extension	Common	ANY

3.5.1 The extension Element

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	Prev	Next	Bottom