Compound Document by Inclusion (CDI) Framework

Abstract

The Compound Document by Inclusion Framework defines how user agents and specification authors should deal with combining multiple namespaces in a single document in terms of DOM and rendering for example.

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 is a First Public Working Draft of the Compound Documents by Inclusion Framework (editor's draft). Public comments to this Working Draft can be made 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.

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.

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.

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.

Table of Contents

• 1. Introduction
  • 1.1. Conformance
  • 1.2. Reference and Inclusion
  • 1.3. Related Documents
    • 1.3.1. WICD Core 2.0
    • 1.3.2. WICD Profiles 2.0
• 2. Document Object Model (DOM)
  • 2.1. DOM Interfaces implemented by Document objects
  • 2.2. Maintaining node state across namespaces
  • 2.3. Events
• 3. Styling with CSS
  • 3.1. Introduction
  • 3.2. Scoped styling
  • 3.3. Namespace-aware selectors
  • 3.4. Controlling inheritance
• 4. Scripting Context
• 5. Identification and Versioning
  • 5.1. Introduction
    • 5.1.1. Background
    • 5.1.2.
    • 5.1.3. Use cases and Examples
  • 5.2. Authoring Tools
    • 5.2.1. Filename suffix
    • 5.2.2. Identification within content
  • 5.3. User Agents
    • 5.3.1. Controlling the size of the HTTP Accept request header
    • 5.3.2. Identification within content
• 6. Miscellaneous CDI and CDR Edge Cases
• 7. Timing
• 8. Component Language Requirements
  • 8.1. Namespaced well-formed XML
  • 8.2. Namespace-based dispatching algorithm
• 9. Internationalization
• 10. Accessibility
• 11. Handling of unknown content
• 12. Guidelines for XML language designers
  • 12.1. Importing elements into various namespaces
  • 12.2. Validating content - schemata
  • 12.3. Defining custom DOM document interfaces
• Acknowledgements

1. Introduction

This section is informative.

Combining content delivery formats can often be desirable in order to provide a seamless experience to 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 Compound Documents:

• XHTML + SVG
• XHTML + XForms
• XHTML + SMIL
• SVG + XForms

This document defines a generic language-independent processing model for combining arbitrary document formats.

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., MathML, SMIL, SVG, VoiceXML, XForms, XHTML, XSL) with each other, together with CSS and the DOM; it can also be used to integrate non-W3C formats with W3C formats or integrate non-W3C formats with other non-W3C formats.

1.1. Conformance

Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

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 [RFC2119].

This specification defines the following classes of products:

conforming implementation

A user agent that implements all interfaces described in this specification and follows all must-, required- and shall-level of critera in this specification.

conforming document

A document that follows all must-, required- and shall-level of critera in this specification that apply to document authors.

conforming authoring tool

One that produces conforming documents.

1.2. Reference and Inclusion

Rename this section to definitions? It's about defining the various scenario's you have after all.

(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, SVG, and SMIL 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, SVG on vector graphis, and SMIL on synchronized multimedia.

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, provide contextual descriptions, to display an input form, with a scalable graphic and animation, all on the same page. XHTML, XForms, SVG, and SMIL, 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 SVG. The namespace declarations are marked by an appended comment to match the numbered namespaces listed below in the XML source in Example 1.

XHTML with SVG:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">   <--  #1
  <head>
    <title>SVG Circles by Inclusion</title>
    <style type="text/css">
    #foo { border: 1px solid red }
    </style>
  </head>
  <body>
    <h1>3 SVG Circles by Inclusion</h1>
    <svg id="foo" style="height:20em"
      xmlns="http://www.w3.org/2000/svg"      <--  #2
      viewBox="0 0 350 450" >
      <g fill-opacity="0.7" stroke="black" stroke-width="2">
        <circle fill="red" cx="220" cy="125"  r="100"/>
        <circle fill="blue" cx="290" cy="225"  r="100"/>
        <circle fill="green" cx="150" cy="225" r="100"/>
      </g>
      <rect width="450" height="350" fill="none" stroke="black"/>
     </svg>
  </body>
</html>

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> element. This can be repeated for as many documents as needed. 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 shows 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="280" width="360" 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 350 450"
     baseProfile="tiny" version="1.2" >
  <g fill-opacity="0.7" stroke="black" stroke-width="2">
    <circle fill="red" cx="220" cy="125"  r="100"/>
    <circle fill="blue" cx="290" cy="225"  r="100"/>
    <circle fill="green" cx="150" cy="225" r="100"/>
  </g>
  <rect width="450" height="350" fill="none" stroke="black"/>
</svg>
        

And of course, a Compound Document may be a hybrid of both compound document by inclusion and Compound Document by reference.

1.3. Related Documents

1.3.1. WICD Core 2.0

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), and XForms in a non device specific manner. WICD (pronounced "wicked") is an acronym for Web Integrated Compound Document.

