Copyright © 2006 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document specifies the Compound Document by Reference Framework 1.0.
When combining separate markup languages, specific problems have to be resolved that are not addressed by their individual language specifications, such as the propagation of events across namespaces, the combination of rendering or the user interaction model.
Compound Document is the W3C term for a document that combines multiple formats.
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 is the 22 November 2006 Last Call Working Draft of the Compound Documents by Reference Framework 1.0, incorporating comments on the 19 December 2005 Last Call Working Draft. The disposition of Last Call comments is available. Changes are summarized in Appendix E, and a diff-marked version is also available to review changes since the last Working Draft.
The purpose of this second Last Call is to allow reviewers to verify that their comments have been included into the specification as agreed by the Compound Document Formats Working Group . It is not intended as a new, general review period. Feedback on this specification should be sent to public-cdf@w3.org. This list is archived and acceptance of this archiving policy is requested automatically upon first post. To subscribe to this list send an email to public-cdf-request@w3.org with the word subscribe in the subject line. The deadline for Last Call comments is 19 December 2006.
This document has been produced by the Compound Document Formats Working Group as part of the Rich Web Clients Activity within the W3C Interaction Domain. 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.
1 Introduction to Compound
Documents
1.1 Scope
1.2 Related
Documents
1.3 Reference and Inclusion
1.4 Referencing Child Objects
1.5 Identification and Versioning
2 Compound Document by Reference
(CDR)
2.1 Document Object
Model
2.2 Events
A Definitions
B Conformance
C References
D Acknowledgements
(Non-Normative)
E Changes Log (Non-Normative)
(This section is informative)
Combining content delivery formats can often be desirable in order to provide a seamless experience for the user.
For example, XHTML-formatted content can be augmented by SVG objects, to create a more dynamic, interactive and self adjusting presentation. A set of standard rules is required in order to provide this capability across a range of user agents and devices.
These are examples of possible Compound Document profiles:
This document defines a generic Compound Document by Reference Framework (CDRF) that defines a language-independent processing model for combining arbitrary document formats.
NOTE: The Compound Document Framework is language-independent. While it is clearly meant to serve as the basis for integrating W3C's family of XML formats within its Interaction Domain (e.g., CSS, MathML, SMIL, SVG, VoiceXML, XForms, XHTML, XSL) with each other, it can also be used to integrate non-W3C formats with W3C formats or integrate non-W3C formats with other non-W3C formats.
(This section is informative)
WICD Core is the foundation of rich multimedia content and describes rules for combining Hypertext Markup Language (XHTML) and scalable child objects, such as Scalable Vector Graphics (SVG) in a non device specific manner.
WICD Core builds upon CDRF.
(This section is informative)
A namespace uniquely identifies a set of names so that there is no ambiguity when objects having different origins but the same names are mixed together. An XML namespace is a collection of element type and attribute names. These element types and attribute names are uniquely identified by the name of the unique XML namespace of which they are a part. In an XML document, any element type or attribute name can thus have a two-part name consisting of the namespace name and the element or attribute name.
A Compound Document by inclusion combines XML markup from several namespaces into a single physical document. A number of standards exist, and continue to be developed, that are descriptions of XML markup within a single namespace. XHTML, XForms, VoiceXML, and MathML are some of the prominent examples of such standards, each having its own namespace. Each of these specifications focuses on one aspect of rich-content development. For example, XForms focuses on data collection and submission, VoiceXML on speech, and MathML on the display of mathematical notations.
To authors of content, each of these many standards is useful and important. However, it is the combination of elements of any number of these standards that lends true flexibility and power to rich document creation. A document may exist to be displayed within a web browser, to display an input form, with a scalable graphic and a bit of mathematical notation, all on the same page. XHTML, XForms, SVG, and MathML, respectively, serve these needs, and could therefore be combined into a single multi-namespace document.
Consider this simple example, a Compound Document combining XHTML and MathML. The namespace declarations are marked by an appended comment to match the numbered namespaces listed below in the XML source in Example 1.
XHTML Namespace declaration. The namespace for XHTML 1.0 is declared. Each XHTML element in the example below is qualified with the xhtml: namespace prefix.
MathML Namespace declaration. The namespace for MathML 2.0 is declared. Each MathML element in the example below is qualified with the mathml: prefix.
A Compound Document example:
<?xml version="1.0" encoding="iso-8859-1"?> <xhtml:html xmlns:xhtml="http://www.w3.org/1999/xhtml"> <!-- 1 --> <xhtml:body> <xhtml:h1>A Compound Document</xhtml:h1> <xhtml:p>A simple formula using MathML in XHTML.</xhtml:p> <mathml:math xmlns:mathml="http://www.w3.org/1998/Math/MathML"> <!-- 2 --> <mathml:mrow> <mathml:msqrt> <mathml:mn>49</mathml:mn> </mathml:msqrt> <mathml:mo>=</mathml:mo> <mathml:mn>7</mathml:mn> </mathml:mrow> </mathml:math> </xhtml:body> </xhtml:html>
Example 1: A Simple Compound Document
Figure 1 (above): Rendered Simple Compound Document - This is a rendered version of the simple Compound Document in Example 1 which combines XHTML and MathML for rich content.
Compound Documents may be composed of a single document that contains multiple namespaces, as seen in Example 1. This is a Compound Document “by Inclusion” (CDI). However, a Compound Document may also be composed over several documents in which one document of a particular namespace references another separate document of a different namespace.
For example, a root or top-most document might contain XHTML content for defining and formatting a page. This parent XHTML document can reference another document, of another namespace, through the use of the XHTML <object> tag. This can be repeated for as many documents as necessary. The root document plus this collection of separate, referenced documents is considered a Compound Document “by Reference” (CDR). See Figure 2 for a simple CDR document in which an XHTML root document contains a reference to a separate SVG child document having markup for three colored circles.
Figure 2 (above): Compound Document by Reference - A simple Compound Document by reference where a XHTML document references a separate SVG document. Below you see the two markup fragments.
XHTML:
<?xml version="1.0"?> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>circles</title> </head> <body> <object height="350" width="600" type="image/svg+xml" data="circles.svg"/> </body> </html>
SVG:
<?xml version="1.0" encoding="UTF-8"?> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" baseProfile="tiny" version="1.2"> <g fill-opacity="0.7" stroke="black" stroke-width="0.2cm"> <circle fill="red" cx="6cm" cy="2cm" transform="translate(0,50)" r="100"/> <circle fill="blue" cx="6cm" cy="2cm" transform="translate(70,150)" r="100"/> <circle fill="green" cx="6cm" cy="2cm" transform="translate(-70,150)" r="100"/> </g> </svg>
And of course, a Compound Document may be a hybrid of both compound document by inclusion and Compound Document by reference.
(This section is informative)
Each hosting language has its own methods for referencing child objects. These provide different functionality, but the following section describes (some of) the common functionality.
In Compound Document by Reference Framework 1.0, embedding media and other objects is done by using the existing elements in the host languages rather than by extending them with new markup. For example, in XHTML documents, the <object> element will be used to reference XML document types. Similarly, in SVG documents, the <foreignObject> element is used, and in SMIL, the <ref> element should be used.
It may be necessary to transfer parameters declaratively to a referenced child object. Compound Document profiles may define specific parameters/values for this purpose. Three examples:
<object type="..." data="..."> <param name="param1" value="true" /> <param name="param2" value="123" /> </object>
This SVG example uses the <foreignObject> element:
<svg xmlns="http://www.w3.org/2000/svg"> <foreignObject> <metadata> param=value; param=value </metadata> </foreignObject> </svg>
This SMIL example uses the <ref> element:
<ref src="http://www.example.com/herbert.face"> <param name="mood" value="surly" valuetype="data"/> <param name="accessories" value="baseball-cap,nose-ring" valuetype="data"/> </ref>
(This section is informative)
A distinct identification of the supported Compound Document capabilities is often not possible by advertising a list of supported content types. Such a list is not sufficient to describe the supported capabilities between compound languages. A unique profile identifier is often better suited to describe such characteristics. CDRF profiles may define their identification and versioning criteria, which should utilize the mechanisms readily available from the root language. For example, if the root language is XHTML, then the content type of "application/xhtml+xml" can be used. It can then be used with the optional parameter of "profile", with a value of a URI that both identifies the profile and its version.
Compound document profiles which leverage the Compound Document Framework and which support scripting must have scripting interfaces that are compatible with the uDOM, or implement a superset such as the DOM Level 3 Core Specification.
Compound Document profiles may subset DOM Level 3 Core, but any DOM Core subsetting should be coordinated with other related DOM subsetting standards efforts. For example, mobile subset efforts for W3C languages such as XHTML, SVG, SMIL and XForms should be coordinated with each other because of the high probability that Compound Document profiles will be defined that combine these languages.
A Compound Document using references consists of a root document which may have one or more child documents, which may in turn have its own child documents. Each child document contains elements and attributes from one or more namespaces. The consequence of this is that each child document generates its own DOM. The interaction points between parent and child documents of a Compound Document are at referencing DOM nodes in a parent document. The Compound Document framework provides a means of accessing the DOMs of the child and parent documents.
Each child document DOM generates its own scripting execution context. Each child DOM scripting execution context provides access to its corresponding global object. The CSS style-sheet cascade is applied to each DOM in isolation. CSS property inheritance is inhibited at inclusion boundaries.
Many languages define specialized DOM APIs. The W3C has defined an HTML DOM which extends the Core DOM and provides various convenience APIs for interacting with HTML documents. Similarly, the SVG language defines an SVG DOM which extends Core DOM.
Compound Document profiles must specify whether the specialized DOM APIs that are defined within the component languages are supported.
Note: Although not required for compliance with the Compound Document Framework, it is strongly recommended that compound document profiles support all specialized DOM APIs that are supported in the component languages.
User agents must allow the child DOM to access the parent DOM.
For a child document to access the parent document, this
specification relies on the Window Object's
frameElement
attribute [WINDOW]. The
frameElement
attribute can be accessed from the
document
attribute [DOM2Views] using the
defaultView
attribute [DOM2Views]. Profiles built upon
this specification must specify on which exact document objects
these interfaces must be implemented.
Example usage of defaultView.frameElement
in
child.svg
<?xml version="1.0" encoding="UTF-8"?> <svg xmlns="http://www.w3.org/2000/svg" height="20" version="1.1" width="20"> <title>child-svg</title> <rect fill="blue" height="20" onload="alert('Child has seen: ' + document.defaultView.frameElement.ownerDocument.title)" width="20" x="10" y="10" /> </svg>
User agents must allow the parent DOM to
access any child DOM. The contentDocument
attribute
must represent the child document.
DOM Level 2 HTML defines a way for several elements to access
the child document using the contentDocument
attribute
[DOM2HTML]. The contentDocument
only applies to
objects implementing the Element
interface defined in
DOM Level 3 Core. [DOM3Core]. Profiles built upon this
specification must specify on which exact element objects the
interface must be implemented.
Example usage of contentDocument
in
parent.xhtml
:
<?xml version="1.0" encoding="UTF-8"?> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>parent-xhtml</title> </head> <body> <object data="child.svg" onload="alert('Parent has seen: ' + this.contentDocument.getElementsByTagNameNS( 'http://www.w3.org/2000/svg', 'title') [0].textContent)" /> </body> </html>
Compound Document profiles which leverage the Compound Document Framework and which support events and interactivity must have event interfaces and an event processing model that are compatible with the DOM Level 3 Events Specification.
Compound Document profiles may subset DOM Level 3 Events, but any DOM Events subsetting should be coordinated with other related DOM subsetting standards efforts. For example, mobile subset efforts for W3C languages such as XHTML, SVG, SMIL and XForms should be coordinated with each other because of the high probability that Compound Document profiles will be defined that combine these languages.
Using the various methods and attributes described in the Window API [WINDOW], in DOM Level 3 Events [DOM3EVENTS] and DOM Level 3 Core [DOM3CORE] it is possible for web authors to attach an event listener to a child document; and then upon catching it, dispatch it to the parent document on the referencing element. The following piece of script would create an event and dispatch it upon the referencing element:
var x = document.createEvent("CustomEvent"); x.initCustomEventNS("http://example.org/test", "test", true, false, null); window.frameElement.dispatchEvent(x);
In order to claim conformance to this Compound Documents Framework, a Compound Document profile must define how all of its event-related language constructs and scripting constructs map to corresponding DOM3 event facilities, unless DOM3 Events has already defined the mapping. In particular:
For each event construct within supported languages, the profile must define the event's namespace and local name, whether it supports the bubble phase, and whether it is cancellable, as well as the name of the DOM interface for its event structure (e.g., events.dom.w3c.org::UIEvent).
Any events that are defined to be equivalent to a corresponding event from DOM3 Events must have compatible behavior, such as the phases supported, cancellability and propagation across parent/child Compound Document boundaries. For example, for a "click" event from language A to be equivalent to the DOM3 "click" event, it also must be cancellable since DOM3 "click" is cancellable.
The profile must define how to map language features for event listeners, event handlers, and event targets into corresponding DOM3 Events facilities.
The following terms and definitions are used within this document.
A Compound Document is a document that combines mutliple document formats either by reference, by inclusion or both.
In the case of combining by reference, one compound document may be a collection of several separate documents.
A parent document represents a document that has a DOM as defined by DOM Level 3 Core and references another document. The DOM that is formed must be tree-based.
In the case of combining by reference, one compound document may be a collection of several separate documents.
The outermost parent document is called the root document.
In the case of combining by reference, one compound document may be a collection of several separate documents.
The document that is referenced is called a child document. If a child document itself references other documents, then it is also a parent document.
A Scalable Child Document is a Child Document for which rendering is possible at a range of output sizes. Scalable means not being limited to a single, fixed, pixel size.
A document which logically includes other documents via a hypertext reference.
A document which directly includes other documents and or namespace markup within the same physical document.
For example: A single XML document making use of XML grammars defined independently, normally making use of multiple namespaces.
See definition in Device Independence Glossary document.
A reduced set of capabilities from the original specification. Meaning, that the subset doesn't add any new features, but only removes them. Content that conforms to the profiled subset must be rendered successfully by a compliant user agent of the full/superset specification. In other words, the full user agent doesn't need to know it is content from a subset profile.
Focus traversal defines the elements that get focus and the order, in which they are traversed.
This specification defines conformance for several classes of products:
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (see ). However, for readability, these words do not appear in all uppercase letters in this specification.
At times, this specification recommends good practice for authors and user agents. These recommendations are not normative and conformance with this specification does not depend on their realization. These recommendations contain the expression "We recommend ...", "This specification recommends ...", or some similar wording.
User Agent Conformance
User agents must allow the child DOM to access the parent DOM.
User agents must allow the parent DOM to access any child DOM. The contentDocument attribute must represent the child document.
A conformant user agent of a superset profile specification must process subset profile content as if it were the superset profile content.
Profile Conformance
Compound Document profiles which support scripting must have scripting interfaces that are compatible with the DOM Level 3 Core Specification.
Compound Document profiles which support events and interactivity must have event interfaces and an event processing model that are compatible with the DOM Level 3 Events Specification.
For each event construct within supported languages, the profile must define the event's namespace and local name, whether it supports the bubble phase, and whether it is cancellable, as well as the name of the DOM interface for its event structure (e.g., events.dom.w3c.org::UIEvent).
Any events that are defined to be equivalent to a corresponding event from DOM3 Events must have compatible behavior, such as the phases supported, cancellability and propagation across parent/child Compound Document boundaries. For example, for a "click" event from language A to be equivalent to the DOM3 "click" event, it also must be cancellable since DOM3 "click" is cancellable.
The profile must define how to map language features for event listeners, event handlers, and event targets into corresponding DOM3 Events facilities.
A conformant subset profile must not add new features from their corresponding superset specification.
A conformant profile must define any dependent subset profiles.
Document Conformance
Conformant content should not raise security exceptions or events.
The editors would like to thank the contributors: