W3C

Data Instance Module

W3C First Public Working Draft 12 October 2008

This version:
http://www.w3.org/TR/2008/WD-xforms11-20081012/
Latest version:
http://www.w3.org/TR/xforms11/

Editor:
Charlie Wiecha, IBM

This document is also available in these non-normative formats: diff-marked HTML .

The English version of this specification is the only normative version. Non-normative translations may also be available.

Copyright © 2008 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

The Data Instance Module is an XML application that represents an abstraction over data and its use for Web applications. The Data Instance Module is not a free-standing document type, but is intended to be integrated into other markup languages, such as XForms, XHTML, ODF or SVG. The underlying data of a web application form is organized into instances of data with associated attributes for loading data from remote resources.

Status of this Document

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 a Working Draft of the W3C. This document has been produced by the W3C Forms Working Group as part of the Forms Activity within the W3C Interaction Domain. The authors of this document are the W3C Forms Working Group participants.

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.

Comments on this document are welcome. Please send discussion comments to www-forms@w3.org. Please send formal comment about this document to the public editor mailing list www-forms-editor@w3.org. (archive).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. The Working Group 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.

Table of Contents

1 The Data Instance Module
    1.1 The instance Element
        1.1.1 Instance element attributes
        1.1.2 Instance element processing
    1.2 Data Instance Events overview
        1.2.1 The data-instance-load Event
        1.2.2 The data-instance-ready Event
        1.2.3 The data-link-error Event
    1.3 DOM Interface for Access to Instance Data
        1.3.1 The getInstanceDocument() Method
        1.3.2 The load() Method

1 The Data Instance Module

The Data Instance Module defines the support for data instances in web applications. The elements and attributes included in this module are:

ElementAttributesMinimal Content Model
instanceCommon, src (xsd:anyURI), resource (xsd:anyURI)(ANY)

1.1 The instance Element

The instance element contains or references XML data.

Editorial note: Support for non-XML Instance data 
It is the hope/intent of the WG to support non-XML Instance data. As such, event names and method descriptions are kept as independent of XML Instance content as possible.

1.1.1 Instance element attributes

Common Attributes: Common

Special Attributes:

src

Optional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception (???).

resource

Optional link to externally defined initial instance data. If the link is traversed and the traversal fails, it is treated as an exception (???).

1.1.2 Instance element processing

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 creation of the XPath data model for the instance data fails due to an XML error, 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.

1.2 Data Instance Events overview

The following events are defined by the Data Instance Module:

Event nameCancelable?Bubbles?Target element
data-instance-loadYesYesinstance
data-instance-readyNoYesinstance
data-link-errorNoYesinstance

1.2.1 The data-instance-load Event

Dispatched as an indication of: initiation of instance initialization including loading of any remote instance data indicated by src or resource attributes.

Target: instance element.

Bubbles: Yes

Cancelable: Yes

Context Info:

PropertyTypeValue
resource-uristringThe URI associated with the remote resource, if any (xsd:anyURI)

Default Action: The associated instance processor performs any steps required to access remote resources and construct or reinitialize the XPath data model for this instance.

1.2.2 The data-instance-ready Event

Dispatched as an indication of: completion of instance initialization including loading of any remote instance data indicated by src or resource attributes.

Target: instance element.

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
resource-uristringThe URI associated with the remote resource, if any (xsd:anyURI)

Default Action: None, notification only.

1.2.3 The data-link-error Event

Dispatched as an indication of: a failure to traverse or process the result of a link in a situation critical to form processing, such as schema or instance initialization.

Target: instance element performing the link

Bubbles: Yes

Cancelable: No

Context Info:

PropertyTypeValue
resource-uristringThe URI associated with the failed link (xsd:anyURI)

Default Action: None, notification only. Note that XForms processors including this module will interpret this as a Fatal error which halts processing.

1.3 DOM Interface for Access to Instance Data

Each instance element defines a structure called instance data that conforms to the XPath Data Model [ref-xpath-1.0]. processors that implement DOM representations of instance storage 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 data-instance-data {
			  interface DataInstanceElement : dom::Element {
				dom::Document getInstanceDocument();
				void load();
			  };
			};

1.3.1 The getInstanceDocument() Method

The document element of the associated instance is returned.

1.3.2 The load() Method

This method signals the processor to access any specified external resources and initialize the instance document, or to refresh instance data from inline markup. This method takes no parameters and raises no exceptions.