WICD Core builds upon CDRF 1.0 and CDIF 2.0.

1.3.2. WICD Profiles 2.0

Profiles designed to enable rich multimedia content on a variety of devices such as: mobile handset devices, dekstop-type agents, and others.

2. Document Object Model (DOM)

Need some text here, perhaps reuse from CDRF.

What do we need to specify for DOM methods such as document.GetElementsByTagName("a") for if we have svg a tag and html a tags in a document?

2.1. DOM Interfaces implemented by Document objects

The Document object in a Compound Document by inclusion must expose the HTMLDocument interface as well as all document-level interfaces of any other namespaces found in the document that the user agent supports. For example, in a compound document mixing XHTML and SVG the document object must expose both the HTMLDocument and the SVGDocument interfaces.

2.2. Maintaining node state across namespaces

Need text. ACTION-524 on Steve...

2.3. Events

Since DOM Level 3 Events handles namespaced eventing and appropriate handling of phases, no restrictions or enhancements are added. CDI profiles may define additional events and event processing restrictions.

Need to clarify that providing event attributes, such as SVG's onzoom on HTML div, it might be assumed by authors that it should be defined. If needed, script can be used addEventListener() on div tag to add handler for the onzoom event from SVG.

If we consider HTML based profiles, we will need to revisit with DOM Level 2 events

3. Styling with CSS

(This section is currently all informative)

3.1. Introduction

XHTML allows multiple <html:style> elements, as children of the <html:head> element. The styles from these elements, plus external style sheets, plus inline style attributes, together influence the complete document tree. SVG Full allows multiple <svg:style> elements throughout the document; again, styles from these elements, plus external style sheets, plus inline style attributes, together influence the complete document tree. SVG Tiny 1.2 restricts styling information to inline presentation attributes, for ease of generation with XSLT. These have a specificity of zero so will be overidden, in a CDI context, by any other style sheets, as the rules there will have a higher specificity.

When content is combined by inclusion, this means that styles are also combined and will affect the entire tree; this may not be desirable.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>circles</title>
    <style type="text/css">
      body { color: black; font-size: 12px }
      a { color: green }
    </style>
  </head>
  <body>
    <h1>Some links and a graphic</h1>
    <p>A <a href="http://example.com/somewhere">link</a></p>
    <object data="scoping.svg" type="image/svg+xml" style="height: 4em"/>
  </body>
</html>
      

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 100" 
     xmlns:x="http://www.w3.org/1999/xlink">
  <style type="text/css">
    * {font-style: italic }
  </style>
  <text x="20" y="60" font-size="40" color="blue">Another 
     <a x:href="http://example.net/elsewhere" fill="currentColor">link</a></text>
  <rect width="250" height="100" fill="none" stroke="#700"/>
</svg>      
      

If these documents are now combined by inclusion, the styles interact:

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>circles</title>
    <style type="text/css">
      body { color: black; font-size: 12px }
      a { color: green }
    </style>
  </head>
  <body>
    <h1>Some links and a graphic</h1>
    <p>A <a href="http://example.com/somewhere">link</a></p>
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 100" 
        xmlns:x="http://www.w3.org/1999/xlink" height="4em">
      <style type="text/css">
        * {font-style: italic }
      </style>
      <text x="20" y="60" font-size="40" color="blue">Another 
        <a x:href="http://example.net/elsewhere" 
        fill="currentColor">link</a></text>
      <rect width="250" height="100" fill="none" stroke="#700"/>
    </svg>
  </body>
