Compound Document by Reference Framework 1.0

2.1.1 Specialized DOM access

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.

2.1.2 Child to Parent DOM Access

User agent must provide access to parent document.

For a child document to access the parent document, this specification introduces the ReferencedDocument interface.

The ReferencedDocument interface only applies to objects implementing the Document interface defined in DOM Level 3 Core. [DOM3Core] profiles built upon this specification must specify on which exact document objects the interface must be implemented. User agents may implement this interface for each document object they consider to be viable.

Accessing the parent document through the DOM can be disabled for security reasons. In such cases user agents should throw a SecurityException as defined in section 2.1.4.

IDL Definition:

interface ReferencedDocument {
  readonly attribute Element referencingElement;
  // Raises SecurityException with code of SECURITY_ERR
  //   when access is disabled for security reasons.
};

The referencingElement attribute must represent the element node used for including the current document in the parent document. If access to the parent document is disabled or there is no parent document the attribute must be null.

2.1.3 Parent to Child DOM Access

User agents, which support a DOM, must provide access to child documents.

DOM Level 2 HTML defined a way for several elements to access the child document using the contentDocument attribute. [DOM2HTML] This specification defines a generic ReferencingElement interface.

The ReferencingElement only applies to objects implementing the Element interface defined in DOM Level 3 Core. [DOM3Core] Profiles build upon this specification must specify on which exact element objects the interface must be implemented. User agents may implement this interface for each element object they consider to be viable.

Accessing the child document through the DOM can be disabled for security reasons. In such cases user agents should throw a SecurityException as defined in section 2.1.4.

IDL Definition:

interface ReferencingElement {
  readonly attribute Document contentDocument;
  // Raises SecurityException with code of SECURITY_ERR
  //   when access is disabled for security reasons.
};

The contentDocument attribute must represent the child document. If access to the child document is disabled or there is no child document the attribute must be null.

2.1.4 SecurityException

Accessing parent or child documents through the DOM as described in sections 2.1.2 and 2.1.3 can be disabled for security reasons. In such cases user agents should throw a SecurityException.

IDL Definition:

exception SecurityException {
  unsigned short   code;
};
// SecurityExceptionCode
const unsigned short      SECURITY_ERR       = 83;

code represents an integer indicating the type of error generated. SECURITY_ERR is given back if an attempt was made to break through the security policy of the user agent.

2.2.1 Event Propagation in a Compound Document

Events targetted at child documents do not reach the parent document by default. The propagate attribute from the DocumentEventPropagation interface enables a way for events to reach a parent document.

The DocumentEventPropagation only applies to objects implementing the Document interface defined in DOM Level 3 Core. [DOM3Core] Profiles build upon this specification must specify on which exact document objects the interface must be implemented. User agents may implement this interface for each document object they consider to be viable.

IDL Definition:

interface DocumentEventPropagation {
  attribute boolean propagate; 
};

When propagate is set to true events targetted at the document shall propagate to the parent document, if any. When propagate is set to false events must not propagate. The default value of the attribute is false.

2.2.2 Security Event

When a document breaks through the user agent security policy, user agents are encouraged to dispatch a security event in the http://www.w3.org/2005/10/cdf namespace on the document object. The event is not cancelable and has no bubbling phase. It implements the Event interface defined in DOM Level 3 Events. [DOM3Events]

Security event is a mechanism for notifying non-scripting related security violations. On the other hand, security exception in 2.1.4 is used for notifying scripting related issues.

2.2.3 Event-Related Legacy Markup

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, what phases it supports (capture, target, bubble), whether it is cancellable, and 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.

2.3.1 Child Documents

(This section is informative)

Since the child document's language specification defines hyperlinking behavior, here are recommendations for language specifications for languages which might be used as child documents within the context of compound documents:

If specifications provide a mechanism for hyperlinking they must also define a way to target specific frames. In addition it must be defined how the current document can be replaced (the document the link is defined in), the parent document and the root document.

