4.2. Level 3
Events Requirements
The DOM Level 3 Events specification will attempt to address
some of the remaining issues from the DOM Level 2 Event
specification as well as a couple or requested enhancements to the
model. It will not attempt to redesign the model nor will attempt
to define any additional event models.
4.2.1. EventListener grouping
The specification must define a technique for registering
EventListeners in groups. These groups will then have
specified behavior in which attempts to modify the flow of an event
will be restricted and affected only the group to which the
EventListener in question belongs.
It is also required that whatever technique is specified to
accomplish this purpose be compatible with the existing DOM Level 2
Event model and any EventListeners registered using
DOM Level 2 Event model methods.
4.2.2. Key event set
The specification must define a set of key events to handle
keyboard input. This key event set must be fully
internationalizable. It is hoped that this key event set will be
compatible with existing key event sets used in current systems
however this is not a requirement.
The specification should attempt to define a set of input events
to handle IME based keyboard input. It is expected that this
requirement will depend heavily on any key event set defined by the
specification.
4.2.4. Device independent event set
The specification must define a device independent event set.
This event set should allow notification of typical user
interaction with a document without requiring the use of either
mouse events or key events.
(ED: The following
requirements come from the WAI-PF Working Group.
)
Each Document View must provide a Device Independent UI Event
Model.
The following events are not present in the DOM Level 2
specification. Those related to selection should be picked up when
a selection model is included:
- gainselection
- The gainselection event occurs when a node or part of it is
selected (unlike the HTML event select, it can be applied to any
element, not just HTML FORM controls). For each selected node a
gainselection event, which can be handled locally or through
bubbling by a root node selection handler, is generated.
- Bubbles: Yes
- Cancelable: No
- Context Info: range
- loseselection
- The loseselection event occurs when a node or part of it is
deselected, for example because the user selects something else.
- Bubbles: Yes
- Cancelable: No
- Context Info: range
- key
- Key input may not be keyboard specific.
- pointermove
- Input may be a stylus rather than a mouse
4.3. Content Models and
Validation Use Cases and Requirements
The content model referenced in these use cases/requirements is
an abstraction and does not refer to DTDs or XML Schemas or any
transformations between the two.
For the CM-editing and document-editing worlds, the following
use cases and requirements are common to both and could be labeled
as the "Validation and Other Common Functionality" section:
Use Cases:
- CU1. Modify an existing content model.
- CU2. Associating a content model (external and/or internal)
with a document, or changing the current association.
- CU3. Using the same external content model with several
documents, without having to reload it.
- CU4. Create a new content model.
Requirements:
- CR1. Validate against the content model.
- CR2. Retrieve information from content model.
- CR3. Load an existing content model, perhaps independently from
a document.
- CR4. Being able to determine if a document has a content model
associated with it.
- CR5. Create a new content model object.
- CR6. Associate a CM with a document and make it the active
CM.
Specific to the CM-editing world, the following are use cases
and requirements and could be labeled as the "CM-editing"
section:
Use Cases:
- CMU1. Clone/map all or parts of an existing content model to a
new or existing content model.
- CMU2. Save a content model in a separate file. For example, a
DTD can be broken up into reusable pieces, which are then brought
in via entity references, these can then be saved in a separate
file.
- CMU3. Partial content model checking. For example, only certain
portions of the content model need be validated.
Requirements:
- CMR1. View and modify all parts of the content model.
- CMR2. Validate the content model itself. For example, if an
element/attribute is inserted incorrectly into the content
model.
- CMR3. Serialize the content model.
- CMR4. Clone all or parts of an existing content model.
- CMR5. Validate portions of the XML document against the content
model.
Specific to the document-editing world, the following are use
cases and requirements and could be labeled as the
"Document-editing" section:
Use Cases:
- DU1. For editing documents with an associated content model,
provide the assistance necessary so that valid documents can be
modified and remain valid.
- DU2. For editing documents with an associated content model,
provide the assistance necessary to transform an invalid document
into a valid one.
Requirements:
- DR1. Being able to determine if the document is not
well-formed, and if not, be given enough assistance to locate the
error.
- DR2. Being able to determine if the document is not namespace
well-formed, and if not, be given enough assistance to locate the
error.
- DR3. Being able to determine if the document is not valid with
respect to its associated content model, and if not, give enough
assistance to locate the error.
- DR4. Being able to determine if specific modifications to a
document would make it become invalid.
- DR5. Retrieve information from all content model. For example,
getting a list of all the defined element names for document
editing purposes.
General Issues:
- I1. Namespace issues associated with the content model. To
address namespaces, a
isNamespaceAware attribute to
the generic CM object has been added to help applications determine
if qualified names are important. Note that this should not be
interpreted as helping identify what the underlying content model
is. A MathML example to show how namespaced documents will be
validated will be added later.
- I2. Multiple CMs being associated with a XML document. For
validation, this could: 1) result in an exception; 2) a merged
content model for the document to be validated against; 3) each
content model for the document to be validated against separately.
In this chapter, we have gone for the third choice, allowing the
user to specify which content model to be active and allowing them
to keep adding content models to a list associated with the
document.
- I3. Content model being able to handle more datatypes than
strings. Currently, this functionality is not available and should
be dealt with in the future.
- I4. Round-trippability for include/ignore statements and other
constructs such as parameter entities, e.g., "macro-like"
constructs, will not be supported since no data representation
exists to support these constructs without having to re-parse
them.
- I5. Basic interface for a common error handler both CM and
Load/Save. Agreement has been to utilize user-registered callbacks
but other details to be worked out.
4.4. Load and Save
Requirements
DOM Level 3 will provide an API for loading XML source documents
into a DOM representation and for saving a DOM representation as a
XML document.
Some environments, such as the Java platform or COM, have their
own ways to persist objects to streams and to restore them. There
is no direct relationship between these mechanisms and the DOM
load/save mechanism. This specification defines how to serialize
documents only to and from XML format.
4.4.1.
General Requirements
Requirements that apply to both loading and saving
documents.
4.4.1.1. Document Sources
Documents must be able to be parsed from and saved to the
following sources:
- Input and Output Streams
- URIs
- Files
Note that Input and Output streams take care of the in memory
case. One point of caution is that a stream doesn't allow a base
URI to be defined against which all relative URIs in the document
are resolved.
4.4.1.2. Content Model
Loading
While creating a new document using the DOM API, a mechanism
must be provided to specify that the new document uses a
pre-existing Content Model and to cause that Content Model to be
loaded.
Note that while DOM Level 2 creation can specify a Content Model
when creating a document (public and system IDs for the external
subset, and a string for the subset), DOM Level 2 implementations
do not process the Content Model's content. For DOM Level 3, the
Content Model's content must be read.
4.4.1.3. Content Model
Reuse
When processing a series of documents, all of which use the same
Content Model, implementations should be able to reuse the already
parsed and loaded Content Model rather than reparsing it again for
each new document.
This feature may not have an explicit DOM API associated with
it, but it does require that nothing in this section, or the
Content Model section, of this specification block it or make it
difficult to implement.
4.4.1.4. Entity Resolution
Some means is required to allow applications to map public and
system IDs to the correct document. This facility should provide
sufficient capability to allow the implementation of catalogs, but
providing catalogs themselves is not a requirement. In addition XML
Base needs to be addressed.
4.4.1.5. Error Reporting
Loading a document can cause the generation of errors
including:
- I/O Errors, such as the inability to find or open the specified
document.
XML well formedness errors.
Validity errors
Saving a document can cause the generation of errors
including:
- I/O Errors, such as the inability to write to a specified
stream, URL, or file.
Improper constructs, such as '--' in comments, in the DOM that
cannot be represented as well formed XML.
This section, as well as the DOM Level 3 Content Model section
should use a common error reporting mechanism. Well-formedness and
validity checking are in the domain of the Content Model section,
even though they may be commonly generated in response to an
application asking that a document be loaded.
4.4.2. Load
Requirements
The following requirements apply to loading documents.
4.4.2.1. Parser Properties and
Options
Parsers may have properties or options that can be set by
applications. Examples include:
- Expansion of entity references.
- Creation of entity ref nodes.
- Handling of white space in element content.
- Enabling of namespace handling.
- Enabling of content model validation.
A mechanism to set properties, query the state of properties,
and to query the set of properties supported by a particular DOM
implementation is required.
4.4.3.
XML Writer Requirements
The fundamental requirement is to write a DOM document as XML
source. All information to be serialized should be available via
the normal DOM API.
4.4.3.1. XML Writer Properties
and Options
There are several options that can be defined when saving an XML
document. Some of these are:
- Saving to Canonical XML format.
- Pretty Printing.
- Specify the encoding in which a document is written.
- How and when to use character entities.
- Namespace prefix handling.
- Saving of Content Models.
- Handling of external entities.
4.4.3.2. Content Model
Saving
Requirement from the Content Model group.
4.4.4. Other
Items Under Consideration
The following items are not committed to, but are under
consideration. Public feedback on these items is especially
requested.
4.4.4.1. Incremental and/or
Concurrent Parsing
Provide the ability for a thread that requested the loading of a
document to continue execution without blocking while the document
is being loaded. This would require some sort of notification or
completion event when the loading process was done.
Provide the ability to examine the partial DOM representation
before it has been fully loaded.
In one form, a document may be loaded asynchronously while a DOM
based application is accessing the document. In another form, the
application may explicitly ask for the next incremental portion of
a document to be loaded.
4.4.4.2. Filtered Save
Provide the capability to write out only a part of a document.
May be able to leverage TreeWalkers, or the Filters associated with
TreeWalkers, or Ranges as a means of specifying the portion of the
document to be written.
4.4.4.3. Document Fragments
Document fragments, as specified by the XML Fragment
specification, should be able to be loaded. This is useful to
applications that only need to process some part of a large
document. Because the DOM is typically implemented as an in-memory
representation of a document, fully loading large documents can
require large amounts of memory.
XPath should also be considered as a way to identify XML
Document fragments to load.
4.4.4.4. Document Fragments in
Context of Existing DOM
Document fragments, as specified by the XML Fragment
specification, should be able to be loaded into the context of an
existing document at a point specified by a node position, or
perhaps a range. This is a separate feature than simply loading
document fragments as a new Node.
4.5. Embedded DOM
Requirements
4.5.1. Abstract
This document discusses the requirements and framework for using
multiple implementations of DOM or DOM-based APIs designed for a
particular markup language within a single standard DOM
application. Up until now, the Document Object Model design has
been concerned with defining an API to an entire XML document,
where all methods and attributes in the API apply equally to the
entire document and it is assumed that only one implementation of
the DOM is needed by an application.
With the advent of markup languages such as Scalable Vector Graphics and
the Mathematical Markup
Language, it has become obvious that this simple model no
longer applies. It is quite possible to have documents which embed
some MathML or SVG markup, where a DOM application might reasonably
expect to be able to use the specialized MathML or SVG DOM-based
APIs. Similarly, many DOM applications are being designed to "glue"
together two systems that both implement the DOM, and need some
standard mechanism to assist in making the multiple implementations
interoperate.
A module of Level 3 DOM, which we shall refer to by the
shorthand name "EDOM", will address this issue.
4.5.2. Introduction
As new XML vocabularies are developed, those defining the
vocabularies are beginning to define specialized APIs for
manipulating XML instances of those vocabularies by extending the
DOM to provide interfaces and methods that perform operations
frequently needed their users. For example, the MathML and SVG
groups are developing DOM extensions to allow users to manipulate
instances of these vocabularies using semantics appropriate to
images and mathematics (respectively) as well as the generic DOM
"tree" semantics. Instances of SVG or MathML are often embedded in
XML documents conforming to a different schema such as XHTML or
DocBook. While the XML Namespaces Recommendation provides a
mechanism for integrating these documents at the syntax level, it
has become clear that the DOM Level 2 Recommendation is not rich
enough to cover all the issues that have been encountered in having
these different DOM implementations be used together in a single
application. The Embedded DOM module deals with the requirements
brought about by embedding fragments written according to a
specific markup language (the embedded component) in a
document where the rest of the markup is not written according to
that specific markup language (the host document). It does
not deal with fragments embedded by reference or linking.
We are seeing at least two implementation scenarios in which DOM
components can be embedded in a host DOM. One extreme might be
called the "monolithic" scenario in which a single product (e.g.
the Mozilla browser) implements both the generic host DOM and the
specialized embedded DOM. The embedded DOM still has a different
DOMImplementation object than the host because it will
support a different feature set, although it is quite likely that
the embedded and host DOMs will use compatible classes or data
structures. At the other extreme, the embedded DOM reflects a
completely different implementation, perhaps from an entirely
different vendor, e.g. an Adobe SVG component plugged into the
SoftQuad editor.
The general objective of the EDOM ET is to define whatever
mechanisms are required in order to make documents that are
actually handled by two or more DOM implementations work together
as seamlessly and compatibly as possible under various
implementation scenarios. Ideally, a DOM application writer should
see the entire document as a coherent unit, with certain Nodes that
are actually handled by embedded DOMs simply having more
specialized capabilities. It is not clear at this point whether
this is achievable for all scenarios, but our goal is to make it
seamless for applications that do not care about the differences,
and to make it possible for applications that do care about the
differences to discover which DOM handles embedded nodes, be
informed of where the boundaries are, and to use that
implementation to its fullest extent.
Achieving these objective may entail clarifications to the
wording of the DOM specification, new interfaces or methods on
existing interfaces, revised requirements for the Load/Save module
so that the multiple DOMs are built and linked together at parse
time, or some combination of these.
4.5.3. Use Cases
We will consider the following use cases when assessing proposed
requirements and in designing the DOM extensions to support
embedded DOMs. All assume that some DOM Level 3 methods have been
called to link the various DOM implementations together so that DOM
boundaries can be detected and handled.
4.5.3.1. Navigation from host to
embedded DOM
A DOM application running on the host DOM implementation may
need to access information controlled by the embedded DOM, e.g. to
serialize the entire document.
4.5.3.2. Navigation from
embedded DOM to host
A DOM application running on the embedded DOM implementation may
need to access information controlled by the host DOM, e.g. to
query a style attribute, namespace declaration, etc.
4.5.3.3. Event capture and
bubbling across Host DOM/Embedded DOM boundary
A DOM application may need to detect and process events
irrespective of whether they occur in a host or embedded DOM.
4.5.3.4. Seamless view of host,
embedded DOMs
It may be acceptable for DOM Level 3 applications to use
additional APIs to detect host/embedded DOM boundaries and to
navigate across them. Nevertheless, it would be far better for
users if ordinary node navigation operations, validation,
iterators/treewalkers, and event propagation worked seamlessly
across DOM boundaries.
4.5.3.5. Notification of
document changes across Host/Embedded boundary
A DOM application may need to be aware of changes to the
document tree irrespective of whether they were initiated in a host
or embedded DOM.
4.5.4. Implementation
Scenarios
We have prepared the following grid to clarify the different
scenarios under which a standard for defining how an embedded DOM
interoperates with a host DOM could be implemented, and what this
means for the application programmer using the DOM interfaces.
One axis of the grid reflects the different architectures in
which one DOM can be imbedded in another. The alternatives we are
considering include:
- Monolithic - The host DOM and the embedded DOM are implemented
by the same code. The host/embedded distinction exists mainly to
reflect the different features of nodes at different levels.
Examples of this would appear to include Mozilla's support for
MathML and SVG, IE5's support for VML, and Amaya's support for
MathML.
- Dynamic Subclass - Some proprietary mechanism such as Microsoft
"binary behaviors" or Netscape's XBL is used to construct embedded
DOM subtrees trees that appear to be subclasses (for DOM purposes)
of the host DOM nodes. In a Java environment, a user could
dynamically subclass another implementation.
- Wrapper - The host and embedded DOMs are completely separate
implementations that are woven together to provide support for a
different subtrees of a single document. Since there is no
subclassing mechanism to redirect implementation-level methods to
the proper code, we envision "wrapper" classes that could implement
the EDOM functionality by redirecting operations on "foreign" nodes
to the standard DOM interfaces rather than the implementation
classes.
- Data Island - Two DOM implementations that are really separate
documents, conceptually different and having no hierarchical
relationship that can be inferred. An example would be a Microsoft
XML data island inside an HTML document. This is essentially a
non-use case, presented simply to identify it and contrast it with
scenarios that we do envision supporting.
The other axis reflects the properties or features of the DOM
API that could be preserved across the host / embedded border. The
features under consideration include:
- Awareness - Can the user query the host DOM about the identity
and location of embedded DOMs? This implies that there is some way
to get an opaque handle that the DOM doesn't know what to do with,
but the application programmer may, at the boundary between a host
DOM and embedded DOM.
- Boundary-aware navigation - Is it possible -- perhaps by
calling a new API method -- for an application programmer to
navigate from a host DOM node into an embedded DOM node, and from
an embedded DOM node into the host DOM that embeds it? In other
words, there is a "semi-permeable barrier" between the host and
embedded DOMs and an API with which to cross it.
- Seamlessness- Can an application programmer navigate across the
host/embedded boundary without being aware it exists? Do properties
such as IDs, unique identifiers, timings, etc. appear to work
seamlessly across embedded DOM boundaries?
- Event propagation - Do DOM events bubble and be captured across
embedded DOM boundaries?
- CSS Inheritance- Do CSS properties on the host DOM pass down to
the embedded DOM?
The Embedded DOM plans to support the following use cases
derived from this grid:
|
Monolithic |
Dynamic |
Wrappers |
Data Island |
| Awareness |
Yes |
Yes |
Yes |
Maybe |
| Boundary Navigation |
Yes |
Yes |
Yes |
Maybe |
| Seamlessness |
Yes |
Yes |
Maybe |
No |
| Event Propagation |
Yes |
Yes |
Maybe |
No |
| CSS Inheritance |
Maybe |
Maybe |
Maybe |
No |
4.5.5. Requirements
- The EDOM MUST specify an object model that describes the
relationship between host DOM nodes and embedded DOM nodes, as well
as an API or other mechanism with which those relationships can be
specified. This object model MUST co-exist gracefully with the DOM
Level 3 Content Model interfaces and work with validation
operations.
The EDOM MAY specify a mechanism -- such as options in the
Load/Save interfaces -- so that the association between Elements
and embedded DOMs is automatically produced when a document is
loaded.
The EDOM NEED NOT specify the actual mechanism by which the
application actually loads a plug-in.
- The EDOM MUST clarify the relationship between the
ownerDocument property of Nodes in an embedded DOM, the top-level
node in an Embedded DOM, and the Document interface. The standard
DOM object model and API may need to accommodate or even preclude
the situation in which elements inside some embedded markup may
have a different "owner document" and "dom implementation" values
than those at another level of the hierarchy. So far the DOM WG has
recommended that there only ever be one ownerDocument, which is the
same for all nodes.
- For the "monolithic" and "dynamic subclassing" implementation
scenarios, the EDOM MUST specify a mechanism so that an embedded
DOM and a host DOM become aware of each other and support all of
the use cases described above.
- For the "wrapper" implementation scenario, the EDOM MUST
specify a mechanism so that an embedded DOM and a host DOM become
aware of each other and that the boundary between them can be
crossed by an application. It would be desirable for this boundary
crossing to be "seamless", and for events and CSS properties to
propagate automatically across the boundary.
4.5.6. Known
Questions
Ranges are probably out of scope for the EDOM, anyone
disagree?
Do we want to support both a procedural mechanism and a
non-procedural mechanism (something like the HTML <object>
tag) to specify the relationship between the host and embedded
DOM?
(ED: The rest of this section
is a bit of a grab bag for ideas we will have to consider when it
comes time to work on the actual specification that meets these
requirements. )
Do we have two DOM trees, one for the generic DOM, and one for
the specialized DOM? (The sentiment at the Redwood Shores F2F was
"no").
How do you know when to hand control over to embedded DOM? Does
getChildNodes() and getParentNode() throw a new exception?
What sort of node should the top-level embedded node be? If it
is a special node that is a "document" in some sense but a child of
another in other senses, that would help. But it does need to be an
element rather than a document, so that the ownerDocument is
consistent throughout the complete document, including the embedded
fragment.
How do you get a handle to a DOMImplementation object without a
Document object ... we may need to solve the bootstrapping
problem.
The embedded DOM API needs to add something like a
createMyTopLevelElement from a Core DOM element, or maybe from a
string. The string method, while not as elegant, is more likely to
work across different languages and platforms.
What happens if a node from the embedded DOM tree is moved
outside the embedded DOM tree? Is this possible?
What about recursive embedded DOMs? Including the case where
XHTML is within SVG is within XHTML.