</html>      

The following sections discuss solutions to this problem. At this stage, the CDF Working Group has not picked one or more solutions, and simply notes them as issues to facilitate discussion.

3.2. Scoped styling

One way to avoid inadvertent styling changes is to explicitly scope the <html:style> and <svg:style> elements. For example:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 100" 
     xmlns:x="http://www.w3.org/1999/xlink">
  <style type="text/css" scope="parent">
    * {font-style: italic }
  </style>
  <text x="20" y="60" font-size="40" color="blue">Another 
    <a x:href="http://example.net/elsewhere" fill="currentColor">link</a></text>
  <rect width="250" height="100" fill="none" stroke="#700"/>
</svg>
      

When the document in Example 8 is included into a compound document, the styling will remain local to the graphic.

A related alternative would be to introduce a new <cdf:style> which is defined to be scoped to its parent by default.

A further refinement would be to add an attribute to the <style> elements, containing a selector which defines the scope (rather than hard-coding the scope to the parent of the style element).

3.3. Namespace-aware selectors

Restricting selectors to apply to particular XML namespaces, rather than all namespaces, also helps to control and localize styling.

 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 100" 
    xmlns:x="http://www.w3.org/1999/xlink">
   <style type="text/css">
     @namespace s url(http://www.w3.org/2000/svg);
     s|* {font-style: italic }
   </style>
   <text x="20" y="60" font-size="40" color="blue">Another 
     <a x:href="http://example.net/elsewhere" fill="currentColor">link</a></text>
   <rect width="250" height="100" fill="none" stroke="#700"/>
 </svg>
     

Modifying Example 7 to use namespace-aware selectors corrects the rendering to that which was desired.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>circles</title>
    <style type="text/css">
      @namespace h url(http://www.w3.org/1999/xhtml);
      body { color: black; font-size: 12px }
      h|a { color: green }
    </style>
  </head>
  <body>
    <h1>Some links and a graphic</h1>
    <p>A <a href="http://example.com/somewhere">link</a></p>
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 250 100" 
         xmlns:x="http://www.w3.org/1999/xlink" height="4em">
      <style type="text/css">
        @namespace s url(http://www.w3.org/2000/svg);
        s|* {font-style: italic }
      </style>
  	  <text x="20" y="60" font-size="40" color="blue">Another 
          <a x:href="http://example.net/elsewhere" 
             fill="currentColor">link</a></text>
      <rect width="250" height="100" fill="none" stroke="#700"/>
     </svg>
  </body>
</html>       
     

3.4. Controlling inheritance

4. Scripting Context

This section is in need of rewording and references...

A profile conforming to this framework must declare which elements contain scripts for execution.

Documents loaded into a user agent may contain scripting elements. Such elements typically contain ECMAScript programs for execution within the user agent displaying the document.

Typical ECMAScript implementations provide the ability to create a scripting execution context which manages an instance of the script execution engine. Such an instance defines methods and properties available to the script author and mediates access to the DOM representing the parent document hosting the script.

In the compound document by reference (CDR) case, an ECMAScript execution context is instantiated for each separate document. These instances manage their own data. For example, an XHTML file referencing an SVG file will result in one instance of the script execution context for XHTML and one for SVG. Each instance may define methods and properties which are isolated between the two component parts of the document.

In the case of a compound document by inclusion (CDI), there is a single ECMAScript execution context. This means that all script elements in all namespaces will be processed by the same instance of the script engine. Thus, if a portion of the CDI document which is in the XHTML namespace contains methods and properties inside of an XHTML script element, these same methods and properties will be exposed to the parts of the document which are in the other namespaces, such as SVG.

Similarly, any script elements defined in the portion of the document which is in the SVG namespace that define properties and methods will have those properties and methods exposed to the parts of the document which are in other namespaces, such as XHTML.

Therefore, the resultant script execution context processes properties and methods which represent the union of all recognized script elements found in all of the namespaces within the CDI document.

Use of a CDI document with scripting provides the ability for content in multiple namespaces to share access to methods and properties declared in all of the component namespaces. This removes the need to provide explicit parent/child access for crossing namespace boundaries in relation to scripting.

Documents may support a mixture of CDI and CDR content. Authors using a mixture of CDR and CDI will have scripting behavior across the namespaces defined by the inclusion mechanism. In the CDR case, the script execution contexts will be isolated for each document.

5. Identification and Versioning

<?cdf profile="profile-uri"?>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<?cdf profile="http://www.w3.org/2006/CDF/WICD"?>

Accept: application/cdf+xml;prof="http://www.w3.org/2007/wicd-mobile http://www.w3.org/2008/prof3"

Accept: application/cdf+xml;prof="wm p3"

6. Miscellaneous CDI and CDR Edge Cases

<html>
  <head>
    <svg:svg id="c1">
      <svg:circle fill="red" r="10px" />
    </svg:svg>
  </head>
  <body>
  
    <!-- Reuse locally, as expected
         CDI case -->
    <svg:use xlink:link="#c1" />
    
    <!-- Reference an SVG item within same document
         CDR case (is there another DOM???) -->
    <object data="#c1">
      <param name="" value=""/>
    </object>

    <!-- Reference an SVG item within same document
         CDR case (is there another DOM???) -->
    <object data="#c1">
      <param name="" value=""/>
    </object>

    <!-- Reference externally but fold into current DOM
         CDI case -->    
    <xinclude src="#c1" />

    <!-- Reference externally but fold into current DOM
         CDI case -->    
    <xinclude src="circle.svg" />
    
  </body>
</html>

<?xml version="1.0" encoding="Cp1252"?>
<xhtml:html  xmlns:xhtml="http://www.w3.org/1999/xhtml"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:xlink="http://www.w3.org/1999/xlink">

  <xhtml:head>
  </xhtml:head>
  <xhtml:body>
    <xhtml:h1 id="foo">
    Hello World
    </xhtml:h1>
    <xhtml:p>
      <svg:svg>
        <svg:circle r="150"></svg:circle>
        <svg:animate attributeName="width"
            attributeType="CSS"
            xlink:href="#foo"
            to="10px" dur="10s" />
      </svg:svg>
    </xhtml:p>
  </xhtml:body>
</xhtml:html>

8. Component Language Requirements

8.1. Namespaced well-formed XML

Component languages, both parent and child, must be well-formed XML documents. XML documents must have a unique non-empty namespaces.

8.2. Namespace-based dispatching algorithm

9. Internationalization

10. Accessibility

See ACTION-505 on Doug S and see XAG (accessibility guidelines)...

11. Handling of unknown content

On ACTION-500 on Steve...

12. Guidelines for XML language designers

We need normative requirements on people making languages...

12.1. Importing elements into various namespaces

CDF profile candidate languages shall not be composed of chameleoned namespaces.

Specifications should not import an existing vocabulary into a another or new namespace (often known as chameleon namespaces), whether it is to use one technology within another or to import elements from a previous version of a specification into a new version. This creates problems for both content authors and user agent implementers when multiple namespaces import the same vocabulary:

1. When authors or implementers building on W3C technologies want to search for, select, or match a certain type of element, having that same element appear in multiple namespaces makes the necessary code more complicated. For example, use of DOM's document.getElementsByTagNameNS [DOM3Core], [Selectors] or XPath's name test [XPath] all become more complicated when searching for the same element name within a set of namespaces, such as searching for an XForms input element [XForms] within the XForms and XHTML2 namespaces.
2. Implementers are likely to face the same cost within their implementations: when they support multiple imports of the same vocabulary, the question of determining whether an element is a certain element type in that vocabulary becomes more complex to write.

Fixup chameleon guideline section

12.2. Validating content - schemata

12.3. Defining custom DOM document interfaces

When defining DOM interfaces, namely one that extends the DOM Document interface, consideration should be taken to ensure that methods and attributes don't conflict with other markup languages. This can't expected to be an exhaustive search, though likely candidates would be HTML and SVG.

Acknowledgements

This section is informative.

The editors would like to thank the following contributors:

• fill in contributors