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/cr. Any future Working Drafts are expected to use a different identifier, though a final identifier will be allocated before XForms becomes a W3C Recommendation.

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 include an attribute of type xsd:ID on each XForms element.

3.2.2 Linking Attributes

The Linking Attributes Collection applies to XForms elements 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 whitespace cautions apply as discussed in [XML Schema part 2].

All linking attributes behave as an [XLink 1.0] link between the element containing the linking attributes and the remote resource indicated, with an actuate value of "onLoad" and a show value of "embed". 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.3 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 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.3 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 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), encoding (xsd:string), omit-xml-declaration (xsd:boolean), standalone (xsd:boolean), cdata-section-elements (QNameList), replace ("all"\|"instance"\|"none"\|qname-but-not-ncname), separator (';' \| '&')	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, has no predefined behavior event-based behavior.

Special Attributes:

functions: Optional space-separated list of XPath extension functions (represented by QNames) used by this XForms Model. It is an error to use an undeclared extension function.
schema: Optional link to a list of XML Schema documents that should be processed along with this instance data. The XML Schemas may be another element referenced by a URI fragment, such as "#myschema". The XForms Processor must process all Schemas listed on this attribute. Within each XForms Model, there is a limit of one Schema per namespace declaration, including inline and linked Schemas.

Issue (locating-schemas):

The Working Group requests implementation feedback on this technique of locating XML Schemas required for form processing.

Resolution:

None recorded.

This example shows a simple usage of model, with the XForms namespace defaulted:

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

The content of the instance element is arbitrary XML in any namespace. The content of this element is treated as opaque data, used to create an XPath data model consisting of various nodes. Authors must ensure that proper namespace declarations are used for content within the instance element.

Issue (instance-interaction):

As currently specified, the instance data is disconnected from the containing document, so that changes to the instance data are not automatically reflected in the containing document. We request implementation feedback on this choice, covering scenarios such as an SVG graph that is updated by values coming from a form.

We also seek feedback on self-referential cases where the instance data and the containing document are one and the same. We plan to use feedback and best practices on these issues to make any needed adjustments to XForms 1.0.

Resolution:

None recorded.

3.3.3 The submission Element

This element encodes how, where, and what to submit.

XML Representation: <submission>

This element represents declarative instructions on what to submit, and how.

Common Attributes: Common

Special Attributes:

ref: Optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission.
action: Required destination URI for submitting instance data.
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 whitespace nodes for readability.
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.
separator: Optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.

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
media-type

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.4.1 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.3 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 fatal error 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