Relevant language specifications should include a mechanism for defining the possible targets for the hyperlink. For example, the HTML4 specification includes a 'target' attribute on the 'html:a' element which supports targets of _blank, _self, _parent, _top and <frametarget> (see http://www.w3.org/TR/html401/types.html#type-frame-target). The SVG Tiny 1.2 specification also supports a 'target' attribute on the 'svg:a' element with the same list of possible values, except with the addition of an "_replace" keyword (see http://www.w3.org/TR/SVGMobile12/linking.html#AElementTargetAttribute). The WebCGM specification also supports targets of _blank, _self, _parent, _top, _replace and <frametarget> (see http://www.w3.org/TR/REC-WebCGM/REC-03-CGM-IC.html#webcgm_3_1_2_2).

NOTE: The keyword _self means different things in SVG than it does in HTML. In HTML it replaces the current document and in SVG it replaces the parent document.

Relevant language specification should provide a clear definition of the behavior of the "_self" keyword. For SVG and WebCGM, when there is a parent HTML document which references an SVG or WebCGM graphic via html:object, the "_self" keyword causes the HTML document to be replaced by the linked content. However, when a parent HTML document references a child HTML document via html:object or html:iframe, some HTML browsers implement the "_self" keyword such that only the child HTML document is replaced. Because of this, relevant language specifications should be clear about UA behavior in response to the "_self" keyword. One strategy to consider: if the primary usage scenario falls under the category of "replaced element" (see http://www.w3.org/TR/REC-CSS2/conform.html#replaced-element), as is the case with SVG, then defining "_self" to replace the parent document is appropriate.

For language specifications such as SVG which define "_self" to replace the parent document, it might be appropriate to support a "_replace" feature similar to what exists in SVG Tiny 1.2 and WebCGM. This feature causes a hyperlink to replace the child document only but leave parents and other ancestor documents unchanged. (For example, if an SVG document is referenced by a parent HTML document via an 'html:object' element, and if the SVG document has an 'svg:a' element with target="_replace", then when that hyperlink is activated, the SVG document gets replaced but there are no changes within the parent HTML document.)

Sometimes in industry practice a plugin user agent is used to handle certain types of child documents. For example, plugins might handle SVG or MathML child documents. In these scenarios the plugin may only be able to handle particular formats via the "_replace" keyword. (For example, a MathML plugin might be able to handle only MathML content.) Because of this, relevant language specification that support "_replace" (or alternative syntax for the same feature) should clearly specify requirements when "_replace" references content of the same type and content of other types. (For example, only content of the same type can be referenced with "_replace", or any type can be referenced with "_replace", but then error processing must be defined for unknown or unsupported content.)

2.3.2 Parent Documents

(This section is informative)

One potential area of ambiguity in the context of compound document is the meaning of the "_self" and "_parent" keywords. (See HTML4's definition at http://www.w3.org/TR/html401/types.html#type-frame-target and SVG Tiny 1.2's definition at http://www.w3.org/TR/SVGMobile12/linking.html#AElementTargetAttribute). For example, suppose a parent XHTML document references a child SVG document via an 'html:object' element and suppose the SVG document has an 'svg:a' element with target="_self". The SVG Tiny 1.2 specification says that "_self" causes both the XHTML parent frame and the child SVG to be replaced when the hyperlink is activated.

However, there are potential ambiguities if the parent language format supports its own particular notions of nested regions (e.g., frames, panes or sub-documents). It is strongly recommended that relevant language specifications clearly define how its own nested region features relate to the hyperlinking keywords _self, _parent, and _top.

2.4.1 Referencing Elements

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.

2.4.2 Declarative Child Object Parameters

It may be necessary to transfer parameters declaratively to a referenced child object. Compound Document profiles may define specific parameters/values for this purpose. Two examples:

<object type="..." data="...">
  <param name="param1" value="true" />
  <param name="param2" value="123" />
</object>

<svg xmlns="http://www.w3.org/2000/svg">
    <foreignObject>
        <metadata>
           param=value;
           param=value
        </metadata>
    </foreignObject>
</svg>

2.5.1 Phishing

A common security problem on the Web is known as "phishing". A web application that looks like one which is trusted by the user collects some data (for example credit card numbers, addresses, etc), and then posts that information to a potentially hostile third party.

Allowing access across document boundaries potentially allows an object to fetch the actual document which is trusted by the user, and read the user's data as it is entered. This approach could defeat many browser interface features which are designed to warn the user that a site is not the one they think.

2.5.2 Firewall Attack

Another common attack is to post a document to a user behind a firewall, and then use it to gain access to a server whose name is known but which is normally behind the firewall, and then post information from the retrieved resources to a hostile party.

2.5.3 How this is handled today?

Currently, the common approach used is to restrict access across documents or network interfaces to material which comes from the same source as the code which tries to make that access. This makes it difficult to re-use resources on the Web, by requiring a copy to be held in the domain of each application which uses that resource. This breaks cacheability, potentially reduces maintainability, and requires services to maintain the entire service rather than taking full advantage of specialised third-party providers.