Check Update

Document Object Model (DOM) Specifications
  • Document Object Model Requirements
  • Document Object Model Level 1
  • Document Object Model Level 2 Core
  • Document Object Model Level 2 Views
  • Document Object Model Level 2 Events
  • Document Object Model Level 2 Style
  • Document Object Model Level 2 Traversal and Range
  • Document Object Model Level 2 HTML
  • Document Object Model Level 3 Core
  • Document Object Model Level 3 Load and Save
  • Document Object Model Level 3 Validation
  • Document Object Model Level 3 XPath
  • Document Object Model Level 3 Views and Formatting
  • Document Object Model Level 3 Events
  • Document Object Model Level 3 Abstract Schemas


Document Object Model Requirements

Document Object Model (DOM) Requirements

W3C Working Group Note 26 February 2004

This version:
http://www.w3.org/TR/2004/NOTE-DOM-Requirements-20040226
Latest version:
http://www.w3.org/TR/DOM-Requirements
Previous version:
http://www.w3.org/TR/2001/WD-DOM-Requirements-20010419
Editors:
Ben Chang, Oracle
Philippe Le Hégaret, W3C
Arnaud Le Hors, IBM
Ray Whitmer, Invited Expert, chair
Mike Champion, Software AG (until 2003)
Tom Pixley, Netscape Communications Corporation (until July 2002)
Joe Kesselman, IBM (until 2001)
Andy Heninger, IBM (until 2001)
Angel Diaz, IBM (until 2001)
James Davidson, Sun (until June 2000)
Lauren Wood, SoftQuad Software Inc. (until November 2000)
Jared Sorensen, Novell, Inc. (until January 1999)

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

Abstract

This document contains the requirements for the Document Object Model, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model provides a standard set of objects for representing HTML and XML documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating them. Vendors can support the DOM as an interface to their proprietary data structures and APIs, and content authors can write to the standard DOM interfaces rather than product-specific APIs, thus increasing interoperability on the Web.

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 Group Note of the requirements of the Document Object Model. Comments on this document are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/. A list of open issues has been published on 23 October 2001. Note that W3C is not committed to work on the open issues.

Publication as a Working Group Note 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.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.

Patent disclosures relevant to this specification may be found on the DOM Working Group's patent disclosure page.

Table of Contents

  • Table of Contents
  • Chapter 1: General requirements
    • 1.1 Basic requirements
    • 1.2 Error Reporting
  • Chapter 2: DOM Level 1 Requirements
    • 2.1 Structure Navigation
      • 2.1.1 General Requirements
      • 2.1.2 HTML Requirements
    • 2.2 Document Manipulation
    • 2.3 Content Manipulation
  • Chapter 3: DOM Level 2 Requirements
    • 3.1 Event Model
    • 3.2 Stylesheet Object Model
    • 3.3 Range model
    • 3.4 Traversal model
  • Chapter 4: DOM Level 3 Requirements
    • 4.1 Core Requirements
    • 4.2 Level 3 Events Requirements
      • 4.2.1 EventListener grouping
      • 4.2.2 Key event set
      • 4.2.3 Input event set
      • 4.2.4 Device independent event set
    • 4.3 Content Models and Validation Use Cases and Requirements
    • 4.4 Load and Save Requirements
      • 4.4.1 General Requirements
      • 4.4.2 Load Requirements
      • 4.4.3 XML Writer Requirements
      • 4.4.4 Other Items Under Consideration
    • 4.5 Embedded DOM Requirements
      • 4.5.1 Abstract
      • 4.5.2 Introduction
      • 4.5.3 Use Cases
      • 4.5.4 Implementation Scenarios
      • 4.5.5 Requirements
      • 4.5.6 Known Questions
    • 4.6 XPath DOM Draft Requirements
      • 4.6.1 Abstract
      • 4.6.2 Introduction
      • 4.6.3 Requirements
      • 4.6.4 Known Questions

1. General requirements

1.1 Basic requirements

  1. References to XML and HTML documents generally denote the physical files that contain structural markup.
  2. Where possible, the Level of the DOM in which the requirements are met is noted.

Listed below are the general requirements of the Document Object Model.

  1. The Object Model is language neutral and platform independent.
  2. There will be a core DOM that is applicable to HTML, CSS and XML documents.
  3. The Object Model can be used to construct and deconstruct the document.
  4. The Object Model will not preclude use by either agents external to the document content, or scripts embedded within the document.
  5. Consistent naming conventions must be used through all levels of the Object Model.
  6. A visual UI component will not be required for a conforming implementation of the Object Model.
  7. The specific HTML, CSS or XML document object models will be driven by the underlying constructs of those languages.
  8. It must be possible to read in a document and write out a structurally isomorphic document.
  9. The Object Model will not expose the user to problems with security, validity, or privacy.
  10. The Object Model will not preclude other mechanisms for manipulating documents.

1.2 Error Reporting

  1. Error reporting will be primarily via return values. Exceptions will be raised on unrecoverable conditions.
  2. The DOM will provide a document-wide reporting mechanism. [After Level 1]
  3. The DOM error state can be queried. [After Level 1]

2. DOM Level 1 Requirements

2.1 Structure Navigation

This refers to the navigation around a document, such as finding the parent of a given element, or what children elements a given parent element contains.

2.1.1 General Requirements

  1. All document content, including elements and attributes, will be programmatically accessible and manipulable.
  2. Navigation from any element to any other element will be possible.
  3. There will be a way to uniquely and reproducibly enumerate the structure of static documents.
  4. There will be a way to query for elements and attributes. [After Level 1]
  5. Basic low-level functions (get first, get next, etc.) will be provided, along with convenience functions that build upon them, but have a consistent access method.

2.1.2 HTML Requirements

These are specific to HTML document.

  1. All elements that are defined in the HTML 4.0 specification are exposed. User agents may expose other elements using similar interfaces.
  2. Unknown tags and attributes are exposed.
  3. Implied elements are exposed even if not explicitly defined in the document (e.g., HTML, HEAD, BODY).

2.2 Document Manipulation

  1. There will be a way to add, remove and change elements and/or tags in the document structure.
  2. There will be a way to add, remove and change attributes in the document structure.
  3. Operations (or a combination of operations) must restore consistency before they return.
  4. A valid static document acted upon by the DOM will deliver a consistent reproducible document structure.

2.3 Content Manipulation

  1. There will be a way to determine the containing element from any text part of the document.
  2. There will be a way to manipulate (add, change, delete) content.
  3. There will be a way to navigate content.

3. DOM Level 2 Requirements

3.1 Event Model

The event model must be rich enough to create completely interactive documents. This requires the ability to respond to any user action that may occur on the document. Therefore, many of these requirements only apply if a UI component is involved.

  1. All elements will be capable of generating events.
  2. There will be user interface events, mutation events, and logical events.
  3. The event delivery mechanism will allow for overriding of default behavior.
  4. The event model will provide a mechanism by which events for specific elements may be received by an ancestor in the DOM hierarchy.
  5. Events may be synchronous.
  6. Events will be defined in a platform independent and language neutral way.
  7. There will be an interface for binding to events.

3.2 Stylesheet Object Model

Cascading Style Sheets (CSS) is one model for manipulating the style of the document. The Stylesheet Object Model exposes the ability to create, modify, and associate CSS style sheets with the document. The stylesheet model will be extensible to other stylesheet formats in the future.

  1. All style sheets will be represented in the object model.
  2. There will be a CSS stylesheet model. The CSS object model will be defined as part of a stylesheet embedding model, where the core part of the model may be applicable to other style languages.
  3. Selectors, rules and properties of individual style sheets can be added, removed and changed.
  4. All elements of a CSS style can be added, removed, and changed in the object model. This includes but is not limited to:
    1. linked style sheets
    2. imported style sheets
    3. alternative style sheets
    4. CSS pseudo-classes and CSS pseudo-elements
    5. contextual selectors
    6. inline styles
    7. all properties as defined in the CSS specification, including but not limited to font properties, colors, backgrounds, and box properties.

3.3 Range model

Linear view
allows querying and editing functionality based on a range of text rather than a subtree of Nodes.
Live
edits on the range modify the underlying tree
Low Level
no parser, no relationship to user agent, no convenience methods or range comparison methods (these would be part of the SmartRange interface)

The DOM Range API should support the following types of operations on ranges:

  • Creating a Range object
  • Extracting text from a Range (with or without markup)
  • Inserting, Deleting text inside the Range
  • Inserting, Deleting document structure inside the Range

3.4 Traversal model

The DOM Traversal API should be able to see a filtered view without comments or entity references, and to have an iterator robust under mutation.

4. DOM Level 3 Requirements

4.1 Core Requirements

Here are the items that will be addressed:

  • getting the text content as a single DOMString from a section of a document.
  • moving (not copying!) a node from one document to another. DOM Level 2 provides an importNode method that copies a node from one document to another, it would be useful to have a way of simply moving a node, even though in some cases, such as across implementations, it may fail.
  • node ordering. Is this node before that one in document order? Although this can be done on top of the DOM Level 2, having it as part of the DOM would provide for possible optimisations.
  • whitespace in element content (a.k.a. "ignorable whitespace"). Does this Text node only contain whitespace in element content?
  • exposing the XML and Text declarations.
  • exposing the base URI of a node (part of the XML Infoset)
  • node identity. Is this object the same node as that one?
  • namespace lookup. DOM Level 2 is based on an early binding model and the implementation does not provide any lookup mechanism.
  • namespace fixup. DOM Level 2 is based on an early binding model and the implementation does not fix the namespace declarations as nodes are moved around or inserted.
  • bootstrapping a DOM in Java. How does one get a hand on a DOMImplementation class?
  • provide for readonly DOMs.
  • allow methods to raise other exceptions. So that for instance insertBefore can fail because of a DTD pb.

Here are other items that will be considered:

  • a way to turn off error checking, so that better performance can be achieved, such as when the DOM is built from a parser which already performs error checking.
  • a way to attach some user data to a node.
  • node equality and hashcode
  • getElementsByAttributeValue.
  • a way to allow text documents

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.

4.2.3 Input event set

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 DOM 3 Requirements and View Use Cases (member-only link) 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:

  1. CU1. Modify an existing content model.
  2. CU2. Associating a content model (external and/or internal) with a document, or changing the current association.
  3. CU3. Using the same external content model with several documents, without having to reload it.
  4. CU4. Create a new content model.

Requirements:

  1. CR1. Validate against the content model.
  2. CR2. Retrieve information from content model.
  3. CR3. Load an existing content model, perhaps independently from a document.
  4. CR4. Being able to determine if a document has a content model associated with it.
  5. CR5. Create a new content model object.
  6. 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:

  1. CMU1. Clone/map all or parts of an existing content model to a new or existing content model.
  2. 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.
  3. CMU3. Partial content model checking. For example, only certain portions of the content model need be validated.

Requirements:

  1. CMR1. View and modify all parts of the content model.
  2. CMR2. Validate the content model itself. For example, if an element/attribute is inserted incorrectly into the content model.
  3. CMR3. Serialize the content model.
  4. CMR4. Clone all or parts of an existing content model.
  5. 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:

  1. DU1. For editing documents with an associated content model, provide the assistance necessary so that valid documents can be modified and remain valid.
  2. DU2. For editing documents with an associated content model, provide the assistance necessary to transform an invalid document into a valid one.

Requirements:

  1. DR1. Being able to determine if the document is not well-formed, and if not, be given enough assistance to locate the error.
  2. DR2. Being able to determine if the document is not namespace well-formed, and if not, be given enough assistance to locate the error.
  3. 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.
  4. DR4. Being able to determine if specific modifications to a document would make it become invalid.
  5. DR5. Retrieve information from all content model. For example, getting a list of all the defined element names for document editing purposes.

General Issues:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

4.6 XPath DOM Draft Requirements

4.6.1 Abstract

There is a widely-perceived need to offer a vendor-neutral way to use XPath expressions to select matching nodes in a DOM document. A module of DOM, which we shall refer to by the shorthand name "XPATH", will address this issue.

4.6.2 Introduction

Levels 1 and 2 of the DOM has some functionality to allow specific nodes to be located without the user having to navigate through the DOM tree, notably getElementsByTagName and getElementById. The Working Group's intention was to add these very limited APIs as a stop-gap until an XML-aware "query" language was available. While not by any means a complete XML query language, XPath does provide a syntax for locating XML content by value and has been a W3C Recommendation since November, 1999. Various DOM implementations support APIs that allow one or more nodes to be located via an XPath expression, and there have been a number of calls from the user community to incorporate this capability into the DOM Level 3 Recommendation.

A semi-public mailing list was established in early 2000 to solicit input and advice (the archives can be viewed at http://lists.w3.org/Archives/Public/www-dom-xpath). The comments on this list tended to push for a quite complete XPath API rather than the quite limited interfaces provided by existing DOM implementations. Since this is out of scope for the DOM WG, efforts were made to find another W3C Working Group to take on this requirement. Those efforts have not been successful.

Thus, it falls to the DOM WG to define a simple but effective API for DOM that provides a basis for writing interoperable DOM applications that use XPath expressions rather than tree navigation to locate nodes matching simple search criteria.

4.6.3 Requirements

  1. The DOM XPATH module MUST provide one or more methods to allow a set of nodes matching an XPath expression to be identified.
  2. The DOM XPATH module MUST provide a mechanism so that the namespace context of the XPath expression can be specified, that is, so that any namespace prefixes in the XPath expression can be resolved.
  3. The DOM XPATH module MUST use the same data model as XPath itself. There are some subtle differences between the XPath data model and the DOM data model (e.g., the ownerDocument vs parentNode property to describe the Element containing an Attribute, the absence of CDATA marked sections in the XPath model, etc.). Since a combined XPath/XSLT/XQuery data model will be defined in the XPath 2.0 timeframe, it may not be possible to define a DOM XPATH module until the XPath 2.0 data model is reasonably stable. In any event, the XPATH DOM must be defined in close coordination with the other working groups addressing this issue.
  4. The DOM XPATH interfaces SHOULD be based as much as possible on the ideas and experiences of DOM implementers that have added XPath extensions.
  5. The DOM XPATH interfaces SHOULD NOT return a "live" object, but should return a list or iterator that will either reflect a snapshot of the DOM tree at the moment the XPath query was evaluated or will become invalidated if changes to the DOM tree could affect its contents.

4.6.4 Known Questions

  1. It is an open issue whether the DOM WG should wait for the XPath 2.0 data model to emerge, or whether some interim solution for the XPath 1.0 data model (mapped onto the DOM data model) is preferable.
  2. T he obvious place to put an XPath method is on the Node interface, but we presumably do not want to make this required for DOM compliance. (We suspect that the XPath module would be implemented primarily by vendors already implementing XSLT, and could be quite burdensome for other developers to support).
  3. Do we want to put any requirements on the type of object returned by an XPath locator? NodeLists are "live", which could cause problems for implementers. NodeIterators are perhaps more appropriate, but are not supported by existing XPath extensions to the DOM.
  4. What about other contextual factors besides namespaces? Do we want to allow variables and non-standard functions to be defined to the XPath engine?


Chapter 1: General requirements

Document Object Model (DOM) Requirements

W3C Working Group Note 26 February 2004

This version:
http://www.w3.org/TR/2004/NOTE-DOM-Requirements-20040226
Latest version:
http://www.w3.org/TR/DOM-Requirements
Previous version:
http://www.w3.org/TR/2001/WD-DOM-Requirements-20010419
Editors:
Ben Chang, Oracle
Philippe Le Hégaret, W3C
Arnaud Le Hors, IBM
Ray Whitmer, Invited Expert, chair
Mike Champion, Software AG (until 2003)
Tom Pixley, Netscape Communications Corporation (until July 2002)
Joe Kesselman, IBM (until 2001)
Andy Heninger, IBM (until 2001)
Angel Diaz, IBM (until 2001)
James Davidson, Sun (until June 2000)
Lauren Wood, SoftQuad Software Inc. (until November 2000)
Jared Sorensen, Novell, Inc. (until January 1999)

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

Abstract

This document contains the requirements for the Document Object Model, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model provides a standard set of objects for representing HTML and XML documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating them. Vendors can support the DOM as an interface to their proprietary data structures and APIs, and content authors can write to the standard DOM interfaces rather than product-specific APIs, thus increasing interoperability on the Web.

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 Group Note of the requirements of the Document Object Model. Comments on this document are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/. A list of open issues has been published on 23 October 2001. Note that W3C is not committed to work on the open issues.

Publication as a Working Group Note 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.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.

Patent disclosures relevant to this specification may be found on the DOM Working Group's patent disclosure page.

Table of Contents

  • Table of Contents
  • Chapter 1: General requirements
    • 1.1 Basic requirements
    • 1.2 Error Reporting
  • Chapter 2: DOM Level 1 Requirements
    • 2.1 Structure Navigation
      • 2.1.1 General Requirements
      • 2.1.2 HTML Requirements
    • 2.2 Document Manipulation
    • 2.3 Content Manipulation
  • Chapter 3: DOM Level 2 Requirements
    • 3.1 Event Model
    • 3.2 Stylesheet Object Model
    • 3.3 Range model
    • 3.4 Traversal model
  • Chapter 4: DOM Level 3 Requirements
    • 4.1 Core Requirements
    • 4.2 Level 3 Events Requirements
      • 4.2.1 EventListener grouping
      • 4.2.2 Key event set
      • 4.2.3 Input event set
      • 4.2.4 Device independent event set
    • 4.3 Content Models and Validation Use Cases and Requirements
    • 4.4 Load and Save Requirements
      • 4.4.1 General Requirements
      • 4.4.2 Load Requirements
      • 4.4.3 XML Writer Requirements
      • 4.4.4 Other Items Under Consideration
    • 4.5 Embedded DOM Requirements
      • 4.5.1 Abstract
      • 4.5.2 Introduction
      • 4.5.3 Use Cases
      • 4.5.4 Implementation Scenarios
      • 4.5.5 Requirements
      • 4.5.6 Known Questions
    • 4.6 XPath DOM Draft Requirements
      • 4.6.1 Abstract
      • 4.6.2 Introduction
      • 4.6.3 Requirements
      • 4.6.4 Known Questions

1. General requirements

1.1 Basic requirements

  1. References to XML and HTML documents generally denote the physical files that contain structural markup.
  2. Where possible, the Level of the DOM in which the requirements are met is noted.

Listed below are the general requirements of the Document Object Model.

  1. The Object Model is language neutral and platform independent.
  2. There will be a core DOM that is applicable to HTML, CSS and XML documents.
  3. The Object Model can be used to construct and deconstruct the document.
  4. The Object Model will not preclude use by either agents external to the document content, or scripts embedded within the document.
  5. Consistent naming conventions must be used through all levels of the Object Model.
  6. A visual UI component will not be required for a conforming implementation of the Object Model.
  7. The specific HTML, CSS or XML document object models will be driven by the underlying constructs of those languages.
  8. It must be possible to read in a document and write out a structurally isomorphic document.
  9. The Object Model will not expose the user to problems with security, validity, or privacy.
  10. The Object Model will not preclude other mechanisms for manipulating documents.

1.2 Error Reporting

  1. Error reporting will be primarily via return values. Exceptions will be raised on unrecoverable conditions.
  2. The DOM will provide a document-wide reporting mechanism. [After Level 1]
  3. The DOM error state can be queried. [After Level 1]

2. DOM Level 1 Requirements

2.1 Structure Navigation

This refers to the navigation around a document, such as finding the parent of a given element, or what children elements a given parent element contains.

2.1.1 General Requirements

  1. All document content, including elements and attributes, will be programmatically accessible and manipulable.
  2. Navigation from any element to any other element will be possible.
  3. There will be a way to uniquely and reproducibly enumerate the structure of static documents.
  4. There will be a way to query for elements and attributes. [After Level 1]
  5. Basic low-level functions (get first, get next, etc.) will be provided, along with convenience functions that build upon them, but have a consistent access method.

2.1.2 HTML Requirements

These are specific to HTML document.

  1. All elements that are defined in the HTML 4.0 specification are exposed. User agents may expose other elements using similar interfaces.
  2. Unknown tags and attributes are exposed.
  3. Implied elements are exposed even if not explicitly defined in the document (e.g., HTML, HEAD, BODY).

2.2 Document Manipulation

  1. There will be a way to add, remove and change elements and/or tags in the document structure.
  2. There will be a way to add, remove and change attributes in the document structure.
  3. Operations (or a combination of operations) must restore consistency before they return.
  4. A valid static document acted upon by the DOM will deliver a consistent reproducible document structure.

2.3 Content Manipulation

  1. There will be a way to determine the containing element from any text part of the document.
  2. There will be a way to manipulate (add, change, delete) content.
  3. There will be a way to navigate content.

3. DOM Level 2 Requirements

3.1 Event Model

The event model must be rich enough to create completely interactive documents. This requires the ability to respond to any user action that may occur on the document. Therefore, many of these requirements only apply if a UI component is involved.

  1. All elements will be capable of generating events.
  2. There will be user interface events, mutation events, and logical events.
  3. The event delivery mechanism will allow for overriding of default behavior.
  4. The event model will provide a mechanism by which events for specific elements may be received by an ancestor in the DOM hierarchy.
  5. Events may be synchronous.
  6. Events will be defined in a platform independent and language neutral way.
  7. There will be an interface for binding to events.

3.2 Stylesheet Object Model

Cascading Style Sheets (CSS) is one model for manipulating the style of the document. The Stylesheet Object Model exposes the ability to create, modify, and associate CSS style sheets with the document. The stylesheet model will be extensible to other stylesheet formats in the future.

  1. All style sheets will be represented in the object model.
  2. There will be a CSS stylesheet model. The CSS object model will be defined as part of a stylesheet embedding model, where the core part of the model may be applicable to other style languages.
  3. Selectors, rules and properties of individual style sheets can be added, removed and changed.
  4. All elements of a CSS style can be added, removed, and changed in the object model. This includes but is not limited to:
    1. linked style sheets
    2. imported style sheets
    3. alternative style sheets
    4. CSS pseudo-classes and CSS pseudo-elements
    5. contextual selectors
    6. inline styles
    7. all properties as defined in the CSS specification, including but not limited to font properties, colors, backgrounds, and box properties.

3.3 Range model

Linear view
allows querying and editing functionality based on a range of text rather than a subtree of Nodes.
Live
edits on the range modify the underlying tree
Low Level
no parser, no relationship to user agent, no convenience methods or range comparison methods (these would be part of the SmartRange interface)

The DOM Range API should support the following types of operations on ranges:

  • Creating a Range object
  • Extracting text from a Range (with or without markup)
  • Inserting, Deleting text inside the Range
  • Inserting, Deleting document structure inside the Range

3.4 Traversal model

The DOM Traversal API should be able to see a filtered view without comments or entity references, and to have an iterator robust under mutation.

4. DOM Level 3 Requirements

4.1 Core Requirements

Here are the items that will be addressed:

  • getting the text content as a single DOMString from a section of a document.
  • moving (not copying!) a node from one document to another. DOM Level 2 provides an importNode method that copies a node from one document to another, it would be useful to have a way of simply moving a node, even though in some cases, such as across implementations, it may fail.
  • node ordering. Is this node before that one in document order? Although this can be done on top of the DOM Level 2, having it as part of the DOM would provide for possible optimisations.
  • whitespace in element content (a.k.a. "ignorable whitespace"). Does this Text node only contain whitespace in element content?
  • exposing the XML and Text declarations.
  • exposing the base URI of a node (part of the XML Infoset)
  • node identity. Is this object the same node as that one?
  • namespace lookup. DOM Level 2 is based on an early binding model and the implementation does not provide any lookup mechanism.
  • namespace fixup. DOM Level 2 is based on an early binding model and the implementation does not fix the namespace declarations as nodes are moved around or inserted.
  • bootstrapping a DOM in Java. How does one get a hand on a DOMImplementation class?
  • provide for readonly DOMs.
  • allow methods to raise other exceptions. So that for instance insertBefore can fail because of a DTD pb.

Here are other items that will be considered:

  • a way to turn off error checking, so that better performance can be achieved, such as when the DOM is built from a parser which already performs error checking.
  • a way to attach some user data to a node.
  • node equality and hashcode
  • getElementsByAttributeValue.
  • a way to allow text documents

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.

4.2.3 Input event set

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 DOM 3 Requirements and View Use Cases (member-only link) 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:

  1. CU1. Modify an existing content model.
  2. CU2. Associating a content model (external and/or internal) with a document, or changing the current association.
  3. CU3. Using the same external content model with several documents, without having to reload it.
  4. CU4. Create a new content model.

Requirements:

  1. CR1. Validate against the content model.
  2. CR2. Retrieve information from content model.
  3. CR3. Load an existing content model, perhaps independently from a document.
  4. CR4. Being able to determine if a document has a content model associated with it.
  5. CR5. Create a new content model object.
  6. 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:

  1. CMU1. Clone/map all or parts of an existing content model to a new or existing content model.
  2. 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.
  3. CMU3. Partial content model checking. For example, only certain portions of the content model need be validated.

Requirements:

  1. CMR1. View and modify all parts of the content model.
  2. CMR2. Validate the content model itself. For example, if an element/attribute is inserted incorrectly into the content model.
  3. CMR3. Serialize the content model.
  4. CMR4. Clone all or parts of an existing content model.
  5. 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:

  1. DU1. For editing documents with an associated content model, provide the assistance necessary so that valid documents can be modified and remain valid.
  2. DU2. For editing documents with an associated content model, provide the assistance necessary to transform an invalid document into a valid one.

Requirements:

  1. DR1. Being able to determine if the document is not well-formed, and if not, be given enough assistance to locate the error.
  2. DR2. Being able to determine if the document is not namespace well-formed, and if not, be given enough assistance to locate the error.
  3. 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.
  4. DR4. Being able to determine if specific modifications to a document would make it become invalid.
  5. DR5. Retrieve information from all content model. For example, getting a list of all the defined element names for document editing purposes.

General Issues:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

4.6 XPath DOM Draft Requirements

4.6.1 Abstract

There is a widely-perceived need to offer a vendor-neutral way to use XPath expressions to select matching nodes in a DOM document. A module of DOM, which we shall refer to by the shorthand name "XPATH", will address this issue.

4.6.2 Introduction

Levels 1 and 2 of the DOM has some functionality to allow specific nodes to be located without the user having to navigate through the DOM tree, notably getElementsByTagName and getElementById. The Working Group's intention was to add these very limited APIs as a stop-gap until an XML-aware "query" language was available. While not by any means a complete XML query language, XPath does provide a syntax for locating XML content by value and has been a W3C Recommendation since November, 1999. Various DOM implementations support APIs that allow one or more nodes to be located via an XPath expression, and there have been a number of calls from the user community to incorporate this capability into the DOM Level 3 Recommendation.

A semi-public mailing list was established in early 2000 to solicit input and advice (the archives can be viewed at http://lists.w3.org/Archives/Public/www-dom-xpath). The comments on this list tended to push for a quite complete XPath API rather than the quite limited interfaces provided by existing DOM implementations. Since this is out of scope for the DOM WG, efforts were made to find another W3C Working Group to take on this requirement. Those efforts have not been successful.

Thus, it falls to the DOM WG to define a simple but effective API for DOM that provides a basis for writing interoperable DOM applications that use XPath expressions rather than tree navigation to locate nodes matching simple search criteria.

4.6.3 Requirements

  1. The DOM XPATH module MUST provide one or more methods to allow a set of nodes matching an XPath expression to be identified.
  2. The DOM XPATH module MUST provide a mechanism so that the namespace context of the XPath expression can be specified, that is, so that any namespace prefixes in the XPath expression can be resolved.
  3. The DOM XPATH module MUST use the same data model as XPath itself. There are some subtle differences between the XPath data model and the DOM data model (e.g., the ownerDocument vs parentNode property to describe the Element containing an Attribute, the absence of CDATA marked sections in the XPath model, etc.). Since a combined XPath/XSLT/XQuery data model will be defined in the XPath 2.0 timeframe, it may not be possible to define a DOM XPATH module until the XPath 2.0 data model is reasonably stable. In any event, the XPATH DOM must be defined in close coordination with the other working groups addressing this issue.
  4. The DOM XPATH interfaces SHOULD be based as much as possible on the ideas and experiences of DOM implementers that have added XPath extensions.
  5. The DOM XPATH interfaces SHOULD NOT return a "live" object, but should return a list or iterator that will either reflect a snapshot of the DOM tree at the moment the XPath query was evaluated or will become invalidated if changes to the DOM tree could affect its contents.

4.6.4 Known Questions

  1. It is an open issue whether the DOM WG should wait for the XPath 2.0 data model to emerge, or whether some interim solution for the XPath 1.0 data model (mapped onto the DOM data model) is preferable.
  2. T he obvious place to put an XPath method is on the Node interface, but we presumably do not want to make this required for DOM compliance. (We suspect that the XPath module would be implemented primarily by vendors already implementing XSLT, and could be quite burdensome for other developers to support).
  3. Do we want to put any requirements on the type of object returned by an XPath locator? NodeLists are "live", which could cause problems for implementers. NodeIterators are perhaps more appropriate, but are not supported by existing XPath extensions to the DOM.
  4. What about other contextual factors besides namespaces? Do we want to allow variables and non-standard functions to be defined to the XPath engine?


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
  • What is the Document Object Model?
    • Introduction
    • What the Document Object Model is
    • What the Document Object Model is not
    • Where the Document Object Model came from
    • Entities and the DOM Core
    • DOM Interfaces and DOM Implementations
    • Limitations of Level 1

  • Chapter 1: Document Object Model (Core) Level 1
    • 1.1. Overview of the DOM Core Interfaces
      • 1.1.1. The DOM Structure Model
      • 1.1.2. Memory Management
      • 1.1.3. Naming Conventions
      • 1.1.4. Inheritance vs Flattened Views of the API
      • 1.1.5. The DOMString type
      • 1.1.6. Case sensitivity in the DOM
    • 1.2. Fundamental Interfaces
    • 1.3. Extended Interfaces
  • Chapter 2: Document Object Model (HTML) Level 1
    • 2.1. Introduction
    • 2.2. HTML Application of Core DOM
      • 2.2.1. Naming Conventions
    • 2.3. Miscellaneous Object Definitions
    • 2.4. Objects related to HTML documents
    • 2.5. HTML Elements
      • 2.5.1. Property Attributes
      • 2.5.2. Naming Exceptions
      • 2.5.3. Exposing Element Type Names (tagName)
      • 2.5.4. The HTMLElement interface
      • 2.5.5. Object definitions

  • Appendix A: Contributors
  • Appendix B: Glossary
  • Appendix C: IDL Definitions
    • C.1. Document Object Model Level 1 Core
    • C.2. Document Object Model Level 1 HTML
  • Appendix D: Java Language Binding
    • D.1. Document Object Model Level 1 Core
    • D.2. Document Object Model Level 1 HTML
  • Appendix E: ECMA Script Language Binding
    • E.1. Document Object Model Level 1 Core
    • E.2. Document Object Model Level 1 HTML
  • References
  • Index
  • Production Notes (Non-Normative)
    • 1. The Document Type Definition
    • 2. The production process
    • 3. Object Definitions

REC-DOM-Level-1-19981001 Copyright Notice


Copyright Notice

Copyright © 1998 World Wide Web Consortium , (Massachusetts Institute of Technology , Institut National de Recherche en Informatique et en Automatique , Keio University ). All Rights Reserved.

Documents on the W3C site are provided by the copyright holders under the following license. By obtaining, using and/or copying this document, or the W3C document from which this statement is linked, you agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URI to the original W3C document.
  2. The pre-existing copyright notice of the original author, if it doesn't exist, a notice of the form: "Copyright © World Wide Web Consortium , (Massachusetts Institute of Technology , Institut National de Recherche en Informatique et en Automatique , Keio University ). All Rights Reserved."
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. In addition, credit shall be attributed to the copyright holders for any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives is granted pursuant to this license.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

Expanded Table of Contents REC-DOM-Level-1-19981001 What is the Document Object Model?


What is the Document Object Model?

Editors
Jonathan Robie, Texcel Research

Introduction

The Document Object Model (DOM) is an application programming interface (API) for HTML and XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term "document" is used in the broad sense - increasingly, XML is being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

With the Document Object Model, programmers can build documents, navigate their structure, and add, modify, or delete elements and content. Anything found in an HTML or XML document can be accessed, changed, deleted, or added using the Document Object Model, with a few exceptions - in particular, the DOM interfaces for the XML internal and external subsets have not yet been specified.

As a W3C specification, one important objective for the Document Object Model is to provide a standard programming interface that can be used in a wide variety of environments and applications. The DOM is designed to be used with any programming language. In order to provide a precise, language-independent specification of the DOM interfaces, we have chosen to define the specifications in OMG IDL, as defined in the CORBA 2.2 specification. In addition to the OMG IDL specification, we provide language bindings for Java and ECMAScript (an industry-standard scripting language based on JavaScript and JScript). Note: OMG IDL is used only as a language-independent and implementation-neutral way to specify interfaces. Various other IDLs could have been used. In general, IDLs are designed for specific computing environments. The Document Object Model can be implemented in any computing environment, and does not require the object binding runtimes generally associated with such IDLs.

What the Document Object Model is

The DOM is a programming API for documents. It closely resembles the structure of the documents it models. For instance, consider this table, taken from an HTML document:

      <TABLE>
      <TBODY>
      <TR>
      <TD>Shady Grove</TD>
      <TD>Aeolian</TD>
      </TR>
      <TR>
      <TD>Over the River, Charlie</TD>
      <TD>Dorian</TD>
      </TR>
      </TBODY>
      </TABLE>

The DOM represents this table like this:

DOM representation of the example table
DOM representation of the example table

In the DOM, documents have a logical structure which is very much like a tree; to be more precise, it is like a "forest" or "grove", which can contain more than one tree. However, the DOM does not specify that documents must be implemented as a tree or a grove, nor does it specify how the relationships among objects be implemented. The DOM is a logical model that may be implemented in any convenient manner. In this specification, we use the term structure model to describe the tree-like representation of a document; we specifically avoid terms like "tree" or "grove" in order to avoid implying a particular implementation. One important property of DOM structure models is structural isomorphism: if any two Document Object Model implementations are used to create a representation of the same document, they will create the same structure model, with precisely the same objects and relationships.

The name "Document Object Model" was chosen because it is an "object model" in the traditional object oriented design sense: documents are modeled using objects, and the model encompasses not only the structure of a document, but also the behavior of a document and the objects of which it is composed. In other words, the nodes in the above diagram do not represent a data structure, they represent objects, which have functions and identity. As an object model, the DOM identifies:

  • the interfaces and objects used to represent and manipulate a document
  • the semantics of these interfaces and objects - including both behavior and attributes
  • the relationships and collaborations among these interfaces and objects

The structure of SGML documents has traditionally been represented by an abstract data model, not by an object model. In an abstract data model, the model is centered around the data. In object oriented programming languages, the data itself is encapsulated in objects that hide the data, protecting it from direct external manipulation. The functions associated with these objects determine how the objects may be manipulated, and they are part of the object model.

The Document Object Model currently consists of two parts, DOM Core and DOM HTML. The DOM Core represents the functionality used for XML documents, and also serves as the basis for DOM HTML. A compliant implementation of the DOM must implement all of the fundamental interfaces in the Core chapter with the semantics as defined. Further, it must implement at least one of the HTML DOM and the extended (XML) interfaces with the semantics as defined.

What the Document Object Model is not

This section is designed to give a more precise understanding of the DOM by distinguishing it from other systems that may seem to be like it.

  • Although the Document Object Model was strongly influenced by "Dynamic HTML", in Level 1, it does not implement all of "Dynamic HTML". In particular, events have not yet been defined. Level 1 is designed to lay a firm foundation for this kind of functionality by providing a robust, flexible model of the document itself.
  • The Document Object Model is not a binary specification. DOM programs written in the same language will be source code compatible across platforms, but the DOM does not define any form of binary interoperability.
  • The Document Object Model is not a way of persisting objects to XML or HTML. Instead of specifying how objects may be represented in XML, the DOM specifies how XML and HTML documents are represented as objects, so that they may be used in object oriented programs.
  • The Document Object Model is not a set of data structures, it is an object model that specifies interfaces. Although this document contains diagrams showing parent/child relationships, these are logical relationships defined by the programming interfaces, not representations of any particular internal data structures.
  • The Document Object Model does not define "the true inner semantics" of XML or HTML. The semantics of those languages are defined by W3C Recommendations for these languages. The DOM is a programming model designed to respect these semantics. The DOM does not have any ramifications for the way you write XML and HTML documents; any document that can be written in these languages can be represented in the DOM.
  • The Document Object Model, despite its name, is not a competitor to the Component Object Model (COM). COM, like CORBA, is a language independent way to specify interfaces and objects; the DOM is a set of interfaces and objects designed for managing HTML and XML documents. The DOM may be implemented using language-independent systems like COM or CORBA; it may also be implemented using language-specific bindings like the Java or ECMAScript bindings specified in this document.

Where the Document Object Model came from

The DOM originated as a specification to allow JavaScript scripts and Java programs to be portable among Web browsers. "Dynamic HTML" was the immediate ancestor of the Document Object Model, and it was originally thought of largely in terms of browsers. However, when the DOM Working Group was formed at W3C, it was also joined by vendors in other domains, including HTML or XML editors and document repositories. Several of these vendors had worked with SGML before XML was developed; as a result, the DOM has been influenced by SGML Groves and the HyTime standard. Some of these vendors had also developed their own object models for documents in order to provide an API for SGML/XML editors or document repositories, and these object models have also influenced the DOM.

Entities and the DOM Core

In the fundamental DOM interfaces, there are no objects representing entities. Numeric character references, and references to the pre-defined entities in HTML and XML, are replaced by the single character that makes up the entity's replacement. For example, in:

        <p>This is a dog &amp; a cat</p>
the "&amp;" will be replaced by the character "&", and the text in the P element will form a single continuous sequence of characters. Since numeric character references and pre-defined entities are not recognized as such in CDATA sections, or the SCRIPT and STYLE elements in HTML, they are not replaced by the single character they appear to refer to. If the example above were enclosed in a CDATA section, the "&amp;" would not be replaced by "&"; neither would the <p> be recognized as a start tag. The representation of general entities, both internal and external, are defined within the extended (XML) interfaces of the Level 1 specification.

Note: When a DOM representation of a document is serialized as XML or HTML text, applications will need to check each character in text data to see if it needs to be escaped using a numeric or pre-defined entity. Failing to do so could result in invalid HTML or XML. Also, implementations should be aware of the fact that serialization into a character encoding ("charset") that does not fully cover ISO 10646 may fail if there are characters in markup or CDATA sections that are not present in the encoding.

DOM Interfaces and DOM Implementations

The DOM specifies interfaces which may be used to manage XML or HTML documents. It is important to realize that these interfaces are an abstraction - much like "abstract base classes" in C++, they are a means of specifying a way to access and manipulate an application's internal representation of a document. Interfaces do not imply a particular concrete implementation. Each DOM application is free to maintain documents in any convenient representation, as long as the interfaces shown in this specification are supported. Some DOM implementations will be existing programs that use the DOM interfaces to access software written long before the DOM specification existed. Therefore, the DOM is designed to avoid implementation dependencies; in particular,

  1. Attributes defined in the IDL do not imply concrete objects which must have specific data members - in the language bindings, they are translated to a pair of get()/set() functions, not to a data member. (Read-only functions have only a get() function in the language bindings).
  2. DOM applications may provide additional interfaces and objects not found in this specification and still be considered DOM compliant.
  3. Because we specify interfaces and not the actual objects that are to be created, the DOM can not know what constructors to call for an implementation. In general, DOM users call the createXXX() methods on the Document class to create document structures, and DOM implementations create their own internal representations of these structures in their implementations of the createXXX() functions.

Limitations of Level 1

The DOM Level 1 specification is intentionally limited to those methods needed to represent and manipulate document structure and content. The plan is for future Levels of the DOM specification to provide:

  1. A structure model for the internal subset and the external subset.
  2. Validation against a schema.
  3. Control for rendering documents via style sheets.
  4. Access control.
  5. Thread-safety.
  6. Events.

Copyright Notice REC-DOM-Level-1-19981001 Document Object Model (Core) Level 1


Document Object Model (Core) Level 1

REC-DOM-Level-1-19981001
What is the Document Object Model? REC-DOM-Level-1-19981001 Document Object Model (HTML) Level 1

1. Document Object Model (Core) Level 1

Editors
Mike Champion, ArborText (from November 20, 1997)
Steve Byrne, JavaSoft (until November 19, 1997)
Gavin Nicol, Inso EPS
Lauren Wood, SoftQuad, Inc.

Table of contents

  • 1.1. Overview of the DOM Core Interfaces
    • 1.1.1. The DOM Structure Model
    • 1.1.2. Memory Management
    • 1.1.3. Naming Conventions
    • 1.1.4. Inheritance vs Flattened Views of the API
    • 1.1.5. The DOMString type
    • 1.1.6. Case sensitivity in the DOM
  • 1.2. Fundamental Interfaces
  • 1.2. Extended Interfaces

1.1. Overview of the DOM Core Interfaces

This section defines a minimal set of objects and interfaces for accessing and manipulating document objects. The functionality specified in this section (the Core functionality) should be sufficient to allow software developers and web script authors to access and manipulate parsed HTML and XML content inside conforming products. The DOM Core API also allows population of a Document object using only DOM API calls; creating the skeleton Document and saving it persistently is left to the product that implements the DOM API.

1.1.1. The DOM Structure Model

The DOM presents documents as a hierarchy of Node objects that also implement other, more specialized interfaces. Some types of nodes may have child nodes of various types, and others are leaf nodes that cannot have anything below them in the document structure. The node types, and which node types they may have as children, are as follows:

  • Document -- Element (maximum of one), ProcessingInstruction, Comment, DocumentType
  • DocumentFragment -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • DocumentType -- no children
  • EntityReference -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Element -- Element, Text, Comment, ProcessingInstruction, CDATASection, EntityReference
  • Attr -- Text, EntityReference
  • ProcessingInstruction -- no children
  • Comment -- no children
  • Text -- no children
  • CDATASection -- no children
  • Entity -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Notation -- no children

The DOM also specifies a NodeList interface to handle ordered lists of Nodes, such as the children of a Node, or the elements returned by the Element.getElementsByTagName method, and also a NamedNodeMap interface to handle unordered sets of nodes referenced by their name attribute, such as the attributes of an Element. NodeLists and NamedNodeMaps in the DOM are "live", that is, changes to the underlying document structure are reflected in all relevant NodeLists and NamedNodeMaps. For example, if a DOM user gets a NodeList object containing the children of an Element, then subsequently adds more children to that element (or removes children, or modifies them), those changes are automatically reflected in the NodeList without further action on the user's part. Likewise changes to a Node in the tree are reflected in all references to that Node in NodeLists and NamedNodeMaps.

1.1.2. Memory Management

Most of the APIs defined by this specification are interfaces rather than classes. That means that an actual implementation need only expose methods with the defined names and specified operation, not actually implement classes that correspond directly to the interfaces. This allows the DOM APIs to be implemented as a thin veneer on top of legacy applications with their own data structures, or on top of newer applications with different class hierarchies. This also means that ordinary constructors (in the Java or C++ sense) cannot be used to create DOM objects, since the underlying objects to be constructed may have little relationship to the DOM interfaces. The conventional solution to this in object-oriented design is to define factory methods that create instances of objects that implement the various interfaces. In the DOM Level 1, objects implementing some interface "X" are created by a "createX()" method on the Document interface; this is because all DOM objects live in the context of a specific Document.

The DOM Level 1 API does not define a standard way to create DOMImplementation or Document objects; actual DOM implementations must provide some proprietary way of bootstrapping these DOM interfaces, and then all other objects can be built from the Create methods on Document (or by various other convenience methods).

The Core DOM APIs are designed to be compatible with a wide range of languages, including both general-user scripting languages and the more challenging languages used mostly by professional programmers. Thus, the DOM APIs need to operate across a variety of memory management philosophies, from language platforms that do not expose memory management to the user at all, through those (notably Java) that provide explicit constructors but provide an automatic garbage collection mechanism to automatically reclaim unused memory, to those (especially C/C++) that generally require the programmer to explicitly allocate object memory, track where it is used, and explicitly free it for re-use. To ensure a consistent API across these platforms, the DOM does not address memory management issues at all, but instead leaves these for the implementation. Neither of the explicit language bindings devised by the DOM Working Group (for ECMAScript and Java) require any memory management methods, but DOM bindings for other languages (especially C or C++) probably will require such support. These extensions will be the responsibility of those adapting the DOM API to a specific language, not the DOM WG.

1.1.3. Naming Conventions

While it would be nice to have attribute and method names that are short, informative, internally consistent, and familiar to users of similar APIs, the names also should not clash with the names in legacy APIs supported by DOM implementations. Furthermore, both OMG IDL and ECMAScript have significant limitations in their ability to disambiguate names from different namespaces that makes it difficult to avoid naming conflicts with short, familiar names. So, DOM names tend to be long and quite descriptive in order to be unique across all environments.

The Working Group has also attempted to be internally consistent in its use of various terms, even though these may not be common distinctions in other APIs. For example, we use the method name "remove" when the method changes the structural model, and the method name "delete" when the method gets rid of something inside the structure model. The thing that is deleted is not returned. The thing that is removed may be returned, when it makes sense to return it.

1.1.4. Inheritance vs Flattened Views of the API

The DOM Core APIs present two somewhat different sets of interfaces to an XML/HTML document; one presenting an "object oriented" approach with a hierarchy of inheritance, and a "simplified" view that allows all manipulation to be done via the Node interface without requiring casts (in Java and other C-like languages) or query interface calls in COM environments. These operations are fairly expensive in Java and COM, and the DOM may be used in performance-critical environments, so we allow significant functionality using just the Node interface. Because many other users will find the inheritance hierarchy easier to understand than the "everything is a Node" approach to the DOM, we also support the full higher-level interfaces for those who prefer a more object-oriented API.

In practice, this means that there is a certain amount of redundancy in the API. The Working Group considers the "inheritance" approach the primary view of the API, and the full set of functionality on Node to be "extra" functionality that users may employ, but that does not eliminate the need for methods on other interfaces that an object-oriented analysis would dictate. (Of course, when the O-O analysis yields an attribute or method that is identical to one on the Node interface, we don't specify a completely redundant one). Thus, even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the Working Group considers it worthwhile to support both, given the different constituencies the DOM API must satisfy.

1.1.5. The DOMString type

To ensure interoperability, the DOM specifies the DOMString type as follows:

  • A DOMString is a sequence of 16-bit quantities. This may be expressed in IDL terms as:

         typedef sequence<unsigned short> DOMString;
  • Applications must encode DOMString using UTF-16 (defined in Appendix C.3 of [UNICODE] and Amendment 1 of [ISO-10646]).The UTF-16 encoding was chosen because of its widespread industry practice. Please note that for both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS-4. A single numeric character reference in a source document may therefore in some cases correspond to two array positions in a DOMString (a high surrogate and a low surrogate). Note: Even though the DOM defines the name of the string type to be DOMString, bindings may used different names. For, example for Java, DOMString is bound to the String type because it also uses UTF-16 as its encoding.
Note: As of August 1998, the OMG IDL specification included a wstring type. However, that definition did not meet the interoperability criteria of the DOM API since it relied on encoding negotiation to decide the width of a character.

1.1.6. Case sensitivity in the DOM

The DOM has many interfaces that imply string matching. HTML processors generally assume an uppercase (less often, lowercase) normalization of names for such things as elements, while XML is explicitly case sensitive. For the purposes of the DOM, string matching takes place on a character code by character code basis, on the 16 bit value of a DOMString. As such, the DOM assumes that any normalizations will take place in the processor, before the DOM structures are built.

This then raises the issue of exactly what normalizations occur. The W3C I18N working group is in the process of defining exactly which normalizations are necessary for applications implementing the DOM.

1.2. Fundamental Interfaces

The interfaces within this section are considered fundamental, and must be fully implemented by all conforming implementations of the DOM, including all HTML DOM implementations.

Exception DOMException

DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable). In general, DOM methods return specific error values in ordinary processing situation, such as out-of-bound errors when using NodeList.

Implementations may raise other exceptions under other circumstances. For example, implementations may raise an implementation-dependent exception if a null argument is passed.

Some languages and object systems do not support the concept of exceptions. For such systems, error conditions may be indicated using native error reporting mechanisms. For some bindings, for example, methods may return error codes similar to those listed in the corresponding method descriptions.

IDL Definition
exception DOMException {
  unsigned short   code;
};

// ExceptionCode
const unsigned short      INDEX_SIZE_ERR     = 1;
const unsigned short      DOMSTRING_SIZE_ERR = 2;
const unsigned short      HIERARCHY_REQUEST_ERR = 3;
const unsigned short      WRONG_DOCUMENT_ERR = 4;
const unsigned short      INVALID_CHARACTER_ERR = 5;
const unsigned short      NO_DATA_ALLOWED_ERR = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short      NOT_FOUND_ERR      = 8;
const unsigned short      NOT_SUPPORTED_ERR  = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR = 10;
Definition group ExceptionCode

An integer indicating the type of error generated.

Defined Constants
INDEX_SIZE_ERR

If index or size is negative, or greater than the allowed value

DOMSTRING_SIZE_ERR

If the specified range of text does not fit into a DOMString

HIERARCHY_REQUEST_ERR

If any node is inserted somewhere it doesn't belong

WRONG_DOCUMENT_ERR

If a node is used in a different document than the one that created it (that doesn't support it)

INVALID_CHARACTER_ERR

If an invalid character is specified, such as in a name.

NO_DATA_ALLOWED_ERR

If data is specified for a node which does not support data

NO_MODIFICATION_ALLOWED_ERR

If an attempt is made to modify an object where modifications are not allowed

NOT_FOUND_ERR

If an attempt was made to reference a node in a context where it does not exist

NOT_SUPPORTED_ERR

If the implementation does not support the type of object requested

INUSE_ATTRIBUTE_ERR

If an attempt is made to add an attribute that is already inuse elsewhere

Interface DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

The DOM Level 1 does not specify a way of creating a document instance, and hence document creation is an operation specific to an implementation. Future Levels of the DOM specification are expected to provide methods for creating documents directly.

IDL Definition
interface DOMImplementation {
  boolean                   hasFeature(in DOMString feature,
                                       in DOMString version);
};
Methods
hasFeature
Test if the DOM implementation implements a specific feature.
Parameters
feature

The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive).

version

This is the version number of the package name to test. In Level 1, this is the string "1.0". If the version is not specified, supporting any version of the feature will cause the method to return true.

Return Value
true if the feature is implemented in the specified version, false otherwise.

This method raises no exceptions.
Interface DocumentFragment

DocumentFragment is a "lightweight" or "minimal" Document object. It is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments and it is quite natural to use a Node for this purpose. While it is true that a Document object could fulfil this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object.

Furthermore, various operations -- such as inserting nodes as children of another Node -- may take DocumentFragment objects as arguments; this results in all the child nodes of the DocumentFragment being moved to the child list of this node.

The children of a DocumentFragment node are zero or more nodes representing the tops of any sub-trees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.

When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as insertBefore() and appendChild().

IDL Definition
interface DocumentFragment : Node {
};
Interface Document

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

IDL Definition
interface Document : Node {
  readonly attribute  DocumentType         doctype;
  readonly attribute  DOMImplementation    implementation;
  readonly attribute  Element              documentElement;
  Element                   createElement(in DOMString tagName)
                                          raises(DOMException);
  DocumentFragment          createDocumentFragment();
  Text                      createTextNode(in DOMString data);
  Comment                   createComment(in DOMString data);
  CDATASection              createCDATASection(in DOMString data)
                                               raises(DOMException);
  ProcessingInstruction     createProcessingInstruction(in DOMString target,
                                                        in DOMString data)
                                                        raises(DOMException);
  Attr                      createAttribute(in DOMString name)
                                            raises(DOMException);
  EntityReference           createEntityReference(in DOMString name)
                                                  raises(DOMException);
  NodeList                  getElementsByTagName(in DOMString tagname);
};
Attributes
doctype
The Document Type Declaration (see DocumentType) associated with this document. For HTML documents as well as XML documents without a document type declaration this returns null. The DOM Level 1 does not support editing the Document Type Declaration, therefore docType cannot be altered in any way.
implementation
The DOMImplementation object that handles this document. A DOM application may use objects from multiple implementations.
documentElement
This is a convenience attribute that allows direct access to the child node that is the root element of the document. For HTML documents, this is the element with the tagName "HTML".
Methods
createElement
Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.
Parameters
tagName

The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.

Return Value
A new Element object.
Exceptions
DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

createDocumentFragment
Creates an empty DocumentFragment object.
Return Value
A new DocumentFragment.

This method has no parameters.
This method raises no exceptions.
createTextNode
Creates a Text node given the specified string.
Parameters
data

The data for the node.

Return Value
The new Text object.

This method raises no exceptions.
createComment
Creates a Comment node given the specified string.
Parameters
data

The data for the node.

Return Value
The new Comment object.

This method raises no exceptions.
createCDATASection
Creates a CDATASection node whose value is the specified string.
Parameters
data

The data for the CDATASection contents.

Return Value
The new CDATASection object.
Exceptions
DOMException

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createProcessingInstruction
Creates a ProcessingInstruction node given the specified name and data strings.
Parameters
target

The target part of the processing instruction.

data

The data for the node.

Return Value
The new ProcessingInstruction object.
Exceptions
DOMException

INVALID_CHARACTER_ERR: Raised if an invalid character is specified.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createAttribute
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttribute method.
Parameters
name

The name of the attribute.

Return Value
A new Attr object.
Exceptions
DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

createEntityReference
Creates an EntityReference object.
Parameters
name

The name of the entity to reference.

Return Value
The new EntityReference object.
Exceptions
DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

getElementsByTagName
Returns a NodeList of all the Elements with a given tag name in the order in which they would be encountered in a preorder traversal of the Document tree.
Parameters
tagname

The name of the tag to match on. The special value "*" matches all tags.

Return Value
A new NodeList object containing all the matched Elements.

This method raises no exceptions.
Interface Node

The Node interface is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes results in a DOMException being raised.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue for an Element or attributes for a Comment), this returns null. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

IDL Definition
interface Node {
  // NodeType
  const unsigned short      ELEMENT_NODE       = 1;
  const unsigned short      ATTRIBUTE_NODE     = 2;
  const unsigned short      TEXT_NODE          = 3;
  const unsigned short      CDATA_SECTION_NODE = 4;
  const unsigned short      ENTITY_REFERENCE_NODE = 5;
  const unsigned short      ENTITY_NODE        = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short      COMMENT_NODE       = 8;
  const unsigned short      DOCUMENT_NODE      = 9;
  const unsigned short      DOCUMENT_TYPE_NODE = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short      NOTATION_NODE      = 12;

  readonly attribute  DOMString            nodeName;
           attribute  DOMString            nodeValue;
                                                 // raises(DOMException) on setting
                                                 // raises(DOMException) on retrieval
  readonly attribute  unsigned short       nodeType;
  readonly attribute  Node                 parentNode;
  readonly attribute  NodeList             childNodes;
  readonly attribute  Node                 firstChild;
  readonly attribute  Node                 lastChild;
  readonly attribute  Node                 previousSibling;
  readonly attribute  Node                 nextSibling;
  readonly attribute  NamedNodeMap         attributes;
  readonly attribute  Document             ownerDocument;
  Node                      insertBefore(in Node newChild,
                                         in Node refChild)
                                         raises(DOMException);
  Node                      replaceChild(in Node newChild,
                                         in Node oldChild)
                                         raises(DOMException);
  Node                      removeChild(in Node oldChild)
                                        raises(DOMException);
  Node                      appendChild(in Node newChild)
                                        raises(DOMException);
  boolean                   hasChildNodes();
  Node                      cloneNode(in boolean deep);
};
Definition group NodeType

An integer indicating which type of node this is.

Defined Constants
ELEMENT_NODE

The node is a Element.

ATTRIBUTE_NODE

The node is an Attr.

TEXT_NODE

The node is a Text node.

CDATA_SECTION_NODE

The node is a CDATASection.

ENTITY_REFERENCE_NODE

The node is an EntityReference.

ENTITY_NODE

The node is an Entity.

PROCESSING_INSTRUCTION_NODE

The node is a ProcessingInstruction.

COMMENT_NODE

The node is a Comment.

DOCUMENT_NODE

The node is a Document.

DOCUMENT_TYPE_NODE

The node is a DocumentType.

DOCUMENT_FRAGMENT_NODE

The node is a DocumentFragment.

NOTATION_NODE

The node is a Notation.

The values of nodeName, nodeValue, and attributes vary according to the node type as follows:
nodeName | nodeValue | attributes
Element | tagName | null | NamedNodeMap
Attr | name of attribute | value of attribute | null
Text | #text | content of the text node | null
CDATASection | #cdata-section | content of the CDATA Section | null
EntityReference | name of entity referenced | null | null
Entity | entity name | null | null
ProcessingInstruction | target | entire content excluding the target | null
Comment | #comment | content of the comment | null
Document | #document | null | null
DocumentType | document type name | null | null
DocumentFragment | #document-fragment | null | null
Notation | notation name | null | null

Attributes
nodeName
The name of this node, depending on its type; see the table above.
nodeValue
The value of this node, depending on its type; see the table above.
Exceptions on setting
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

Exceptions on retrieval
DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

nodeType
A code representing the type of the underlying object, as defined above.
parentNode
The parent of this node. All nodes, except Document, DocumentFragment, and Attr may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.
childNodes
A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes. The content of the returned NodeList is "live" in the sense that, for instance, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the NodeList accessors; it is not a static snapshot of the content of the node. This is true for every NodeList, including the ones returned by the getElementsByTagName method.
firstChild
The first child of this node. If there is no such node, this returns null.
lastChild
The last child of this node. If there is no such node, this returns null.
previousSibling
The node immediately preceding this node. If there is no such node, this returns null.
nextSibling
The node immediately following this node. If there is no such node, this returns null.
attributes
A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.
ownerDocument
The Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document this is null.
Methods
insertBefore
Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.

If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.

Parameters
newChild

The node to insert.

refChild

The reference node, i.e., the node before which the new node must be inserted.

Return Value
The node being inserted.
Exceptions
DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if refChild is not a child of this node.

replaceChild
Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node. If the newChild is already in the tree, it is first removed.
Parameters
newChild

The new node to put in the child list.

oldChild

The node being replaced in the list.

Return Value
The node replaced.
Exceptions
DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or it the node to put in is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.

removeChild
Removes the child node indicated by oldChild from the list of children, and returns it.
Parameters
oldChild

The node being removed.

Return Value
The node removed.
Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.

appendChild
Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.
Parameters
newChild

The node to add.

If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node

Return Value
The node added.
Exceptions
DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

hasChildNodes
This is a convenience method to allow easy determination of whether a node has any children.
Return Value
true if the node has any children, false if the node has no children.

This method has no parameters.
This method raises no exceptions.
cloneNode
Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent (parentNode returns null.).

Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning any other type of node simply returns a copy of this node.

Parameters
deep

If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element).

Return Value
The duplicate node.

This method raises no exceptions.
Interface NodeList

The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented.

The items in the NodeList are accessible via an integral index, starting from 0.

IDL Definition
interface NodeList {
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};
Methods
item
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
index

Index into the collection.

Return Value
The node at the indexth position in the NodeList, or null if that is not a valid index.

This method raises no exceptions.
Attributes
length
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
Interface NamedNodeMap

Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name. Note that NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not maintained in any particular order. Objects contained in an object implementing NamedNodeMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a NamedNodeMap, and does not imply that the DOM specifies an order to these Nodes.

IDL Definition
interface NamedNodeMap {
  Node                      getNamedItem(in DOMString name);
  Node                      setNamedItem(in Node arg)
                                         raises(DOMException);
  Node                      removeNamedItem(in DOMString name)
                                            raises(DOMException);
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};
Methods
getNamedItem
Retrieves a node specified by name.
Parameters
name

Name of a node to retrieve.

Return Value
A Node (of any type) with the specified name, or null if the specified name did not identify any node in the map.

This method raises no exceptions.
setNamedItem
Adds a node using its nodeName attribute.

As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased.

Parameters
arg

A node to store in a named node map. The node will later be accessible using the value of the nodeName attribute of the node. If a node with that name is already present in the map, it is replaced by the new one.

Return Value
If the new Node replaces an existing node with the same name the previously existing Node is returned, otherwise null is returned.
Exceptions
DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created the NamedNodeMap.

NO_MODIFICATION_ALLOWED_ERR: Raised if this NamedNodeMap is readonly.

INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

removeNamedItem
Removes a node specified by name. If the removed node is an Attr with a default value it is immediately replaced.
Parameters
name

The name of a node to remove.

Return Value
The node removed from the map or null if no node with such a name exists.
Exceptions
DOMException

NOT_FOUND_ERR: Raised if there is no node named name in the map.

item
Returns the indexth item in the map. If index is greater than or equal to the number of nodes in the map, this returns null.
Parameters
index

Index into the map.

Return Value
The node at the indexth position in the NamedNodeMap, or null if that is not a valid index.

This method raises no exceptions.
Attributes
length
The number of nodes in the map. The range of valid child node indices is 0 to length-1 inclusive.
Interface CharacterData

The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM. For clarity this set is defined here rather than on each object that uses these attributes and methods. No DOM objects correspond directly to CharacterData, though Text and others do inherit the interface from it. All offsets in this interface start from 0.

IDL Definition
interface CharacterData : Node {
           attribute  DOMString            data;
                                 // raises(DOMException) on setting
                                 // raises(DOMException) on retrieval
  readonly attribute  unsigned long        length;
  DOMString                 substringData(in unsigned long offset,
                                          in unsigned long count)
                                          raises(DOMException);
  void                      appendData(in DOMString arg)
                                       raises(DOMException);
  void                      insertData(in unsigned long offset,
                                       in DOMString arg)
                                       raises(DOMException);
  void                      deleteData(in unsigned long offset,
                                       in unsigned long count)
                                       raises(DOMException);
  void                      replaceData(in unsigned long offset,
                                        in unsigned long count,
                                        in DOMString arg)
                                        raises(DOMException);
};
Attributes
data
The character data of the node that implements this interface. The DOM implementation may not put arbitrary limits on the amount of data that may be stored in a CharacterData node. However, implementation limits may mean that the entirety of a node's data may not fit into a single DOMString. In such cases, the user may call substringData to retrieve the data in appropriately sized pieces.
Exceptions on setting
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

Exceptions on retrieval
DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

length
The number of characters that are available through data and the substringData method below. This may have the value zero, i.e., CharacterData nodes may be empty.
Methods
substringData
Extracts a range of data from the node.
Parameters
offset

Start offset of substring to extract.

count

The number of characters to extract.

Return Value
The specified substring. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.
Exceptions
DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

DOMSTRING_SIZE_ERR: Raised if the specified range of text does not fit into a DOMString.

appendData
Append the string to the end of the character data of the node. Upon success, data provides access to the concatenation of data and the DOMString specified.
Parameters
arg

The DOMString to append.

Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
insertData
Insert a string at the specified character offset.
Parameters
offset

The character offset at which to insert.

arg

The DOMString to insert.

Exceptions
DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
deleteData
Remove a range of characters from the node. Upon success, data and length reflect the change.
Parameters
offset

The offset from which to remove characters.

count

The number of characters to delete. If the sum of offset and count exceeds length then all characters from offset to the end of the data are deleted.

Exceptions
DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
replaceData
Replace the characters starting at the specified character offset with the specified string.
Parameters
offset

The offset from which to start replacing.

count

The number of characters to replace. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced (i.e., the effect is the same as a remove method call with the same range, followed by an append method invocation).

arg

The DOMString with which the range must be replaced.

Exceptions
DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
Interface Attr

The Attr interface represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a document type definition.

Attr objects inherit the Node interface, but since they are not actually child nodes of the element they describe, the DOM does not consider them part of the document tree. Thus, the Node attributes parentNode, previousSibling, and nextSibling have a null value for Attr objects. The DOM takes the view that attributes are properties of elements rather than having a separate identity from the elements they are associated with; this should make it more efficient to implement such features as default attributes associated with all elements of a given type. Furthermore, Attr nodes may not be immediate children of a DocumentFragment. However, they can be associated with Element nodes contained within a DocumentFragment. In short, users and implementors of the DOM need to be aware that Attr nodes have some things in common with other objects inheriting the Node interface, but they also are quite distinct.

The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute does not exist on this element in the structure model until it has been explicitly added. Note that the nodeValue attribute on the Attr instance can also be used to retrieve the string version of the attribute's value(s).

In XML, where the value of an attribute can contain entity references, the child nodes of the Attr node provide a representation in which entity references are not expanded. These child nodes may be either Text or EntityReference nodes. Because the attribute type may be unknown, there are no tokenized attribute values.

IDL Definition
interface Attr : Node {
  readonly attribute  DOMString            name;
  readonly attribute  boolean              specified;
           attribute  DOMString            value;
};
Attributes
name
Returns the name of this attribute.
specified
If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false. Note that the implementation is in charge of this attribute, not the user. If the user changes the value of the attribute (even if it ends up having the same value as the default value) then the specified flag is automatically flipped to true. To re-specify the attribute as the default value from the DTD, the user must delete the attribute. The implementation will then make a new attribute available with specified set to false and the default value (if one exists).

In summary:

  • If the attribute has an assigned value in the document then specified is true, and the value is the assigned value.
  • If the attribute has no assigned value in the document and has a default value in the DTD, then specified is false, and the value is the default value in the DTD.
  • If the attribute has no assigned value in the document and has a value of #IMPLIED in the DTD, then the attribute does not appear in the structure model of the document.
value
On retrieval, the value of the attribute is returned as a string. Character and general entity references are replaced with their values.

On setting, this creates a Text node with the unparsed contents of the string.

Interface Element

By far the vast majority of objects (apart from text) that authors encounter when traversing a document are Element nodes. Assume the following XML document:

<elementExample id="demo">
  <subelement1/>
  <subelement2><subsubelement/></subelement2>
</elementExample>

When represented using DOM, the top node is an Element node for "elementExample", which contains two child Element nodes, one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes.

Elements may have attributes associated with them; since the Element interface inherits from Node, the generic Node interface method getAttributes may be used to retrieve the set of all attributes for an element. There are methods on the Element interface to retrieve either an Attr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, an Attr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

IDL Definition
interface Element : Node {
  readonly attribute  DOMString            tagName;
  DOMString                 getAttribute(in DOMString name);
  void                      setAttribute(in DOMString name,
                                         in DOMString value)
                                         raises(DOMException);
  void                      removeAttribute(in DOMString name)
                                            raises(DOMException);
  Attr                      getAttributeNode(in DOMString name);
  Attr                      setAttributeNode(in Attr newAttr)
                                             raises(DOMException);
  Attr                      removeAttributeNode(in Attr oldAttr)
                                                raises(DOMException);
  NodeList                  getElementsByTagName(in DOMString name);
  void                      normalize();
};
Attributes
tagName
The name of the element. For example, in:

<elementExample id="demo">
        ...
</elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM. The HTML DOM returns the tagName of an HTML element in the canonical uppercase form, regardless of the case in the source HTML document.
Methods
getAttribute
Retrieves an attribute value by name.
Parameters
name

The name of the attribute to retrieve.

Return Value
The Attr value as a string, or the empty string if that attribute does not have a specified or default value.

This method raises no exceptions.
setAttribute
Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string, it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute.
Parameters
name

The name of the attribute to create or alter.

value

Value to set in string form.

Exceptions
DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
removeAttribute
Removes an attribute by name. If the removed attribute has a default value it is immediately replaced.
Parameters
name

The name of the attribute to remove.

Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

This method returns nothing.
getAttributeNode
Retrieves an Attr node by name.
Parameters
name

The name of the attribute to retrieve.

Return Value
The Attr node with the specified attribute name or null if there is no such attribute.

This method raises no exceptions.
setAttributeNode
Adds a new attribute. If an attribute with that name is already present in the element, it is replaced by the new one.
Parameters
newAttr

The Attr node to add to the attribute list.

Return Value
If the newAttr attribute replaces an existing attribute with the same name, the previously existing Attr node is returned, otherwise null is returned.
Exceptions
DOMException

WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

removeAttributeNode
Removes the specified attribute.
Parameters
oldAttr

The Attr node to remove from the attribute list. If the removed Attr has a default value it is immediately replaced.

Return Value
The Attr node that was removed.
Exceptions
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldAttr is not an attribute of the element.

getElementsByTagName
Returns a NodeList of all descendant elements with a given tag name, in the order in which they would be encountered in a preorder traversal of the Element tree.
Parameters
name

The name of the tag to match on. The special value "*" matches all tags.

Return Value
A list of matching Element nodes.

This method raises no exceptions.
normalize
Puts all Text nodes in the full depth of the sub-tree underneath this Element into a "normal" form where only markup (e.g., tags, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are no adjacent Text nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer lookups) that depend on a particular document tree structure are to be used.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface Text

The Text interface represents the textual content (termed character data in XML) of an Element or Attr. If there is no markup inside an element's content, the text is contained in a single object implementing the Text interface that is the only child of the element. If there is markup, it is parsed into a list of elements and Text nodes that form the list of children of the element.

When a document is first made available via the DOM, there is only one Text node for each block of text. Users may create adjacent Text nodes that represent the contents of a given element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, so they will not (in general) persist between DOM editing sessions. The normalize() method on Element merges any such adjacent Text objects into a single node for each block of text; this is recommended before employing operations that depend on a particular document structure, such as navigation with XPointers.

IDL Definition
interface Text : CharacterData {
  Text                      splitText(in unsigned long offset)
                                      raises(DOMException);
};
Methods
splitText
Breaks this Text node into two Text nodes at the specified offset, keeping both in the tree as siblings. This node then only contains all the content up to the offset point. And a new Text node, which is inserted as the next sibling of this node, contains all the content at and after the offset point.
Parameters
offset

The offset at which to split, starting from 0.

Return Value
The new Text node.
Exceptions
DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of characters in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

Interface Comment

This represents the content of a comment, i.e., all the characters between the starting '<!--' and ending '-->'. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.

IDL Definition
interface Comment : CharacterData {
};

1.3. Extended Interfaces

The interfaces defined here form part of the DOM Level 1 Core specification, but objects that expose these interfaces will never be encountered in a DOM implementation that deals only with HTML. As such, HTML-only DOM implementations do not need to have objects that implement these interfaces.

Interface CDATASection

CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. The only delimiter that is recognized in a CDATA section is the "]]>" string that ends the CDATA section. CDATA sections can not be nested. The primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.

The DOMString attribute of the Text node holds the text that is contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections and that, depending on the character encoding ("charset") chosen for serialization, it may be impossible to write out some characters as part of a CDATA section.

The CDATASection interface inherits the CharacterData interface through the Text interface. Adjacent CDATASections nodes are not merged by use of the Element.normalize() method.

IDL Definition
interface CDATASection : Text {
};
Interface DocumentType

Each Document has a doctype attribute whose value is either null or a DocumentType object. The DocumentType interface in the DOM Level 1 Core provides an interface to the list of entities that are defined for the document, and little else because the effect of namespaces and the various XML scheme efforts on DTD representation are not clearly understood as of this writing.

The DOM Level 1 doesn't support editing DocumentType nodes.

IDL Definition
interface DocumentType : Node {
  readonly attribute  DOMString            name;
  readonly attribute  NamedNodeMap         entities;
  readonly attribute  NamedNodeMap         notations;
};
Attributes
name
The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
entities
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Duplicates are discarded. For example in:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY % baz "baz">
]>
<ex/>
the interface provides access to foo and bar but not baz. Every node in this map also implements the Entity interface.

The DOM Level 1 does not support editing entities, therefore entities cannot be altered in any way.

notations
A NamedNodeMap containing the notations declared in the DTD. Duplicates are discarded. Every node in this map also implements the Notation interface.

The DOM Level 1 does not support editing notations, therefore notations cannot be altered in any way.

Interface Notation

This interface represents a notation declared in the DTD. A notation either declares, by name, the format of an unparsed entity (see section 4.7 of the XML 1.0 specification), or is used for formal declaration of Processing Instruction targets (see section 2.6 of the XML 1.0 specification). The nodeName attribute inherited from Node is set to the declared name of the notation.

The DOM Level 1 does not support editing Notation nodes; they are therefore readonly.

A Notation node does not have any parent.

IDL Definition
interface Notation : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
};
Attributes
publicId
The public identifier of this notation. If the public identifier was not specified, this is null.
systemId
The system identifier of this notation. If the system identifier was not specified, this is null.
Interface Entity

This interface represents an entity, either parsed or unparsed, in an XML document. Note that this models the entity itself not the entity declaration. Entity declaration modeling has been left for a later Level of the DOM specification.

The nodeName attribute that is inherited from Node contains the name of the entity.

An XML processor may choose to completely expand entities before the structure model is passed to the DOM; in this case there will be no EntityReference nodes in the document tree.

XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or declared in external parameter entities. This means that parsed entities declared in the external subset need not be expanded by some classes of applications, and that the replacement value of the entity may not be available. When the replacement value is available, the corresponding Entity node's child list represents the structure of that replacement text. Otherwise, the child list is empty.

The resolution of the children of the Entity (the replacement value) may be lazily evaluated; actions by the user (such as calling the childNodes method on the Entity Node) are assumed to trigger the evaluation.

The DOM Level 1 does not support editing Entity nodes; if a user wants to make changes to the contents of an Entity, every related EntityReference node has to be replaced in the structure model by a clone of the Entity's contents, and then the desired changes must be made to each of those clones instead. All the descendants of an Entity node are readonly.

An Entity node does not have any parent.

IDL Definition
interface Entity : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
  readonly attribute  DOMString            notationName;
};
Attributes
publicId
The public identifier associated with the entity, if specified. If the public identifier was not specified, this is null.
systemId
The system identifier associated with the entity, if specified. If the system identifier was not specified, this is null.
notationName
For unparsed entities, the name of the notation for the entity. For parsed entities, this is null.
Interface EntityReference

EntityReference objects may be inserted into the structure model when an entity reference is in the source document, or when the user wishes to insert an entity reference. Note that character references and references to predefined entities are considered to be expanded by the HTML or XML processor so that characters are represented by their Unicode equivalent rather than by an entity reference. Moreover, the XML processor may completely expand references to entities while building the structure model, instead of providing EntityReference objects. If it does provide such objects, then for a given EntityReference node, it may be that there is no Entity node representing the referenced entity; but if such an Entity exists, then the child list of the EntityReference node is the same as that of the Entity node. As with the Entity node, all descendants of the EntityReference are readonly.

The resolution of the children of the EntityReference (the replacement value of the referenced Entity) may be lazily evaluated; actions by the user (such as calling the childNodes method on the EntityReference node) are assumed to trigger the evaluation.

IDL Definition
interface EntityReference : Node {
};
Interface ProcessingInstruction

The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.

IDL Definition
interface ProcessingInstruction : Node {
  readonly attribute  DOMString            target;
           attribute  DOMString            data;
                                      // raises(DOMException) on setting
};
Attributes
target
The target of this processing instruction. XML defines this as being the first token following the markup that begins the processing instruction.
data
The content of this processing instruction. This is from the first non white space character after the target to the character immediately preceding the ?>.
Exceptions on setting
DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

What is the Document Object Model? REC-DOM-Level-1-19981001 Document Object Model (HTML) Level 1


Document Object Model (HTML) Level 1

REC-DOM-Level-1-19981001
Document Object Model (Core) Level 1 REC-DOM-Level-1-19981001 Contributors

2. Document Object Model (HTML) Level 1

Editors
Mike Champion, ArborText
Vidur Apparao, Netscape
Scott Isaacs, Microsoft (until January 1998)
Chris Wilson, Microsoft (after January 1998)
Ian Jacobs, W3C

Table of contents

  • 2.1. Introduction
  • 2.1. HTML Application of Core DOM
    • 2.1.1. Naming Conventions
  • 2.2. Miscellaneous Object Definitions
  • 2.2. Objects related to HTML documents
  • 2.2. HTML Elements
    • 2.2.1. Property Attributes
    • 2.2.2. Naming Exceptions
    • 2.2.3. Exposing Element Type Names (tagName)
    • 2.2.4. The HTMLElement interface
    • 2.2.5. Object definitions

2.1. Introduction

This section extends the Level 1 Core API to describe objects and methods specific to HTML documents. In general, the functionality needed to manipulate hierarchical document structures, elements, and attributes will be found in the core section; functionality that depends on the specific elements defined in HTML will be found in this section.

The goals of the HTML-specific DOM API are:

  • to specialize and add functionality that relates specifically to HTML documents and elements.
  • to address issues of backwards compatibility with the "DOM Level 0".
  • to provide convenience mechanisms, where appropriate, for common and frequent operations on HTML documents.

The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".

The key differences between the core DOM and the HTML application of DOM is that the HTML Document Object Model exposes a number of convenience methods and properties that are consistent with the existing models and are more appropriate to script writers. In many cases, these enhancements are not applicable to a general DOM because they rely on the presence of a predefined DTD. For DOM Level 1, the transitional and frameset DTDs for HTML 4.0 are assumed. Interoperability between implementations is only guaranteed for elements and attributes that are specified in these DTDs.

More specifically, this document includes the following specializations for HTML:

  • An HTMLDocument interface, derived from the core Document interface. HTMLDocument specifies the operations and queries that can be made on a HTML document.
  • An HTMLElement interface, derived from the core Element interface. HTMLElement specifies the operations and queries that can be made on any HTML element. Methods on HTMLElement include those that allow for the retrieval and modification of attributes that apply to all HTML elements.
  • Specializations for all HTML elements that have attributes that extend beyond those specified in the HTMLElement interface. For all such attributes, the derived interface for the element contains explicit methods for setting and getting the values.

The DOM Level 1 does not include mechanisms to access and modify style specified through CSS 1. Furthermore, it does not define an event model for HTML documents. This functionality is planned to be specified in a future Level of this specification.

2.2. HTML Application of Core DOM

2.2.1. Naming Conventions

The HTML DOM follows a naming convention for properties, methods, events, collections, and data types. All names are defined as one or more English words concatenated together to form a single string. Properties and Methods

The property or method name starts with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object. In Java, properties are exposed with get and set methods. Non-HTML 4.0 interfaces and attributes

While most of the interfaces defined below can be mapped directly to elements defined in the HTML 4.0 Recommendation, some of them cannot. Similarly, not all attributes listed below have counterparts in the HTML 4.0 specification (and some do, but have been renamed to avoid conflicts with scripting languages). Interfaces and attribute definitions that have links to the HTML 4.0 specification have corresponding element and attribute definitions there; all others are added by this specification, either for convenience or backwards compatibility with "DOM Level 0" implementations.

2.3. Miscellaneous Object Definitions

Interface HTMLCollection

An HTMLCollection is a list of nodes. An individual node may be accessed by either ordinal index or the node's name or id attributes. Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

IDL Definition
interface HTMLCollection {
  readonly attribute  unsigned long        length;
  Node                      item(in unsigned long index);
  Node                      namedItem(in DOMString name);
};
Attributes
length
This attribute specifies the length or size of the list.
Methods
item
This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).
Parameters
index

The index of the node to be fetched. The index origin is 0.

Return Value
The Node at the corresponding position upon success. A value of null is returned if the index is out of range.

This method raises no exceptions.
namedItem
This method retrieves a Node using a name. It first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute.
Parameters
name

The name of the Node to be fetched.

Return Value
The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.

This method raises no exceptions.

2.4. Objects related to HTML documents

Interface HTMLDocument

An HTMLDocument is the root of the HTML hierarchy and holds the entire content. Beside providing access to the hierarchy, it also provides some convenience methods for accessing certain sets of information from the document.

The following properties have been deprecated in favor of the corresponding ones for the BODY element:

  • alinkColor
  • background
  • bgColor
  • fgColor
  • linkColor
  • vlinkColor

IDL Definition
interface HTMLDocument : Document {
           attribute  DOMString            title;
  readonly attribute  DOMString            referrer;
  readonly attribute  DOMString            domain;
  readonly attribute  DOMString            URL;
           attribute  HTMLElement          body;
  readonly attribute  HTMLCollection       images;
  readonly attribute  HTMLCollection       applets;
  readonly attribute  HTMLCollection       links;
  readonly attribute  HTMLCollection       forms;
  readonly attribute  HTMLCollection       anchors;
           attribute  DOMString            cookie;
  void                      open();
  void                      close();
  void                      write(in DOMString text);
  void                      writeln(in DOMString text);
  Element                   getElementById(in DOMString elementId);
  NodeList                  getElementsByName(in DOMString elementName);
};
Attributes
title
The title of a document as specified by the TITLE element in the head of the document.
referrer
Returns the URI of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).
domain
The domain name of the server that served the document, or a null string if the server cannot be identified by a domain name.
URL
The complete URI of the document.
body
The element that contains the content for the document. In documents with BODY contents, returns the BODY element, and in frameset documents, this returns the outermost FRAMESET element.
images
A collection of all the IMG elements in a document. The behavior is limited to IMG elements for backwards compatibility.
applets
A collection of all the OBJECT elements that include applets and APPLET (deprecated) elements in a document.
links
A collection of all AREA elements and anchor (A) elements in a document with a value for the href attribute.
forms
A collection of all the forms of a document.
anchors
A collection of all the anchor (A) elements in a document with a value for the name attribute.Note. For reasons of backwards compatibility, the returned set of anchors only contains those anchors created with the name attribute, not those created with the id attribute.
cookie
The cookies associated with this document. If there are none, the value is an empty string. Otherwise, the value is a string: a semicolon-delimited list of "name, value" pairs for all the cookies associated with the page. For example, name=value;expires=date.
Methods
open
Note. This method and the ones following allow a user to add to or replace the structure model of a document using strings of unparsed HTML. At the time of writing alternate methods for providing similar functionality for both HTML and XML documents were being considered. The following methods may be deprecated at some point in the future in favor of a more general-purpose mechanism.

Open a document stream for writing. If a document exists in the target, this method clears it.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.

close
Closes a document stream opened by open() and forces rendering.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
write
Write a string of text to a document stream opened by open(). The text is parsed into the document's structure model.
Parameters
text

The string to be parsed into some structure in the document structure model.

This method returns nothing.
This method raises no exceptions.
writeln
Write a string of text followed by a newline character to a document stream opened by open(). The text is parsed into the document's structure model.
Parameters
text

The string to be parsed into some structure in the document structure model.

This method returns nothing.
This method raises no exceptions.
getElementById
Returns the Element whose id is given by elementId. If no such element exists, returns null. Behavior is not defined if more than one element has this id.
Parameters
elementId

The unique id value for an element.

Return Value
The matching element.

This method raises no exceptions.
getElementsByName
Returns the (possibly empty) collection of elements whose name value is given by elementName.
Parameters
elementName

The name attribute value for an element.

Return Value
The matching elements.

This method raises no exceptions.

2.5. HTML Elements

2.5.1. Property Attributes

HTML attributes are exposed as properties on the element object. The name of the exposed property always uses the naming conventions, and is independent of the case of the attribute in the source document. The data type of the property is determined by the type of the attribute as determined by the HTML 4.0 transitional and frameset DTDs. The attributes have the semantics (including case-sensitivity) given in the HTML 4.0 specification.

The attributes are exposed as properties for compatibility with "DOM Level 0". This usage is deprecated because it can not be generalized to all possible attribute names, as is required both for XML and potentially for future versions of HTML. We recommend the use of generic methods on the core Element interface for setting, getting and removing attributes.
DTD Data Type | Object Model Data Type
CDATA | DOMString
Value list (e.g., (left | right | center)) | DOMString
one-value Value list (e.g., (border)) | boolean
Number | long int

The return value of an attribute that has a data type that is a value list is always capitalized, independent of the case of the value in the source document. For example, if the value of the align attribute on a P element is "left" then it is returned as "Left". For attributes with the CDATA data type, the case of the return value is that given in the source document.

2.5.2. Naming Exceptions

To avoid name-space conflicts, an attribute with the same name as a keyword in one of our chosen binding languages is prefixed. For HTML, the prefix used is "html". For example, the for attribute of the LABEL element collides with loop construct naming conventions and is renamed htmlFor.

2.5.3. Exposing Element Type Names (tagName)

The element type names exposed through a property are in uppercase. For example, the body element type name is exposed through the "tagName" property as "BODY".

2.5.4. The HTMLElement interface

Interface HTMLElement

All HTML element interfaces derive from this class. Elements that only expose the HTML core attributes are represented by the base HTMLElement interface. These elements are as follows:

  • HEAD
  • special: SUB, SUP, SPAN, BDO
  • font: TT, I, B, U, S, STRIKE, BIG, SMALL
  • phrase: EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ACRONYM, ABBR
  • list: DD, DT
  • NOFRAMES, NOSCRIPT
  • ADDRESS, CENTER

Note. The style attribute for this interface is reserved for future usage.

IDL Definition
interface HTMLElement : Element {
           attribute  DOMString            id;
           attribute  DOMString            title;
           attribute  DOMString            lang;
           attribute  DOMString            dir;
           attribute  DOMString            className;
};
Attributes
id
The element's identifier. See the id attribute definition in HTML 4.0.
title
The element's advisory title. See the title attribute definition in HTML 4.0.
lang
Language code defined in RFC 1766. See the lang attribute definition in HTML 4.0.
dir
Specifies the base direction of directionally neutral text and the directionality of tables. See the dir attribute definition in HTML 4.0.
className
The class attribute of the element. This attribute has been renamed due to conflicts with the "class" keyword exposed by many languages. See the class attribute definition in HTML 4.0.

2.5.5. Object definitions

Interface HTMLHtmlElement

Root of an HTML document. See the HTML element definition in HTML 4.0.

IDL Definition
interface HTMLHtmlElement : HTMLElement {
           attribute  DOMString            version;
};
Attributes
version
Version information about the document's DTD. See the version attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLHeadElement

Document head information. See the HEAD element definition in HTML 4.0.

IDL Definition
interface HTMLHeadElement : HTMLElement {
           attribute  DOMString            profile;
};
Attributes
profile
URI designating a metadata profile. See the profile attribute definition in HTML 4.0.
Interface HTMLLinkElement

The LINK element specifies a link to an external resource, and defines this document's relationship to that resource (or vice versa). See the LINK element definition in HTML 4.0.

IDL Definition
interface HTMLLinkElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            charset;
           attribute  DOMString            href;
           attribute  DOMString            hreflang;
           attribute  DOMString            media;
           attribute  DOMString            rel;
           attribute  DOMString            rev;
           attribute  DOMString            target;
           attribute  DOMString            type;
};
Attributes
disabled
Enables/disables the link. This is currently only used for style sheet links, and may be used to activate or deactivate style sheets.
charset
The character encoding of the resource being linked to. See the charset attribute definition in HTML 4.0.
href
The URI of the linked resource. See the href attribute definition in HTML 4.0.
hreflang
Language code of the linked resource. See the hreflang attribute definition in HTML 4.0.
media
Designed for use with one or more target media. See the media attribute definition in HTML 4.0.
rel
Forward link type. See the rel attribute definition in HTML 4.0.
rev
Reverse link type. See the rev attribute definition in HTML 4.0.
target
Frame to render the resource in. See the target attribute definition in HTML 4.0.
type
Advisory content type. See the type attribute definition in HTML 4.0.
Interface HTMLTitleElement

The document title. See the TITLE element definition in HTML 4.0.

IDL Definition
interface HTMLTitleElement : HTMLElement {
           attribute  DOMString            text;
};
Attributes
text
The specified title as a string.
Interface HTMLMetaElement

This contains generic meta-information about the document. See the META element definition in HTML 4.0.

IDL Definition
interface HTMLMetaElement : HTMLElement {
           attribute  DOMString            content;
           attribute  DOMString            httpEquiv;
           attribute  DOMString            name;
           attribute  DOMString            scheme;
};
Attributes
content
Associated information. See the content attribute definition in HTML 4.0.
httpEquiv
HTTP response header name. See the http-equiv attribute definition in HTML 4.0.
name
Meta information name. See the name attribute definition in HTML 4.0.
scheme
Select form of content. See the scheme attribute definition in HTML 4.0.
Interface HTMLBaseElement

Document base URI. See the BASE element definition in HTML 4.0.

IDL Definition
interface HTMLBaseElement : HTMLElement {
           attribute  DOMString            href;
           attribute  DOMString            target;
};
Attributes
href
The base URI See the href attribute definition in HTML 4.0.
target
The default target frame. See the target attribute definition in HTML 4.0.
Interface HTMLIsIndexElement

This element is used for single-line text input. See the ISINDEX element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLIsIndexElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            prompt;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
prompt
The prompt message. See the prompt attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLStyleElement

Style information. A more detailed style sheet object model is planned to be defined in a separate document. See the STYLE element definition in HTML 4.0.

IDL Definition
interface HTMLStyleElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            media;
           attribute  DOMString            type;
};
Attributes
disabled
Enables/disables the style sheet.
media
Designed for use with one or more target media. See the media attribute definition in HTML 4.0.
type
The style sheet language (Internet media type). See the type attribute definition in HTML 4.0.
Interface HTMLBodyElement

The HTML document body. This element is always present in the DOM API, even if the tags are not present in the source document. See the BODY element definition in HTML 4.0.

IDL Definition
interface HTMLBodyElement : HTMLElement {
           attribute  DOMString            aLink;
           attribute  DOMString            background;
           attribute  DOMString            bgColor;
           attribute  DOMString            link;
           attribute  DOMString            text;
           attribute  DOMString            vLink;
};
Attributes
aLink
Color of active links (after mouse-button down, but before mouse-button up). See the alink attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
background
URI of the background texture tile image. See the background attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
bgColor
Document background color. See the bgcolor attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
link
Color of links that are not active and unvisited. See the link attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
text
Document text color. See the text attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
vLink
Color of links that have been visited by the user. See the vlink attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLFormElement

The FORM element encompasses behavior similar to a collection and an element. It provides direct access to the contained input elements as well as the attributes of the form element. See the FORM element definition in HTML 4.0.

IDL Definition
interface HTMLFormElement : HTMLElement {
  readonly attribute  HTMLCollection       elements;
  readonly attribute  long                 length;
           attribute  DOMString            name;
           attribute  DOMString            acceptCharset;
           attribute  DOMString            action;
           attribute  DOMString            enctype;
           attribute  DOMString            method;
           attribute  DOMString            target;
  void                      submit();
  void                      reset();
};
Attributes
elements
Returns a collection of all control elements in the form.
length
The number of form controls in the form.
name
Names the form.
acceptCharset
List of character sets supported by the server. See the accept-charset attribute definition in HTML 4.0.
action
Server-side form handler. See the action attribute definition in HTML 4.0.
enctype
The content type of the submitted form, generally "application/x-www-form-urlencoded". See the enctype attribute definition in HTML 4.0.
method
HTTP method used to submit form. See the method attribute definition in HTML 4.0.
target
Frame to render the resource in. See the target attribute definition in HTML 4.0.
Methods
submit
Submits the form. It performs the same action as a submit button.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
reset
Restores a form element's default values. It performs the same action as a reset button.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface HTMLSelectElement

The select element allows the selection of an option. The contained options can be directly accessed through the select element as a collection. See the SELECT element definition in HTML 4.0.

IDL Definition
interface HTMLSelectElement : HTMLElement {
  readonly attribute  DOMString            type;
           attribute  long                 selectedIndex;
           attribute  DOMString            value;
  readonly attribute  long                 length;
  readonly attribute  HTMLFormElement      form;
  readonly attribute  HTMLCollection       options;
           attribute  boolean              disabled;
           attribute  boolean              multiple;
           attribute  DOMString            name;
           attribute  long                 size;
           attribute  long                 tabIndex;
  void                      add(in HTMLElement element,
                                in HTMLElement before);
  void                      remove(in long index);
  void                      blur();
  void                      focus();
};
Attributes
type
The type of control created.
selectedIndex
The ordinal index of the selected option. The value -1 is returned if no element is selected. If multiple options are selected, the index of the first selected option is returned.
value
The current form control value.
length
The number of options in this SELECT.
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
options
The collection of OPTION elements contained by this element.
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
multiple
If true, multiple OPTION elements may be selected in this SELECT. See the multiple attribute definition in HTML 4.0.
name
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.0.
size
Number of visible rows. See the size attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
Methods
add
Add a new element to the collection of OPTION elements for this SELECT.
Parameters
element

The element to add.

before

The element to insert before, or NULL for the head of the list.

This method returns nothing.
This method raises no exceptions.
remove
Remove an element from the collection of OPTION elements for this SELECT. Does nothing if no element has the given index.
Parameters
index

The index of the item to remove.

This method returns nothing.
This method raises no exceptions.
blur
Removes keyboard focus from this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
focus
Gives keyboard focus to this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface HTMLOptGroupElement

Group options together in logical subdivisions. See the OPTGROUP element definition in HTML 4.0.

IDL Definition
interface HTMLOptGroupElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            label;
};
Attributes
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
label
Assigns a label to this option group. See the label attribute definition in HTML 4.0.
Interface HTMLOptionElement

A selectable choice. See the OPTION element definition in HTML 4.0.

IDL Definition
interface HTMLOptionElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  boolean              defaultSelected;
  readonly attribute  DOMString            text;
           attribute  long                 index;
           attribute  boolean              disabled;
           attribute  DOMString            label;
  readonly attribute  boolean              selected;
           attribute  DOMString            value;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
defaultSelected
Stores the initial value of the selected attribute.
text
The text contained within the option element.
index
The index of this OPTION in its parent SELECT.
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
label
Option label for use in hierarchical menus. See the label attribute definition in HTML 4.0.
selected
Means that this option is initially selected. See the selected attribute definition in HTML 4.0.
value
The current form control value. See the value attribute definition in HTML 4.0.
Interface HTMLInputElement

Form control. Note. Depending upon the environment the page is being viewed, the value property may be read-only for the file upload input type. For the "password" input type, the actual value returned may be masked to prevent unauthorized use. See the INPUT element definition in HTML 4.0.

IDL Definition
interface HTMLInputElement : HTMLElement {
           attribute  DOMString            defaultValue;
           attribute  boolean              defaultChecked;
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accept;
           attribute  DOMString            accessKey;
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  boolean              checked;
           attribute  boolean              disabled;
           attribute  long                 maxLength;
           attribute  DOMString            name;
           attribute  boolean              readOnly;
           attribute  DOMString            size;
           attribute  DOMString            src;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            useMap;
           attribute  DOMString            value;
  void                      blur();
  void                      focus();
  void                      select();
  void                      click();
};
Attributes
defaultValue
Stores the initial control value (i.e., the initial value of value).
defaultChecked
When type has the value "Radio" or "Checkbox", stores the initial value of the checked attribute.
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
accept
A comma-separated list of content types that a server processing this form will handle correctly. See the accept attribute definition in HTML 4.0.
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
align
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
alt
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.0.
checked
Describes whether a radio or check box is checked, when type has the value "Radio" or "Checkbox". The value is TRUE if explicitly set. Represents the current state of the checkbox or radio button. See the checked attribute definition in HTML 4.0.
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
maxLength
Maximum number of characters for text fields, when type has the value "Text" or "Password". See the maxlength attribute definition in HTML 4.0.
name
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.0.
readOnly
This control is read-only. When type has the value "text" or "password" only. See the readonly attribute definition in HTML 4.0.
size
Size information. The precise meaning is specific to each type of field. See the size attribute definition in HTML 4.0.
src
When the type attribute has the value "Image", this attribute specifies the location of the image to be used to decorate the graphical submit button. See the src attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
type
The type of control created. See the type attribute definition in HTML 4.0.
useMap
Use client-side image map. See the usemap attribute definition in HTML 4.0.
value
The current form control value. Used for radio buttons and check boxes. See the value attribute definition in HTML 4.0.
Methods
blur
Removes keyboard focus from this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
focus
Gives keyboard focus to this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
select
Select the contents of the text area. For INPUT elements whose type attribute has one of the following values: "Text", "File", or "Password".
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
click
Simulate a mouse-click. For INPUT elements whose type attribute has one of the following values: "Button", "Checkbox", "Radio", "Reset", or "Submit".
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface HTMLTextAreaElement

Multi-line text field. See the TEXTAREA element definition in HTML 4.0.

IDL Definition
interface HTMLTextAreaElement : HTMLElement {
           attribute  DOMString            defaultValue;
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  long                 cols;
           attribute  boolean              disabled;
           attribute  DOMString            name;
           attribute  boolean              readOnly;
           attribute  long                 rows;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            value;
  void                      blur();
  void                      focus();
  void                      select();
};
Attributes
defaultValue
Stores the initial control value (i.e., the initial value of value).
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
cols
Width of control (in characters). See the cols attribute definition in HTML 4.0.
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
name
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.0.
readOnly
This control is read-only. See the readonly attribute definition in HTML 4.0.
rows
Number of text rows. See the rows attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
type
The type of this form control.
value
The current textual content of the multi-line text field. If the entirety of the data can not fit into a single wstring, the implementation may truncate the data.
Methods
blur
Removes keyboard focus from this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
focus
Gives keyboard focus to this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
select
Select the contents of the TEXTAREA.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface HTMLButtonElement

Push button. See the BUTTON element definition in HTML 4.0.

IDL Definition
interface HTMLButtonElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  boolean              disabled;
           attribute  DOMString            name;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            value;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
disabled
The control is unavailable in this context. See the disabled attribute definition in HTML 4.0.
name
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
type
The type of button. See the type attribute definition in HTML 4.0.
value
The current form control value. See the value attribute definition in HTML 4.0.
Interface HTMLLabelElement

Form field label text. See the LABEL element definition in HTML 4.0.

IDL Definition
interface HTMLLabelElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  DOMString            htmlFor;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
htmlFor
This attribute links this label with another form control by id attribute. See the for attribute definition in HTML 4.0.
Interface HTMLFieldSetElement

Organizes form controls into logical groups. See the FIELDSET element definition in HTML 4.0.

IDL Definition
interface HTMLFieldSetElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
Interface HTMLLegendElement

Provides a caption for a FIELDSET grouping. See the LEGEND element definition in HTML 4.0.

IDL Definition
interface HTMLLegendElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  DOMString            align;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
align
Text alignment relative to FIELDSET. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLUListElement

Unordered list. See the UL element definition in HTML 4.0.

IDL Definition
interface HTMLUListElement : HTMLElement {
           attribute  boolean              compact;
           attribute  DOMString            type;
};
Attributes
compact
Reduce spacing between list items. See the compact attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
type
Bullet style. See the type attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLOListElement

Ordered list. See the OL element definition in HTML 4.0.

IDL Definition
interface HTMLOListElement : HTMLElement {
           attribute  boolean              compact;
           attribute  long                 start;
           attribute  DOMString            type;
};
Attributes
compact
Reduce spacing between list items. See the compact attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
start
Starting sequence number. See the start attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
type
Numbering style. See the type attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLDListElement

Definition list. See the DL element definition in HTML 4.0.

IDL Definition
interface HTMLDListElement : HTMLElement {
           attribute  boolean              compact;
};
Attributes
compact
Reduce spacing between list items. See the compact attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLDirectoryElement

Directory list. See the DIR element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLDirectoryElement : HTMLElement {
           attribute  boolean              compact;
};
Attributes
compact
Reduce spacing between list items. See the compact attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLMenuElement

Menu list. See the MENU element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLMenuElement : HTMLElement {
           attribute  boolean              compact;
};
Attributes
compact
Reduce spacing between list items. See the compact attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLLIElement

List item. See the LI element definition in HTML 4.0.

IDL Definition
interface HTMLLIElement : HTMLElement {
           attribute  DOMString            type;
           attribute  long                 value;
};
Attributes
type
List item bullet style. See the type attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
value
Reset sequence number when used in OL See the value attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLBlockquoteElement

??? See the BLOCKQUOTE element definition in HTML 4.0.

IDL Definition
interface HTMLBlockquoteElement : HTMLElement {
           attribute  DOMString            cite;
};
Attributes
cite
A URI designating a document that describes the reason for the change. See the cite attribute definition in HTML 4.0.
Interface HTMLDivElement

Generic block container. See the DIV element definition in HTML 4.0.

IDL Definition
interface HTMLDivElement : HTMLElement {
           attribute  DOMString            align;
};
Attributes
align
Horizontal text alignment. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLParagraphElement

Paragraphs. See the P element definition in HTML 4.0.

IDL Definition
interface HTMLParagraphElement : HTMLElement {
           attribute  DOMString            align;
};
Attributes
align
Horizontal text alignment. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLHeadingElement

For the H1 to H6 elements. See the H1 element definition in HTML 4.0.

IDL Definition
interface HTMLHeadingElement : HTMLElement {
           attribute  DOMString            align;
};
Attributes
align
Horizontal text alignment. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLQuoteElement

For the Q and BLOCKQUOTE elements. See the Q element definition in HTML 4.0.

IDL Definition
interface HTMLQuoteElement : HTMLElement {
           attribute  DOMString            cite;
};
Attributes
cite
A URI designating a document that designates a source document or message. See the cite attribute definition in HTML 4.0.
Interface HTMLPreElement

Preformatted text. See the PRE element definition in HTML 4.0.

IDL Definition
interface HTMLPreElement : HTMLElement {
           attribute  long                 width;
};
Attributes
width
Fixed width for content. See the width attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLBRElement

Force a line break. See the BR element definition in HTML 4.0.

IDL Definition
interface HTMLBRElement : HTMLElement {
           attribute  DOMString            clear;
};
Attributes
clear
Control flow of text around floats. See the clear attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLBaseFontElement

Base font. See the BASEFONT element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLBaseFontElement : HTMLElement {
           attribute  DOMString            color;
           attribute  DOMString            face;
           attribute  DOMString            size;
};
Attributes
color
Font color. See the color attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
face
Font face identifier. See the face attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
size
Font size. See the size attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLFontElement

Local change to font. See the FONT element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLFontElement : HTMLElement {
           attribute  DOMString            color;
           attribute  DOMString            face;
           attribute  DOMString            size;
};
Attributes
color
Font color. See the color attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
face
Font face identifier. See the face attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
size
Font size. See the size attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLHRElement

Create a horizontal rule. See the HR element definition in HTML 4.0.

IDL Definition
interface HTMLHRElement : HTMLElement {
           attribute  DOMString            align;
           attribute  boolean              noShade;
           attribute  DOMString            size;
           attribute  DOMString            width;
};
Attributes
align
Align the rule on the page. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
noShade
Indicates to the user agent that there should be no shading in the rendering of this element. See the noshade attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
size
The height of the rule. See the size attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
width
The width of the rule. See the width attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLModElement

Notice of modification to part of a document. See the INS and DEL element definitions in HTML 4.0.

IDL Definition
interface HTMLModElement : HTMLElement {
           attribute  DOMString            cite;
           attribute  DOMString            dateTime;
};
Attributes
cite
A URI designating a document that describes the reason for the change. See the cite attribute definition in HTML 4.0.
dateTime
The date and time of the change. See the datetime attribute definition in HTML 4.0.
Interface HTMLAnchorElement

The anchor element. See the A element definition in HTML 4.0.

IDL Definition
interface HTMLAnchorElement : HTMLElement {
           attribute  DOMString            accessKey;
           attribute  DOMString            charset;
           attribute  DOMString            coords;
           attribute  DOMString            href;
           attribute  DOMString            hreflang;
           attribute  DOMString            name;
           attribute  DOMString            rel;
           attribute  DOMString            rev;
           attribute  DOMString            shape;
           attribute  long                 tabIndex;
           attribute  DOMString            target;
           attribute  DOMString            type;
  void                      blur();
  void                      focus();
};
Attributes
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
charset
The character encoding of the linked resource. See the charset attribute definition in HTML 4.0.
coords
Comma-separated list of lengths, defining an active region geometry. See also shape for the shape of the region. See the coords attribute definition in HTML 4.0.
href
The URI of the linked resource. See the href attribute definition in HTML 4.0.
hreflang
Language code of the linked resource. See the hreflang attribute definition in HTML 4.0.
name
Anchor name. See the name attribute definition in HTML 4.0.
rel
Forward link type. See the rel attribute definition in HTML 4.0.
rev
Reverse link type. See the rev attribute definition in HTML 4.0.
shape
The shape of the active area. The coordinates are given by coords. See the shape attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
target
Frame to render the resource in. See the target attribute definition in HTML 4.0.
type
Advisory content type. See the type attribute definition in HTML 4.0.
Methods
blur
Removes keyboard focus from this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
focus
Gives keyboard focus to this element.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
Interface HTMLImageElement

Embedded image. See the IMG element definition in HTML 4.0.

IDL Definition
interface HTMLImageElement : HTMLElement {
           attribute  DOMString            lowSrc;
           attribute  DOMString            name;
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  DOMString            border;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  boolean              isMap;
           attribute  DOMString            longDesc;
           attribute  DOMString            src;
           attribute  DOMString            useMap;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};
Attributes
lowSrc
URI designating the source of this image, for low-resolution output.
name
The name of the element (for backwards compatibility).
align
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
alt
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.0.
border
Width of border around image. See the border attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
height
Override height. See the height attribute definition in HTML 4.0.
hspace
Horizontal space to the left and right of this image. See the hspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
isMap
Use server-side image map. See the ismap attribute definition in HTML 4.0.
longDesc
URI designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.0.
src
URI designating the source of this image. See the src attribute definition in HTML 4.0.
useMap
Use client-side image map. See the usemap attribute definition in HTML 4.0.
vspace
Vertical space above and below this image. See the vspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
width
Override width. See the width attribute definition in HTML 4.0.
Interface HTMLObjectElement

Generic embedded object. Note. In principle, all properties on the object element are read-write but in some environments some properties may be read-only once the underlying object is instantiated. See the OBJECT element definition in HTML 4.0.

IDL Definition
interface HTMLObjectElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            code;
           attribute  DOMString            align;
           attribute  DOMString            archive;
           attribute  DOMString            border;
           attribute  DOMString            codeBase;
           attribute  DOMString            codeType;
           attribute  DOMString            data;
           attribute  boolean              declare;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  DOMString            name;
           attribute  DOMString            standby;
           attribute  long                 tabIndex;
           attribute  DOMString            type;
           attribute  DOMString            useMap;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};
Attributes
form
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
code
Applet class file. See the code attribute for HTMLAppletElement.
align
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
archive
Space-separated list of archives. See the archive attribute definition in HTML 4.0.
border
Width of border around the object. See the border attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
codeBase
Base URI for classid, data, and archive attributes. See the codebase attribute definition in HTML 4.0.
codeType
Content type for data downloaded via classid attribute. See the codetype attribute definition in HTML 4.0.
data
A URI specifying the location of the object's data. See the data attribute definition in HTML 4.0.
declare
Declare (for future reference), but do not instantiate, this object. See the declare attribute definition in HTML 4.0.
height
Override height. See the height attribute definition in HTML 4.0.
hspace
Horizontal space to the left and right of this image, applet, or object. See the hspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
name
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.0.
standby
Message to render while loading the object. See the standby attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
type
Content type for data downloaded via data attribute. See the type attribute definition in HTML 4.0.
useMap
Use client-side image map. See the usemap attribute definition in HTML 4.0.
vspace
Vertical space above and below this image, applet, or object. See the vspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
width
Override width. See the width attribute definition in HTML 4.0.
Interface HTMLParamElement

Parameters fed to the OBJECT element. See the PARAM element definition in HTML 4.0.

IDL Definition
interface HTMLParamElement : HTMLElement {
           attribute  DOMString            name;
           attribute  DOMString            type;
           attribute  DOMString            value;
           attribute  DOMString            valueType;
};
Attributes
name
The name of a run-time parameter. See the name attribute definition in HTML 4.0.
type
Content type for the value attribute when valuetype has the value "ref". See the type attribute definition in HTML 4.0.
value
The value of a run-time parameter. See the value attribute definition in HTML 4.0.
valueType
Information about the meaning of the value attribute value. See the valuetype attribute definition in HTML 4.0.
Interface HTMLAppletElement

An embedded Java applet. See the APPLET element definition in HTML 4.0. This element is deprecated in HTML 4.0.

IDL Definition
interface HTMLAppletElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  DOMString            archive;
           attribute  DOMString            code;
           attribute  DOMString            codeBase;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  DOMString            name;
           attribute  DOMString            object;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};
Attributes
align
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
alt
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
archive
Comma-separated archive list. See the archive attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
code
Applet class file. See the code attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
codeBase
Optional base URI for applet. See the codebase attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
height
Override height. See the height attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
hspace
Horizontal space to the left and right of this image, applet, or object. See the hspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
name
The name of the applet. See the name attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
object
Serialized applet file. See the object attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
vspace
Vertical space above and below this image, applet, or object. See the vspace attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
width
Override width. See the width attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLMapElement

Client-side image map. See the MAP element definition in HTML 4.0.

IDL Definition
interface HTMLMapElement : HTMLElement {
  readonly attribute  HTMLCollection       areas;
           attribute  DOMString            name;
};
Attributes
areas
The list of areas defined for the image map.
name
Names the map (for use with usemap). See the name attribute definition in HTML 4.0.
Interface HTMLAreaElement

Client-side image map area definition. See the AREA element definition in HTML 4.0.

IDL Definition
interface HTMLAreaElement : HTMLElement {
           attribute  DOMString            accessKey;
           attribute  DOMString            alt;
           attribute  DOMString            coords;
           attribute  DOMString            href;
           attribute  boolean              noHref;
           attribute  DOMString            shape;
           attribute  long                 tabIndex;
           attribute  DOMString            target;
};
Attributes
accessKey
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.0.
alt
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.0.
coords
Comma-separated list of lengths, defining an active region geometry. See also shape for the shape of the region. See the coords attribute definition in HTML 4.0.
href
The URI of the linked resource. See the href attribute definition in HTML 4.0.
noHref
Specifies that this area is inactive, i.e., has no associated action. See the nohref attribute definition in HTML 4.0.
shape
The shape of the active area. The coordinates are given by coords. See the shape attribute definition in HTML 4.0.
tabIndex
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.0.
target
Frame to render the resource in. See the target attribute definition in HTML 4.0.
Interface HTMLScriptElement

Script statements. See the SCRIPT element definition in HTML 4.0.

IDL Definition
interface HTMLScriptElement : HTMLElement {
           attribute  DOMString            text;
           attribute  DOMString            htmlFor;
           attribute  DOMString            event;
           attribute  DOMString            charset;
           attribute  boolean              defer;
           attribute  DOMString            src;
           attribute  DOMString            type;
};
Attributes
text
The script content of the element.
htmlFor
Reserved for future use.
event
Reserved for future use.
charset
The character encoding of the linked resource. See the charset attribute definition in HTML 4.0.
defer
Indicates that the user agent can defer processing of the script. See the defer attribute definition in HTML 4.0.
src
URI designating an external script. See the src attribute definition in HTML 4.0.
type
The content type of the script language. See the type attribute definition in HTML 4.0.
Interface HTMLTableElement

The create* and delete* methods on the table allow authors to construct and modify tables. HTML 4.0 specifies that only one of each of the CAPTION, THEAD, and TFOOT elements may exist in a table. Therefore, if one exists, and the createTHead() or createTFoot() method is called, the method returns the existing THead or TFoot element. See the TABLE element definition in HTML 4.0.

IDL Definition
interface HTMLTableElement : HTMLElement {
           attribute  HTMLTableCaptionElement caption;
           attribute  HTMLTableSectionElement tHead;
           attribute  HTMLTableSectionElement tFoot;
  readonly attribute  HTMLCollection       rows;
  readonly attribute  HTMLCollection       tBodies;
           attribute  DOMString            align;
           attribute  DOMString            bgColor;
           attribute  DOMString            border;
           attribute  DOMString            cellPadding;
           attribute  DOMString            cellSpacing;
           attribute  DOMString            frame;
           attribute  DOMString            rules;
           attribute  DOMString            summary;
           attribute  DOMString            width;
  HTMLElement               createTHead();
  void                      deleteTHead();
  HTMLElement               createTFoot();
  void                      deleteTFoot();
  HTMLElement               createCaption();
  void                      deleteCaption();
  HTMLElement               insertRow(in long index);
  void                      deleteRow(in long index);
};
Attributes
caption
Returns the table's CAPTION, or void if none exists.
tHead
Returns the table's THEAD, or null if none exists.
tFoot
Returns the table's TFOOT, or null if none exists.
rows
Returns a collection of all the rows in the table, including all in THEAD, TFOOT, all TBODY elements.
tBodies
Returns a collection of the defined table bodies.
align
Specifies the table's position with respect to the rest of the document. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
bgColor
Cell background color. See the bgcolor attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
border
The width of the border around the table. See the border attribute definition in HTML 4.0.
cellPadding
Specifies the horizontal and vertical space between cell content and cell borders. See the cellpadding attribute definition in HTML 4.0.
cellSpacing
Specifies the horizontal and vertical separation between cells. See the cellspacing attribute definition in HTML 4.0.
frame
Specifies which external table borders to render. See the frame attribute definition in HTML 4.0.
rules
Specifies which internal table borders to render. See the rules attribute definition in HTML 4.0.
summary
Supplementary description about the purpose or structure of a table. See the summary attribute definition in HTML 4.0.
width
Specifies the desired table width. See the width attribute definition in HTML 4.0.
Methods
createTHead
Create a table header row or return an existing one.
Return Value
A new table header element (THEAD).

This method has no parameters.
This method raises no exceptions.
deleteTHead
Delete the header from the table, if one exists.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
createTFoot
Create a table footer row or return an existing one.
Return Value
A footer element (TFOOT).

This method has no parameters.
This method raises no exceptions.
deleteTFoot
Delete the footer from the table, if one exists.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
createCaption
Create a new table caption object or return an existing one.
Return Value
A CAPTION element.

This method has no parameters.
This method raises no exceptions.
deleteCaption
Delete the table caption, if one exists.
This method has no parameters.
This method returns nothing.
This method raises no exceptions.
insertRow
Insert a new empty row in the table. Note. A table row cannot be empty according to HTML 4.0 Recommendation.
Parameters
index

The row number where to insert a new row.

Return Value
The newly created row.

This method raises no exceptions.
deleteRow
Delete a table row.
Parameters
index

The index of the row to be deleted.

This method returns nothing.
This method raises no exceptions.
Interface HTMLTableCaptionElement

Table caption See the CAPTION element definition in HTML 4.0.

IDL Definition
interface HTMLTableCaptionElement : HTMLElement {
           attribute  DOMString            align;
};
Attributes
align
Caption alignment with respect to the table. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLTableColElement

Regroups the COL and COLGROUP elements. See the COL element definition in HTML 4.0.

IDL Definition
interface HTMLTableColElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  long                 span;
           attribute  DOMString            vAlign;
           attribute  DOMString            width;
};
Attributes
align
Horizontal alignment of cell data in column. See the align attribute definition in HTML 4.0.
ch
Alignment character for cells in a column. See the char attribute definition in HTML 4.0.
chOff
Offset of alignment character. See the charoff attribute definition in HTML 4.0.
span
Indicates the number of columns in a group or affected by a grouping. See the span attribute definition in HTML 4.0.
vAlign
Vertical alignment of cell data in column. See the valign attribute definition in HTML 4.0.
width
Default column width. See the width attribute definition in HTML 4.0.
Interface HTMLTableSectionElement

The THEAD, TFOOT, and TBODY elements.

IDL Definition
interface HTMLTableSectionElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  DOMString            vAlign;
  readonly attribute  HTMLCollection       rows;
  HTMLElement               insertRow(in long index);
  void                      deleteRow(in long index);
};
Attributes
align
Horizontal alignment of data in cells. See the align attribute for HTMLTheadElement for details.
ch
Alignment character for cells in a column. See the char attribute definition in HTML 4.0.
chOff
Offset of alignment character. See the charoff attribute definition in HTML 4.0.
vAlign
Vertical alignment of data in cells. See the valign attribute for HTMLTheadElement for details.
rows
The collection of rows in this table section.
Methods
insertRow
Insert a row into this section.
Parameters
index

The row number where to insert a new row.

Return Value
The newly created row.

This method raises no exceptions.
deleteRow
Delete a row from this section.
Parameters
index

The index of the row to be deleted.

This method returns nothing.
This method raises no exceptions.
Interface HTMLTableRowElement

A row in a table. See the TR element definition in HTML 4.0.

IDL Definition
interface HTMLTableRowElement : HTMLElement {
           attribute  long                 rowIndex;
           attribute  long                 sectionRowIndex;
           attribute  HTMLCollection       cells;
           attribute  DOMString            align;
           attribute  DOMString            bgColor;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  DOMString            vAlign;
  HTMLElement               insertCell(in long index);
  void                      deleteCell(in long index);
};
Attributes
rowIndex
The index of this row, relative to the entire table.
sectionRowIndex
The index of this row, relative to the current section (THEAD, TFOOT, or TBODY).
cells
The collection of cells in this row.
align
Horizontal alignment of data within cells of this row. See the align attribute definition in HTML 4.0.
bgColor
Background color for rows. See the bgcolor attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
ch
Alignment character for cells in a column. See the char attribute definition in HTML 4.0.
chOff
Offset of alignment character. See the charoff attribute definition in HTML 4.0.
vAlign
Vertical alignment of data within cells of this row. See the valign attribute definition in HTML 4.0.
Methods
insertCell
Insert an empty TD cell into this row.
Parameters
index

The place to insert the cell.

Return Value
The newly created cell.

This method raises no exceptions.
deleteCell
Delete a cell from the current row.
Parameters
index

The index of the cell to delete.

This method returns nothing.
This method raises no exceptions.
Interface HTMLTableCellElement

The object used to represent the TH and TD elements. See the TD element definition in HTML 4.0.

IDL Definition
interface HTMLTableCellElement : HTMLElement {
           attribute  long                 cellIndex;
           attribute  DOMString            abbr;
           attribute  DOMString            align;
           attribute  DOMString            axis;
           attribute  DOMString            bgColor;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  long                 colSpan;
           attribute  DOMString            headers;
           attribute  DOMString            height;
           attribute  boolean              noWrap;
           attribute  long                 rowSpan;
           attribute  DOMString            scope;
           attribute  DOMString            vAlign;
           attribute  DOMString            width;
};
Attributes
cellIndex
The index of this cell in the row.
abbr
Abbreviation for header cells. See the abbr attribute definition in HTML 4.0.
align
Horizontal alignment of data in cell. See the align attribute definition in HTML 4.0.
axis
Names group of related headers. See the axis attribute definition in HTML 4.0.
bgColor
Cell background color. See the bgcolor attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
ch
Alignment character for cells in a column. See the char attribute definition in HTML 4.0.
chOff
Offset of alignment character. See the charoff attribute definition in HTML 4.0.
colSpan
Number of columns spanned by cell. See the colspan attribute definition in HTML 4.0.
headers
List of id attribute values for header cells. See the headers attribute definition in HTML 4.0.
height
Cell height. See the height attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
noWrap
Suppress word wrapping. See the nowrap attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
rowSpan
Number of rows spanned by cell. See the rowspan attribute definition in HTML 4.0.
scope
Scope covered by header cells. See the scope attribute definition in HTML 4.0.
vAlign
Vertical alignment of data in cell. See the valign attribute definition in HTML 4.0.
width
Cell width. See the width attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
Interface HTMLFrameSetElement

Create a grid of frames. See the FRAMESET element definition in HTML 4.0.

IDL Definition
interface HTMLFrameSetElement : HTMLElement {
           attribute  DOMString            cols;
           attribute  DOMString            rows;
};
Attributes
cols
The number of columns of frames in the frameset. See the cols attribute definition in HTML 4.0.
rows
The number of rows of frames in the frameset. See the rows attribute definition in HTML 4.0.
Interface HTMLFrameElement

Create a frame. See the FRAME element definition in HTML 4.0.

IDL Definition
interface HTMLFrameElement : HTMLElement {
           attribute  DOMString            frameBorder;
           attribute  DOMString            longDesc;
           attribute  DOMString            marginHeight;
           attribute  DOMString            marginWidth;
           attribute  DOMString            name;
           attribute  boolean              noResize;
           attribute  DOMString            scrolling;
           attribute  DOMString            src;
};
Attributes
frameBorder
Request frame borders. See the frameborder attribute definition in HTML 4.0.
longDesc
URI designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.0.
marginHeight
Frame margin height, in pixels. See the marginheight attribute definition in HTML 4.0.
marginWidth
Frame margin width, in pixels. See the marginwidth attribute definition in HTML 4.0.
name
The frame name (object of the target attribute). See the name attribute definition in HTML 4.0.
noResize
When true, forbid user from resizing frame. See the noresize attribute definition in HTML 4.0.
scrolling
Specify whether or not the frame should have scrollbars. See the scrolling attribute definition in HTML 4.0.
src
A URI designating the initial frame contents. See the src attribute definition in HTML 4.0.
Interface HTMLIFrameElement

Inline subwindows. See the IFRAME element definition in HTML 4.0.

IDL Definition
interface HTMLIFrameElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            frameBorder;
           attribute  DOMString            height;
           attribute  DOMString            longDesc;
           attribute  DOMString            marginHeight;
           attribute  DOMString            marginWidth;
           attribute  DOMString            name;
           attribute  DOMString            scrolling;
           attribute  DOMString            src;
           attribute  DOMString            width;
};
Attributes
align
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.0. This attribute is deprecated in HTML 4.0.
frameBorder
Request frame borders. See the frameborder attribute definition in HTML 4.0.
height
Frame height. See the height attribute definition in HTML 4.0.
longDesc
URI designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.0.
marginHeight
Frame margin height, in pixels. See the marginheight attribute definition in HTML 4.0.
marginWidth
Frame margin width, in pixels. See the marginwidth attribute definition in HTML 4.0.
name
The frame name (object of the target attribute). See the name attribute definition in HTML 4.0.
scrolling
Specify whether or not the frame should have scrollbars. See the scrolling attribute definition in HTML 4.0.
src
A URI designating the initial frame contents. See the src attribute definition in HTML 4.0.
width
Frame width. See the width attribute definition in HTML 4.0.

Document Object Model (Core) Level 1 REC-DOM-Level-1-19981001 Contributors


Contributors

REC-DOM-Level-1-19981001
Document Object Model (HTML) Level 1 REC-DOM-Level-1-19981001 Glossary

Appendix A: Contributors

Members of the DOM Working Group and Interest Group contributing to this specification were:

Lauren Wood, SoftQuad, Inc., chair
Arnaud Le Hors, W3C, W3C staff contact
Andrew Watson, Object Management Group
Bill Smith, Sun
Chris Lovett, Microsoft
Chris Wilson, Microsoft
David Brownell, Sun
David Singer, IBM
Don Park, invited
Eric Vasilik, Microsoft
Gavin Nicol, INSO
Ian Jacobs, W3C
James Clark, invited
Jared Sorensen, Novell
Jonathan Robie, Texcel
Mike Champion, ArborText
Paul Grosso, ArborText
Peter Sharpe, SoftQuad, Inc.
Phil Karlton, Netscape
Ray Whitmer, iMall
Rich Rollman, Microsoft
Rick Gessner, Netscape
Robert Sutor, IBM
Scott Isaacs, Microsoft
Sharon Adler, INSO
Steve Byrne, JavaSoft
Tim Bray, invited
Tom Pixley, Netscape
Vidur Apparao, Netscape
Document Object Model (HTML) Level 1 REC-DOM-Level-1-19981001 Glossary


Glossary

REC-DOM-Level-1-19981001
Contributors REC-DOM-Level-1-19981001 IDL Definitions

Appendix B: Glossary

Editors
Robert S. Sutor, IBM Research

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

ancestor
An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root."
API
An API is an application programming interface, a set of functions or methods used to access some functionality.
child
A child is an immediate descendant node of a node.
client application
A [client] application is any software that uses the Document Object Model programming interfaces provided by the hosting implementation to accomplish useful work. Some examples of client applications are scripts within an HTML or XML document.
COM
COM is Microsoft's Component Object Model, a technology for building applications from binary software components.
content model
The content model is a simple grammar governing the allowed types of the child elements and the order in which they appear. See [XML ]
context
A context specifies an access pattern (or path): a set of interfaces which give you a way to interact with a model. For example, imagine a model with different colored arcs connecting data nodes. A context might be a sheet of colored acetate that is placed over the model allowing you a partial view of the total information in the model.
convenience
A convenience method is an operation on an object that could be accomplished by a program consisting of more basic operations on the object. Convenience methods are usually provided to make the API easier and simpler to use or to allow specific programs to create more optimized implementations for common operations. A similar definition holds for a convenience property.
cooked model
A model for a document that represents the document after it has been manipulated in some way. For example, any combination of any of the following transformations would create a cooked model:
  1. Expansion of internal text entities.
  2. Expansion of external entities.
  3. Model augmentation with style-specified generated text.
  4. Execution of style-specified reordering.
  5. Execution of scripts.
A browser might only be able to provide access to a cooked model, while an editor might provide access to a cooked or the initial structure model (also known as the uncooked model) for a document.
CORBA
CORBA is the Common Object Request Broker Architecture from the OMG . This architecture is a collection of objects and libraries that allow the creation of applications containing objects that make and receive requests and responses in a distributed environment.
cursor
A cursor is an object representation of a node. It may possess information about context and the path traversed to reach the node.
data model
A data model is a collection of descriptions of data structures and their contained fields, together with the operations or functions that manipulate them.
deprecation
When new releases of specifications are released, some older features may be marked as being deprecated. This means that new work should not use the features and that although they are supported in the current release, they may not be supported or available in future releases.
descendant
A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root."
ECMAScript
The programming language defined by the ECMA-262 standard. As stated in the standard, the originating technology for ECMAScript was JavaScript. Note that in the ECMAScript binding, the word "property" is used in the same sense as the IDL term "attribute."
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. [XML ]
event propagation, also known as event bubbling
This is the idea that an event can affect one object and a set of related objects. Any of the potentially affected objects can block the event or substitute a different one (upward event propagation). The event is broadcast from the node at which it originates to every parent node.
equivalence
Two nodes are equivalent if they have the same node type and same node name. Also, if the nodes contain data, that must be the same. Finally, if the nodes have attributes then collection of attribute names must be the same and the attributes corresponding by name must be equivalent as nodes. Two nodes are deeply equivalent if they are equivalent, the child node lists are equivalent are equivalent as NodeList objects, and the pairs of equivalent attributes must in fact be deeply equivalent. Two NodeList objects are equivalent if they have the same length, and the nodes corresponding by index are deeply equivalent. Two NamedNodeMap objects are equivalent if they are have the same length, they have same collection of names, and the nodes corresponding by name in the maps are deeply equivalent. Two DocumentType nodes are equivalent if they are equivalent as nodes, have the same names, and have equivalent entities and attributes NamedNodeMap objects.
hosting implementation
A [hosting] implementation is a software module that provides an implementation of the DOM interfaces so that a client application can use them. Some examples of hosting implementations are browsers, editors and document repositories.
HTML
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents with generic semantics that are appropriate for representing information from a wide range of applications. [HTML 3.2 ] [HTML4.0 ]
IDL
An Interface Definition Language (IDL) is used to define the interfaces for accessing and operating upon objects. Examples of IDLs are the Object Management Group's IDL , Microsoft's IDL , and Sun's Java IDL .
implementor
Companies, organizations, and individuals that claim to support the Document Object Model as an API for their products.
inheritance
In object-oriented programming, the ability to create new classes (or interfaces) that contain all the methods and properties of another class (or interface), plus additional methods and properties. If class (or interface) D inherits from class (or interface) B, then D is said to be derived from B. B is said to be a base class (or interface) for D. Some programming languages allow for multiple inheritance, that is, inheritance from more than one class or interface.
initial structure model
Also known as the raw structure model or the uncooked model, this represents the document before it has been modified by entity expansions, generated text, style-specified reordering, or the execution of scripts. In some implementations, this might correspond to the "initial parse tree" for the document, if it ever exists. Note that a given implementation might not be able to provide access to the initial structure model for a document, though an editor probably would.
interface
An interface is a declaration of a set of methods with no information given about their implementation. In object systems that support interfaces and inheritance, interfaces can usually inherit from one another.
language binding
A programming language binding for an IDL specification is an implementation of the interfaces in the specification for the given language. For example, a Java language binding for the Document Object Model IDL specification would implement the concrete Java classes that provide the functionality exposed by the interfaces.
method
A method is an operation or function that is associated with an object and is allowed to manipulate the object's data.
model
A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else.
object model
An object model is a collection of descriptions of classes or interfaces, together with their member data, member functions, and class-static operations.
parent
A parent is an immediate ancestor node of a node.
root node
The root node is the unique node that is not a child of any other node. All other nodes are children or other descendents of the root node. [XML ]
sibling
Two nodes are siblings if they have the same parent node.
string comparison
When string matching is required, it is to occur as though the comparison was between 2 sequences of code points from the Unicode 2.0 standard.
tag valid document
A document is tag valid if all begin and end tags are properly balanced and nested.
type valid document
A document is type valid if it conforms to an explicit DTD.
uncooked model
See initial structure model.
well-formed document
A document is well-formed if it is tag valid and entities are limited to single elements (i.e., single sub-trees).
XML
Extensible Markup Language (XML) is an extremely simple dialect of SGML which is completely described in this document. The goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. [XML ]
Contributors REC-DOM-Level-1-19981001 IDL Definitions


IDL Definitions

REC-DOM-Level-1-19981001
Glossary REC-DOM-Level-1-19981001 Java Language Binding

Appendix C: IDL Definitions

This appendix contains the complete OMG IDL for the Level 1 Document Object Model definitions. The definitions are divided into Core and HTML.

The IDL files are also available as: http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/idl.zip

C.1: Document Object Model Level 1 Core

This section contains the OMG IDL definitions for the interfaces in the Core Document Object Model specification, including the extended (XML) interfaces.

exception DOMException {
  unsigned short   code;
};

// ExceptionCode
const unsigned short      INDEX_SIZE_ERR     = 1;
const unsigned short      DOMSTRING_SIZE_ERR = 2;
const unsigned short      HIERARCHY_REQUEST_ERR = 3;
const unsigned short      WRONG_DOCUMENT_ERR = 4;
const unsigned short      INVALID_CHARACTER_ERR = 5;
const unsigned short      NO_DATA_ALLOWED_ERR = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short      NOT_FOUND_ERR      = 8;
const unsigned short      NOT_SUPPORTED_ERR  = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR = 10;

// ExceptionCode
const unsigned short      INDEX_SIZE_ERR     = 1;
const unsigned short      DOMSTRING_SIZE_ERR = 2;
const unsigned short      HIERARCHY_REQUEST_ERR = 3;
const unsigned short      WRONG_DOCUMENT_ERR = 4;
const unsigned short      INVALID_CHARACTER_ERR = 5;
const unsigned short      NO_DATA_ALLOWED_ERR = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR = 7;
const unsigned short      NOT_FOUND_ERR      = 8;
const unsigned short      NOT_SUPPORTED_ERR  = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR = 10;

interface DOMImplementation {
  boolean                   hasFeature(in DOMString feature,
                                       in DOMString version);
};

interface DocumentFragment : Node {
};

interface Document : Node {
  readonly attribute  DocumentType         doctype;
  readonly attribute  DOMImplementation    implementation;
  readonly attribute  Element              documentElement;
  Element                   createElement(in DOMString tagName)
                                          raises(DOMException);
  DocumentFragment          createDocumentFragment();
  Text                      createTextNode(in DOMString data);
  Comment                   createComment(in DOMString data);
  CDATASection              createCDATASection(in DOMString data)
                                               raises(DOMException);
  ProcessingInstruction     createProcessingInstruction(in DOMString target,
                                                        in DOMString data)
                                                        raises(DOMException);
  Attr                      createAttribute(in DOMString name)
                                            raises(DOMException);
  EntityReference           createEntityReference(in DOMString name)
                                                  raises(DOMException);
  NodeList                  getElementsByTagName(in DOMString tagname);
};

interface Node {
  // NodeType
  const unsigned short      ELEMENT_NODE       = 1;
  const unsigned short      ATTRIBUTE_NODE     = 2;
  const unsigned short      TEXT_NODE          = 3;
  const unsigned short      CDATA_SECTION_NODE = 4;
  const unsigned short      ENTITY_REFERENCE_NODE = 5;
  const unsigned short      ENTITY_NODE        = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short      COMMENT_NODE       = 8;
  const unsigned short      DOCUMENT_NODE      = 9;
  const unsigned short      DOCUMENT_TYPE_NODE = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short      NOTATION_NODE      = 12;

  readonly attribute  DOMString            nodeName;
           attribute  DOMString            nodeValue;
                                                 // raises(DOMException) on setting
                                                 // raises(DOMException) on retrieval
  readonly attribute  unsigned short       nodeType;
  readonly attribute  Node                 parentNode;
  readonly attribute  NodeList             childNodes;
  readonly attribute  Node                 firstChild;
  readonly attribute  Node                 lastChild;
  readonly attribute  Node                 previousSibling;
  readonly attribute  Node                 nextSibling;
  readonly attribute  NamedNodeMap         attributes;
  readonly attribute  Document             ownerDocument;
  Node                      insertBefore(in Node newChild,
                                         in Node refChild)
                                         raises(DOMException);
  Node                      replaceChild(in Node newChild,
                                         in Node oldChild)
                                         raises(DOMException);
  Node                      removeChild(in Node oldChild)
                                        raises(DOMException);
  Node                      appendChild(in Node newChild)
                                        raises(DOMException);
  boolean                   hasChildNodes();
  Node                      cloneNode(in boolean deep);
};

interface NodeList {
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};

interface NamedNodeMap {
  Node                      getNamedItem(in DOMString name);
  Node                      setNamedItem(in Node arg)
                                         raises(DOMException);
  Node                      removeNamedItem(in DOMString name)
                                            raises(DOMException);
  Node                      item(in unsigned long index);
  readonly attribute  unsigned long        length;
};

interface CharacterData : Node {
           attribute  DOMString            data;
                                 // raises(DOMException) on setting
                                 // raises(DOMException) on retrieval
  readonly attribute  unsigned long        length;
  DOMString                 substringData(in unsigned long offset,
                                          in unsigned long count)
                                          raises(DOMException);
  void                      appendData(in DOMString arg)
                                       raises(DOMException);
  void                      insertData(in unsigned long offset,
                                       in DOMString arg)
                                       raises(DOMException);
  void                      deleteData(in unsigned long offset,
                                       in unsigned long count)
                                       raises(DOMException);
  void                      replaceData(in unsigned long offset,
                                        in unsigned long count,
                                        in DOMString arg)
                                        raises(DOMException);
};

interface Attr : Node {
  readonly attribute  DOMString            name;
  readonly attribute  boolean              specified;
           attribute  DOMString            value;
};

interface Element : Node {
  readonly attribute  DOMString            tagName;
  DOMString                 getAttribute(in DOMString name);
  void                      setAttribute(in DOMString name,
                                         in DOMString value)
                                         raises(DOMException);
  void                      removeAttribute(in DOMString name)
                                            raises(DOMException);
  Attr                      getAttributeNode(in DOMString name);
  Attr                      setAttributeNode(in Attr newAttr)
                                             raises(DOMException);
  Attr                      removeAttributeNode(in Attr oldAttr)
                                                raises(DOMException);
  NodeList                  getElementsByTagName(in DOMString name);
  void                      normalize();
};

interface Text : CharacterData {
  Text                      splitText(in unsigned long offset)
                                      raises(DOMException);
};

interface Comment : CharacterData {
};

interface CDATASection : Text {
};

interface DocumentType : Node {
  readonly attribute  DOMString            name;
  readonly attribute  NamedNodeMap         entities;
  readonly attribute  NamedNodeMap         notations;
};

interface Notation : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
};

interface Entity : Node {
  readonly attribute  DOMString            publicId;
  readonly attribute  DOMString            systemId;
  readonly attribute  DOMString            notationName;
};

interface EntityReference : Node {
};

interface ProcessingInstruction : Node {
  readonly attribute  DOMString            target;
           attribute  DOMString            data;
                                      // raises(DOMException) on setting
};

C.2: Document Object Model Level 1 HTML

interface HTMLCollection {
  readonly attribute  unsigned long        length;
  Node                      item(in unsigned long index);
  Node                      namedItem(in DOMString name);
};

interface HTMLDocument : Document {
           attribute  DOMString            title;
  readonly attribute  DOMString            referrer;
  readonly attribute  DOMString            domain;
  readonly attribute  DOMString            URL;
           attribute  HTMLElement          body;
  readonly attribute  HTMLCollection       images;
  readonly attribute  HTMLCollection       applets;
  readonly attribute  HTMLCollection       links;
  readonly attribute  HTMLCollection       forms;
  readonly attribute  HTMLCollection       anchors;
           attribute  DOMString            cookie;
  void                      open();
  void                      close();
  void                      write(in DOMString text);
  void                      writeln(in DOMString text);
  Element                   getElementById(in DOMString elementId);
  NodeList                  getElementsByName(in DOMString elementName);
};

interface HTMLElement : Element {
           attribute  DOMString            id;
           attribute  DOMString            title;
           attribute  DOMString            lang;
           attribute  DOMString            dir;
           attribute  DOMString            className;
};

interface HTMLHtmlElement : HTMLElement {
           attribute  DOMString            version;
};

interface HTMLHeadElement : HTMLElement {
           attribute  DOMString            profile;
};

interface HTMLLinkElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            charset;
           attribute  DOMString            href;
           attribute  DOMString            hreflang;
           attribute  DOMString            media;
           attribute  DOMString            rel;
           attribute  DOMString            rev;
           attribute  DOMString            target;
           attribute  DOMString            type;
};

interface HTMLTitleElement : HTMLElement {
           attribute  DOMString            text;
};

interface HTMLMetaElement : HTMLElement {
           attribute  DOMString            content;
           attribute  DOMString            httpEquiv;
           attribute  DOMString            name;
           attribute  DOMString            scheme;
};

interface HTMLBaseElement : HTMLElement {
           attribute  DOMString            href;
           attribute  DOMString            target;
};

interface HTMLIsIndexElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            prompt;
};

interface HTMLStyleElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            media;
           attribute  DOMString            type;
};

interface HTMLBodyElement : HTMLElement {
           attribute  DOMString            aLink;
           attribute  DOMString            background;
           attribute  DOMString            bgColor;
           attribute  DOMString            link;
           attribute  DOMString            text;
           attribute  DOMString            vLink;
};

interface HTMLFormElement : HTMLElement {
  readonly attribute  HTMLCollection       elements;
  readonly attribute  long                 length;
           attribute  DOMString            name;
           attribute  DOMString            acceptCharset;
           attribute  DOMString            action;
           attribute  DOMString            enctype;
           attribute  DOMString            method;
           attribute  DOMString            target;
  void                      submit();
  void                      reset();
};

interface HTMLSelectElement : HTMLElement {
  readonly attribute  DOMString            type;
           attribute  long                 selectedIndex;
           attribute  DOMString            value;
  readonly attribute  long                 length;
  readonly attribute  HTMLFormElement      form;
  readonly attribute  HTMLCollection       options;
           attribute  boolean              disabled;
           attribute  boolean              multiple;
           attribute  DOMString            name;
           attribute  long                 size;
           attribute  long                 tabIndex;
  void                      add(in HTMLElement element,
                                in HTMLElement before);
  void                      remove(in long index);
  void                      blur();
  void                      focus();
};

interface HTMLOptGroupElement : HTMLElement {
           attribute  boolean              disabled;
           attribute  DOMString            label;
};

interface HTMLOptionElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  boolean              defaultSelected;
  readonly attribute  DOMString            text;
           attribute  long                 index;
           attribute  boolean              disabled;
           attribute  DOMString            label;
  readonly attribute  boolean              selected;
           attribute  DOMString            value;
};

interface HTMLInputElement : HTMLElement {
           attribute  DOMString            defaultValue;
           attribute  boolean              defaultChecked;
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accept;
           attribute  DOMString            accessKey;
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  boolean              checked;
           attribute  boolean              disabled;
           attribute  long                 maxLength;
           attribute  DOMString            name;
           attribute  boolean              readOnly;
           attribute  DOMString            size;
           attribute  DOMString            src;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            useMap;
           attribute  DOMString            value;
  void                      blur();
  void                      focus();
  void                      select();
  void                      click();
};

interface HTMLTextAreaElement : HTMLElement {
           attribute  DOMString            defaultValue;
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  long                 cols;
           attribute  boolean              disabled;
           attribute  DOMString            name;
           attribute  boolean              readOnly;
           attribute  long                 rows;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            value;
  void                      blur();
  void                      focus();
  void                      select();
};

interface HTMLButtonElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  boolean              disabled;
           attribute  DOMString            name;
           attribute  long                 tabIndex;
  readonly attribute  DOMString            type;
           attribute  DOMString            value;
};

interface HTMLLabelElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  DOMString            htmlFor;
};

interface HTMLFieldSetElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
};

interface HTMLLegendElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            accessKey;
           attribute  DOMString            align;
};

interface HTMLUListElement : HTMLElement {
           attribute  boolean              compact;
           attribute  DOMString            type;
};

interface HTMLOListElement : HTMLElement {
           attribute  boolean              compact;
           attribute  long                 start;
           attribute  DOMString            type;
};

interface HTMLDListElement : HTMLElement {
           attribute  boolean              compact;
};

interface HTMLDirectoryElement : HTMLElement {
           attribute  boolean              compact;
};

interface HTMLMenuElement : HTMLElement {
           attribute  boolean              compact;
};

interface HTMLLIElement : HTMLElement {
           attribute  DOMString            type;
           attribute  long                 value;
};

interface HTMLBlockquoteElement : HTMLElement {
           attribute  DOMString            cite;
};

interface HTMLDivElement : HTMLElement {
           attribute  DOMString            align;
};

interface HTMLParagraphElement : HTMLElement {
           attribute  DOMString            align;
};

interface HTMLHeadingElement : HTMLElement {
           attribute  DOMString            align;
};

interface HTMLQuoteElement : HTMLElement {
           attribute  DOMString            cite;
};

interface HTMLPreElement : HTMLElement {
           attribute  long                 width;
};

interface HTMLBRElement : HTMLElement {
           attribute  DOMString            clear;
};

interface HTMLBaseFontElement : HTMLElement {
           attribute  DOMString            color;
           attribute  DOMString            face;
           attribute  DOMString            size;
};

interface HTMLFontElement : HTMLElement {
           attribute  DOMString            color;
           attribute  DOMString            face;
           attribute  DOMString            size;
};

interface HTMLHRElement : HTMLElement {
           attribute  DOMString            align;
           attribute  boolean              noShade;
           attribute  DOMString            size;
           attribute  DOMString            width;
};

interface HTMLModElement : HTMLElement {
           attribute  DOMString            cite;
           attribute  DOMString            dateTime;
};

interface HTMLAnchorElement : HTMLElement {
           attribute  DOMString            accessKey;
           attribute  DOMString            charset;
           attribute  DOMString            coords;
           attribute  DOMString            href;
           attribute  DOMString            hreflang;
           attribute  DOMString            name;
           attribute  DOMString            rel;
           attribute  DOMString            rev;
           attribute  DOMString            shape;
           attribute  long                 tabIndex;
           attribute  DOMString            target;
           attribute  DOMString            type;
  void                      blur();
  void                      focus();
};

interface HTMLImageElement : HTMLElement {
           attribute  DOMString            lowSrc;
           attribute  DOMString            name;
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  DOMString            border;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  boolean              isMap;
           attribute  DOMString            longDesc;
           attribute  DOMString            src;
           attribute  DOMString            useMap;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};

interface HTMLObjectElement : HTMLElement {
  readonly attribute  HTMLFormElement      form;
           attribute  DOMString            code;
           attribute  DOMString            align;
           attribute  DOMString            archive;
           attribute  DOMString            border;
           attribute  DOMString            codeBase;
           attribute  DOMString            codeType;
           attribute  DOMString            data;
           attribute  boolean              declare;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  DOMString            name;
           attribute  DOMString            standby;
           attribute  long                 tabIndex;
           attribute  DOMString            type;
           attribute  DOMString            useMap;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};

interface HTMLParamElement : HTMLElement {
           attribute  DOMString            name;
           attribute  DOMString            type;
           attribute  DOMString            value;
           attribute  DOMString            valueType;
};

interface HTMLAppletElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            alt;
           attribute  DOMString            archive;
           attribute  DOMString            code;
           attribute  DOMString            codeBase;
           attribute  DOMString            height;
           attribute  DOMString            hspace;
           attribute  DOMString            name;
           attribute  DOMString            object;
           attribute  DOMString            vspace;
           attribute  DOMString            width;
};

interface HTMLMapElement : HTMLElement {
  readonly attribute  HTMLCollection       areas;
           attribute  DOMString            name;
};

interface HTMLAreaElement : HTMLElement {
           attribute  DOMString            accessKey;
           attribute  DOMString            alt;
           attribute  DOMString            coords;
           attribute  DOMString            href;
           attribute  boolean              noHref;
           attribute  DOMString            shape;
           attribute  long                 tabIndex;
           attribute  DOMString            target;
};

interface HTMLScriptElement : HTMLElement {
           attribute  DOMString            text;
           attribute  DOMString            htmlFor;
           attribute  DOMString            event;
           attribute  DOMString            charset;
           attribute  boolean              defer;
           attribute  DOMString            src;
           attribute  DOMString            type;
};

interface HTMLTableElement : HTMLElement {
           attribute  HTMLTableCaptionElement caption;
           attribute  HTMLTableSectionElement tHead;
           attribute  HTMLTableSectionElement tFoot;
  readonly attribute  HTMLCollection       rows;
  readonly attribute  HTMLCollection       tBodies;
           attribute  DOMString            align;
           attribute  DOMString            bgColor;
           attribute  DOMString            border;
           attribute  DOMString            cellPadding;
           attribute  DOMString            cellSpacing;
           attribute  DOMString            frame;
           attribute  DOMString            rules;
           attribute  DOMString            summary;
           attribute  DOMString            width;
  HTMLElement               createTHead();
  void                      deleteTHead();
  HTMLElement               createTFoot();
  void                      deleteTFoot();
  HTMLElement               createCaption();
  void                      deleteCaption();
  HTMLElement               insertRow(in long index);
  void                      deleteRow(in long index);
};

interface HTMLTableCaptionElement : HTMLElement {
           attribute  DOMString            align;
};

interface HTMLTableColElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  long                 span;
           attribute  DOMString            vAlign;
           attribute  DOMString            width;
};

interface HTMLTableSectionElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  DOMString            vAlign;
  readonly attribute  HTMLCollection       rows;
  HTMLElement               insertRow(in long index);
  void                      deleteRow(in long index);
};

interface HTMLTableRowElement : HTMLElement {
           attribute  long                 rowIndex;
           attribute  long                 sectionRowIndex;
           attribute  HTMLCollection       cells;
           attribute  DOMString            align;
           attribute  DOMString            bgColor;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  DOMString            vAlign;
  HTMLElement               insertCell(in long index);
  void                      deleteCell(in long index);
};

interface HTMLTableCellElement : HTMLElement {
           attribute  long                 cellIndex;
           attribute  DOMString            abbr;
           attribute  DOMString            align;
           attribute  DOMString            axis;
           attribute  DOMString            bgColor;
           attribute  DOMString            ch;
           attribute  DOMString            chOff;
           attribute  long                 colSpan;
           attribute  DOMString            headers;
           attribute  DOMString            height;
           attribute  boolean              noWrap;
           attribute  long                 rowSpan;
           attribute  DOMString            scope;
           attribute  DOMString            vAlign;
           attribute  DOMString            width;
};

interface HTMLFrameSetElement : HTMLElement {
           attribute  DOMString            cols;
           attribute  DOMString            rows;
};

interface HTMLFrameElement : HTMLElement {
           attribute  DOMString            frameBorder;
           attribute  DOMString            longDesc;
           attribute  DOMString            marginHeight;
           attribute  DOMString            marginWidth;
           attribute  DOMString            name;
           attribute  boolean              noResize;
           attribute  DOMString            scrolling;
           attribute  DOMString            src;
};

interface HTMLIFrameElement : HTMLElement {
           attribute  DOMString            align;
           attribute  DOMString            frameBorder;
           attribute  DOMString            height;
           attribute  DOMString            longDesc;
           attribute  DOMString            marginHeight;
           attribute  DOMString            marginWidth;
           attribute  DOMString            name;
           attribute  DOMString            scrolling;
           attribute  DOMString            src;
           attribute  DOMString            width;
};

Glossary REC-DOM-Level-1-19981001 Java Language Binding


Java Language Binding

REC-DOM-Level-1-19981001
IDL Definitions REC-DOM-Level-1-19981001 ECMA Script Language Binding

Appendix D: Java Language Binding

This appendix contains the complete Java binding for the Level 1 Document Object Model. The definitions are divided into Core and HTML.

The Java files are also available as http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/java-binding.zip

D.1: Document Object Model Level 1 Core

public abstract class DOMException extends RuntimeException {
  public DOMException(short code, String message) {
     super(message);
     this.code = code;
  }
  public short   code;
  // ExceptionCode
  public static final short           INDEX_SIZE_ERR       = 1;
  public static final short           DOMSTRING_SIZE_ERR   = 2;
  public static final short           HIERARCHY_REQUEST_ERR = 3;
  public static final short           WRONG_DOCUMENT_ERR   = 4;
  public static final short           INVALID_CHARACTER_ERR = 5;
  public static final short           NO_DATA_ALLOWED_ERR  = 6;
  public static final short           NO_MODIFICATION_ALLOWED_ERR = 7;
  public static final short           NOT_FOUND_ERR        = 8;
  public static final short           NOT_SUPPORTED_ERR    = 9;
  public static final short           INUSE_ATTRIBUTE_ERR  = 10;

}

// ExceptionCode
public static final short           INDEX_SIZE_ERR       = 1;
public static final short           DOMSTRING_SIZE_ERR   = 2;
public static final short           HIERARCHY_REQUEST_ERR = 3;
public static final short           WRONG_DOCUMENT_ERR   = 4;
public static final short           INVALID_CHARACTER_ERR = 5;
public static final short           NO_DATA_ALLOWED_ERR  = 6;
public static final short           NO_MODIFICATION_ALLOWED_ERR = 7;
public static final short           NOT_FOUND_ERR        = 8;
public static final short           NOT_SUPPORTED_ERR    = 9;
public static final short           INUSE_ATTRIBUTE_ERR  = 10;

}

public interface DOMImplementation {
  public boolean            hasFeature(String feature,
                                       String version);
}

public interface DocumentFragment extends Node {
}

public interface Document extends Node {
  public DocumentType       getDoctype();
  public DOMImplementation  getImplementation();
  public Element            getDocumentElement();
  public Element            createElement(String tagName)
                                          throws DOMException;
  public DocumentFragment   createDocumentFragment();
  public Text               createTextNode(String data);
  public Comment            createComment(String data);
  public CDATASection       createCDATASection(String data)
                                               throws DOMException;
  public ProcessingInstruction createProcessingInstruction(String target,
                                                           String data)
                                                           throws DOMException;
  public Attr               createAttribute(String name)
                                            throws DOMException;
  public EntityReference    createEntityReference(String name)
                                                  throws DOMException;
  public NodeList           getElementsByTagName(String tagname);
}

public interface Node {
  // NodeType
  public static final short           ELEMENT_NODE         = 1;
  public static final short           ATTRIBUTE_NODE       = 2;
  public static final short           TEXT_NODE            = 3;
  public static final short           CDATA_SECTION_NODE   = 4;
  public static final short           ENTITY_REFERENCE_NODE = 5;
  public static final short           ENTITY_NODE          = 6;
  public static final short           PROCESSING_INSTRUCTION_NODE = 7;
  public static final short           COMMENT_NODE         = 8;
  public static final short           DOCUMENT_NODE        = 9;
  public static final short           DOCUMENT_TYPE_NODE   = 10;
  public static final short           DOCUMENT_FRAGMENT_NODE = 11;
  public static final short           NOTATION_NODE        = 12;

  public String             getNodeName();
  public String             getNodeValue()
                                                 throws DOMException;
  public void               setNodeValue(String nodeValue)
                                                 throws DOMException;
  public short              getNodeType();
  public Node               getParentNode();
  public NodeList           getChildNodes();
  public Node               getFirstChild();
  public Node               getLastChild();
  public Node               getPreviousSibling();
  public Node               getNextSibling();
  public NamedNodeMap       getAttributes();
  public Document           getOwnerDocument();
  public Node               insertBefore(Node newChild,
                                         Node refChild)
                                         throws DOMException;
  public Node               replaceChild(Node newChild,
                                         Node oldChild)
                                         throws DOMException;
  public Node               removeChild(Node oldChild)
                                        throws DOMException;
  public Node               appendChild(Node newChild)
                                        throws DOMException;
  public boolean            hasChildNodes();
  public Node               cloneNode(boolean deep);
}

public interface NodeList {
  public Node               item(int index);
  public int                getLength();
}

public interface NamedNodeMap {
  public Node               getNamedItem(String name);
  public Node               setNamedItem(Node arg)
                                         throws DOMException;
  public Node               removeNamedItem(String name)
                                            throws DOMException;
  public Node               item(int index);
  public int                getLength();
}

public interface CharacterData extends Node {
  public String             getData()
                                 throws DOMException;
  public void               setData(String data)
                                 throws DOMException;
  public int                getLength();
  public String             substringData(int offset,
                                          int count)
                                          throws DOMException;
  public void               appendData(String arg)
                                       throws DOMException;
  public void               insertData(int offset,
                                       String arg)
                                       throws DOMException;
  public void               deleteData(int offset,
                                       int count)
                                       throws DOMException;
  public void               replaceData(int offset,
                                        int count,
                                        String arg)
                                        throws DOMException;
}

public interface Attr extends Node {
  public String             getName();
  public boolean            getSpecified();
  public String             getValue();
  public void               setValue(String value);
}

public interface Element extends Node {
  public String             getTagName();
  public String             getAttribute(String name);
  public void               setAttribute(String name,
                                         String value)
                                         throws DOMException;
  public void               removeAttribute(String name)
                                            throws DOMException;
  public Attr               getAttributeNode(String name);
  public Attr               setAttributeNode(Attr newAttr)
                                             throws DOMException;
  public Attr               removeAttributeNode(Attr oldAttr)
                                                throws DOMException;
  public NodeList           getElementsByTagName(String name);
  public void               normalize();
}

public interface Text extends CharacterData {
  public Text               splitText(int offset)
                                      throws DOMException;
}

public interface Comment extends CharacterData {
}

public interface CDATASection extends Text {
}

public interface DocumentType extends Node {
  public String             getName();
  public NamedNodeMap       getEntities();
  public NamedNodeMap       getNotations();
}

public interface Notation extends Node {
  public String             getPublicId();
  public String             getSystemId();
}

public interface Entity extends Node {
  public String             getPublicId();
  public String             getSystemId();
  public String             getNotationName();
}

public interface EntityReference extends Node {
}

public interface ProcessingInstruction extends Node {
  public String             getTarget();
  public String             getData();
  public void               setData(String data)
                                      throws DOMException;
}

D.2: Document Object Model Level 1 HTML

public interface HTMLCollection {
  public int                getLength();
  public Node               item(int index);
  public Node               namedItem(String name);
}

public interface HTMLDocument extends Document {
  public String             getTitle();
  public void               setTitle(String title);
  public String             getReferrer();
  public String             getDomain();
  public String             getURL();
  public HTMLElement        getBody();
  public void               setBody(HTMLElement body);
  public HTMLCollection     getImages();
  public HTMLCollection     getApplets();
  public HTMLCollection     getLinks();
  public HTMLCollection     getForms();
  public HTMLCollection     getAnchors();
  public String             getCookie();
  public void               setCookie(String cookie);
  public void               open();
  public void               close();
  public void               write(String text);
  public void               writeln(String text);
  public Element            getElementById(String elementId);
  public NodeList           getElementsByName(String elementName);
}

public interface HTMLElement extends Element {
  public String             getId();
  public void               setId(String id);
  public String             getTitle();
  public void               setTitle(String title);
  public String             getLang();
  public void               setLang(String lang);
  public String             getDir();
  public void               setDir(String dir);
  public String             getClassName();
  public void               setClassName(String className);
}

public interface HTMLHtmlElement extends HTMLElement {
  public String             getVersion();
  public void               setVersion(String version);
}

public interface HTMLHeadElement extends HTMLElement {
  public String             getProfile();
  public void               setProfile(String profile);
}

public interface HTMLLinkElement extends HTMLElement {
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getCharset();
  public void               setCharset(String charset);
  public String             getHref();
  public void               setHref(String href);
  public String             getHreflang();
  public void               setHreflang(String hreflang);
  public String             getMedia();
  public void               setMedia(String media);
  public String             getRel();
  public void               setRel(String rel);
  public String             getRev();
  public void               setRev(String rev);
  public String             getTarget();
  public void               setTarget(String target);
  public String             getType();
  public void               setType(String type);
}

public interface HTMLTitleElement extends HTMLElement {
  public String             getText();
  public void               setText(String text);
}

public interface HTMLMetaElement extends HTMLElement {
  public String             getContent();
  public void               setContent(String content);
  public String             getHttpEquiv();
  public void               setHttpEquiv(String httpEquiv);
  public String             getName();
  public void               setName(String name);
  public String             getScheme();
  public void               setScheme(String scheme);
}

public interface HTMLBaseElement extends HTMLElement {
  public String             getHref();
  public void               setHref(String href);
  public String             getTarget();
  public void               setTarget(String target);
}

public interface HTMLIsIndexElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public String             getPrompt();
  public void               setPrompt(String prompt);
}

public interface HTMLStyleElement extends HTMLElement {
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getMedia();
  public void               setMedia(String media);
  public String             getType();
  public void               setType(String type);
}

public interface HTMLBodyElement extends HTMLElement {
  public String             getALink();
  public void               setALink(String aLink);
  public String             getBackground();
  public void               setBackground(String background);
  public String             getBgColor();
  public void               setBgColor(String bgColor);
  public String             getLink();
  public void               setLink(String link);
  public String             getText();
  public void               setText(String text);
  public String             getVLink();
  public void               setVLink(String vLink);
}

public interface HTMLFormElement extends HTMLElement {
  public HTMLCollection     getElements();
  public int                getLength();
  public String             getName();
  public void               setName(String name);
  public String             getAcceptCharset();
  public void               setAcceptCharset(String acceptCharset);
  public String             getAction();
  public void               setAction(String action);
  public String             getEnctype();
  public void               setEnctype(String enctype);
  public String             getMethod();
  public void               setMethod(String method);
  public String             getTarget();
  public void               setTarget(String target);
  public void               submit();
  public void               reset();
}

public interface HTMLSelectElement extends HTMLElement {
  public String             getType();
  public int                getSelectedIndex();
  public void               setSelectedIndex(int selectedIndex);
  public String             getValue();
  public void               setValue(String value);
  public int                getLength();
  public HTMLFormElement    getForm();
  public HTMLCollection     getOptions();
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public boolean            getMultiple();
  public void               setMultiple(boolean multiple);
  public String             getName();
  public void               setName(String name);
  public int                getSize();
  public void               setSize(int size);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public void               add(HTMLElement element,
                                HTMLElement before);
  public void               remove(int index);
  public void               blur();
  public void               focus();
}

public interface HTMLOptGroupElement extends HTMLElement {
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getLabel();
  public void               setLabel(String label);
}

public interface HTMLOptionElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public boolean            getDefaultSelected();
  public void               setDefaultSelected(boolean defaultSelected);
  public String             getText();
  public int                getIndex();
  public void               setIndex(int index);
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getLabel();
  public void               setLabel(String label);
  public boolean            getSelected();
  public String             getValue();
  public void               setValue(String value);
}

public interface HTMLInputElement extends HTMLElement {
  public String             getDefaultValue();
  public void               setDefaultValue(String defaultValue);
  public boolean            getDefaultChecked();
  public void               setDefaultChecked(boolean defaultChecked);
  public HTMLFormElement    getForm();
  public String             getAccept();
  public void               setAccept(String accept);
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public String             getAlign();
  public void               setAlign(String align);
  public String             getAlt();
  public void               setAlt(String alt);
  public boolean            getChecked();
  public void               setChecked(boolean checked);
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public int                getMaxLength();
  public void               setMaxLength(int maxLength);
  public String             getName();
  public void               setName(String name);
  public boolean            getReadOnly();
  public void               setReadOnly(boolean readOnly);
  public String             getSize();
  public void               setSize(String size);
  public String             getSrc();
  public void               setSrc(String src);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getType();
  public String             getUseMap();
  public void               setUseMap(String useMap);
  public String             getValue();
  public void               setValue(String value);
  public void               blur();
  public void               focus();
  public void               select();
  public void               click();
}

public interface HTMLTextAreaElement extends HTMLElement {
  public String             getDefaultValue();
  public void               setDefaultValue(String defaultValue);
  public HTMLFormElement    getForm();
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public int                getCols();
  public void               setCols(int cols);
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getName();
  public void               setName(String name);
  public boolean            getReadOnly();
  public void               setReadOnly(boolean readOnly);
  public int                getRows();
  public void               setRows(int rows);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getType();
  public String             getValue();
  public void               setValue(String value);
  public void               blur();
  public void               focus();
  public void               select();
}

public interface HTMLButtonElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public boolean            getDisabled();
  public void               setDisabled(boolean disabled);
  public String             getName();
  public void               setName(String name);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getType();
  public String             getValue();
  public void               setValue(String value);
}

public interface HTMLLabelElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public String             getHtmlFor();
  public void               setHtmlFor(String htmlFor);
}

public interface HTMLFieldSetElement extends HTMLElement {
  public HTMLFormElement    getForm();
}

public interface HTMLLegendElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public String             getAlign();
  public void               setAlign(String align);
}

public interface HTMLUListElement extends HTMLElement {
  public boolean            getCompact();
  public void               setCompact(boolean compact);
  public String             getType();
  public void               setType(String type);
}

public interface HTMLOListElement extends HTMLElement {
  public boolean            getCompact();
  public void               setCompact(boolean compact);
  public int                getStart();
  public void               setStart(int start);
  public String             getType();
  public void               setType(String type);
}

public interface HTMLDListElement extends HTMLElement {
  public boolean            getCompact();
  public void               setCompact(boolean compact);
}

public interface HTMLDirectoryElement extends HTMLElement {
  public boolean            getCompact();
  public void               setCompact(boolean compact);
}

public interface HTMLMenuElement extends HTMLElement {
  public boolean            getCompact();
  public void               setCompact(boolean compact);
}

public interface HTMLLIElement extends HTMLElement {
  public String             getType();
  public void               setType(String type);
  public int                getValue();
  public void               setValue(int value);
}

public interface HTMLBlockquoteElement extends HTMLElement {
  public String             getCite();
  public void               setCite(String cite);
}

public interface HTMLDivElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
}

public interface HTMLParagraphElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
}

public interface HTMLHeadingElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
}

public interface HTMLQuoteElement extends HTMLElement {
  public String             getCite();
  public void               setCite(String cite);
}

public interface HTMLPreElement extends HTMLElement {
  public int                getWidth();
  public void               setWidth(int width);
}

public interface HTMLBRElement extends HTMLElement {
  public String             getClear();
  public void               setClear(String clear);
}

public interface HTMLBaseFontElement extends HTMLElement {
  public String             getColor();
  public void               setColor(String color);
  public String             getFace();
  public void               setFace(String face);
  public String             getSize();
  public void               setSize(String size);
}

public interface HTMLFontElement extends HTMLElement {
  public String             getColor();
  public void               setColor(String color);
  public String             getFace();
  public void               setFace(String face);
  public String             getSize();
  public void               setSize(String size);
}

public interface HTMLHRElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
  public boolean            getNoShade();
  public void               setNoShade(boolean noShade);
  public String             getSize();
  public void               setSize(String size);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLModElement extends HTMLElement {
  public String             getCite();
  public void               setCite(String cite);
  public String             getDateTime();
  public void               setDateTime(String dateTime);
}

public interface HTMLAnchorElement extends HTMLElement {
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public String             getCharset();
  public void               setCharset(String charset);
  public String             getCoords();
  public void               setCoords(String coords);
  public String             getHref();
  public void               setHref(String href);
  public String             getHreflang();
  public void               setHreflang(String hreflang);
  public String             getName();
  public void               setName(String name);
  public String             getRel();
  public void               setRel(String rel);
  public String             getRev();
  public void               setRev(String rev);
  public String             getShape();
  public void               setShape(String shape);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getTarget();
  public void               setTarget(String target);
  public String             getType();
  public void               setType(String type);
  public void               blur();
  public void               focus();
}

public interface HTMLImageElement extends HTMLElement {
  public String             getLowSrc();
  public void               setLowSrc(String lowSrc);
  public String             getName();
  public void               setName(String name);
  public String             getAlign();
  public void               setAlign(String align);
  public String             getAlt();
  public void               setAlt(String alt);
  public String             getBorder();
  public void               setBorder(String border);
  public String             getHeight();
  public void               setHeight(String height);
  public String             getHspace();
  public void               setHspace(String hspace);
  public boolean            getIsMap();
  public void               setIsMap(boolean isMap);
  public String             getLongDesc();
  public void               setLongDesc(String longDesc);
  public String             getSrc();
  public void               setSrc(String src);
  public String             getUseMap();
  public void               setUseMap(String useMap);
  public String             getVspace();
  public void               setVspace(String vspace);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLObjectElement extends HTMLElement {
  public HTMLFormElement    getForm();
  public String             getCode();
  public void               setCode(String code);
  public String             getAlign();
  public void               setAlign(String align);
  public String             getArchive();
  public void               setArchive(String archive);
  public String             getBorder();
  public void               setBorder(String border);
  public String             getCodeBase();
  public void               setCodeBase(String codeBase);
  public String             getCodeType();
  public void               setCodeType(String codeType);
  public String             getData();
  public void               setData(String data);
  public boolean            getDeclare();
  public void               setDeclare(boolean declare);
  public String             getHeight();
  public void               setHeight(String height);
  public String             getHspace();
  public void               setHspace(String hspace);
  public String             getName();
  public void               setName(String name);
  public String             getStandby();
  public void               setStandby(String standby);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getType();
  public void               setType(String type);
  public String             getUseMap();
  public void               setUseMap(String useMap);
  public String             getVspace();
  public void               setVspace(String vspace);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLParamElement extends HTMLElement {
  public String             getName();
  public void               setName(String name);
  public String             getType();
  public void               setType(String type);
  public String             getValue();
  public void               setValue(String value);
  public String             getValueType();
  public void               setValueType(String valueType);
}

public interface HTMLAppletElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
  public String             getAlt();
  public void               setAlt(String alt);
  public String             getArchive();
  public void               setArchive(String archive);
  public String             getCode();
  public void               setCode(String code);
  public String             getCodeBase();
  public void               setCodeBase(String codeBase);
  public String             getHeight();
  public void               setHeight(String height);
  public String             getHspace();
  public void               setHspace(String hspace);
  public String             getName();
  public void               setName(String name);
  public String             getObject();
  public void               setObject(String object);
  public String             getVspace();
  public void               setVspace(String vspace);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLMapElement extends HTMLElement {
  public HTMLCollection     getAreas();
  public String             getName();
  public void               setName(String name);
}

public interface HTMLAreaElement extends HTMLElement {
  public String             getAccessKey();
  public void               setAccessKey(String accessKey);
  public String             getAlt();
  public void               setAlt(String alt);
  public String             getCoords();
  public void               setCoords(String coords);
  public String             getHref();
  public void               setHref(String href);
  public boolean            getNoHref();
  public void               setNoHref(boolean noHref);
  public String             getShape();
  public void               setShape(String shape);
  public int                getTabIndex();
  public void               setTabIndex(int tabIndex);
  public String             getTarget();
  public void               setTarget(String target);
}

public interface HTMLScriptElement extends HTMLElement {
  public String             getText();
  public void               setText(String text);
  public String             getHtmlFor();
  public void               setHtmlFor(String htmlFor);
  public String             getEvent();
  public void               setEvent(String event);
  public String             getCharset();
  public void               setCharset(String charset);
  public boolean            getDefer();
  public void               setDefer(boolean defer);
  public String             getSrc();
  public void               setSrc(String src);
  public String             getType();
  public void               setType(String type);
}

public interface HTMLTableElement extends HTMLElement {
  public HTMLTableCaptionElement getCaption();
  public void               setCaption(HTMLTableCaptionElement caption);
  public HTMLTableSectionElement getTHead();
  public void               setTHead(HTMLTableSectionElement tHead);
  public HTMLTableSectionElement getTFoot();
  public void               setTFoot(HTMLTableSectionElement tFoot);
  public HTMLCollection     getRows();
  public HTMLCollection     getTBodies();
  public String             getAlign();
  public void               setAlign(String align);
  public String             getBgColor();
  public void               setBgColor(String bgColor);
  public String             getBorder();
  public void               setBorder(String border);
  public String             getCellPadding();
  public void               setCellPadding(String cellPadding);
  public String             getCellSpacing();
  public void               setCellSpacing(String cellSpacing);
  public String             getFrame();
  public void               setFrame(String frame);
  public String             getRules();
  public void               setRules(String rules);
  public String             getSummary();
  public void               setSummary(String summary);
  public String             getWidth();
  public void               setWidth(String width);
  public HTMLElement        createTHead();
  public void               deleteTHead();
  public HTMLElement        createTFoot();
  public void               deleteTFoot();
  public HTMLElement        createCaption();
  public void               deleteCaption();
  public HTMLElement        insertRow(int index);
  public void               deleteRow(int index);
}

public interface HTMLTableCaptionElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
}

public interface HTMLTableColElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
  public String             getCh();
  public void               setCh(String ch);
  public String             getChOff();
  public void               setChOff(String chOff);
  public int                getSpan();
  public void               setSpan(int span);
  public String             getVAlign();
  public void               setVAlign(String vAlign);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLTableSectionElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
  public String             getCh();
  public void               setCh(String ch);
  public String             getChOff();
  public void               setChOff(String chOff);
  public String             getVAlign();
  public void               setVAlign(String vAlign);
  public HTMLCollection     getRows();
  public HTMLElement        insertRow(int index);
  public void               deleteRow(int index);
}

public interface HTMLTableRowElement extends HTMLElement {
  public int                getRowIndex();
  public void               setRowIndex(int rowIndex);
  public int                getSectionRowIndex();
  public void               setSectionRowIndex(int sectionRowIndex);
  public HTMLCollection     getCells();
  public void               setCells(HTMLCollection cells);
  public String             getAlign();
  public void               setAlign(String align);
  public String             getBgColor();
  public void               setBgColor(String bgColor);
  public String             getCh();
  public void               setCh(String ch);
  public String             getChOff();
  public void               setChOff(String chOff);
  public String             getVAlign();
  public void               setVAlign(String vAlign);
  public HTMLElement        insertCell(int index);
  public void               deleteCell(int index);
}

public interface HTMLTableCellElement extends HTMLElement {
  public int                getCellIndex();
  public void               setCellIndex(int cellIndex);
  public String             getAbbr();
  public void               setAbbr(String abbr);
  public String             getAlign();
  public void               setAlign(String align);
  public String             getAxis();
  public void               setAxis(String axis);
  public String             getBgColor();
  public void               setBgColor(String bgColor);
  public String             getCh();
  public void               setCh(String ch);
  public String             getChOff();
  public void               setChOff(String chOff);
  public int                getColSpan();
  public void               setColSpan(int colSpan);
  public String             getHeaders();
  public void               setHeaders(String headers);
  public String             getHeight();
  public void               setHeight(String height);
  public boolean            getNoWrap();
  public void               setNoWrap(boolean noWrap);
  public int                getRowSpan();
  public void               setRowSpan(int rowSpan);
  public String             getScope();
  public void               setScope(String scope);
  public String             getVAlign();
  public void               setVAlign(String vAlign);
  public String             getWidth();
  public void               setWidth(String width);
}

public interface HTMLFrameSetElement extends HTMLElement {
  public String             getCols();
  public void               setCols(String cols);
  public String             getRows();
  public void               setRows(String rows);
}

public interface HTMLFrameElement extends HTMLElement {
  public String             getFrameBorder();
  public void               setFrameBorder(String frameBorder);
  public String             getLongDesc();
  public void               setLongDesc(String longDesc);
  public String             getMarginHeight();
  public void               setMarginHeight(String marginHeight);
  public String             getMarginWidth();
  public void               setMarginWidth(String marginWidth);
  public String             getName();
  public void               setName(String name);
  public boolean            getNoResize();
  public void               setNoResize(boolean noResize);
  public String             getScrolling();
  public void               setScrolling(String scrolling);
  public String             getSrc();
  public void               setSrc(String src);
}

public interface HTMLIFrameElement extends HTMLElement {
  public String             getAlign();
  public void               setAlign(String align);
  public String             getFrameBorder();
  public void               setFrameBorder(String frameBorder);
  public String             getHeight();
  public void               setHeight(String height);
  public String             getLongDesc();
  public void               setLongDesc(String longDesc);
  public String             getMarginHeight();
  public void               setMarginHeight(String marginHeight);
  public String             getMarginWidth();
  public void               setMarginWidth(String marginWidth);
  public String             getName();
  public void               setName(String name);
  public String             getScrolling();
  public void               setScrolling(String scrolling);
  public String             getSrc();
  public void               setSrc(String src);
  public String             getWidth();
  public void               setWidth(String width);
}

IDL Definitions REC-DOM-Level-1-19981001 ECMA Script Language Binding


ECMA Script Language Binding

REC-DOM-Level-1-19981001
Java Language Binding REC-DOM-Level-1-19981001 References

Appendix E: ECMA Script Language Binding

This appendix contains the complete ECMA Script binding for the Level 1 Document Object Model definitions. The definitions are divided into Core and HTML.

E.1: Document Object Model Level 1 Core

Object DOMException
Object ExceptionCode
Object DOMImplementation
The DOMImplementation object has the following methods:
hasFeature(feature, version)
This method returns a boolean. The feature parameter is of type DOMString. The version parameter is of type DOMString.
Object DocumentFragment
DocumentFragment has the all the properties and methods of Node as well as the properties and methods defined below.
Object Document
Document has the all the properties and methods of Node as well as the properties and methods defined below.
The Document object has the following properties:
doctype
This property is of type DocumentType.
implementation
This property is of type DOMImplementation.
documentElement
This property is of type Element.
The Document object has the following methods:
createElement(tagName)
This method returns a Element. The tagName parameter is of type DOMString.
createDocumentFragment()
This method returns a DocumentFragment.
createTextNode(data)
This method returns a Text. The data parameter is of type DOMString.
createComment(data)
This method returns a Comment. The data parameter is of type DOMString.
createCDATASection(data)
This method returns a CDATASection. The data parameter is of type DOMString.
createProcessingInstruction(target, data)
This method returns a ProcessingInstruction. The target parameter is of type DOMString. The data parameter is of type DOMString.
createAttribute(name)
This method returns a Attr. The name parameter is of type DOMString.
createEntityReference(name)
This method returns a EntityReference. The name parameter is of type DOMString.
getElementsByTagName(tagname)
This method returns a NodeList. The tagname parameter is of type DOMString.
Object Node
The Node object has the following properties:
nodeName
This property is of type String.
nodeValue
This property is of type String.
nodeType
This property is of type short.
parentNode
This property is of type Node.
childNodes
This property is of type NodeList.
firstChild
This property is of type Node.
lastChild
This property is of type Node.
previousSibling
This property is of type Node.
nextSibling
This property is of type Node.
attributes
This property is of type NamedNodeMap.
ownerDocument
This property is of type Document.
The Node object has the following methods:
insertBefore(newChild, refChild)
This method returns a Node. The newChild parameter is of type Node. The refChild parameter is of type Node.
replaceChild(newChild, oldChild)
This method returns a Node. The newChild parameter is of type Node. The oldChild parameter is of type Node.
removeChild(oldChild)
This method returns a Node. The oldChild parameter is of type Node.
appendChild(newChild)
This method returns a Node. The newChild parameter is of type Node.
hasChildNodes()
This method returns a boolean.
cloneNode(deep)
This method returns a Node. The deep parameter is of type boolean.
Object NodeList
The NodeList object has the following properties:
length
This property is of type int.
The NodeList object has the following methods:
item(index)
This method returns a Node. The index parameter is of type unsigned long.
Object NamedNodeMap
The NamedNodeMap object has the following properties:
length
This property is of type int.
The NamedNodeMap object has the following methods:
getNamedItem(name)
This method returns a Node. The name parameter is of type DOMString.
setNamedItem(arg)
This method returns a Node. The arg parameter is of type Node.
removeNamedItem(name)
This method returns a Node. The name parameter is of type DOMString.
item(index)
This method returns a Node. The index parameter is of type unsigned long.
Object CharacterData
CharacterData has the all the properties and methods of Node as well as the properties and methods defined below.
The CharacterData object has the following properties:
data
This property is of type String.
length
This property is of type int.
The CharacterData object has the following methods:
substringData(offset, count)
This method returns a DOMString. The offset parameter is of type unsigned long. The count parameter is of type unsigned long.
appendData(arg)
This method returns a void. The arg parameter is of type DOMString.
insertData(offset, arg)
This method returns a void. The offset parameter is of type unsigned long. The arg parameter is of type DOMString.
deleteData(offset, count)
This method returns a void. The offset parameter is of type unsigned long. The count parameter is of type unsigned long.
replaceData(offset, count, arg)
This method returns a void. The offset parameter is of type unsigned long. The count parameter is of type unsigned long. The arg parameter is of type DOMString.
Object Attr
Attr has the all the properties and methods of Node as well as the properties and methods defined below.
The Attr object has the following properties:
name
This property is of type String.
specified
This property is of type boolean.
value
This property is of type String.
Object Element
Element has the all the properties and methods of Node as well as the properties and methods defined below.
The Element object has the following properties:
tagName
This property is of type String.
The Element object has the following methods:
getAttribute(name)
This method returns a DOMString. The name parameter is of type DOMString.
setAttribute(name, value)
This method returns a void. The name parameter is of type DOMString. The value parameter is of type DOMString.
removeAttribute(name)
This method returns a void. The name parameter is of type DOMString.
getAttributeNode(name)
This method returns a Attr. The name parameter is of type DOMString.
setAttributeNode(newAttr)
This method returns a Attr. The newAttr parameter is of type Attr.
removeAttributeNode(oldAttr)
This method returns a Attr. The oldAttr parameter is of type Attr.
getElementsByTagName(name)
This method returns a NodeList. The name parameter is of type DOMString.
normalize()
This method returns a void.
Object Text
Text has the all the properties and methods of CharacterData as well as the properties and methods defined below.
The Text object has the following methods:
splitText(offset)
This method returns a Text. The offset parameter is of type unsigned long.
Object Comment
Comment has the all the properties and methods of CharacterData as well as the properties and methods defined below.
Object CDATASection
CDATASection has the all the properties and methods of Text as well as the properties and methods defined below.
Object DocumentType
DocumentType has the all the properties and methods of Node as well as the properties and methods defined below.
The DocumentType object has the following properties:
name
This property is of type String.
entities
This property is of type NamedNodeMap.
notations
This property is of type NamedNodeMap.
Object Notation
Notation has the all the properties and methods of Node as well as the properties and methods defined below.
The Notation object has the following properties:
publicId
This property is of type String.
systemId
This property is of type String.
Object Entity
Entity has the all the properties and methods of Node as well as the properties and methods defined below.
The Entity object has the following properties:
publicId
This property is of type String.
systemId
This property is of type String.
notationName
This property is of type String.
Object EntityReference
EntityReference has the all the properties and methods of Node as well as the properties and methods defined below.
Object ProcessingInstruction
ProcessingInstruction has the all the properties and methods of Node as well as the properties and methods defined below.
The ProcessingInstruction object has the following properties:
target
This property is of type String.
data
This property is of type String.

E.2: Document Object Model Level 1 HTML

Object HTMLCollection
The HTMLCollection object has the following properties:
length
This property is of type int.
The HTMLCollection object has the following methods:
item(index)
This method returns a Node. The index parameter is of type unsigned long.
namedItem(name)
This method returns a Node. The name parameter is of type DOMString.
Object HTMLDocument
HTMLDocument has the all the properties and methods of Document as well as the properties and methods defined below.
The HTMLDocument object has the following properties:
title
This property is of type String.
referrer
This property is of type String.
domain
This property is of type String.
URL
This property is of type String.
body
This property is of type HTMLElement.
images
This property is of type HTMLCollection.
applets
This property is of type HTMLCollection.
links
This property is of type HTMLCollection.
forms
This property is of type HTMLCollection.
anchors
This property is of type HTMLCollection.
cookie
This property is of type String.
The HTMLDocument object has the following methods:
open()
This method returns a void.
close()
This method returns a void.
write(text)
This method returns a void. The text parameter is of type DOMString.
writeln(text)
This method returns a void. The text parameter is of type DOMString.
getElementById(elementId)
This method returns a Element. The elementId parameter is of type DOMString.
getElementsByName(elementName)
This method returns a NodeList. The elementName parameter is of type DOMString.
Object HTMLElement
HTMLElement has the all the properties and methods of Element as well as the properties and methods defined below.
The HTMLElement object has the following properties:
id
This property is of type String.
title
This property is of type String.
lang
This property is of type String.
dir
This property is of type String.
className
This property is of type String.
Object HTMLHtmlElement
HTMLHtmlElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLHtmlElement object has the following properties:
version
This property is of type String.
Object HTMLHeadElement
HTMLHeadElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLHeadElement object has the following properties:
profile
This property is of type String.
Object HTMLLinkElement
HTMLLinkElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLLinkElement object has the following properties:
disabled
This property is of type boolean.
charset
This property is of type String.
href
This property is of type String.
hreflang
This property is of type String.
media
This property is of type String.
rel
This property is of type String.
rev
This property is of type String.
target
This property is of type String.
type
This property is of type String.
Object HTMLTitleElement
HTMLTitleElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTitleElement object has the following properties:
text
This property is of type String.
Object HTMLMetaElement
HTMLMetaElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLMetaElement object has the following properties:
content
This property is of type String.
httpEquiv
This property is of type String.
name
This property is of type String.
scheme
This property is of type String.
Object HTMLBaseElement
HTMLBaseElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLBaseElement object has the following properties:
href
This property is of type String.
target
This property is of type String.
Object HTMLIsIndexElement
HTMLIsIndexElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLIsIndexElement object has the following properties:
form
This property is of type HTMLFormElement.
prompt
This property is of type String.
Object HTMLStyleElement
HTMLStyleElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLStyleElement object has the following properties:
disabled
This property is of type boolean.
media
This property is of type String.
type
This property is of type String.
Object HTMLBodyElement
HTMLBodyElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLBodyElement object has the following properties:
aLink
This property is of type String.
background
This property is of type String.
bgColor
This property is of type String.
link
This property is of type String.
text
This property is of type String.
vLink
This property is of type String.
Object HTMLFormElement
HTMLFormElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLFormElement object has the following properties:
elements
This property is of type HTMLCollection.
length
This property is of type long.
name
This property is of type String.
acceptCharset
This property is of type String.
action
This property is of type String.
enctype
This property is of type String.
method
This property is of type String.
target
This property is of type String.
The HTMLFormElement object has the following methods:
submit()
This method returns a void.
reset()
This method returns a void.
Object HTMLSelectElement
HTMLSelectElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLSelectElement object has the following properties:
type
This property is of type String.
selectedIndex
This property is of type long.
value
This property is of type String.
length
This property is of type long.
form
This property is of type HTMLFormElement.
options
This property is of type HTMLCollection.
disabled
This property is of type boolean.
multiple
This property is of type boolean.
name
This property is of type String.
size
This property is of type long.
tabIndex
This property is of type long.
The HTMLSelectElement object has the following methods:
add(element, before)
This method returns a void. The element parameter is of type HTMLElement. The before parameter is of type HTMLElement.
remove(index)
This method returns a void. The index parameter is of type long.
blur()
This method returns a void.
focus()
This method returns a void.
Object HTMLOptGroupElement
HTMLOptGroupElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLOptGroupElement object has the following properties:
disabled
This property is of type boolean.
label
This property is of type String.
Object HTMLOptionElement
HTMLOptionElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLOptionElement object has the following properties:
form
This property is of type HTMLFormElement.
defaultSelected
This property is of type boolean.
text
This property is of type String.
index
This property is of type long.
disabled
This property is of type boolean.
label
This property is of type String.
selected
This property is of type boolean.
value
This property is of type String.
Object HTMLInputElement
HTMLInputElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLInputElement object has the following properties:
defaultValue
This property is of type String.
defaultChecked
This property is of type boolean.
form
This property is of type HTMLFormElement.
accept
This property is of type String.
accessKey
This property is of type String.
align
This property is of type String.
alt
This property is of type String.
checked
This property is of type boolean.
disabled
This property is of type boolean.
maxLength
This property is of type long.
name
This property is of type String.
readOnly
This property is of type boolean.
size
This property is of type String.
src
This property is of type String.
tabIndex
This property is of type long.
type
This property is of type String.
useMap
This property is of type String.
value
This property is of type String.
The HTMLInputElement object has the following methods:
blur()
This method returns a void.
focus()
This method returns a void.
select()
This method returns a void.
click()
This method returns a void.
Object HTMLTextAreaElement
HTMLTextAreaElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTextAreaElement object has the following properties:
defaultValue
This property is of type String.
form
This property is of type HTMLFormElement.
accessKey
This property is of type String.
cols
This property is of type long.
disabled
This property is of type boolean.
name
This property is of type String.
readOnly
This property is of type boolean.
rows
This property is of type long.
tabIndex
This property is of type long.
type
This property is of type String.
value
This property is of type String.
The HTMLTextAreaElement object has the following methods:
blur()
This method returns a void.
focus()
This method returns a void.
select()
This method returns a void.
Object HTMLButtonElement
HTMLButtonElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLButtonElement object has the following properties:
form
This property is of type HTMLFormElement.
accessKey
This property is of type String.
disabled
This property is of type boolean.
name
This property is of type String.
tabIndex
This property is of type long.
type
This property is of type String.
value
This property is of type String.
Object HTMLLabelElement
HTMLLabelElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLLabelElement object has the following properties:
form
This property is of type HTMLFormElement.
accessKey
This property is of type String.
htmlFor
This property is of type String.
Object HTMLFieldSetElement
HTMLFieldSetElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLFieldSetElement object has the following properties:
form
This property is of type HTMLFormElement.
Object HTMLLegendElement
HTMLLegendElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLLegendElement object has the following properties:
form
This property is of type HTMLFormElement.
accessKey
This property is of type String.
align
This property is of type String.
Object HTMLUListElement
HTMLUListElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLUListElement object has the following properties:
compact
This property is of type boolean.
type
This property is of type String.
Object HTMLOListElement
HTMLOListElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLOListElement object has the following properties:
compact
This property is of type boolean.
start
This property is of type long.
type
This property is of type String.
Object HTMLDListElement
HTMLDListElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLDListElement object has the following properties:
compact
This property is of type boolean.
Object HTMLDirectoryElement
HTMLDirectoryElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLDirectoryElement object has the following properties:
compact
This property is of type boolean.
Object HTMLMenuElement
HTMLMenuElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLMenuElement object has the following properties:
compact
This property is of type boolean.
Object HTMLLIElement
HTMLLIElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLLIElement object has the following properties:
type
This property is of type String.
value
This property is of type long.
Object HTMLBlockquoteElement
HTMLBlockquoteElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLBlockquoteElement object has the following properties:
cite
This property is of type String.
Object HTMLDivElement
HTMLDivElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLDivElement object has the following properties:
align
This property is of type String.
Object HTMLParagraphElement
HTMLParagraphElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLParagraphElement object has the following properties:
align
This property is of type String.
Object HTMLHeadingElement
HTMLHeadingElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLHeadingElement object has the following properties:
align
This property is of type String.
Object HTMLQuoteElement
HTMLQuoteElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLQuoteElement object has the following properties:
cite
This property is of type String.
Object HTMLPreElement
HTMLPreElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLPreElement object has the following properties:
width
This property is of type long.
Object HTMLBRElement
HTMLBRElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLBRElement object has the following properties:
clear
This property is of type String.
Object HTMLBaseFontElement
HTMLBaseFontElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLBaseFontElement object has the following properties:
color
This property is of type String.
face
This property is of type String.
size
This property is of type String.
Object HTMLFontElement
HTMLFontElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLFontElement object has the following properties:
color
This property is of type String.
face
This property is of type String.
size
This property is of type String.
Object HTMLHRElement
HTMLHRElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLHRElement object has the following properties:
align
This property is of type String.
noShade
This property is of type boolean.
size
This property is of type String.
width
This property is of type String.
Object HTMLModElement
HTMLModElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLModElement object has the following properties:
cite
This property is of type String.
dateTime
This property is of type String.
Object HTMLAnchorElement
HTMLAnchorElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLAnchorElement object has the following properties:
accessKey
This property is of type String.
charset
This property is of type String.
coords
This property is of type String.
href
This property is of type String.
hreflang
This property is of type String.
name
This property is of type String.
rel
This property is of type String.
rev
This property is of type String.
shape
This property is of type String.
tabIndex
This property is of type long.
target
This property is of type String.
type
This property is of type String.
The HTMLAnchorElement object has the following methods:
blur()
This method returns a void.
focus()
This method returns a void.
Object HTMLImageElement
HTMLImageElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLImageElement object has the following properties:
lowSrc
This property is of type String.
name
This property is of type String.
align
This property is of type String.
alt
This property is of type String.
border
This property is of type String.
height
This property is of type String.
hspace
This property is of type String.
isMap
This property is of type boolean.
longDesc
This property is of type String.
src
This property is of type String.
useMap
This property is of type String.
vspace
This property is of type String.
width
This property is of type String.
Object HTMLObjectElement
HTMLObjectElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLObjectElement object has the following properties:
form
This property is of type HTMLFormElement.
code
This property is of type String.
align
This property is of type String.
archive
This property is of type String.
border
This property is of type String.
codeBase
This property is of type String.
codeType
This property is of type String.
data
This property is of type String.
declare
This property is of type boolean.
height
This property is of type String.
hspace
This property is of type String.
name
This property is of type String.
standby
This property is of type String.
tabIndex
This property is of type long.
type
This property is of type String.
useMap
This property is of type String.
vspace
This property is of type String.
width
This property is of type String.
Object HTMLParamElement
HTMLParamElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLParamElement object has the following properties:
name
This property is of type String.
type
This property is of type String.
value
This property is of type String.
valueType
This property is of type String.
Object HTMLAppletElement
HTMLAppletElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLAppletElement object has the following properties:
align
This property is of type String.
alt
This property is of type String.
archive
This property is of type String.
code
This property is of type String.
codeBase
This property is of type String.
height
This property is of type String.
hspace
This property is of type String.
name
This property is of type String.
object
This property is of type String.
vspace
This property is of type String.
width
This property is of type String.
Object HTMLMapElement
HTMLMapElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLMapElement object has the following properties:
areas
This property is of type HTMLCollection.
name
This property is of type String.
Object HTMLAreaElement
HTMLAreaElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLAreaElement object has the following properties:
accessKey
This property is of type String.
alt
This property is of type String.
coords
This property is of type String.
href
This property is of type String.
noHref
This property is of type boolean.
shape
This property is of type String.
tabIndex
This property is of type long.
target
This property is of type String.
Object HTMLScriptElement
HTMLScriptElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLScriptElement object has the following properties:
text
This property is of type String.
htmlFor
This property is of type String.
event
This property is of type String.
charset
This property is of type String.
defer
This property is of type boolean.
src
This property is of type String.
type
This property is of type String.
Object HTMLTableElement
HTMLTableElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableElement object has the following properties:
caption
This property is of type HTMLTableCaptionElement.
tHead
This property is of type HTMLTableSectionElement.
tFoot
This property is of type HTMLTableSectionElement.
rows
This property is of type HTMLCollection.
tBodies
This property is of type HTMLCollection.
align
This property is of type String.
bgColor
This property is of type String.
border
This property is of type String.
cellPadding
This property is of type String.
cellSpacing
This property is of type String.
frame
This property is of type String.
rules
This property is of type String.
summary
This property is of type String.
width
This property is of type String.
The HTMLTableElement object has the following methods:
createTHead()
This method returns a HTMLElement.
deleteTHead()
This method returns a void.
createTFoot()
This method returns a HTMLElement.
deleteTFoot()
This method returns a void.
createCaption()
This method returns a HTMLElement.
deleteCaption()
This method returns a void.
insertRow(index)
This method returns a HTMLElement. The index parameter is of type long.
deleteRow(index)
This method returns a void. The index parameter is of type long.
Object HTMLTableCaptionElement
HTMLTableCaptionElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableCaptionElement object has the following properties:
align
This property is of type String.
Object HTMLTableColElement
HTMLTableColElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableColElement object has the following properties:
align
This property is of type String.
ch
This property is of type String.
chOff
This property is of type String.
span
This property is of type long.
vAlign
This property is of type String.
width
This property is of type String.
Object HTMLTableSectionElement
HTMLTableSectionElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableSectionElement object has the following properties:
align
This property is of type String.
ch
This property is of type String.
chOff
This property is of type String.
vAlign
This property is of type String.
rows
This property is of type HTMLCollection.
The HTMLTableSectionElement object has the following methods:
insertRow(index)
This method returns a HTMLElement. The index parameter is of type long.
deleteRow(index)
This method returns a void. The index parameter is of type long.
Object HTMLTableRowElement
HTMLTableRowElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableRowElement object has the following properties:
rowIndex
This property is of type long.
sectionRowIndex
This property is of type long.
cells
This property is of type HTMLCollection.
align
This property is of type String.
bgColor
This property is of type String.
ch
This property is of type String.
chOff
This property is of type String.
vAlign
This property is of type String.
The HTMLTableRowElement object has the following methods:
insertCell(index)
This method returns a HTMLElement. The index parameter is of type long.
deleteCell(index)
This method returns a void. The index parameter is of type long.
Object HTMLTableCellElement
HTMLTableCellElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLTableCellElement object has the following properties:
cellIndex
This property is of type long.
abbr
This property is of type String.
align
This property is of type String.
axis
This property is of type String.
bgColor
This property is of type String.
ch
This property is of type String.
chOff
This property is of type String.
colSpan
This property is of type long.
headers
This property is of type String.
height
This property is of type String.
noWrap
This property is of type boolean.
rowSpan
This property is of type long.
scope
This property is of type String.
vAlign
This property is of type String.
width
This property is of type String.
Object HTMLFrameSetElement
HTMLFrameSetElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLFrameSetElement object has the following properties:
cols
This property is of type String.
rows
This property is of type String.
Object HTMLFrameElement
HTMLFrameElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLFrameElement object has the following properties:
frameBorder
This property is of type String.
longDesc
This property is of type String.
marginHeight
This property is of type String.
marginWidth
This property is of type String.
name
This property is of type String.
noResize
This property is of type boolean.
scrolling
This property is of type String.
src
This property is of type String.
Object HTMLIFrameElement
HTMLIFrameElement has the all the properties and methods of HTMLElement as well as the properties and methods defined below.
The HTMLIFrameElement object has the following properties:
align
This property is of type String.
frameBorder
This property is of type String.
height
This property is of type String.
longDesc
This property is of type String.
marginHeight
This property is of type String.
marginWidth
This property is of type String.
name
This property is of type String.
scrolling
This property is of type String.
src
This property is of type String.
width
This property is of type String.

Java Language Binding REC-DOM-Level-1-19981001 References


References

XML
W3C (World Wide Web Consortium) Extensible Markup Language (XML) 1.0. See http://www.w3.org/TR/REC-xml .
HTML4.0
W3C (World Wide Web Consortium) HTML 4.0 Specification. See http://www.w3.org/TR/REC-html40 .
Unicode
The Unicode Consortium. The Unicode Standard, Version 2.0. Reading, Mass.: Addison-Wesley Developers Press, 1996.
CORBA
OMG (Object Management Group) The Common Object Request Broker: Architecture and Specification. See http://www.omg.org/corba/corbiiop.htm .
Java
Sun The Java Language Specification. See http://java.sun.com/docs/books/jls/ .
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. See http://www.ecma.ch/stand/ECMA-262.htm .
ECMA Script Language Binding REC-DOM-Level-1-19981001 Index


Index

ATTRIBUTE_NODE 1 | Attr 1 | CDATASection 1
CDATA_SECTION_NODE 1 | COMMENT_NODE 1 | CharacterData 1
Comment 1 | DOCUMENT_FRAGMENT_NODE 1 | DOCUMENT_NODE 1
DOCUMENT_TYPE_NODE 1 | DOMException 1 | DOMImplementation 1
DOMSTRING_SIZE_ERR 1 | Document 1 | DocumentFragment 1
DocumentType 1 | ELEMENT_NODE 1 | ENTITY_NODE 1
ENTITY_REFERENCE_NODE 1 | Element 1 | Entity 1
EntityReference 1 | HIERARCHY_REQUEST_ERR 1 | HTMLAnchorElement 1
HTMLAppletElement 1 | HTMLAreaElement 1 | HTMLBRElement 1
HTMLBaseElement 1 | HTMLBaseFontElement 1 | HTMLBlockquoteElement 1
HTMLBodyElement 1 | HTMLButtonElement 1 | HTMLCollection 1
HTMLDListElement 1 | HTMLDirectoryElement 1 | HTMLDivElement 1
HTMLDocument 1 | HTMLElement 1 | HTMLFieldSetElement 1
HTMLFontElement 1 | HTMLFormElement 1 | HTMLFrameElement 1
HTMLFrameSetElement 1 | HTMLHRElement 1 | HTMLHeadElement 1
HTMLHeadingElement 1 | HTMLHtmlElement 1 | HTMLIFrameElement 1
HTMLImageElement 1 | HTMLInputElement 1 | HTMLIsIndexElement 1
HTMLLIElement 1 | HTMLLabelElement 1 | HTMLLegendElement 1
HTMLLinkElement 1 | HTMLMapElement 1 | HTMLMenuElement 1
HTMLMetaElement 1 | HTMLModElement 1 | HTMLOListElement 1
HTMLObjectElement 1 | HTMLOptGroupElement 1 | HTMLOptionElement 1
HTMLParagraphElement 1 | HTMLParamElement 1 | HTMLPreElement 1
HTMLQuoteElement 1 | HTMLScriptElement 1 | HTMLSelectElement 1
HTMLStyleElement 1 | HTMLTableCaptionElement 1 | HTMLTableCellElement 1
HTMLTableColElement 1 | HTMLTableElement 1 | HTMLTableRowElement 1
HTMLTableSectionElement 1 | HTMLTextAreaElement 1 | HTMLTitleElement 1
HTMLUListElement 1 | INDEX_SIZE_ERR 1 | INUSE_ATTRIBUTE_ERR 1
INVALID_CHARACTER_ERR 1 | NOTATION_NODE 1 | NOT_FOUND_ERR 1
NOT_SUPPORTED_ERR 1 | NO_DATA_ALLOWED_ERR 1 | NO_MODIFICATION_ALLOWED_ERR 1
NamedNodeMap 1 | Node 1 | NodeList 1
Notation 1 | PROCESSING_INSTRUCTION_NODE 1 | ProcessingInstruction 1
TEXT_NODE 1 | Text 1 | URL 1
WRONG_DOCUMENT_ERR 1 | aLink 1 | abbr 1
accept 1 | acceptCharset 1 | accessKey 1, 2, 3, 4, 5, 6, 7
action 1 | add 1 | align 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
alt 1, 2, 3, 4 | anchors 1 | appendChild 1
appendData 1 | applets 1 | archive 1, 2
areas 1 | attributes 1 | axis 1
background 1 | bgColor 1, 2, 3, 4 | blur 1, 2, 3, 4
body 1 | border 1, 2, 3 | caption 1
cellIndex 1 | cellPadding 1 | cellSpacing 1
cells 1 | ch 1, 2, 3, 4 | chOff 1, 2, 3, 4
charset 1, 2, 3 | checked 1 | childNodes 1
cite 1, 2, 3 | className 1 | clear 1
click 1 | cloneNode 1 | close 1
code 1, 2 | codeBase 1, 2 | codeType 1
colSpan 1 | color 1, 2 | cols 1, 2
compact 1, 2, 3, 4, 5 | content 1 | cookie 1
coords 1, 2 | createAttribute 1 | createCDATASection 1
createCaption 1 | createComment 1 | createDocumentFragment 1
createElement 1 | createEntityReference 1 | createProcessingInstruction 1
createTFoot 1 | createTHead 1 | createTextNode 1
data 1, 2, 3 | dateTime 1 | declare 1
defaultChecked 1 | defaultSelected 1 | defaultValue 1, 2
defer 1 | deleteCaption 1 | deleteCell 1
deleteData 1 | deleteRow 1, 2 | deleteTFoot 1
deleteTHead 1 | dir 1 | disabled 1, 2, 3, 4, 5, 6, 7, 8
doctype 1 | documentElement 1 | domain 1
elements 1 | enctype 1 | entities 1
event 1 | face 1, 2 | firstChild 1
focus 1, 2, 3, 4 | form 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | forms 1
frame 1 | frameBorder 1, 2 | getAttribute 1
getAttributeNode 1 | getElementById 1 | getElementsByName 1
getElementsByTagName 1, 2 | getNamedItem 1 | hasChildNodes 1
hasFeature 1 | headers 1 | height 1, 2, 3, 4, 5
href 1, 2, 3, 4 | hreflang 1, 2 | hspace 1, 2, 3
htmlFor 1, 2 | httpEquiv 1 | id 1
images 1 | implementation 1 | index 1
insertBefore 1 | insertCell 1 | insertData 1
insertRow 1, 2 | isMap 1 | item 1, 2, 3
label 1, 2 | lang 1 | lastChild 1
length 1, 2, 3, 4, 5, 6 | link 1 | links 1
longDesc 1, 2, 3 | lowSrc 1 | marginHeight 1, 2
marginWidth 1, 2 | maxLength 1 | media 1, 2
method 1 | multiple 1 | name 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
namedItem 1 | nextSibling 1 | noHref 1
noResize 1 | noShade 1 | noWrap 1
nodeName 1 | nodeType 1 | nodeValue 1
normalize 1 | notationName 1 | notations 1
object 1 | open 1 | options 1
ownerDocument 1 | parentNode 1 | previousSibling 1
profile 1 | prompt 1 | publicId 1, 2
readOnly 1, 2 | referrer 1 | rel 1, 2
remove 1 | removeAttribute 1 | removeAttributeNode 1
removeChild 1 | removeNamedItem 1 | replaceChild 1
replaceData 1 | reset 1 | rev 1, 2
rowIndex 1 | rowSpan 1 | rows 1, 2, 3, 4
rules 1 | scheme 1 | scope 1
scrolling 1, 2 | sectionRowIndex 1 | select 1, 2
selected 1 | selectedIndex 1 | setAttribute 1
setAttributeNode 1 | setNamedItem 1 | shape 1, 2
size 1, 2, 3, 4, 5 | span 1 | specified 1
splitText 1 | src 1, 2, 3, 4, 5 | standby 1
start 1 | submit 1 | substringData 1
summary 1 | systemId 1, 2 | tBodies 1
tFoot 1 | tHead 1 | tabIndex 1, 2, 3, 4, 5, 6, 7
tagName 1 | target 1, 2, 3, 4, 5, 6 | text 1, 2, 3, 4
title 1, 2 | type 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 | useMap 1, 2, 3
vAlign 1, 2, 3, 4 | vLink 1 | value 1, 2, 3, 4, 5, 6, 7, 8
valueType 1 | version 1 | vspace 1, 2, 3
width 1, 2, 3, 4, 5, 6, 7, 8, 9 | write 1 | writeln 1
References REC-DOM-Level-1-19981001 Production Notes (Non-Normative)


Production Notes (Non-Normative)

Editors
Gavin Nicol, Inso EPS

The DOM specification serves as a good example of the power of using XML: all of the HTML documents, Java bindings, OMG IDL bindings, and ECMA Script bindings are generated from a single set of XML source files. This section outlines how this specification is written in XML, and how the various derived works are created.

1. The Document Type Definition

This specification was written entirely in XML, using a DTD based heavily on the DTD used by the XML Working Group for the XML specification. The major difference between the DTD used by the XML Working Group, and the DTD used for this specification is the addition of a DTD module for interface specifications.

The DTD module for interfaces specifications is a very loose translation of the Extended Backus-Naur Form (EBNF) specification of the OMG IDL syntax into XML DTD syntax. In addition to the translation, the ability to describe the interfaces was added, thereby creating a limited form of literate programming for interface definitions.

While the DTD module is sufficient for the purposes of the DOM WG, it is very loosely typed, meaning that there are very few constraints placed on the type specifications (the type information is effectively treated as an opaque string). In a DTD for object to object communication, some stricter enforcement of data types would probably be beneficial.

2. The production process

The DOM specification is written using XML. All documents are valid XML. In order to produce the HTML versions of the specification, the object indexes, the Java source code, and the OMG IDL and ECMA Script definitions, the XML specification is converted.

The tool currently used for conversion is COST by Joe English. COST takes the ESIS output of nsgmls, creates an internal representation, and then allows scripts, and event handlers to be run over the internal data structure. Event handlers allow document patterns and associated processing to be specified: when the pattern is matched during a pre-order traversal of a document subtree, the associated action is executed. This is the heart of the conversion process. Scripts are used to tie the various components together. For example, each of the major derived data sources (Java code etc.) is created by the execution of a script, which in turn executes one or more event handlers. The scripts and event handlers are specified using TCL.

The current version of COST has been somewhat modified from the publicly available version. In particular, it now runs correctly under 32-bit Windows, uses TCL 8.0, and correctly handles the case sensitivity of XML (though it probably could not correctly handle native language markup).

We could also have used Jade, by James Clark. Like COST, Jade allows patterns and actions to be specified, but Jade is based on DSSSL, an international standard, whereas COST is not. Jade is more powerful than COST in many ways, but prior experience of the editor with Cost made it easier to use this rather than Jade. A future version or Level of the DOM specification may be produced using Jade or an XSL processor.

The complete XML source files are available at: http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/xml-source.zip

3. Object Definitions

As stated earlier, all object definitions are specified in XML. The Java bindings, OMG IDL bindings, and ECMA Script bindings are all generated automatically from the XML source code.

This is possible because the information specified in XML is a superset of what these other syntax need. This is a general observation, and the same kind of technique can be applied to many other areas: given rich structure, rich processing and conversion are possible. For Java and OMG IDL, it is basically just a matter of renaming syntactic keywords; for ECMA Script, the process is somewhat more involved.

A typical object definition in XML looks something like this:

<interface name="foo">
  <descr><p>Description goes here...</p></descr>
  <method name="bar">
    <descr><p>Description goes here...</p></descr>
    <parameters>
      <param name="baz" type="DOMString" attr="in">
        <descr><p>Description goes here...</p></descr>
      </param>
    </parameters>
    <returns type="void">
       <descr><p>Description goes here...</p></descr>
    </returns>
    <raises>
       <!-- Throws no exceptions -->
    </raises>
  </method>
</interface>

As can easily be seen, this is quite verbose, but not unlike OMG IDL. In fact, when the specification was originally converted to use XML, the OMG IDL definitions were automatically converted into the corresponding XML source using common Unix text manipulation tools.

Index REC-DOM-Level-1-19981001


Document Object Model (DOM) Level 2 Core Specification

Version 1.0

W3C Recommendation 13 November, 2000

This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113
( PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Core
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Core-20000927
Editors:
Arnaud Le Hors, W3C team contact until October 1999, then IBM
Philippe Le Hégaret, W3C, team contact (from November 1999)
Lauren Wood, SoftQuad Software Inc., WG Chair
Gavin Nicol, Inso EPS (for DOM Level 1)
Jonathan Robie, Texcel Research and Software AG (for DOM Level 1)
Mike Champion, ArborText and Software AG (for DOM Level 1 from November 20, 1997)
Steve Byrne, JavaSoft (for DOM Level 1 until November 19, 1997)

Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Level 2 Core, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content and structure of documents. The Document Object Model Level 2 Core builds on the Document Object Model Level 1 Core.

The DOM Level 2 Core is made of a set of core interfaces to create and manipulate the structure and contents of a document. The Core also contains specialized interfaces dedicated to XML.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members. Different modules of the Document Object Model have different editors.

Please send general comments about this document to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • What is the Document Object Model?
  • 1. Document Object Model Core
  • Appendix A: Changes
  • Appendix B: Accessing code point boundaries
  • Appendix C: IDL Definitions
  • Appendix D: Java Language Binding
  • Appendix E: ECMAScript Language Binding
  • Appendix F: Acknowledgements
  • Glossary
  • References
  • Index
next contents index


Copyright Notice

Copyright © 2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

This document is published under the W3C Document Copyright Notice and License. The bindings within this document are published under the W3C Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java Language binding, the package names can no longer be in the 'org.w3c' package.

W3C Document Copyright Notice and License

Note: This section is a copy of the W3C Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-documents-19990405.

Copyright © 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice of the form: "Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/" (Hypertext is preferred, but a textual representation is permitted.)
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

W3C Software Copyright Notice and License

Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720

Copyright © 1994-2000 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers. If none exist, then a notice of the following form: "Copyright © [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/."
  3. Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

previous next contents index


What is the Document Object Model?

Editors
Philippe Le Hégaret, W3C
Lauren Wood, SoftQuad Software Inc., WG Chair
Jonathan Robie, Texcel (for DOM Level 1)

Introduction

The Document Object Model (DOM) is an application programming interface (API) for valid HTML and well-formed XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term "document" is used in the broad sense - increasingly, XML is being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

With the Document Object Model, programmers can build documents, navigate their structure, and add, modify, or delete elements and content. Anything found in an HTML or XML document can be accessed, changed, deleted, or added using the Document Object Model, with a few exceptions - in particular, the DOM interfaces for the XML internal and external subsets have not yet been specified.

As a W3C specification, one important objective for the Document Object Model is to provide a standard programming interface that can be used in a wide variety of environments and applications. The DOM is designed to be used with any programming language. In order to provide a precise, language-independent specification of the DOM interfaces, we have chosen to define the specifications in Object Management Group (OMG) IDL [OMGIDL], as defined in the CORBA 2.3.1 specification [CORBA]. In addition to the OMG IDL specification, we provide language bindings for Java [Java] and ECMAScript [ECMAScript] (an industry-standard scripting language based on JavaScript [JavaScript] and JScript [JScript]).

Note: OMG IDL is used only as a language-independent and implementation-neutral way to specify interfaces. Various other IDLs could have been used ([COM], [JavaIDL], [MIDL], ...). In general, IDLs are designed for specific computing environments. The Document Object Model can be implemented in any computing environment, and does not require the object binding runtimes generally associated with such IDLs.

What the Document Object Model is

The DOM is a programming API for documents. It is based on an object structure that closely resembles the structure of the documents it models. For instance, consider this table, taken from an HTML document:

      <TABLE>
      <TBODY>
      <TR>
      <TD>Shady Grove</TD>
      <TD>Aeolian</TD>
      </TR>
      <TR>
      <TD>Over the River, Charlie</TD>
      <TD>Dorian</TD>
      </TR>
      </TBODY>
      </TABLE>

A graphical representation of the DOM of the example table is:

graphical representation of the DOM of the example table
graphical representation of the DOM of the example table

In the DOM, documents have a logical structure which is very much like a tree; to be more precise, which is like a "forest" or "grove", which can contain more than one tree. Each document contains zero or one doctype nodes, one root element node, and zero or more comments or processing instructions; the root element serves as the root of the element tree for the document. However, the DOM does not specify that documents must be implemented as a tree or a grove, nor does it specify how the relationships among objects be implemented. The DOM is a logical model that may be implemented in any convenient manner. In this specification, we use the term structure model to describe the tree-like representation of a document. We also use the term "tree" when referring to the arrangement of those information items which can be reached by using "tree-walking" methods; (this does not include attributes). One important property of DOM structure models is structural isomorphism: if any two Document Object Model implementations are used to create a representation of the same document, they will create the same structure model, in accordance with the XML Information Set [Infoset].

Note: There may be some variations depending on the parser being used to build the DOM. For instance, the DOM may not contain whitespaces in element content if the parser discards them.

The name "Document Object Model" was chosen because it is an "object model" in the traditional object oriented design sense: documents are modeled using objects, and the model encompasses not only the structure of a document, but also the behavior of a document and the objects of which it is composed. In other words, the nodes in the above diagram do not represent a data structure, they represent objects, which have functions and identity. As an object model, the DOM identifies:

  • the interfaces and objects used to represent and manipulate a document
  • the semantics of these interfaces and objects - including both behavior and attributes
  • the relationships and collaborations among these interfaces and objects

The structure of SGML documents has traditionally been represented by an abstract data model, not by an object model. In an abstract data model, the model is centered around the data. In object oriented programming languages, the data itself is encapsulated in objects that hide the data, protecting it from direct external manipulation. The functions associated with these objects determine how the objects may be manipulated, and they are part of the object model.

What the Document Object Model is not

This section is designed to give a more precise understanding of the DOM by distinguishing it from other systems that may seem to be like it.

  • The Document Object Model is not a binary specification. DOM programs written in the same language binding will be source code compatible across platforms, but the DOM does not define any form of binary interoperability.
  • The Document Object Model is not a way of persisting objects to XML or HTML. Instead of specifying how objects may be represented in XML, the DOM specifies how XML and HTML documents are represented as objects, so that they may be used in object oriented programs.
  • The Document Object Model is not a set of data structures; it is an object model that specifies interfaces. Although this document contains diagrams showing parent/child relationships, these are logical relationships defined by the programming interfaces, not representations of any particular internal data structures.
  • The Document Object Model does not define what information in a document is relevant or how information in a document is structured. For XML, this is specified by the W3C XML Information Set [Infoset]. The DOM is simply an API to this information set.
  • The Document Object Model, despite its name, is not a competitor to the Component Object Model (COM). COM, like CORBA, is a language independent way to specify interfaces and objects; the DOM is a set of interfaces and objects designed for managing HTML and XML documents. The DOM may be implemented using language-independent systems like COM or CORBA; it may also be implemented using language-specific bindings like the Java or ECMAScript bindings specified in this document.

Where the Document Object Model came from

The DOM originated as a specification to allow JavaScript scripts and Java programs to be portable among Web browsers. "Dynamic HTML" was the immediate ancestor of the Document Object Model, and it was originally thought of largely in terms of browsers. However, when the DOM Working Group was formed at W3C, it was also joined by vendors in other domains, including HTML or XML editors and document repositories. Several of these vendors had worked with SGML before XML was developed; as a result, the DOM has been influenced by SGML Groves and the HyTime standard. Some of these vendors had also developed their own object models for documents in order to provide an API for SGML/XML editors or document repositories, and these object models have also influenced the DOM.

Entities and the DOM Core

In the fundamental DOM interfaces, there are no objects representing entities. Numeric character references, and references to the pre-defined entities in HTML and XML, are replaced by the single character that makes up the entity's replacement. For example, in:

        <p>This is a dog &amp; a cat</p>

the "&amp;" will be replaced by the character "&", and the text in the P element will form a single continuous sequence of characters. Since numeric character references and pre-defined entities are not recognized as such in CDATA sections, or in the SCRIPT and STYLE elements in HTML, they are not replaced by the single character they appear to refer to. If the example above were enclosed in a CDATA section, the "&amp;" would not be replaced by "&"; neither would the <p> be recognized as a start tag. The representation of general entities, both internal and external, are defined within the extended (XML) interfaces of DOM Level 1 [DOM Level 1].

Note: When a DOM representation of a document is serialized as XML or HTML text, applications will need to check each character in text data to see if it needs to be escaped using a numeric or pre-defined entity. Failing to do so could result in invalid HTML or XML. Also, implementations should be aware of the fact that serialization into a character encoding ("charset") that does not fully cover ISO 10646 may fail if there are characters in markup or CDATA sections that are not present in the encoding.

Conformance

This section explains the different levels of conformance to DOM Level 2. DOM Level 2 consists of 14 modules. It is possible to conform to DOM Level 2, or to a DOM Level 2 module.

An implementation is DOM Level 2 conformant if it supports the Core module defined in this document (see Fundamental Interfaces). An implementation conforms to a DOM Level 2 module if it supports all the interfaces for that module and the associated semantics.

Here is the complete list of DOM Level 2.0 modules and the features used by them. Feature names are case-insensitive.

Core module
defines the feature "Core".
XML module
defines the feature "XML".
HTML module
defines the feature "HTML". (see [DOM Level 2 HTML]).

Note: At time of publication, this DOM Level 2 module is not yet a W3C Recommendation.

Views module
defines the feature "Views" in [DOM Level 2 Views].
Style Sheets module
defines the feature "StyleSheets" in [DOM Level 2 Style Sheets].
CSS module
defines the feature "CSS" in [DOM Level 2 CSS].
CSS2 module
defines the feature "CSS2" in [DOM Level 2 CSS].
Events module
defines the feature "Events" in [DOM Level 2 Events].
User interface Events module
defines the feature "UIEvents" in [DOM Level 2 Events].
Mouse Events module
defines the feature "MouseEvents" in [DOM Level 2 Events].
Mutation Events module
defines the feature "MutationEvents" in [DOM Level 2 Events].
HTML Events module
defines the feature "HTMLEvents" in [DOM Level 2 Events].
Range module
defines the feature "Range" in [DOM Level 2 Range].
Traversal module
defines the feature "Traversal" in [DOM Level 2 Traversal].

A DOM implementation must not return "true" to the hasFeature(feature, version) method of the DOMImplementation interface for that feature unless the implementation conforms to that module. The version number for all features used in DOM Level 2.0 is "2.0".

DOM Interfaces and DOM Implementations

The DOM specifies interfaces which may be used to manage XML or HTML documents. It is important to realize that these interfaces are an abstraction - much like "abstract base classes" in C++, they are a means of specifying a way to access and manipulate an application's internal representation of a document. Interfaces do not imply a particular concrete implementation. Each DOM application is free to maintain documents in any convenient representation, as long as the interfaces shown in this specification are supported. Some DOM implementations will be existing programs that use the DOM interfaces to access software written long before the DOM specification existed. Therefore, the DOM is designed to avoid implementation dependencies; in particular,

  1. Attributes defined in the IDL do not imply concrete objects which must have specific data members - in the language bindings, they are translated to a pair of get()/set() functions, not to a data member. Read-only attributes have only a get() function in the language bindings.
  2. DOM applications may provide additional interfaces and objects not found in this specification and still be considered DOM conformant.
  3. Because we specify interfaces and not the actual objects that are to be created, the DOM cannot know what constructors to call for an implementation. In general, DOM users call the createX() methods on the Document class to create document structures, and DOM implementations create their own internal representations of these structures in their implementations of the createX() functions.

The Level 1 interfaces were extended to provide both Level 1 and Level 2 functionality.

DOM implementations in languages other than Java or ECMAScript may choose bindings that are appropriate and natural for their language and run time environment. For example, some systems may need to create a Document2 class which inherits from Document and contains the new methods and attributes.

DOM Level 2 does not specify multithreading mechanisms.

previous next contents index


Document Object Model Core

previous next contents index

13 November, 2000

1. Document Object Model Core

Editors
Arnaud Le Hors, IBM
Gavin Nicol, Inso EPS (for DOM Level 1)
Lauren Wood, SoftQuad, Inc. (for DOM Level 1)
Mike Champion, ArborText (for DOM Level 1 from November 20, 1997)
Steve Byrne, JavaSoft (for DOM Level 1 until November 19, 1997)

Table of contents

  • 1.1. Overview of the DOM Core Interfaces
    • 1.1.1. The DOM Structure Model
    • 1.1.2. Memory Management
    • 1.1.3. Naming Conventions
    • 1.1.4. Inheritance vs. Flattened Views of the API
    • 1.1.5. The DOMString type
    • 1.1.6. The DOMTimeStamp type
    • 1.1.7. String comparisons in the DOM
    • 1.1.8. XML Namespaces
  • 1.2. Fundamental Interfaces
    • DOMException, ExceptionCode, DOMImplementation, DocumentFragment, Document, Node, NodeList, NamedNodeMap, CharacterData, Attr, Element, Text, Comment
  • 1.3. Extended Interfaces
    • CDATASection, DocumentType, Notation, Entity, EntityReference, ProcessingInstruction

1.1. Overview of the DOM Core Interfaces

This section defines a set of objects and interfaces for accessing and manipulating document objects. The functionality specified in this section (the Core functionality) is sufficient to allow software developers and web script authors to access and manipulate parsed HTML and XML content inside conforming products. The DOM Core API also allows creation and population of a Document object using only DOM API calls; loading a Document and saving it persistently is left to the product that implements the DOM API.

1.1.1. The DOM Structure Model

The DOM presents documents as a hierarchy of Node objects that also implement other, more specialized interfaces. Some types of nodes may have child nodes of various types, and others are leaf nodes that cannot have anything below them in the document structure. For XML and HTML, the node types, and which node types they may have as children, are as follows:

  • Document -- Element (maximum of one), ProcessingInstruction, Comment, DocumentType (maximum of one)
  • DocumentFragment -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • DocumentType -- no children
  • EntityReference -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Element -- Element, Text, Comment, ProcessingInstruction, CDATASection, EntityReference
  • Attr -- Text, EntityReference
  • ProcessingInstruction -- no children
  • Comment -- no children
  • Text -- no children
  • CDATASection -- no children
  • Entity -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Notation -- no children

The DOM also specifies a NodeList interface to handle ordered lists of Nodes, such as the children of a Node, or the elements returned by the getElementsByTagName method of the Element interface, and also a NamedNodeMap interface to handle unordered sets of nodes referenced by their name attribute, such as the attributes of an Element. NodeList and NamedNodeMap objects in the DOM are live; that is, changes to the underlying document structure are reflected in all relevant NodeList and NamedNodeMap objects. For example, if a DOM user gets a NodeList object containing the children of an Element, then subsequently adds more children to that element (or removes children, or modifies them), those changes are automatically reflected in the NodeList, without further action on the user's part. Likewise, changes to a Node in the tree are reflected in all references to that Node in NodeList and NamedNodeMap objects.

Finally, the interfaces Text, Comment, and CDATASection all inherit from the CharacterData interface.

1.1.2. Memory Management

Most of the APIs defined by this specification are interfaces rather than classes. That means that an implementation need only expose methods with the defined names and specified operation, not implement classes that correspond directly to the interfaces. This allows the DOM APIs to be implemented as a thin veneer on top of legacy applications with their own data structures, or on top of newer applications with different class hierarchies. This also means that ordinary constructors (in the Java or C++ sense) cannot be used to create DOM objects, since the underlying objects to be constructed may have little relationship to the DOM interfaces. The conventional solution to this in object-oriented design is to define factory methods that create instances of objects that implement the various interfaces. Objects implementing some interface "X" are created by a "createX()" method on the Document interface; this is because all DOM objects live in the context of a specific Document.

The DOM Level 2 API does not define a standard way to create DOMImplementation objects; DOM implementations must provide some proprietary way of bootstrapping these DOM interfaces, and then all other objects can be built from there.

The Core DOM APIs are designed to be compatible with a wide range of languages, including both general-user scripting languages and the more challenging languages used mostly by professional programmers. Thus, the DOM APIs need to operate across a variety of memory management philosophies, from language bindings that do not expose memory management to the user at all, through those (notably Java) that provide explicit constructors but provide an automatic garbage collection mechanism to automatically reclaim unused memory, to those (especially C/C++) that generally require the programmer to explicitly allocate object memory, track where it is used, and explicitly free it for re-use. To ensure a consistent API across these platforms, the DOM does not address memory management issues at all, but instead leaves these for the implementation. Neither of the explicit language bindings defined by the DOM API (for ECMAScript and Java) require any memory management methods, but DOM bindings for other languages (especially C or C++) may require such support. These extensions will be the responsibility of those adapting the DOM API to a specific language, not the DOM Working Group.

1.1.3. Naming Conventions

While it would be nice to have attribute and method names that are short, informative, internally consistent, and familiar to users of similar APIs, the names also should not clash with the names in legacy APIs supported by DOM implementations. Furthermore, both OMG IDL and ECMAScript have significant limitations in their ability to disambiguate names from different namespaces that make it difficult to avoid naming conflicts with short, familiar names. So, DOM names tend to be long and descriptive in order to be unique across all environments.

The Working Group has also attempted to be internally consistent in its use of various terms, even though these may not be common distinctions in other APIs. For example, the DOM API uses the method name "remove" when the method changes the structural model, and the method name "delete" when the method gets rid of something inside the structure model. The thing that is deleted is not returned. The thing that is removed may be returned, when it makes sense to return it.

1.1.4. Inheritance vs. Flattened Views of the API

The DOM Core APIs present two somewhat different sets of interfaces to an XML/HTML document: one presenting an "object oriented" approach with a hierarchy of inheritance, and a "simplified" view that allows all manipulation to be done via the Node interface without requiring casts (in Java and other C-like languages) or query interface calls in COM environments. These operations are fairly expensive in Java and COM, and the DOM may be used in performance-critical environments, so we allow significant functionality using just the Node interface. Because many other users will find the inheritance hierarchy easier to understand than the "everything is a Node" approach to the DOM, we also support the full higher-level interfaces for those who prefer a more object-oriented API.

In practice, this means that there is a certain amount of redundancy in the API. The Working Group considers the "inheritance" approach the primary view of the API, and the full set of functionality on Node to be "extra" functionality that users may employ, but that does not eliminate the need for methods on other interfaces that an object-oriented analysis would dictate. (Of course, when the O-O analysis yields an attribute or method that is identical to one on the Node interface, we don't specify a completely redundant one.) Thus, even though there is a generic nodeName attribute on the Node interface, there is still a tagName attribute on the Element interface; these two attributes must contain the same value, but the it is worthwhile to support both, given the different constituencies the DOM API must satisfy.

1.1.5. The DOMString type

To ensure interoperability, the DOM specifies the following:

  • Type Definition DOMString

    A DOMString is a sequence of 16-bit units.

    IDL Definition
    valuetype DOMString sequence<unsigned short>;

  • Applications must encode DOMString using UTF-16 (defined in [Unicode] and Amendment 1 of [ISO/IEC 10646]).
    The UTF-16 encoding was chosen because of its widespread industry practice. Note that for both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS [ISO-10646]. A single numeric character reference in a source document may therefore in some cases correspond to two 16-bit units in a DOMString (a high surrogate and a low surrogate).

    Note: Even though the DOM defines the name of the string type to be DOMString, bindings may use different names. For example for Java, DOMString is bound to the String type because it also uses UTF-16 as its encoding.

Note: As of August 2000, the OMG IDL specification ([OMGIDL]) included a wstring type. However, that definition did not meet the interoperability criteria of the DOM API since it relied on negotiation to decide the width and encoding of a character.

1.1.6. The DOMTimeStamp type

To ensure interoperability, the DOM specifies the following:

  • Type Definition DOMTimeStamp

    A DOMTimeStamp represents a number of milliseconds.

    IDL Definition
    typedef unsigned long long DOMTimeStamp;

  • Note: Even though the DOM uses the type DOMTimeStamp, bindings may use different types. For example for Java, DOMTimeStamp is bound to the long type. In ECMAScript, TimeStamp is bound to the Date type because the range of the integer type is too small.

1.1.7. String comparisons in the DOM

The DOM has many interfaces that imply string matching. HTML processors generally assume an uppercase (less often, lowercase) normalization of names for such things as elements, while XML is explicitly case sensitive. For the purposes of the DOM, string matching is performed purely by binary comparison of the 16-bit units of the DOMString. In addition, the DOM assumes that any case normalizations take place in the processor, before the DOM structures are built.

Note: Besides case folding, there are additional normalizations that can be applied to text. The W3C I18N Working Group is in the process of defining exactly which normalizations are necessary, and where they should be applied. The W3C I18N Working Group expects to require early normalization, which means that data read into the DOM is assumed to already be normalized. The DOM and applications built on top of it in this case only have to assure that text remains normalized when being changed. For further details, please see [Charmod].

1.1.8. XML Namespaces

The DOM Level 2 supports XML namespaces [Namespaces] by augmenting several interfaces of the DOM Level 1 Core to allow creating and manipulating elements and attributes associated to a namespace.

As far as the DOM is concerned, special attributes used for declaring XML namespaces are still exposed and can be manipulated just like any other attribute. However, nodes are permanently bound to namespace URIs as they get created. Consequently, moving a node within a document, using the DOM, in no case results in a change of its namespace prefix or namespace URI. Similarly, creating a node with a namespace prefix and namespace URI, or changing the namespace prefix of a node, does not result in any addition, removal, or modification of any special attributes for declaring the appropriate XML namespaces. Namespace validation is not enforced; the DOM application is responsible. In particular, since the mapping between prefixes and namespace URIs is not enforced, in general, the resulting document cannot be serialized naively. For example, applications may have to declare every namespace in use when serializing a document.

DOM Level 2 doesn't perform any URI normalization or canonicalization. The URIs given to the DOM are assumed to be valid (e.g., characters such as whitespaces are properly escaped), and no lexical checking is performed. Absolute URI references are treated as strings and compared literally. How relative namespace URI references are treated is undefined. To ensure interoperability only absolute namespace URI references (i.e., URI references beginning with a scheme name and a colon) should be used. Note that because the DOM does no lexical checking, the empty string will be treated as a real namespace URI in DOM Level 2 methods. Applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.

Note: In the DOM, all namespace declaration attributes are by definition bound to the namespace URI: "http://www.w3.org/2000/xmlns/". These are the attributes whose namespace prefix or qualified name is "xmlns". Although, at the time of writing, this is not part of the XML Namespaces specification [Namespaces], it is planned to be incorporated in a future revision.

In a document with no namespaces, the child list of an EntityReference node is always the same as that of the corresponding Entity. This is not true in a document where an entity contains unbound namespace prefixes. In such a case, the descendants of the corresponding EntityReference nodes may be bound to different namespace URIs, depending on where the entity references are. Also, because, in the DOM, nodes always remain bound to the same namespace URI, moving such EntityReference nodes can lead to documents that cannot be serialized. This is also true when the DOM Level 1 method createEntityReference of the Document interface is used to create entity references that correspond to such entities, since the descendants of the returned EntityReference are unbound. The DOM Level 2 does not support any mechanism to resolve namespace prefixes. For all of these reasons, use of such entities and entity references should be avoided or used with extreme care. A future Level of the DOM may include some additional support for handling these.

The new methods, such as createElementNS and createAttributeNS of the Document interface, are meant to be used by namespace aware applications. Simple applications that do not use namespaces can use the DOM Level 1 methods, such as createElement and createAttribute. Elements and attributes created in this way do not have any namespace prefix, namespace URI, or local name.

Note: DOM Level 1 methods are namespace ignorant. Therefore, while it is safe to use these methods when not dealing with namespaces, using them and the new ones at the same time should be avoided. DOM Level 1 methods solely identify attribute nodes by their nodeName. On the contrary, the DOM Level 2 methods related to namespaces, identify attribute nodes by their namespaceURI and localName. Because of this fundamental difference, mixing both sets of methods can lead to unpredictable results. In particular, using setAttributeNS, an element may have two attributes (or more) that have the same nodeName, but different namespaceURIs. Calling getAttribute with that nodeName could then return any of those attributes. The result depends on the implementation. Similarly, using setAttributeNode, one can set two attributes (or more) that have different nodeNames but the same prefix and namespaceURI. In this case getAttributeNodeNS will return either attribute, in an implementation dependent manner. The only guarantee in such cases is that all methods that access a named item by its nodeName will access the same item, and all methods which access a node by its URI and local name will access the same node. For instance, setAttribute and setAttributeNS affect the node that getAttribute and getAttributeNS, respectively, return.

1.2. Fundamental Interfaces

The interfaces within this section are considered fundamental, and must be fully implemented by all conforming implementations of the DOM, including all HTML DOM implementations [DOM Level 2 HTML], unless otherwise specified.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Core" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. Any implementation that conforms to DOM Level 2 or a DOM Level 2 module must conform to the Core module. Please refer to additional information about conformance in this specification.

Exception DOMException

DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable). In general, DOM methods return specific error values in ordinary processing situations, such as out-of-bound errors when using NodeList.

Implementations should raise other exceptions under other circumstances. For example, implementations should raise an implementation-dependent exception if a null argument is passed.

Some languages and object systems do not support the concept of exceptions. For such systems, error conditions may be indicated using native error reporting mechanisms. For some bindings, for example, methods may return error codes similar to those listed in the corresponding method descriptions.

IDL Definition
exception DOMException {
  unsigned short   code;
};
// ExceptionCode
const unsigned short      INDEX_SIZE_ERR                 = 1;
const unsigned short      DOMSTRING_SIZE_ERR             = 2;
const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
const unsigned short      WRONG_DOCUMENT_ERR             = 4;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
const unsigned short      NOT_FOUND_ERR                  = 8;
const unsigned short      NOT_SUPPORTED_ERR              = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
// Introduced in DOM Level 2:
const unsigned short      INVALID_STATE_ERR              = 11;
// Introduced in DOM Level 2:
const unsigned short      SYNTAX_ERR                     = 12;
// Introduced in DOM Level 2:
const unsigned short      INVALID_MODIFICATION_ERR       = 13;
// Introduced in DOM Level 2:
const unsigned short      NAMESPACE_ERR                  = 14;
// Introduced in DOM Level 2:
const unsigned short      INVALID_ACCESS_ERR             = 15;

Definition group ExceptionCode

An integer indicating the type of error generated.

Note: Other numeric codes are reserved for W3C for possible future use.

Defined Constants
DOMSTRING_SIZE_ERR
If the specified range of text does not fit into a DOMString
HIERARCHY_REQUEST_ERR
If any node is inserted somewhere it doesn't belong
INDEX_SIZE_ERR
If index or size is negative, or greater than the allowed value
INUSE_ATTRIBUTE_ERR
If an attempt is made to add an attribute that is already in use elsewhere
INVALID_ACCESS_ERR, introduced in DOM Level 2.
If a parameter or an operation is not supported by the underlying object.
INVALID_CHARACTER_ERR
If an invalid or illegal character is specified, such as in a name. See production 2 in the XML specification for the definition of a legal character, and production 5 for the definition of a legal name character.
INVALID_MODIFICATION_ERR, introduced in DOM Level 2.
If an attempt is made to modify the type of the underlying object.
INVALID_STATE_ERR, introduced in DOM Level 2.
If an attempt is made to use an object that is not, or is no longer, usable.
NAMESPACE_ERR, introduced in DOM Level 2.
If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.
NOT_FOUND_ERR
If an attempt is made to reference a node in a context where it does not exist
NOT_SUPPORTED_ERR
If the implementation does not support the requested type of object or operation.
NO_DATA_ALLOWED_ERR
If data is specified for a node which does not support data
NO_MODIFICATION_ALLOWED_ERR
If an attempt is made to modify an object where modifications are not allowed
SYNTAX_ERR, introduced in DOM Level 2.
If an invalid or illegal string is specified.
WRONG_DOCUMENT_ERR
If a node is used in a different document than the one that created it (that doesn't support it)
Interface DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

IDL Definition
interface DOMImplementation {
  boolean            hasFeature(in DOMString feature,
                                in DOMString version);
  // Introduced in DOM Level 2:
  DocumentType       createDocumentType(in DOMString qualifiedName,
                                        in DOMString publicId,
                                        in DOMString systemId)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Document           createDocument(in DOMString namespaceURI,
                                    in DOMString qualifiedName,
                                    in DocumentType doctype)
                                        raises(DOMException);
};

Methods
createDocument introduced in DOM Level 2
Creates an XML Document object of the specified type with its document element. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the document element to create.
qualifiedName of type DOMString
The qualified name of the document element to be created.
doctype of type DocumentType
The type of document to be created or null.
When doctype is not null, its Node.ownerDocument attribute is set to the document being created.
Return Value

Document

A new Document object.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.

NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace" [Namespaces].

WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a different document or was created from a different implementation.
createDocumentType introduced in DOM Level 2
Creates an empty DocumentType node. Entity declarations and notations are not made available. Entity reference expansions and default attribute additions do not occur. It is expected that a future version of the DOM will provide a way for populating a DocumentType.
HTML-only DOM implementations do not need to implement this method.
Parameters
qualifiedName of type DOMString
The qualified name of the document type to be created.
publicId of type DOMString
The external subset public identifier.
systemId of type DOMString
The external subset system identifier.
Return Value

DocumentType

A new DocumentType node with Node.ownerDocument set to null.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.

NAMESPACE_ERR: Raised if the qualifiedName is malformed.
hasFeature
Test if the DOM implementation implements a specific feature.
Parameters
feature of type DOMString
The name of the feature to test (case-insensitive). The values used by DOM features are defined throughout the DOM Level 2 specifications and listed in the Conformance section. The name must be an XML name. To avoid possible conflicts, as a convention, names referring to features defined outside the DOM specification should be made unique by reversing the name of the Internet domain name of the person (or the organization that the person belongs to) who defines the feature, component by component, and using this as a prefix. For instance, the W3C SVG Working Group defines the feature "org.w3c.dom.svg".
version of type DOMString
This is the version number of the feature to test. In Level 2, the string can be either "2.0" or "1.0". If the version is not specified, supporting any version of the feature causes the method to return true.
Return Value

boolean

true if the feature is implemented in the specified version, false otherwise.
No Exceptions
Interface DocumentFragment

DocumentFragment is a "lightweight" or "minimal" Document object. It is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments and it is quite natural to use a Node for this purpose. While it is true that a Document object could fulfill this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object.

Furthermore, various operations -- such as inserting nodes as children of another Node -- may take DocumentFragment objects as arguments; this results in all the child nodes of the DocumentFragment being moved to the child list of this node.

The children of a DocumentFragment node are zero or more nodes representing the tops of any sub-trees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.

When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as insertBefore and appendChild.

IDL Definition
interface DocumentFragment : Node {
};

Interface Document

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

IDL Definition
interface Document : Node {
  readonly attribute DocumentType     doctype;
  readonly attribute DOMImplementation  implementation;
  readonly attribute Element          documentElement;
  Element            createElement(in DOMString tagName)
                                        raises(DOMException);
  DocumentFragment   createDocumentFragment();
  Text               createTextNode(in DOMString data);
  Comment            createComment(in DOMString data);
  CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
  ProcessingInstruction createProcessingInstruction(in DOMString target,
                                                    in DOMString data)
                                        raises(DOMException);
  Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
  EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString tagname);
  // Introduced in DOM Level 2:
  Node               importNode(in Node importedNode,
                                in boolean deep)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Element            createElementNS(in DOMString namespaceURI,
                                     in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Attr               createAttributeNS(in DOMString namespaceURI,
                                       in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                            in DOMString localName);
  // Introduced in DOM Level 2:
  Element            getElementById(in DOMString elementId);
};

Attributes
doctype of type DocumentType, readonly
The Document Type Declaration (see DocumentType) associated with this document. For HTML documents as well as XML documents without a document type declaration this returns null. The DOM Level 2 does not support editing the Document Type Declaration. docType cannot be altered in any way, including through the use of methods inherited from the Node interface, such as insertNode or removeNode.
documentElement of type Element, readonly
This is a convenience attribute that allows direct access to the child node that is the root element of the document. For HTML documents, this is the element with the tagName "HTML".
implementation of type DOMImplementation, readonly
The DOMImplementation object that handles this document. A DOM application may use objects from multiple implementations.
Methods
createAttribute
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttributeNode method.
To create an attribute with a qualified name and namespace URI, use the createAttributeNS method.
Parameters
name of type DOMString
The name of the attribute.
Return Value

Attr

A new Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null. The value of the attribute is the empty string.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
createAttributeNS introduced in DOM Level 2
Creates an attribute of the given qualified name and namespace URI. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to create.
qualifiedName of type DOMString
The qualified name of the attribute to instantiate.
Return Value

Attr

A new Attr object with the following attributes:

Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Attr.name | qualifiedName
Node.nodeValue | the empty string
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.

NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", or if the qualifiedName is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".
createCDATASection
Creates a CDATASection node whose value is the specified string.
Parameters
data of type DOMString
The data for the CDATASection contents.
Return Value

CDATASection

The new CDATASection object.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
createComment
Creates a Comment node given the specified string.
Parameters
data of type DOMString
The data for the node.
Return Value

Comment

The new Comment object.
No Exceptions
createDocumentFragment
Creates an empty DocumentFragment object.
Return Value

DocumentFragment

A new DocumentFragment.
No Parameters
No Exceptions
createElement
Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.
In addition, if there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.
To create an element with a qualified name and namespace URI, use the createElementNS method.
Parameters
tagName of type DOMString
The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.
Return Value

Element

A new Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
createElementNS introduced in DOM Level 2
Creates an element of the given qualified name and namespace URI. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the element to create.
qualifiedName of type DOMString
The qualified name of the element type to instantiate.
Return Value

Element

A new Element object with the following attributes:

Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Element.tagName | qualifiedName
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.

NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace" [Namespaces].
createEntityReference
Creates an EntityReference object. In addition, if the referenced entity is known, the child list of the EntityReference node is made the same as that of the corresponding Entity node.

Note: If any descendant of the Entity node has an unbound namespace prefix, the corresponding descendant of the created EntityReference node is also unbound; (its namespaceURI is null). The DOM Level 2 does not support any mechanism to resolve namespace prefixes.

Parameters
name of type DOMString
The name of the entity to reference.
Return Value

EntityReference

The new EntityReference object.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
createProcessingInstruction
Creates a ProcessingInstruction node given the specified name and data strings.
Parameters
target of type DOMString
The target part of the processing instruction.
data of type DOMString
The data for the node.
Return Value

ProcessingInstruction

The new ProcessingInstruction object.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified target contains an illegal character.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
createTextNode
Creates a Text node given the specified string.
Parameters
data of type DOMString
The data for the node.
Return Value

Text

The new Text object.
No Exceptions
getElementById introduced in DOM Level 2
Returns the Element whose ID is given by elementId. If no such element exists, returns null. Behavior is not defined if more than one element has this ID.

Note: The DOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.

Parameters
elementId of type DOMString
The unique id value for an element.
Return Value

Element

The matching element.
No Exceptions
getElementsByTagName
Returns a NodeList of all the Elements with a given tag name in the order in which they are encountered in a preorder traversal of the Document tree.
Parameters
tagname of type DOMString
The name of the tag to match on. The special value "*" matches all tags.
Return Value

NodeList

A new NodeList object containing all the matched Elements.
No Exceptions
getElementsByTagNameNS introduced in DOM Level 2
Returns a NodeList of all the Elements with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of the Document tree.
Parameters
namespaceURI of type DOMString
The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName of type DOMString
The local name of the elements to match on. The special value "*" matches all local names.
Return Value

NodeList

A new NodeList object containing all the matched Elements.
No Exceptions
importNode introduced in DOM Level 2
Imports a node from another document to this document. The returned node has no parent; (parentNode is null). The source node is not altered or removed from the original document; this method creates a new copy of the source node.
For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's nodeName and nodeType, plus the attributes related to namespaces (prefix, localName, and namespaceURI). As in the cloneNode operation on a Node, the source node is not altered.
Additional information is copied as appropriate to the nodeType, attempting to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, recognizing that the two documents may have different DTDs in the XML case. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the generated Attr. The descendants of the source Attr are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
Note that the deep parameter has no effect on Attr nodes; they always carry their children with them when imported.
DOCUMENT_FRAGMENT_NODE
If the deep option was set to true, the descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree. Otherwise, this simply generates an empty DocumentFragment.
DOCUMENT_NODE
Document nodes cannot be imported.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be imported.
ELEMENT_NODE
Specified attribute nodes of the source element are imported, and the generated Attr nodes are attached to the generated Element. Default attributes are not copied, though if the document being imported into defines default attributes for this element name, those are assigned. If the importNode deep parameter was set to true, the descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_NODE
Entity nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.
On import, the publicId, systemId, and notationName attributes are copied. If a deep import is requested, the descendants of the the source Entity are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_REFERENCE_NODE
Only the EntityReference itself is copied, even if a deep import is requested, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.
On import, the publicId and systemId attributes are copied.
Note that the deep parameter has no effect on Notation nodes since they never have any children.
PROCESSING_INSTRUCTION_NODE
The imported node copies its target and data values from those of the source node.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These three types of nodes inheriting from CharacterData copy their data and length attributes from those of the source node.
Parameters
importedNode of type Node
The node to import.
deep of type boolean
If true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This has no effect on Attr, EntityReference, and Notation nodes.
Return Value

Node

The imported node that belongs to this Document.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.
Interface Node

The Node interface is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes results in a DOMException being raised.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue for an Element or attributes for a Comment), this returns null. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

IDL Definition
interface Node {

  // NodeType
  const unsigned short      ELEMENT_NODE                   = 1;
  const unsigned short      ATTRIBUTE_NODE                 = 2;
  const unsigned short      TEXT_NODE                      = 3;
  const unsigned short      CDATA_SECTION_NODE             = 4;
  const unsigned short      ENTITY_REFERENCE_NODE          = 5;
  const unsigned short      ENTITY_NODE                    = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
  const unsigned short      COMMENT_NODE                   = 8;
  const unsigned short      DOCUMENT_NODE                  = 9;
  const unsigned short      DOCUMENT_TYPE_NODE             = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
  const unsigned short      NOTATION_NODE                  = 12;

  readonly attribute DOMString        nodeName;
           attribute DOMString        nodeValue;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned short   nodeType;
  readonly attribute Node             parentNode;
  readonly attribute NodeList         childNodes;
  readonly attribute Node             firstChild;
  readonly attribute Node             lastChild;
  readonly attribute Node             previousSibling;
  readonly attribute Node             nextSibling;
  readonly attribute NamedNodeMap     attributes;
  // Modified in DOM Level 2:
  readonly attribute Document         ownerDocument;
  Node               insertBefore(in Node newChild,
                                  in Node refChild)
                                        raises(DOMException);
  Node               replaceChild(in Node newChild,
                                  in Node oldChild)
                                        raises(DOMException);
  Node               removeChild(in Node oldChild)
                                        raises(DOMException);
  Node               appendChild(in Node newChild)
                                        raises(DOMException);
  boolean            hasChildNodes();
  Node               cloneNode(in boolean deep);
  // Modified in DOM Level 2:
  void               normalize();
  // Introduced in DOM Level 2:
  boolean            isSupported(in DOMString feature,
                                 in DOMString version);
  // Introduced in DOM Level 2:
  readonly attribute DOMString        namespaceURI;
  // Introduced in DOM Level 2:
           attribute DOMString        prefix;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 2:
  readonly attribute DOMString        localName;
  // Introduced in DOM Level 2:
  boolean            hasAttributes();
};

Definition group NodeType

An integer indicating which type of node this is.

Note: Numeric codes up to 200 are reserved to W3C for possible future use.

Defined Constants
ATTRIBUTE_NODE
The node is an Attr.
CDATA_SECTION_NODE
The node is a CDATASection.
COMMENT_NODE
The node is a Comment.
DOCUMENT_FRAGMENT_NODE
The node is a DocumentFragment.
DOCUMENT_NODE
The node is a Document.
DOCUMENT_TYPE_NODE
The node is a DocumentType.
ELEMENT_NODE
The node is an Element.
ENTITY_NODE
The node is an Entity.
ENTITY_REFERENCE_NODE
The node is an EntityReference.
NOTATION_NODE
The node is a Notation.
PROCESSING_INSTRUCTION_NODE
The node is a ProcessingInstruction.
TEXT_NODE
The node is a Text node.

The values of nodeName, nodeValue, and attributes vary according to the node type as follows:

Interface | nodeName | nodeValue | attributes
Attr | name of attribute | value of attribute | null
CDATASection | #cdata-section | content of the CDATA Section | null
Comment | #comment | content of the comment | null
Document | #document | null | null
DocumentFragment | #document-fragment | null | null
DocumentType | document type name | null | null
Element | tag name | null | NamedNodeMap
Entity | entity name | null | null
EntityReference | name of entity referenced | null | null
Notation | notation name | null | null
ProcessingInstruction | target | entire content excluding the target | null
Text | #text | content of the text node | null
Attributes
attributes of type NamedNodeMap, readonly
A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.
childNodes of type NodeList, readonly
A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.
firstChild of type Node, readonly
The first child of this node. If there is no such node, this returns null.
lastChild of type Node, readonly
The last child of this node. If there is no such node, this returns null.
localName of type DOMString, readonly, introduced in DOM Level 2
Returns the local part of the qualified name of this node.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.
namespaceURI of type DOMString, readonly, introduced in DOM Level 2
The namespace URI of this node, or null if it is unspecified.
This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.

Note: Per the Namespaces in XML Specification [Namespaces] an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.

nextSibling of type Node, readonly
The node immediately following this node. If there is no such node, this returns null.
nodeName of type DOMString, readonly
The name of this node, depending on its type; see the table above.
nodeType of type unsigned short, readonly
A code representing the type of the underlying object, as defined above.
nodeValue of type DOMString
The value of this node, depending on its type; see the table above. When it is defined to be null, setting it has no effect.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
Exceptions on retrieval

DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
ownerDocument of type Document, readonly, modified in DOM Level 2
The Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document or a DocumentType which is not used with any Document yet, this is null.
parentNode of type Node, readonly
The parent of this node. All nodes, except Attr, Document, DocumentFragment, Entity, and Notation may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.
prefix of type DOMString, introduced in DOM Level 2
The namespace prefix of this node, or null if it is unspecified.
Note that setting this attribute, when permitted, changes the nodeName attribute, which holds the qualified name, as well as the tagName and name attributes of the Element and Attr interfaces, when applicable.
Note also that changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespaceURI and localName do not change.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.
Exceptions on setting

DOMException

INVALID_CHARACTER_ERR: Raised if the specified prefix contains an illegal character.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NAMESPACE_ERR: Raised if the specified prefix is malformed, if the namespaceURI of this node is null, if the specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName of this node is "xmlns" [Namespaces].
previousSibling of type Node, readonly
The node immediately preceding this node. If there is no such node, this returns null.
Methods
appendChild
Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.
Parameters
newChild of type Node
The node to add.
If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node
Return Value

Node

The node added.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
cloneNode
Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent; (parentNode is null.).
Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any text it contains unless it is a deep clone, since the text is contained in a child Text node. Cloning an Attribute directly, as opposed to be cloned as part of an Element cloning operation, returns a specified attribute (specified is true). Cloning any other type of node simply returns a copy of this node.
Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly. In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.
Parameters
deep of type boolean
If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element).
Return Value

Node

The duplicate node.
No Exceptions
hasAttributes introduced in DOM Level 2
Returns whether this node (if it is an element) has any attributes.
Return Value

boolean

true if this node has any attributes, false otherwise.
No Parameters
No Exceptions
hasChildNodes
Returns whether this node has any children.
Return Value

boolean

true if this node has any children, false otherwise.
No Parameters
No Exceptions
insertBefore
Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.
If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.
Parameters
newChild of type Node
The node to insert.
refChild of type Node
The reference node, i.e., the node before which the new node must be inserted.
Return Value

Node

The node being inserted.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the parent of the node being inserted is readonly.

NOT_FOUND_ERR: Raised if refChild is not a child of this node.
isSupported introduced in DOM Level 2
Tests whether the DOM implementation implements a specific feature and that feature is supported by this node.
Parameters
feature of type DOMString
The name of the feature to test. This is the same name which can be passed to the method hasFeature on DOMImplementation.
version of type DOMString
This is the version number of the feature to test. In Level 2, version 1, this is the string "2.0". If the version is not specified, supporting any version of the feature will cause the method to return true.
Return Value

boolean

Returns true if the specified feature is supported on this node, false otherwise.
No Exceptions
normalize modified in DOM Level 2
Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer [XPointer] lookups) that depend on a particular document tree structure are to be used.

Note: In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

No Parameters
No Return Value
No Exceptions
removeChild
Removes the child node indicated by oldChild from the list of children, and returns it.
Parameters
oldChild of type Node
The node being removed.
Return Value

Node

The node removed.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
replaceChild
Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.
Parameters
newChild of type Node
The new node to put in the child list.
oldChild of type Node
The node being replaced in the list.
Return Value

Node

The node replaced.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the new node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.
Interface NodeList

The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented. NodeList objects in the DOM are live.

The items in the NodeList are accessible via an integral index, starting from 0.

IDL Definition
interface NodeList {
  Node               item(in unsigned long index);
  readonly attribute unsigned long    length;
};

Attributes
length of type unsigned long, readonly
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

Node

The node at the indexth position in the NodeList, or null if that is not a valid index.
No Exceptions
Interface NamedNodeMap

Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name. Note that NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not maintained in any particular order. Objects contained in an object implementing NamedNodeMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a NamedNodeMap, and does not imply that the DOM specifies an order to these Nodes.

NamedNodeMap objects in the DOM are live.

IDL Definition
interface NamedNodeMap {
  Node               getNamedItem(in DOMString name);
  Node               setNamedItem(in Node arg)
                                        raises(DOMException);
  Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
  Node               item(in unsigned long index);
  readonly attribute unsigned long    length;
  // Introduced in DOM Level 2:
  Node               getNamedItemNS(in DOMString namespaceURI,
                                    in DOMString localName);
  // Introduced in DOM Level 2:
  Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Node               removeNamedItemNS(in DOMString namespaceURI,
                                       in DOMString localName)
                                        raises(DOMException);
};

Attributes
length of type unsigned long, readonly
The number of nodes in this map. The range of valid child node indices is 0 to length-1 inclusive.
Methods
getNamedItem
Retrieves a node specified by name.
Parameters
name of type DOMString
The nodeName of a node to retrieve.
Return Value

Node

A Node (of any type) with the specified nodeName, or null if it does not identify any node in this map.
No Exceptions
getNamedItemNS introduced in DOM Level 2
Retrieves a node specified by local name and namespace URI. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to retrieve.
localName of type DOMString
The local name of the node to retrieve.
Return Value

Node

A Node (of any type) with the specified local name and namespace URI, or null if they do not identify any node in this map.
No Exceptions
item
Returns the indexth item in the map. If index is greater than or equal to the number of nodes in this map, this returns null.
Parameters
index of type unsigned long
Index into this map.
Return Value

Node

The node at the indexth position in the map, or null if that is not a valid index.
No Exceptions
removeNamedItem
Removes a node specified by name. When this map contains the attributes attached to an element, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Parameters
name of type DOMString
The nodeName of the node to remove.
Return Value

Node

The node removed from this map if a node with such a name exists.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node named name in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
removeNamedItemNS introduced in DOM Level 2
Removes a node specified by local name and namespace URI. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the Node interface. If so, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to remove.
localName of type DOMString
The local name of the node to remove.
Return Value

Node

The node removed from this map if a node with such a local name and namespace URI exists.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node with the specified namespaceURI and localName in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
setNamedItem
Adds a node using its nodeName attribute. If a node with that name is already present in this map, it is replaced by the new one.
As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased.
Parameters
arg of type Node
A node to store in this map. The node will later be accessible using the value of its nodeName attribute.
Return Value

Node

If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
setNamedItemNS introduced in DOM Level 2
Adds a node using its namespaceURI and localName. If a node with that namespace URI and that local name is already present in this map, it is replaced by the new one.
HTML-only DOM implementations do not need to implement this method.
Parameters
arg of type Node
A node to store in this map. The node will later be accessible using the value of its namespaceURI and localName attributes.
Return Value

Node

If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
Interface CharacterData

The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM. For clarity this set is defined here rather than on each object that uses these attributes and methods. No DOM objects correspond directly to CharacterData, though Text and others do inherit the interface from it. All offsets in this interface start from 0.

As explained in the DOMString interface, text strings in the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In the following, the term 16-bit units is used whenever necessary to indicate that indexing on CharacterData is done in 16-bit units.

IDL Definition
interface CharacterData : Node {
           attribute DOMString        data;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned long    length;
  DOMString          substringData(in unsigned long offset,
                                   in unsigned long count)
                                        raises(DOMException);
  void               appendData(in DOMString arg)
                                        raises(DOMException);
  void               insertData(in unsigned long offset,
                                in DOMString arg)
                                        raises(DOMException);
  void               deleteData(in unsigned long offset,
                                in unsigned long count)
                                        raises(DOMException);
  void               replaceData(in unsigned long offset,
                                 in unsigned long count,
                                 in DOMString arg)
                                        raises(DOMException);
};

Attributes
data of type DOMString
The character data of the node that implements this interface. The DOM implementation may not put arbitrary limits on the amount of data that may be stored in a CharacterData node. However, implementation limits may mean that the entirety of a node's data may not fit into a single DOMString. In such cases, the user may call substringData to retrieve the data in appropriately sized pieces.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
Exceptions on retrieval

DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.
length of type unsigned long, readonly
The number of 16-bit units that are available through data and the substringData method below. This may have the value zero, i.e., CharacterData nodes may be empty.
Methods
appendData
Append the string to the end of the character data of the node. Upon success, data provides access to the concatenation of data and the DOMString specified.
Parameters
arg of type DOMString
The DOMString to append.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
deleteData
Remove a range of 16-bit units from the node. Upon success, data and length reflect the change.
Parameters
offset of type unsigned long
The offset from which to start removing.
count of type unsigned long
The number of 16-bit units to delete. If the sum of offset and count exceeds length then all 16-bit units from offset to the end of the data are deleted.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
insertData
Insert a string at the specified 16-bit unit offset.
Parameters
offset of type unsigned long
The character offset at which to insert.
arg of type DOMString
The DOMString to insert.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
replaceData
Replace the characters starting at the specified 16-bit unit offset with the specified string.
Parameters
offset of type unsigned long
The offset from which to start replacing.
count of type unsigned long
The number of 16-bit units to replace. If the sum of offset and count exceeds length, then all 16-bit units to the end of the data are replaced; (i.e., the effect is the same as a remove method call with the same range, followed by an append method invocation).
arg of type DOMString
The DOMString with which the range must be replaced.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
substringData
Extracts a range of data from the node.
Parameters
offset of type unsigned long
Start offset of substring to extract.
count of type unsigned long
The number of 16-bit units to extract.
Return Value

DOMString

The specified substring. If the sum of offset and count exceeds the length, then all 16-bit units to the end of the data are returned.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

DOMSTRING_SIZE_ERR: Raised if the specified range of text does not fit into a DOMString.
Interface Attr

The Attr interface represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a document type definition.

Attr objects inherit the Node interface, but since they are not actually child nodes of the element they describe, the DOM does not consider them part of the document tree. Thus, the Node attributes parentNode, previousSibling, and nextSibling have a null value for Attr objects. The DOM takes the view that attributes are properties of elements rather than having a separate identity from the elements they are associated with; this should make it more efficient to implement such features as default attributes associated with all elements of a given type. Furthermore, Attr nodes may not be immediate children of a DocumentFragment. However, they can be associated with Element nodes contained within a DocumentFragment. In short, users and implementors of the DOM need to be aware that Attr nodes have some things in common with other objects inheriting the Node interface, but they also are quite distinct.

The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute does not exist on this element in the structure model until it has been explicitly added. Note that the nodeValue attribute on the Attr instance can also be used to retrieve the string version of the attribute's value(s).

In XML, where the value of an attribute can contain entity references, the child nodes of the Attr node may be either Text or EntityReference nodes (when these are in use; see the description of EntityReference for discussion). Because the DOM Core is not aware of attribute types, it treats all attribute values as simple strings, even if the DTD or schema declares them as having tokenized types.

IDL Definition
interface Attr : Node {
  readonly attribute DOMString        name;
  readonly attribute boolean          specified;
           attribute DOMString        value;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 2:
  readonly attribute Element          ownerElement;
};

Attributes
name of type DOMString, readonly
Returns the name of this attribute.
ownerElement of type Element, readonly, introduced in DOM Level 2
The Element node this attribute is attached to or null if this attribute is not in use.
specified of type boolean, readonly
If this attribute was explicitly given a value in the original document, this is true; otherwise, it is false. Note that the implementation is in charge of this attribute, not the user. If the user changes the value of the attribute (even if it ends up having the same value as the default value) then the specified flag is automatically flipped to true. To re-specify the attribute as the default value from the DTD, the user must delete the attribute. The implementation will then make a new attribute available with specified set to false and the default value (if one exists).
In summary:
  • If the attribute has an assigned value in the document then specified is true, and the value is the assigned value.
  • If the attribute has no assigned value in the document and has a default value in the DTD, then specified is false, and the value is the default value in the DTD.
  • If the attribute has no assigned value in the document and has a value of #IMPLIED in the DTD, then the attribute does not appear in the structure model of the document.
  • If the ownerElement attribute is null (i.e. because it was just created or was set to null by the various removal and cloning operations) specified is true.

value of type DOMString
On retrieval, the value of the attribute is returned as a string. Character and general entity references are replaced with their values. See also the method getAttribute on the Element interface.
On setting, this creates a Text node with the unparsed contents of the string. I.e. any characters that an XML processor would recognize as markup are instead treated as literal text. See also the method setAttribute on the Element interface.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
Interface Element

The Element interface represents an element in an HTML or XML document. Elements may have attributes associated with them; since the Element interface inherits from Node, the generic Node interface attribute attributes may be used to retrieve the set of all attributes for an element. There are methods on the Element interface to retrieve either an Attr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, an Attr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

Note: In DOM Level 2, the method normalize is inherited from the Node interface where it was moved.

IDL Definition
interface Element : Node {
  readonly attribute DOMString        tagName;
  DOMString          getAttribute(in DOMString name);
  void               setAttribute(in DOMString name,
                                  in DOMString value)
                                        raises(DOMException);
  void               removeAttribute(in DOMString name)
                                        raises(DOMException);
  Attr               getAttributeNode(in DOMString name);
  Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
  Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString name);
  // Introduced in DOM Level 2:
  DOMString          getAttributeNS(in DOMString namespaceURI,
                                    in DOMString localName);
  // Introduced in DOM Level 2:
  void               setAttributeNS(in DOMString namespaceURI,
                                    in DOMString qualifiedName,
                                    in DOMString value)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  void               removeAttributeNS(in DOMString namespaceURI,
                                       in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Attr               getAttributeNodeNS(in DOMString namespaceURI,
                                        in DOMString localName);
  // Introduced in DOM Level 2:
  Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                            in DOMString localName);
  // Introduced in DOM Level 2:
  boolean            hasAttribute(in DOMString name);
  // Introduced in DOM Level 2:
  boolean            hasAttributeNS(in DOMString namespaceURI,
                                    in DOMString localName);
};

Attributes
tagName of type DOMString, readonly
The name of the element. For example, in:
<elementExample id="demo">
        ...
</elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM. The HTML DOM returns the tagName of an HTML element in the canonical uppercase form, regardless of the case in the source HTML document.
Methods
getAttribute
Retrieves an attribute value by name.
Parameters
name of type DOMString
The name of the attribute to retrieve.
Return Value

DOMString

The Attr value as a string, or the empty string if that attribute does not have a specified or default value.
No Exceptions
getAttributeNS introduced in DOM Level 2
Retrieves an attribute value by local name and namespace URI. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value

DOMString

The Attr value as a string, or the empty string if that attribute does not have a specified or default value.
No Exceptions
getAttributeNode
Retrieves an attribute node by name.
To retrieve an attribute node by qualified name and namespace URI, use the getAttributeNodeNS method.
Parameters
name of type DOMString
The name (nodeName) of the attribute to retrieve.
Return Value

Attr

The Attr node with the specified name (nodeName) or null if there is no such attribute.
No Exceptions
getAttributeNodeNS introduced in DOM Level 2
Retrieves an Attr node by local name and namespace URI. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value

Attr

The Attr node with the specified attribute local name and namespace URI or null if there is no such attribute.
No Exceptions
getElementsByTagName
Returns a NodeList of all descendant Elements with a given tag name, in the order in which they are encountered in a preorder traversal of this Element tree.
Parameters
name of type DOMString
The name of the tag to match on. The special value "*" matches all tags.
Return Value

NodeList

A list of matching Element nodes.
No Exceptions
getElementsByTagNameNS introduced in DOM Level 2
Returns a NodeList of all the descendant Elements with a given local name and namespace URI in the order in which they are encountered in a preorder traversal of this Element tree.
HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName of type DOMString
The local name of the elements to match on. The special value "*" matches all local names.
Return Value

NodeList

A new NodeList object containing all the matched Elements.
No Exceptions
hasAttribute introduced in DOM Level 2
Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.
Parameters
name of type DOMString
The name of the attribute to look for.
Return Value

boolean

true if an attribute with the given name is specified on this element or has a default value, false otherwise.
No Exceptions
hasAttributeNS introduced in DOM Level 2
Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise. HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to look for.
localName of type DOMString
The local name of the attribute to look for.
Return Value

boolean

true if an attribute with the given local name and namespace URI is specified or has a default value on this element, false otherwise.
No Exceptions
removeAttribute
Removes an attribute by name. If the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
To remove an attribute by local name and namespace URI, use the removeAttributeNS method.
Parameters
name of type DOMString
The name of the attribute to remove.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
removeAttributeNS introduced in DOM Level 2
Removes an attribute by local name and namespace URI. If the removed attribute has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix.
HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to remove.
localName of type DOMString
The local name of the attribute to remove.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
removeAttributeNode
Removes the specified attribute node. If the removed Attr has a default value it is immediately replaced. The replacing attribute has the same namespace URI and local name, as well as the original prefix, when applicable.
Parameters
oldAttr of type Attr
The Attr node to remove from the attribute list.
Return Value

Attr

The Attr node that was removed.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldAttr is not an attribute of the element.
setAttribute
Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute.
To set an attribute with a qualified name and namespace URI, use the setAttributeNS method.
Parameters
name of type DOMString
The name of the attribute to create or alter.
value of type DOMString
Value to set in string form.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
No Return Value
setAttributeNS introduced in DOM Level 2
Adds a new attribute. If an attribute with the same local name and namespace URI is already present on the element, its prefix is changed to be the prefix part of the qualifiedName, and its value is changed to be the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNodeNS or setAttributeNode to assign it as the value of an attribute.
HTML-only DOM implementations do not need to implement this method.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to create or alter.
qualifiedName of type DOMString
The qualified name of the attribute to create or alter.
value of type DOMString
The value to set in string form.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name contains an illegal character.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", or if the qualifiedName is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".
No Return Value
setAttributeNode
Adds a new attribute node. If an attribute with that name (nodeName) is already present in the element, it is replaced by the new one.
To add a new attribute node with a qualified name and namespace URI, use the setAttributeNodeNS method.
Parameters
newAttr of type Attr
The Attr node to add to the attribute list.
Return Value

Attr

If the newAttr attribute replaces an existing attribute, the replaced Attr node is returned, otherwise null is returned.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
setAttributeNodeNS introduced in DOM Level 2
Adds a new attribute. If an attribute with that local name and that namespace URI is already present in the element, it is replaced by the new one.
HTML-only DOM implementations do not need to implement this method.
Parameters
newAttr of type Attr
The Attr node to add to the attribute list.
Return Value

Attr

If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the replaced Attr node is returned, otherwise null is returned.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.
Interface Text

The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr. If there is no markup inside an element's content, the text is contained in a single object implementing the Text interface that is the only child of the element. If there is markup, it is parsed into the information items (elements, comments, etc.) and Text nodes that form the list of children of the element.

When a document is first made available via the DOM, there is only one Text node for each block of text. Users may create adjacent Text nodes that represent the contents of a given element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, so they will not (in general) persist between DOM editing sessions. The normalize() method on Node merges any such adjacent Text objects into a single node for each block of text.

IDL Definition
interface Text : CharacterData {
  Text               splitText(in unsigned long offset)
                                        raises(DOMException);
};

Methods
splitText
Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings. After being split, this node will contain all the content up to the offset point. A new node of the same type, which contains all the content at and after the offset point, is returned. If the original node had a parent node, the new node is inserted as the next sibling of the original node. When the offset is equal to the length of this node, the new node has no data.
Parameters
offset of type unsigned long
The 16-bit unit offset at which to split, starting from 0.
Return Value

Text

The new node, of the same type as this node.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
Interface Comment

This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting '<!--' and ending '-->'. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.

IDL Definition
interface Comment : CharacterData {
};

1.3. Extended Interfaces

The interfaces defined here form part of the DOM Core specification, but objects that expose these interfaces will never be encountered in a DOM implementation that deals only with HTML. As such, HTML-only DOM implementations [DOM Level 2 HTML] do not need to have objects that implement these interfaces.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "XML" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined in Fundamental Interfaces. Please refer to additional information about Conformance in this specification.

Interface CDATASection

CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. The only delimiter that is recognized in a CDATA section is the "]]>" string that ends the CDATA section. CDATA sections cannot be nested. Their primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.

The DOMString attribute of the Text node holds the text that is contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections and that, depending on the character encoding ("charset") chosen for serialization, it may be impossible to write out some characters as part of a CDATA section.

The CDATASection interface inherits from the CharacterData interface through the Text interface. Adjacent CDATASection nodes are not merged by use of the normalize method of the Node interface.

Note: Because no markup is recognized within a CDATASection, character numeric references cannot be used as an escape mechanism when serializing. Therefore, action needs to be taken when serializing a CDATASection with a character encoding where some of the contained characters cannot be represented. Failure to do so would not produce well-formed XML.
One potential solution in the serialization process is to end the CDATA section before the character, output the character using a character reference or entity reference, and open a new CDATA section for any further characters in the text node. Note, however, that some code conversion libraries at the time of writing do not return an error or exception when a character is missing from the encoding, making the task of ensuring that data is not corrupted on serialization more difficult.

IDL Definition
interface CDATASection : Text {
};

Interface DocumentType

Each Document has a doctype attribute whose value is either null or a DocumentType object. The DocumentType interface in the DOM Core provides an interface to the list of entities that are defined for the document, and little else because the effect of namespaces and the various XML schema efforts on DTD representation are not clearly understood as of this writing.

The DOM Level 2 doesn't support editing DocumentType nodes.

IDL Definition
interface DocumentType : Node {
  readonly attribute DOMString        name;
  readonly attribute NamedNodeMap     entities;
  readonly attribute NamedNodeMap     notations;
  // Introduced in DOM Level 2:
  readonly attribute DOMString        publicId;
  // Introduced in DOM Level 2:
  readonly attribute DOMString        systemId;
  // Introduced in DOM Level 2:
  readonly attribute DOMString        internalSubset;
};

Attributes
entities of type NamedNodeMap, readonly
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Parameter entities are not contained. Duplicates are discarded. For example in:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY bar "bar2">
  <!ENTITY % baz "baz">
]>
<ex/>
the interface provides access to foo and the first declaration of bar but not the second declaration of bar or baz. Every node in this map also implements the Entity interface.
The DOM Level 2 does not support editing entities, therefore entities cannot be altered in any way.
internalSubset of type DOMString, readonly, introduced in DOM Level 2
The internal subset as a string.

Note: The actual content returned depends on how much information is available to the implementation. This may vary depending on various parameters, including the XML processor used to build the document.

name of type DOMString, readonly
The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
notations of type NamedNodeMap, readonly
A NamedNodeMap containing the notations declared in the DTD. Duplicates are discarded. Every node in this map also implements the Notation interface.
The DOM Level 2 does not support editing notations, therefore notations cannot be altered in any way.
publicId of type DOMString, readonly, introduced in DOM Level 2
The public identifier of the external subset.
systemId of type DOMString, readonly, introduced in DOM Level 2
The system identifier of the external subset.
Interface Notation

This interface represents a notation declared in the DTD. A notation either declares, by name, the format of an unparsed entity (see section 4.7 of the XML 1.0 specification [XML]), or is used for formal declaration of processing instruction targets (see section 2.6 of the XML 1.0 specification [XML]). The nodeName attribute inherited from Node is set to the declared name of the notation.

The DOM Level 1 does not support editing Notation nodes; they are therefore readonly.

A Notation node does not have any parent.

IDL Definition
interface Notation : Node {
  readonly attribute DOMString        publicId;
  readonly attribute DOMString        systemId;
};

Attributes
publicId of type DOMString, readonly
The public identifier of this notation. If the public identifier was not specified, this is null.
systemId of type DOMString, readonly
The system identifier of this notation. If the system identifier was not specified, this is null.
Interface Entity

This interface represents an entity, either parsed or unparsed, in an XML document. Note that this models the entity itself not the entity declaration. Entity declaration modeling has been left for a later Level of the DOM specification.

The nodeName attribute that is inherited from Node contains the name of the entity.

An XML processor may choose to completely expand entities before the structure model is passed to the DOM; in this case there will be no EntityReference nodes in the document tree.

XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or declared in external parameter entities. This means that parsed entities declared in the external subset need not be expanded by some classes of applications, and that the replacement value of the entity may not be available. When the replacement value is available, the corresponding Entity node's child list represents the structure of that replacement text. Otherwise, the child list is empty.

The DOM Level 2 does not support editing Entity nodes; if a user wants to make changes to the contents of an Entity, every related EntityReference node has to be replaced in the structure model by a clone of the Entity's contents, and then the desired changes must be made to each of those clones instead. Entity nodes and all their descendants are readonly.

An Entity node does not have any parent.

Note: If the entity contains an unbound namespace prefix, the namespaceURI of the corresponding node in the Entity node subtree is null. The same is true for EntityReference nodes that refer to this entity, when they are created using the createEntityReference method of the Document interface. The DOM Level 2 does not support any mechanism to resolve namespace prefixes.

IDL Definition
interface Entity : Node {
  readonly attribute DOMString        publicId;
  readonly attribute DOMString        systemId;
  readonly attribute DOMString        notationName;
};

Attributes
notationName of type DOMString, readonly
For unparsed entities, the name of the notation for the entity. For parsed entities, this is null.
publicId of type DOMString, readonly
The public identifier associated with the entity, if specified. If the public identifier was not specified, this is null.
systemId of type DOMString, readonly
The system identifier associated with the entity, if specified. If the system identifier was not specified, this is null.
Interface EntityReference

EntityReference objects may be inserted into the structure model when an entity reference is in the source document, or when the user wishes to insert an entity reference. Note that character references and references to predefined entities are considered to be expanded by the HTML or XML processor so that characters are represented by their Unicode equivalent rather than by an entity reference. Moreover, the XML processor may completely expand references to entities while building the structure model, instead of providing EntityReference objects. If it does provide such objects, then for a given EntityReference node, it may be that there is no Entity node representing the referenced entity. If such an Entity exists, then the subtree of the EntityReference node is in general a copy of the Entity node subtree. However, this may not be true when an entity contains an unbound namespace prefix. In such a case, because the namespace prefix resolution depends on where the entity reference is, the descendants of the EntityReference node may be bound to different namespace URIs.

As for Entity nodes, EntityReference nodes and all their descendants are readonly.

IDL Definition
interface EntityReference : Node {
};

Interface ProcessingInstruction

The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.

IDL Definition
interface ProcessingInstruction : Node {
  readonly attribute DOMString        target;
           attribute DOMString        data;
                                        // raises(DOMException) on setting

};

Attributes
data of type DOMString
The content of this processing instruction. This is from the first non white space character after the target to the character immediately preceding the ?>.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
target of type DOMString, readonly
The target of this processing instruction. XML defines this as being the first token following the markup that begins the processing instruction.
previous next contents index


Changes

previous next contents index

13 November, 2000

Appendix A: Changes

Editors
Arnaud Le Hors, IBM
Philippe Le Hégaret, W3C

A.1: Changes between DOM Level 1 Core and DOM Level 2 Core

OMG IDL
The DOM Level 2 specifications are now using Corba 2.3.1 instead of Corba 2.2.
Type DOMString
The definition of DOMString in IDL is now a valuetype.

A.1.1: Changes to DOM Level 1 Core interfaces and exceptions

Interface Attr
The Attr interface has one new attribute: ownerElement.
Interface Document
The Document interface has five new methods: importNode, createElementNS, createAttributeNS, getElementsByTagNameNS and getElementById.
Interface NamedNodeMap
The NamedNodeMap interface has three new methods: getNamedItemNS, setNamedItemNS, removeNamedItemNS.
Interface Node
The Node interface has two new methods: isSupported and hasAttributes.
normalize, previously in the Element interface, has been moved in the Node interface.
The Node interface has three new attributes: namespaceURI, prefix and localName.
The ownerDocument attribute was specified to be null when the node is a Document. It now is also null when the node is a DocumentType which is not used with any Document yet.
Interface DocumentType
The DocumentType interface has three attributes: publicId, systemId and internalSubset.
Interface DOMImplementation
The DOMImplementation interface has two new methods: createDocumentType and createDocument.
Interface Element
The Element interface has eight new methods: getAttributeNS, setAttributeNS, removeAttributeNS, getAttributeNodeNS, setAttributeNodeNS, getElementsByTagNameNS, hasAttribute and hasAttributeNS.
The method normalize is now inherited from the Node interface where it was moved.
Exception DOMException
The DOMException has five new exception codes: INVALID_STATE_ERR, SYNTAX_ERR, INVALID_MODIFICATION_ERR, NAMESPACE_ERR and INVALID_ACCESS_ERR.

A.1.2: New features

A.1.2.1: New types

DOMTimeStamp
The DOMTimeStamp type was added to the Core module.
previous next contents index


Accessing code point boundaries

previous next contents index

13 November, 2000

Appendix B: Accessing code point boundaries

Mark Davis, IBM
Lauren Wood, SoftQuad Software Inc.

Table of contents

  • 2.1. Introduction
  • 2.2. Methods
    • StringExtend

B.1: Introduction

This appendix is an informative, not a normative, part of the Level 2 DOM specification.

Characters are represented in Unicode by numbers called code points (also called scalar values). These numbers can range from 0 up to 1,114,111 = 10FFFF16 (although some of these values are illegal). Each code point can be directly encoded with a 32-bit code unit. This encoding is termed UCS-4 (or UTF-32). The DOM specification, however, uses UTF-16, in which the most frequent characters (which have values less than FFFF16) are represented by a single 16-bit code unit, while characters above FFFF16 use a special pair of code units called a surrogate pair. For more information, see [Unicode] or the Unicode Web site.

While indexing by code points as opposed to code units is not common in programs, some specifications such as XPath (and therefore XSLT and XPointer) use code point indices. For interfacing with such formats it is recommended that the programming language provide string processing methods for converting code point indices to code unit indices and back. Some languages do not provide these functions natively; for these it is recommended that the native String type that is bound to DOMString be extended to enable this conversion. An example of how such an API might look is supplied below.

Note: Since these methods are supplied as an illustrative example of the type of functionality that is required, the names of the methods, exceptions, and interface may differ from those given here.

B.2: Methods

Interface StringExtend

Extensions to a language's native String class or interface

IDL Definition
interface StringExtend {
  int                findOffset16(in int offset32)
                                        raises(StringIndexOutOfBoundsException);
  int                findOffset32(in int offset16)
                                        raises(StringIndexOutOfBoundsException);
};

Methods
findOffset16
Returns the UTF-16 offset that corresponds to a UTF-32 offset. Used for random access.

Note: You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.

Parameters
offset32 of type int
UTF-32 offset.
Return Value

int

UTF-16 offset
Exceptions

StringIndexOutOfBoundsException

if offset32 is out of bounds.
findOffset32
Returns the UTF-32 offset corresponding to a UTF-16 offset. Used for random access. To find the UTF-32 length of a string, use:
len32 = findOffset32(source, source.length());

Note: If the UTF-16 offset is into the middle of a surrogate pair, then the UTF-32 offset of the end of the pair is returned; that is, the index of the char after the end of the pair. You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.

Parameters
offset16 of type int
UTF-16 offset
Return Value

int

UTF-32 offset
Exceptions

StringIndexOutOfBoundsException

if offset16 is out of bounds.
previous next contents index


IDL Definitions

previous next contents index

13 November, 2000

Appendix C: IDL Definitions

This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Core definitions.

The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/idl.zip

dom.idl:

// File: dom.idl

#ifndef _DOM_IDL_
#define _DOM_IDL_

#pragma prefix "w3c.org"
module dom
{

  valuetype DOMString sequence<unsigned short>;

  typedef   unsigned long long DOMTimeStamp;

  interface DocumentType;
  interface Document;
  interface NodeList;
  interface NamedNodeMap;
  interface Element;

  exception DOMException {
    unsigned short   code;
  };
  // ExceptionCode
  const unsigned short      INDEX_SIZE_ERR                 = 1;
  const unsigned short      DOMSTRING_SIZE_ERR             = 2;
  const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
  const unsigned short      WRONG_DOCUMENT_ERR             = 4;
  const unsigned short      INVALID_CHARACTER_ERR          = 5;
  const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
  const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
  const unsigned short      NOT_FOUND_ERR                  = 8;
  const unsigned short      NOT_SUPPORTED_ERR              = 9;
  const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_STATE_ERR              = 11;
  // Introduced in DOM Level 2:
  const unsigned short      SYNTAX_ERR                     = 12;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_MODIFICATION_ERR       = 13;
  // Introduced in DOM Level 2:
  const unsigned short      NAMESPACE_ERR                  = 14;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_ACCESS_ERR             = 15;

  interface DOMImplementation {
    boolean            hasFeature(in DOMString feature,
                                  in DOMString version);
    // Introduced in DOM Level 2:
    DocumentType       createDocumentType(in DOMString qualifiedName,
                                          in DOMString publicId,
                                          in DOMString systemId)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Document           createDocument(in DOMString namespaceURI,
                                      in DOMString qualifiedName,
                                      in DocumentType doctype)
                                        raises(DOMException);
  };

  interface Node {

    // NodeType
    const unsigned short      ELEMENT_NODE                   = 1;
    const unsigned short      ATTRIBUTE_NODE                 = 2;
    const unsigned short      TEXT_NODE                      = 3;
    const unsigned short      CDATA_SECTION_NODE             = 4;
    const unsigned short      ENTITY_REFERENCE_NODE          = 5;
    const unsigned short      ENTITY_NODE                    = 6;
    const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
    const unsigned short      COMMENT_NODE                   = 8;
    const unsigned short      DOCUMENT_NODE                  = 9;
    const unsigned short      DOCUMENT_TYPE_NODE             = 10;
    const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
    const unsigned short      NOTATION_NODE                  = 12;

    readonly attribute DOMString        nodeName;
             attribute DOMString        nodeValue;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

    readonly attribute unsigned short   nodeType;
    readonly attribute Node             parentNode;
    readonly attribute NodeList         childNodes;
    readonly attribute Node             firstChild;
    readonly attribute Node             lastChild;
    readonly attribute Node             previousSibling;
    readonly attribute Node             nextSibling;
    readonly attribute NamedNodeMap     attributes;
    // Modified in DOM Level 2:
    readonly attribute Document         ownerDocument;
    Node               insertBefore(in Node newChild,
                                    in Node refChild)
                                        raises(DOMException);
    Node               replaceChild(in Node newChild,
                                    in Node oldChild)
                                        raises(DOMException);
    Node               removeChild(in Node oldChild)
                                        raises(DOMException);
    Node               appendChild(in Node newChild)
                                        raises(DOMException);
    boolean            hasChildNodes();
    Node               cloneNode(in boolean deep);
    // Modified in DOM Level 2:
    void               normalize();
    // Introduced in DOM Level 2:
    boolean            isSupported(in DOMString feature,
                                   in DOMString version);
    // Introduced in DOM Level 2:
    readonly attribute DOMString        namespaceURI;
    // Introduced in DOM Level 2:
             attribute DOMString        prefix;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 2:
    readonly attribute DOMString        localName;
    // Introduced in DOM Level 2:
    boolean            hasAttributes();
  };

  interface NodeList {
    Node               item(in unsigned long index);
    readonly attribute unsigned long    length;
  };

  interface NamedNodeMap {
    Node               getNamedItem(in DOMString name);
    Node               setNamedItem(in Node arg)
                                        raises(DOMException);
    Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
    Node               item(in unsigned long index);
    readonly attribute unsigned long    length;
    // Introduced in DOM Level 2:
    Node               getNamedItemNS(in DOMString namespaceURI,
                                      in DOMString localName);
    // Introduced in DOM Level 2:
    Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Node               removeNamedItemNS(in DOMString namespaceURI,
                                         in DOMString localName)
                                        raises(DOMException);
  };

  interface CharacterData : Node {
             attribute DOMString        data;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

    readonly attribute unsigned long    length;
    DOMString          substringData(in unsigned long offset,
                                     in unsigned long count)
                                        raises(DOMException);
    void               appendData(in DOMString arg)
                                        raises(DOMException);
    void               insertData(in unsigned long offset,
                                  in DOMString arg)
                                        raises(DOMException);
    void               deleteData(in unsigned long offset,
                                  in unsigned long count)
                                        raises(DOMException);
    void               replaceData(in unsigned long offset,
                                   in unsigned long count,
                                   in DOMString arg)
                                        raises(DOMException);
  };

  interface Attr : Node {
    readonly attribute DOMString        name;
    readonly attribute boolean          specified;
             attribute DOMString        value;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 2:
    readonly attribute Element          ownerElement;
  };

  interface Element : Node {
    readonly attribute DOMString        tagName;
    DOMString          getAttribute(in DOMString name);
    void               setAttribute(in DOMString name,
                                    in DOMString value)
                                        raises(DOMException);
    void               removeAttribute(in DOMString name)
                                        raises(DOMException);
    Attr               getAttributeNode(in DOMString name);
    Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
    Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
    NodeList           getElementsByTagName(in DOMString name);
    // Introduced in DOM Level 2:
    DOMString          getAttributeNS(in DOMString namespaceURI,
                                      in DOMString localName);
    // Introduced in DOM Level 2:
    void               setAttributeNS(in DOMString namespaceURI,
                                      in DOMString qualifiedName,
                                      in DOMString value)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    void               removeAttributeNS(in DOMString namespaceURI,
                                         in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Attr               getAttributeNodeNS(in DOMString namespaceURI,
                                          in DOMString localName);
    // Introduced in DOM Level 2:
    Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                              in DOMString localName);
    // Introduced in DOM Level 2:
    boolean            hasAttribute(in DOMString name);
    // Introduced in DOM Level 2:
    boolean            hasAttributeNS(in DOMString namespaceURI,
                                      in DOMString localName);
  };

  interface Text : CharacterData {
    Text               splitText(in unsigned long offset)
                                        raises(DOMException);
  };

  interface Comment : CharacterData {
  };

  interface CDATASection : Text {
  };

  interface DocumentType : Node {
    readonly attribute DOMString        name;
    readonly attribute NamedNodeMap     entities;
    readonly attribute NamedNodeMap     notations;
    // Introduced in DOM Level 2:
    readonly attribute DOMString        publicId;
    // Introduced in DOM Level 2:
    readonly attribute DOMString        systemId;
    // Introduced in DOM Level 2:
    readonly attribute DOMString        internalSubset;
  };

  interface Notation : Node {
    readonly attribute DOMString        publicId;
    readonly attribute DOMString        systemId;
  };

  interface Entity : Node {
    readonly attribute DOMString        publicId;
    readonly attribute DOMString        systemId;
    readonly attribute DOMString        notationName;
  };

  interface EntityReference : Node {
  };

  interface ProcessingInstruction : Node {
    readonly attribute DOMString        target;
             attribute DOMString        data;
                                        // raises(DOMException) on setting

  };

  interface DocumentFragment : Node {
  };

  interface Document : Node {
    readonly attribute DocumentType     doctype;
    readonly attribute DOMImplementation  implementation;
    readonly attribute Element          documentElement;
    Element            createElement(in DOMString tagName)
                                        raises(DOMException);
    DocumentFragment   createDocumentFragment();
    Text               createTextNode(in DOMString data);
    Comment            createComment(in DOMString data);
    CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
    ProcessingInstruction createProcessingInstruction(in DOMString target,
                                                      in DOMString data)
                                        raises(DOMException);
    Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
    EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
    NodeList           getElementsByTagName(in DOMString tagname);
    // Introduced in DOM Level 2:
    Node               importNode(in Node importedNode,
                                  in boolean deep)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Element            createElementNS(in DOMString namespaceURI,
                                       in DOMString qualifiedName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Attr               createAttributeNS(in DOMString namespaceURI,
                                         in DOMString qualifiedName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                              in DOMString localName);
    // Introduced in DOM Level 2:
    Element            getElementById(in DOMString elementId);
  };
};

#endif // _DOM_IDL_
previous next contents index


Java Language Binding

previous next contents index

13 November, 2000

Appendix D: Java Language Binding

This appendix contains the complete Java Language [Java] binding for the Level 2 Document Object Model Core.

The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/java-binding.zip

org/w3c/dom/DOMException.java:

package org.w3c.dom;

public class DOMException extends RuntimeException {
    public DOMException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // ExceptionCode
    public static final short INDEX_SIZE_ERR            = 1;
    public static final short DOMSTRING_SIZE_ERR        = 2;
    public static final short HIERARCHY_REQUEST_ERR     = 3;
    public static final short WRONG_DOCUMENT_ERR        = 4;
    public static final short INVALID_CHARACTER_ERR     = 5;
    public static final short NO_DATA_ALLOWED_ERR       = 6;
    public static final short NO_MODIFICATION_ALLOWED_ERR = 7;
    public static final short NOT_FOUND_ERR             = 8;
    public static final short NOT_SUPPORTED_ERR         = 9;
    public static final short INUSE_ATTRIBUTE_ERR       = 10;
    public static final short INVALID_STATE_ERR         = 11;
    public static final short SYNTAX_ERR                = 12;
    public static final short INVALID_MODIFICATION_ERR  = 13;
    public static final short NAMESPACE_ERR             = 14;
    public static final short INVALID_ACCESS_ERR        = 15;

}

org/w3c/dom/DOMImplementation.java:

package org.w3c.dom;

public interface DOMImplementation {
    public boolean hasFeature(String feature,
                              String version);

    public DocumentType createDocumentType(String qualifiedName,
                                           String publicId,
                                           String systemId)
                                           throws DOMException;

    public Document createDocument(String namespaceURI,
                                   String qualifiedName,
                                   DocumentType doctype)
                                   throws DOMException;

}

org/w3c/dom/DocumentFragment.java:

package org.w3c.dom;

public interface DocumentFragment extends Node {
}

org/w3c/dom/Document.java:

package org.w3c.dom;

public interface Document extends Node {
    public DocumentType getDoctype();

    public DOMImplementation getImplementation();

    public Element getDocumentElement();

    public Element createElement(String tagName)
                                 throws DOMException;

    public DocumentFragment createDocumentFragment();

    public Text createTextNode(String data);

    public Comment createComment(String data);

    public CDATASection createCDATASection(String data)
                                           throws DOMException;

    public ProcessingInstruction createProcessingInstruction(String target,
                                                             String data)
                                                             throws DOMException;

    public Attr createAttribute(String name)
                                throws DOMException;

    public EntityReference createEntityReference(String name)
                                                 throws DOMException;

    public NodeList getElementsByTagName(String tagname);

    public Node importNode(Node importedNode,
                           boolean deep)
                           throws DOMException;

    public Element createElementNS(String namespaceURI,
                                   String qualifiedName)
                                   throws DOMException;

    public Attr createAttributeNS(String namespaceURI,
                                  String qualifiedName)
                                  throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI,
                                           String localName);

    public Element getElementById(String elementId);

}

org/w3c/dom/Node.java:

package org.w3c.dom;

public interface Node {
    // NodeType
    public static final short ELEMENT_NODE              = 1;
    public static final short ATTRIBUTE_NODE            = 2;
    public static final short TEXT_NODE                 = 3;
    public static final short CDATA_SECTION_NODE        = 4;
    public static final short ENTITY_REFERENCE_NODE     = 5;
    public static final short ENTITY_NODE               = 6;
    public static final short PROCESSING_INSTRUCTION_NODE = 7;
    public static final short COMMENT_NODE              = 8;
    public static final short DOCUMENT_NODE             = 9;
    public static final short DOCUMENT_TYPE_NODE        = 10;
    public static final short DOCUMENT_FRAGMENT_NODE    = 11;
    public static final short NOTATION_NODE             = 12;

    public String getNodeName();

    public String getNodeValue()
                                  throws DOMException;
    public void setNodeValue(String nodeValue)
                                  throws DOMException;

    public short getNodeType();

    public Node getParentNode();

    public NodeList getChildNodes();

    public Node getFirstChild();

    public Node getLastChild();

    public Node getPreviousSibling();

    public Node getNextSibling();

    public NamedNodeMap getAttributes();

    public Document getOwnerDocument();

    public Node insertBefore(Node newChild,
                             Node refChild)
                             throws DOMException;

    public Node replaceChild(Node newChild,
                             Node oldChild)
                             throws DOMException;

    public Node removeChild(Node oldChild)
                            throws DOMException;

    public Node appendChild(Node newChild)
                            throws DOMException;

    public boolean hasChildNodes();

    public Node cloneNode(boolean deep);

    public void normalize();

    public boolean isSupported(String feature,
                               String version);

    public String getNamespaceURI();

    public String getPrefix();
    public void setPrefix(String prefix)
                               throws DOMException;

    public String getLocalName();

    public boolean hasAttributes();

}

org/w3c/dom/NodeList.java:

package org.w3c.dom;

public interface NodeList {
    public Node item(int index);

    public int getLength();

}

org/w3c/dom/NamedNodeMap.java:

package org.w3c.dom;

public interface NamedNodeMap {
    public Node getNamedItem(String name);

    public Node setNamedItem(Node arg)
                             throws DOMException;

    public Node removeNamedItem(String name)
                                throws DOMException;

    public Node item(int index);

    public int getLength();

    public Node getNamedItemNS(String namespaceURI,
                               String localName);

    public Node setNamedItemNS(Node arg)
                               throws DOMException;

    public Node removeNamedItemNS(String namespaceURI,
                                  String localName)
                                  throws DOMException;

}

org/w3c/dom/CharacterData.java:

package org.w3c.dom;

public interface CharacterData extends Node {
    public String getData()
                                  throws DOMException;
    public void setData(String data)
                                  throws DOMException;

    public int getLength();

    public String substringData(int offset,
                                int count)
                                throws DOMException;

    public void appendData(String arg)
                           throws DOMException;

    public void insertData(int offset,
                           String arg)
                           throws DOMException;

    public void deleteData(int offset,
                           int count)
                           throws DOMException;

    public void replaceData(int offset,
                            int count,
                            String arg)
                            throws DOMException;

}

org/w3c/dom/Attr.java:

package org.w3c.dom;

public interface Attr extends Node {
    public String getName();

    public boolean getSpecified();

    public String getValue();
    public void setValue(String value)
                            throws DOMException;

    public Element getOwnerElement();

}

org/w3c/dom/Element.java:

package org.w3c.dom;

public interface Element extends Node {
    public String getTagName();

    public String getAttribute(String name);

    public void setAttribute(String name,
                             String value)
                             throws DOMException;

    public void removeAttribute(String name)
                                throws DOMException;

    public Attr getAttributeNode(String name);

    public Attr setAttributeNode(Attr newAttr)
                                 throws DOMException;

    public Attr removeAttributeNode(Attr oldAttr)
                                    throws DOMException;

    public NodeList getElementsByTagName(String name);

    public String getAttributeNS(String namespaceURI,
                                 String localName);

    public void setAttributeNS(String namespaceURI,
                               String qualifiedName,
                               String value)
                               throws DOMException;

    public void removeAttributeNS(String namespaceURI,
                                  String localName)
                                  throws DOMException;

    public Attr getAttributeNodeNS(String namespaceURI,
                                   String localName);

    public Attr setAttributeNodeNS(Attr newAttr)
                                   throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI,
                                           String localName);

    public boolean hasAttribute(String name);

    public boolean hasAttributeNS(String namespaceURI,
                                  String localName);

}

org/w3c/dom/Text.java:

package org.w3c.dom;

public interface Text extends CharacterData {
    public Text splitText(int offset)
                          throws DOMException;

}

org/w3c/dom/Comment.java:

package org.w3c.dom;

public interface Comment extends CharacterData {
}

org/w3c/dom/CDATASection.java:

package org.w3c.dom;

public interface CDATASection extends Text {
}

org/w3c/dom/DocumentType.java:

package org.w3c.dom;

public interface DocumentType extends Node {
    public String getName();

    public NamedNodeMap getEntities();

    public NamedNodeMap getNotations();

    public String getPublicId();

    public String getSystemId();

    public String getInternalSubset();

}

org/w3c/dom/Notation.java:

package org.w3c.dom;

public interface Notation extends Node {
    public String getPublicId();

    public String getSystemId();

}

org/w3c/dom/Entity.java:

package org.w3c.dom;

public interface Entity extends Node {
    public String getPublicId();

    public String getSystemId();

    public String getNotationName();

}

org/w3c/dom/EntityReference.java:

package org.w3c.dom;

public interface EntityReference extends Node {
}

org/w3c/dom/ProcessingInstruction.java:

package org.w3c.dom;

public interface ProcessingInstruction extends Node {
    public String getTarget();

    public String getData();
    public void setData(String data)
                          throws DOMException;

}
previous next contents index


ECMAScript Language Binding

previous next contents index

13 November, 2000

Appendix E: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Core definitions.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

Prototype Object DOMException
The DOMException class has the following constants:
DOMException.INDEX_SIZE_ERR
This constant is of type Number and its value is 1.
DOMException.DOMSTRING_SIZE_ERR
This constant is of type Number and its value is 2.
DOMException.HIERARCHY_REQUEST_ERR
This constant is of type Number and its value is 3.
DOMException.WRONG_DOCUMENT_ERR
This constant is of type Number and its value is 4.
DOMException.INVALID_CHARACTER_ERR
This constant is of type Number and its value is 5.
DOMException.NO_DATA_ALLOWED_ERR
This constant is of type Number and its value is 6.
DOMException.NO_MODIFICATION_ALLOWED_ERR
This constant is of type Number and its value is 7.
DOMException.NOT_FOUND_ERR
This constant is of type Number and its value is 8.
DOMException.NOT_SUPPORTED_ERR
This constant is of type Number and its value is 9.
DOMException.INUSE_ATTRIBUTE_ERR
This constant is of type Number and its value is 10.
DOMException.INVALID_STATE_ERR
This constant is of type Number and its value is 11.
DOMException.SYNTAX_ERR
This constant is of type Number and its value is 12.
DOMException.INVALID_MODIFICATION_ERR
This constant is of type Number and its value is 13.
DOMException.NAMESPACE_ERR
This constant is of type Number and its value is 14.
DOMException.INVALID_ACCESS_ERR
This constant is of type Number and its value is 15.
Object DOMException
The DOMException object has the following properties:
code
This property is of type Number.
Object DOMImplementation
The DOMImplementation object has the following methods:
hasFeature(feature, version)
This method returns a Boolean.
The feature parameter is of type String.
The version parameter is of type String.
createDocumentType(qualifiedName, publicId, systemId)
This method returns a DocumentType object.
The qualifiedName parameter is of type String.
The publicId parameter is of type String.
The systemId parameter is of type String.
This method can raise a DOMException object.
createDocument(namespaceURI, qualifiedName, doctype)
This method returns a Document object.
The namespaceURI parameter is of type String.
The qualifiedName parameter is of type String.
The doctype parameter is a DocumentType object.
This method can raise a DOMException object.
Object DocumentFragment
DocumentFragment has the all the properties and methods of the Node object as well as the properties and methods defined below.
Object Document
Document has the all the properties and methods of the Node object as well as the properties and methods defined below.
The Document object has the following properties:
doctype
This read-only property is a DocumentType object.
implementation
This read-only property is a DOMImplementation object.
documentElement
This read-only property is a Element object.
The Document object has the following methods:
createElement(tagName)
This method returns a Element object.
The tagName parameter is of type String.
This method can raise a DOMException object.
createDocumentFragment()
This method returns a DocumentFragment object.
createTextNode(data)
This method returns a Text object.
The data parameter is of type String.
createComment(data)
This method returns a Comment object.
The data parameter is of type String.
createCDATASection(data)
This method returns a CDATASection object.
The data parameter is of type String.
This method can raise a DOMException object.
createProcessingInstruction(target, data)
This method returns a ProcessingInstruction object.
The target parameter is of type String.
The data parameter is of type String.
This method can raise a DOMException object.
createAttribute(name)
This method returns a Attr object.
The name parameter is of type String.
This method can raise a DOMException object.
createEntityReference(name)
This method returns a EntityReference object.
The name parameter is of type String.
This method can raise a DOMException object.
getElementsByTagName(tagname)
This method returns a NodeList object.
The tagname parameter is of type String.
importNode(importedNode, deep)
This method returns a Node object.
The importedNode parameter is a Node object.
The deep parameter is of type Boolean.
This method can raise a DOMException object.
createElementNS(namespaceURI, qualifiedName)
This method returns a Element object.
The namespaceURI parameter is of type String.
The qualifiedName parameter is of type String.
This method can raise a DOMException object.
createAttributeNS(namespaceURI, qualifiedName)
This method returns a Attr object.
The namespaceURI parameter is of type String.
The qualifiedName parameter is of type String.
This method can raise a DOMException object.
getElementsByTagNameNS(namespaceURI, localName)
This method returns a NodeList object.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
getElementById(elementId)
This method returns a Element object.
The elementId parameter is of type String.
Prototype Object Node
The Node class has the following constants:
Node.ELEMENT_NODE
This constant is of type Number and its value is 1.
Node.ATTRIBUTE_NODE
This constant is of type Number and its value is 2.
Node.TEXT_NODE
This constant is of type Number and its value is 3.
Node.CDATA_SECTION_NODE
This constant is of type Number and its value is 4.
Node.ENTITY_REFERENCE_NODE
This constant is of type Number and its value is 5.
Node.ENTITY_NODE
This constant is of type Number and its value is 6.
Node.PROCESSING_INSTRUCTION_NODE
This constant is of type Number and its value is 7.
Node.COMMENT_NODE
This constant is of type Number and its value is 8.
Node.DOCUMENT_NODE
This constant is of type Number and its value is 9.
Node.DOCUMENT_TYPE_NODE
This constant is of type Number and its value is 10.
Node.DOCUMENT_FRAGMENT_NODE
This constant is of type Number and its value is 11.
Node.NOTATION_NODE
This constant is of type Number and its value is 12.
Object Node
The Node object has the following properties:
nodeName
This read-only property is of type String.
nodeValue
This property is of type String, can raise a DOMException object on setting and can raise a DOMException object on retrieval.
nodeType
This read-only property is of type Number.
parentNode
This read-only property is a Node object.
childNodes
This read-only property is a NodeList object.
firstChild
This read-only property is a Node object.
lastChild
This read-only property is a Node object.
previousSibling
This read-only property is a Node object.
nextSibling
This read-only property is a Node object.
attributes
This read-only property is a NamedNodeMap object.
ownerDocument
This read-only property is a Document object.
namespaceURI
This read-only property is of type String.
prefix
This property is of type String and can raise a DOMException object on setting.
localName
This read-only property is of type String.
The Node object has the following methods:
insertBefore(newChild, refChild)
This method returns a Node object.
The newChild parameter is a Node object.
The refChild parameter is a Node object.
This method can raise a DOMException object.
replaceChild(newChild, oldChild)
This method returns a Node object.
The newChild parameter is a Node object.
The oldChild parameter is a Node object.
This method can raise a DOMException object.
removeChild(oldChild)
This method returns a Node object.
The oldChild parameter is a Node object.
This method can raise a DOMException object.
appendChild(newChild)
This method returns a Node object.
The newChild parameter is a Node object.
This method can raise a DOMException object.
hasChildNodes()
This method returns a Boolean.
cloneNode(deep)
This method returns a Node object.
The deep parameter is of type Boolean.
normalize()
This method has no return value.
isSupported(feature, version)
This method returns a Boolean.
The feature parameter is of type String.
The version parameter is of type String.
hasAttributes()
This method returns a Boolean.
Object NodeList
The NodeList object has the following properties:
length
This read-only property is of type Number.
The NodeList object has the following methods:
item(index)
This method returns a Node object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Object NamedNodeMap
The NamedNodeMap object has the following properties:
length
This read-only property is of type Number.
The NamedNodeMap object has the following methods:
getNamedItem(name)
This method returns a Node object.
The name parameter is of type String.
setNamedItem(arg)
This method returns a Node object.
The arg parameter is a Node object.
This method can raise a DOMException object.
removeNamedItem(name)
This method returns a Node object.
The name parameter is of type String.
This method can raise a DOMException object.
item(index)
This method returns a Node object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
getNamedItemNS(namespaceURI, localName)
This method returns a Node object.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
setNamedItemNS(arg)
This method returns a Node object.
The arg parameter is a Node object.
This method can raise a DOMException object.
removeNamedItemNS(namespaceURI, localName)
This method returns a Node object.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
This method can raise a DOMException object.
Object CharacterData
CharacterData has the all the properties and methods of the Node object as well as the properties and methods defined below.
The CharacterData object has the following properties:
data
This property is of type String, can raise a DOMException object on setting and can raise a DOMException object on retrieval.
length
This read-only property is of type Number.
The CharacterData object has the following methods:
substringData(offset, count)
This method returns a String.
The offset parameter is of type Number.
The count parameter is of type Number.
This method can raise a DOMException object.
appendData(arg)
This method has no return value.
The arg parameter is of type String.
This method can raise a DOMException object.
insertData(offset, arg)
This method has no return value.
The offset parameter is of type Number.
The arg parameter is of type String.
This method can raise a DOMException object.
deleteData(offset, count)
This method has no return value.
The offset parameter is of type Number.
The count parameter is of type Number.
This method can raise a DOMException object.
replaceData(offset, count, arg)
This method has no return value.
The offset parameter is of type Number.
The count parameter is of type Number.
The arg parameter is of type String.
This method can raise a DOMException object.
Object Attr
Attr has the all the properties and methods of the Node object as well as the properties and methods defined below.
The Attr object has the following properties:
name
This read-only property is of type String.
specified
This read-only property is of type Boolean.
value
This property is of type String and can raise a DOMException object on setting.
ownerElement
This read-only property is a Element object.
Object Element
Element has the all the properties and methods of the Node object as well as the properties and methods defined below.
The Element object has the following properties:
tagName
This read-only property is of type String.
The Element object has the following methods:
getAttribute(name)
This method returns a String.
The name parameter is of type String.
setAttribute(name, value)
This method has no return value.
The name parameter is of type String.
The value parameter is of type String.
This method can raise a DOMException object.
removeAttribute(name)
This method has no return value.
The name parameter is of type String.
This method can raise a DOMException object.
getAttributeNode(name)
This method returns a Attr object.
The name parameter is of type String.
setAttributeNode(newAttr)
This method returns a Attr object.
The newAttr parameter is a Attr object.
This method can raise a DOMException object.
removeAttributeNode(oldAttr)
This method returns a Attr object.
The oldAttr parameter is a Attr object.
This method can raise a DOMException object.
getElementsByTagName(name)
This method returns a NodeList object.
The name parameter is of type String.
getAttributeNS(namespaceURI, localName)
This method returns a String.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
setAttributeNS(namespaceURI, qualifiedName, value)
This method has no return value.
The namespaceURI parameter is of type String.
The qualifiedName parameter is of type String.
The value parameter is of type String.
This method can raise a DOMException object.
removeAttributeNS(namespaceURI, localName)
This method has no return value.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
This method can raise a DOMException object.
getAttributeNodeNS(namespaceURI, localName)
This method returns a Attr object.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
setAttributeNodeNS(newAttr)
This method returns a Attr object.
The newAttr parameter is a Attr object.
This method can raise a DOMException object.
getElementsByTagNameNS(namespaceURI, localName)
This method returns a NodeList object.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
hasAttribute(name)
This method returns a Boolean.
The name parameter is of type String.
hasAttributeNS(namespaceURI, localName)
This method returns a Boolean.
The namespaceURI parameter is of type String.
The localName parameter is of type String.
Object Text
Text has the all the properties and methods of the CharacterData object as well as the properties and methods defined below.
The Text object has the following methods:
splitText(offset)
This method returns a Text object.
The offset parameter is of type Number.
This method can raise a DOMException object.
Object Comment
Comment has the all the properties and methods of the CharacterData object as well as the properties and methods defined below.
Object CDATASection
CDATASection has the all the properties and methods of the Text object as well as the properties and methods defined below.
Object DocumentType
DocumentType has the all the properties and methods of the Node object as well as the properties and methods defined below.
The DocumentType object has the following properties:
name
This read-only property is of type String.
entities
This read-only property is a NamedNodeMap object.
notations
This read-only property is a NamedNodeMap object.
publicId
This read-only property is of type String.
systemId
This read-only property is of type String.
internalSubset
This read-only property is of type String.
Object Notation
Notation has the all the properties and methods of the Node object as well as the properties and methods defined below.
The Notation object has the following properties:
publicId
This read-only property is of type String.
systemId
This read-only property is of type String.
Object Entity
Entity has the all the properties and methods of the Node object as well as the properties and methods defined below.
The Entity object has the following properties:
publicId
This read-only property is of type String.
systemId
This read-only property is of type String.
notationName
This read-only property is of type String.
Object EntityReference
EntityReference has the all the properties and methods of the Node object as well as the properties and methods defined below.
Object ProcessingInstruction
ProcessingInstruction has the all the properties and methods of the Node object as well as the properties and methods defined below.
The ProcessingInstruction object has the following properties:
target
This read-only property is of type String.
data
This property is of type String and can raise a DOMException object on setting.
previous next contents index


Acknowledgements

previous next contents index

13 November, 2000

Appendix F: Acknowledgements

Many people contributed to this specification, including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Lauren Wood (SoftQuad Software Inc., chair), Andrew Watson (Object Management Group), Andy Heninger (IBM), Arnaud Le Hors (W3C and IBM), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Singer (IBM), Don Park (invited), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home and Netscape), Rich Rollman (Microsoft), Rick Gessner (Netscape), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tom Pixley (Netscape), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections.

F.1: Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMA Script bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

For DOM Level 2, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.

previous next contents index


Glossary

Editors
Arnaud Le Hors, IBM
Lauren Wood, SoftQuad Software Inc.
Robert S. Sutor, IBM (for DOM Level 1)

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

16-bit unit
The base unit of a DOMString. This indicates that indexing on a DOMString occurs in units of 16 bits. This must not be misunderstood to mean that a DOMString can store arbitrary 16-bit units. A DOMString is a character string encoded in UTF-16; this means that the restrictions of UTF-16 as well as the other relevant restrictions on character strings must be maintained. A single character, for example in the form of a numeric character reference, may correspond to one or two 16-bit units.
For more information, see [Unicode] and [ISO/IEC 10646].
ancestor
An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root."
API
An API is an application programming interface, a set of functions or methods used to access some functionality.
child
A child is an immediate descendant node of a node.
client application
A [client] application is any software that uses the Document Object Model programming interfaces provided by the hosting implementation to accomplish useful work. Some examples of client applications are scripts within an HTML or XML document.
COM
COM is Microsoft's Component Object Model [COM], a technology for building applications from binary software components.
convenience
A convenience method is an operation on an object that could be accomplished by a program consisting of more basic operations on the object. Convenience methods are usually provided to make the API easier and simpler to use or to allow specific programs to create more optimized implementations for common operations. A similar definition holds for a convenience property.
data model
A data model is a collection of descriptions of data structures and their contained fields, together with the operations or functions that manipulate them.
descendant
A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root."
ECMAScript
The programming language defined by the ECMA-262 standard [ECMAScript]. As stated in the standard, the originating technology for ECMAScript was JavaScript [JavaScript]. Note that in the ECMAScript Language binding, the word "property" is used in the same sense as the IDL term "attribute."
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. See Logical Structures in XML [XML].
information item
An information item is an abstract representation of some component of an XML document. See the [Infoset] for details.
hosting implementation
A [hosting] implementation is a software module that provides an implementation of the DOM interfaces so that a client application can use them. Some examples of hosting implementations are browsers, editors and document repositories.
HTML
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents with generic semantics that are appropriate for representing information from a wide range of applications. [HTML4.0]
inheritance
In object-oriented programming, the ability to create new classes (or interfaces) that contain all the methods and properties of another class (or interface), plus additional methods and properties. If class (or interface) D inherits from class (or interface) B, then D is said to be derived from B. B is said to be a base class (or interface) for D. Some programming languages allow for multiple inheritance, that is, inheritance from more than one class or interface.
interface
An interface is a declaration of a set of methods with no information given about their implementation. In object systems that support interfaces and inheritance, interfaces can usually inherit from one another.
language binding
A programming language binding for an IDL specification is an implementation of the interfaces in the specification for the given language. For example, a Java language binding for the Document Object Model IDL specification would implement the concrete Java classes that provide the functionality exposed by the interfaces.
local name
A local name is the local part of a qualified name. This is called the local part in Namespaces in XML [Namespaces].
method
A method is an operation or function that is associated with an object and is allowed to manipulate the object's data.
model
A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else.
namespace prefix
A namespace prefix is a string that associates an element or attribute name with a namespace URI in XML. See namespace prefix in Namespaces in XML [Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. Strictly speaking, this actually is a namespace URI reference. This is called the namespace name in Namespaces in XML [Namespaces].
object model
An object model is a collection of descriptions of classes or interfaces, together with their member data, member functions, and class-static operations.
parent
A parent is an immediate ancestor node of a node.
qualified name
A qualified name is the name of an element or attribute defined as the concatenation of a local name (as defined in this specification), optionally preceded by a namespace prefix and colon character. See Qualified Names in Namespaces in XML [Namespaces].
readonly node
A readonly node is a node that is immutable. This means its list of children, its content, and its attributes, when it is an element, cannot be changed in any way. However, a readonly node can possibly be moved, when it is not itself contained in a readonly node.
root node
The root node is the unique node that is not a child of any other node. All other nodes are children or other descendants of the root node.
sibling
Two nodes are siblings if and only if they have the same parent node.
string comparison
When string matching is required, it is to occur as though the comparison was between 2 sequences of code points from the Unicode 3.0 standard [Unicode].
token
An information item such as an XML Name which has been tokenized.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
well-formed document
A document is well-formed if it is tag valid and entities are limited to single elements (i.e., single sub-trees). See Well-Formed XML Documents in XML [XML].
XML
Extensible Markup Language (XML) is an extremely simple dialect of SGML. The goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML [XML] has been designed for ease of implementation and for interoperability with both SGML and HTML.
XML name
See XML name in the XML specification [XML].
XML namespace
An XML namespace is a collection of names, identified by a URI reference [RFC2396], which are used in XML documents as element types and attribute names. [Namespaces]
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

H.1: Normative references

Charmod
W3C (World Wide Web Consortium) Character Model for the World Wide Web, November 1999. Available at http://www.w3.org/TR/1999/WD-charmod-19991129
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
HTML4.0
W3C (World Wide Web Consortium) HTML 4.0 Specification, April 1998. Available at http://www.w3.org/TR/1998/REC-html40-19980424
ISO/IEC 10646
ISO (International Organization for Standardization). ISO/IEC 10646-1:2000 (E). Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization.
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
Namespaces
W3C (World Wide Web Consortium) Namespaces in XML, January 1999. Available at http://www.w3.org/TR/1999/REC-xml-names-19990114
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
RFC2396
IETF (Internet Engineering Task Force) RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, eds. T. Berners-Lee, R. Fielding, L. Masinter. August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt
Unicode
The Unicode Consortium. The Unicode Standard, Version 3.0., February 2000. Available at http://www.unicode.org/unicode/standard/versions/Unicode3.0.html.
XML
W3C (World Wide Web Consortium) Extensible Markup Language (XML) 1.0, February 1998. Available at http://www.w3.org/TR/1998/REC-xml-19980210

H.2: Informative references

DOM Level 2 CSS
W3C (World Wide Web Consortium) Document Object Model Level 2 CSS. Available at http://www.w3.org/TR/DOM-Level-2-Style/css
COM
Microsoft Corp. The Component Object Model. Available at http://www.microsoft.com/com
CORBA
OMG (Object Management Group) The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
DOM Level 1
W3C (World Wide Web Consortium) DOM Level 1 Specification, October 1998. Available at http://www.w3.org/TR/REC-DOM-Level-1
DOM Level 2 HTML
W3C (World Wide Web Consortium) Document Object Model Level 2 HTML Specification. Available at http://www.w3.org/TR/DOM-Level-2-HTML
DOM Level 2 Events
W3C (World Wide Web Consortium) Document Object Model Level 2 Events Specification. Available at http://www.w3.org/TR/DOM-Level-2-Events
Infoset
W3C (World Wide Web Consortium) XML Information Set, December 1999. Available at http://www.w3.org/TR/xml-infoset
JavaIDL
Sun Microsystems Inc. Java IDL. Available at http://java.sun.com/products/jdk/1.2/docs/guide/idl
JavaScript
Netscape Communications Corp. JavaScript Resources. Available at http://developer.netscape.com/tech/javascript/resources.html
JScript
Microsoft Corp. JScript Resources. Available at http://msdn.microsoft.com/scripting/default.htm
MIDL
Microsoft Corp. MIDL Language Reference. Available at http://msdn.microsoft.com/library/psdk/midl/mi-laref_1r1h.htm
DOM Level 2 Style Sheets
W3C (World Wide Web Consortium) Document Object Model Level 2 Style Sheets. Available at http://www.w3.org/TR/DOM-Level-2-Style/stylesheets
DOM Level 2 Traversal
W3C (World Wide Web Consortium) Document Object Model Level 2 Traversal. Available at http://www.w3.org/TR/DOM-Level-2-Traversal-Range/traversal
DOM Level 2 Range
W3C (World Wide Web Consortium) Document Object Model Level 2 Range. Available at http://www.w3.org/TR/DOM-Level-2-Traversal-Range/ranges
DOM Level 2 Views
W3C (World Wide Web Consortium) Document Object Model Level 2 Views Specification. Available at http://www.w3.org/TR/DOM-Level-2-Views
XPointer
W3C (World Wide Web Consortium) XML Pointer Language (XPointer), June 2000. Available at http://www.w3.org/TR/xptr
previous next contents index


Index

16-bit unit 1, 2, 3, 4, 5, 6, 7, 8, 9
ancestor 1, 2, 3, 4 | API 1, 2, 3, 4, 5, 6 | appendChild
appendData | Attr | ATTRIBUTE_NODE
attributes
CDATA_SECTION_NODE | CDATASection | CharacterData
Charmod 1, 2 | child 1, 2, 3 | childNodes
client application 1, 2 | cloneNode | COM 1, 2, 3, 4
Comment | COMMENT_NODE | convenience 1, 2, 3
CORBA 1, 2 | createAttribute | createAttributeNS
createCDATASection | createComment | createDocument
createDocumentFragment | createDocumentType | createElement
createElementNS | createEntityReference | createProcessingInstruction
createTextNode
data 1, 2 | data model 1, 2 | deleteData
descendant 1, 2, 3, 4, 5, 6, 7 | doctype | Document
DOCUMENT_FRAGMENT_NODE | DOCUMENT_NODE | DOCUMENT_TYPE_NODE
documentElement | DocumentFragment | DocumentType
DOM Level 1 1, 2 | DOM Level 2 CSS 1, 2 | DOM Level 2 Events 1, 2
DOM Level 2 HTML 1, 2, 3, 4 | DOM Level 2 Range 1, 2 | DOM Level 2 Style Sheets 1, 2
DOM Level 2 Traversal 1, 2 | DOM Level 2 Views 1, 2 | DOMException
DOMImplementation | DOMString | DOMSTRING_SIZE_ERR
DOMTimeStamp
ECMAScript 1, 2, 3, 4 | Element 1, 2, 3, 4, 5, 6 | ELEMENT_NODE
entities | Entity | ENTITY_NODE
ENTITY_REFERENCE_NODE | EntityReference
firstChild
getAttribute | getAttributeNode | getAttributeNodeNS
getAttributeNS | getElementById | getElementsByTagName 1, 2
getElementsByTagNameNS 1, 2 | getNamedItem | getNamedItemNS
hasAttribute | hasAttributeNS | hasAttributes
hasChildNodes | hasFeature | HIERARCHY_REQUEST_ERR
hosting implementation 1, 2 | HTML 1, 2 | HTML4.0 1, 2
implementation | importNode | INDEX_SIZE_ERR
information item 1, 2 | Infoset 1, 2, 3, 4 | inheritance 1, 2
insertBefore | insertData | interface 1, 2
internalSubset | INUSE_ATTRIBUTE_ERR | INVALID_ACCESS_ERR
INVALID_CHARACTER_ERR | INVALID_MODIFICATION_ERR | INVALID_STATE_ERR
ISO/IEC 10646 1, 2, 3 | isSupported | item 1, 2
Java 1, 2 | JavaIDL 1, 2 | JavaScript 1, 2, 3
JScript 1, 2
language binding 1, 2 | lastChild | length 1, 2, 3
live 1, 2, 3 | local name 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 | localName
method 1, 2 | MIDL 1, 2 | model 1, 2
name 1, 2 | NamedNodeMap | namespace prefix 1, 2, 3, 4, 5, 6
namespace URI 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17 | NAMESPACE_ERR | Namespaces 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11
namespaceURI | nextSibling | NO_DATA_ALLOWED_ERR
NO_MODIFICATION_ALLOWED_ERR | Node | NodeList
nodeName | nodeType | nodeValue
normalize | NOT_FOUND_ERR | NOT_SUPPORTED_ERR
Notation | NOTATION_NODE | notationName
notations
object model 1, 2, 3 | OMGIDL 1, 2, 3 | ownerDocument
ownerElement
parent 1, 2 | parentNode | prefix
previousSibling | PROCESSING_INSTRUCTION_NODE | ProcessingInstruction
publicId 1, 2, 3
qualified name 1, 2, 3, 4, 5, 6, 7, 8, 9
readonly node 1, 2, 3, 4, 5 | removeAttribute | removeAttributeNode
removeAttributeNS | removeChild | removeNamedItem
removeNamedItemNS | replaceChild | replaceData
RFC2396 1, 2 | root node 1, 2
setAttribute | setAttributeNode | setAttributeNodeNS
setAttributeNS | setNamedItem | setNamedItemNS
sibling 1, 2, 3 | specified | splitText
string comparison 1, 2, 3 | substringData | SYNTAX_ERR
systemId 1, 2, 3
tagName | target | Text
TEXT_NODE | token 1, 2 | tokenized 1, 2
Unicode 1, 2, 3, 4
value
well-formed document 1, 2 | WRONG_DOCUMENT_ERR
XML 1, 2, 3, 4, 5, 6, 7 | XML name 1, 2 | XML namespace 1, 2
XPointer 1, 2
previous contents


Document Object Model (DOM) Level 2 Views Specification

Version 1.0

W3C Recommendation 13 November, 2000

This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113
( PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Views
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Views-20000927
Editors:
Arnaud Le Hors, W3C team contact until October 1999, then IBM
Laurence Cable, Sun Microsystems

Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Level 2 Views, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content of a representation of a document. The Document Object Model Level 2 Views builds on the Document Object Model Level 2 Core [DOM Level 2 Core].

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members. Different modules of the Document Object Model have different editors.

Please send general comments about this document to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • 1. Document Object Model Views
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • References
  • Index
next contents index


Document Object Model Views

previous next contents index

13 November, 2000

1. Document Object Model Views

Editors
Arnaud Le Hors, IBM
Laurence Cable, Sun Microsystems

Table of contents

  • 1.1. Introduction
  • 1.2. Interfaces
    • AbstractView, DocumentView

1.1. Introduction

A document may have one or more "views" associated with it, e.g., a computed view on a document after applying a CSS stylesheet, or multiple presentations (e.g., HTML Frame) of the same document in a client. That is, a view is some alternate representation of, or a presentation of, and associated with, a source document.

A view may be static, reflecting the state of the document when the view was created, or dynamic, reflecting changes in the target document as they occur, subsequent to the view being created. This Level of the DOM specification makes no statement about these behaviors.

This section defines an AbstractView interface which provides a base interface from which all such views shall derive. It defines an attribute which references the target document of the AbstractView. The only semantics of the AbstractView defined here create an association between a view and its target document.

There are no subinterfaces of AbstractView defined in the DOM Level 2.

However, AbstractView is defined in and used in this Level in two places:

  • A Document may implement a DocumentView that has a default view attribute associated with it. This default view is typically dependent on the implementation (e.g., the browser frame rendering the document). The default view can be used in order to identify and/or associate a view with its target document (by testing object equality on the AbstractView or obtaining the DocumentView attribute).
  • A UIEvent typically occurs upon a view of a Document (e.g., a mouse click on a browser frame rendering a particular Document instance). A UIEvent has an AbstractView associated with it which identifies both the particular (implementation-dependent) view in which the event occurs, and the target document the UIEvent is related to.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Views" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined defined in the Document Object Model Level 2 Core specification [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification.

1.2. Interfaces

Interface AbstractView (introduced in DOM Level 2)

A base interface that all views shall derive from.

IDL Definition
// Introduced in DOM Level 2:
interface AbstractView {
  readonly attribute DocumentView     document;
};

Attributes
document of type DocumentView, readonly
The source DocumentView of which this is an AbstractView.
Interface DocumentView (introduced in DOM Level 2)

The DocumentView interface is implemented by Document objects in DOM implementations supporting DOM Views. It provides an attribute to retrieve the default view of a document.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentView {
  readonly attribute AbstractView     defaultView;
};

Attributes
defaultView of type AbstractView, readonly
The default AbstractView for this Document, or null if none available.
previous next contents index


IDL Definitions

previous next contents index

13 November, 2000

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Views definitions.

The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113/idl.zip

views.idl:

// File: views.idl

#ifndef _VIEWS_IDL_
#define _VIEWS_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module views
{

  interface DocumentView;

  // Introduced in DOM Level 2:
  interface AbstractView {
    readonly attribute DocumentView     document;
  };

  // Introduced in DOM Level 2:
  interface DocumentView {
    readonly attribute AbstractView     defaultView;
  };
};

#endif // _VIEWS_IDL_
previous next contents index


Java Language Binding

previous next contents index

13 November, 2000

Appendix B: Java Language Binding

This appendix contains the complete Java Language [Java] binding for the Level 2 Document Object Model Views.

The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113/java-binding.zip

org/w3c/dom/views/AbstractView.java:

package org.w3c.dom.views;

public interface AbstractView {
    public DocumentView getDocument();

}

org/w3c/dom/views/DocumentView.java:

package org.w3c.dom.views;

public interface DocumentView {
    public AbstractView getDefaultView();

}
previous next contents index


ECMAScript Language Binding

previous next contents index

13 November, 2000

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Views definitions.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

Object AbstractView
The AbstractView object has the following properties:
document
This read-only property is a DocumentView object.
Object DocumentView
The DocumentView object has the following properties:
defaultView
This read-only property is a AbstractView object.
previous next contents index


Acknowledgements

previous next contents index

13 November, 2000

Appendix D: Acknowledgements

Many people contributed to this specification, including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Lauren Wood (SoftQuad Software Inc., chair), Andrew Watson (Object Management Group), Andy Heninger (IBM), Arnaud Le Hors (W3C and IBM), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Singer (IBM), Don Park (invited), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home and Netscape), Rich Rollman (Microsoft), Rick Gessner (Netscape), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tom Pixley (Netscape), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections.

D.1: Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMA Script bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

For DOM Level 2, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.

previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

E.1: Normative references

DOM Level 2 Core
W3C (World Wide Web Consortium) Document Object Model Level 2 Core Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
previous next contents index


Index

AbstractView
defaultView document DocumentView
DOM Level 2 Core 1, 2
ECMAScript
Java
OMGIDL
previous contents


Document Object Model (DOM) Level 2 Events Specification

Version 1.0

W3C Recommendation 13 November, 2000

This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113
( PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Events
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Events-20000927
Editors:
Tom Pixley, Netscape Communications Corp.

Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Level 2 Events, a platform- and language-neutral interface that gives to programs and scripts a generic event system. The Document Object Model Level 2 Events builds on the Document Object Model Level 2 Core [DOM Level 2 Core] and on Document Object Model Level 2 Views [DOM Level 2 Views].

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members. Different modules of the Document Object Model have different editors.

Please send general comments about this document to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • 1. Document Object Model Events
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • Glossary
  • References
  • Index
next contents index


Document Object Model Events

previous next contents index

13 November, 2000

1. Document Object Model Events

Editors
Tom Pixley, Netscape Communications Corp.

Table of contents

  • 1.1. Overview of the DOM Level 2 Event Model
    • 1.1.1. Terminology
  • 1.2. Description of event flow
    • 1.2.1. Basic event flow
    • 1.2.2. Event capture
    • 1.2.3. Event bubbling
    • 1.2.4. Event cancelation
  • 1.3. Event listener registration
    • 1.3.1. Event registration interfaces
      • EventTarget, EventListener
    • 1.3.2. Interaction with HTML 4.0 event listeners
  • 1.4. Event interface
    • Event, EventException, EventExceptionCode
  • 1.5. DocumentEvent interface
    • DocumentEvent
  • 1.6. Event module definitions
    • 1.6.1. User Interface event types
      • UIEvent
    • 1.6.2. Mouse event types
      • MouseEvent
    • 1.6.3. Key events
    • 1.6.4. Mutation event types
      • MutationEvent
    • 1.6.5. HTML event types

1.1. Overview of the DOM Level 2 Event Model

The DOM Level 2 Event Model is designed with two main goals. The first goal is the design of a generic event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.

The second goal of the event model is to provide a common subset of the current event systems used in DOM Level 0 browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.

The following sections of the Event Model specification define both the specification for the DOM Event Model and a number of conformant event modules designed for use within the model. The Event Model consists of the two sections on event propagation and event listener registration and the Event interface.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Events" and "2.0" (respectively) to determine whether or not the event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined in the DOM Level 2 Core specification [DOM Level 2 Core]. Please, refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Each event module describes its own feature string in the event module listing.

1.1.1. Terminology

UI events
User interface events. These events are generated by user interaction through an external device (mouse, keyboard, etc.)
UI Logical events
Device independent user interface events such as focus change messages or element triggering notifications.
Mutation events
Events caused by any action which modifies the structure of the document.
Capturing
The process by which an event can be handled by one of the event's target's ancestors before being handled by the event's target.
Bubbling
The process by which an event propagates upward through its ancestors after being handled by the event's target.
Cancelable
A designation for events which indicates that upon handling the event the client may choose to prevent the DOM implementation from processing any default action associated with the event.

1.2. Description of event flow

Event flow is the process through which the an event originates from the DOM implementation and is passed into the Document Object Model. The methods of event capture and event bubbling, along with various event listener registration techniques, allow the event to then be handled in a number of ways. It can be handled locally at the EventTarget level or centrally from an EventTarget higher in the document tree.

1.2.1. Basic event flow

Each event has an EventTarget toward which the event is directed by the DOM implementation. This EventTarget is specified in the Event's target attribute. When the event reaches the target, any event listeners registered on the EventTarget are triggered. Although all EventListeners on the EventTarget are guaranteed to be triggered by any event which is received by that EventTarget, no specification is made as to the order in which they will receive the event with regards to the other EventListeners on the EventTarget. If neither event capture or event bubbling are in use for that particular event, the event flow process will complete after all listeners have been triggered. If event capture or event bubbling is in use, the event flow will be modified as described in the sections below.

Any exceptions thrown inside an EventListener will not stop propagation of the event. It will continue processing any additional EventListener in the described manner.

It is expected that actions taken by EventListeners may cause additional events to fire. Additional events should be handled in a synchronous manner and may cause reentrancy into the event model.

1.2.2. Event capture

Event capture is the process by which an EventListener registered on an ancestor of the event's target can intercept events of a given type before they are received by the event's target. Capture operates from the top of the tree, generally the Document, downward, making it the symmetrical opposite of bubbling which is described below. The chain of EventTargets from the top of the tree to the event's target is determined before the initial dispatch of the event. If modifications occur to the tree during event processing, event flow will proceed based on the initial state of the tree.

An EventListener being registered on an EventTarget may choose to have that EventListener capture events by specifying the useCapture parameter of the addEventListener method to be true. Thereafter, when an event of the given type is dispatched toward a descendant of the capturing object, the event will trigger any capturing event listeners of the appropriate type which exist in the direct line between the top of the document and the event's target. This downward propagation continues until the event's target is reached. A capturing EventListener will not be triggered by events dispatched directly to the EventTarget upon which it is registered.

If the capturing EventListener wishes to prevent further processing of the event from occurring it may call the stopProgagation method of the Event interface. This will prevent further dispatch of the event, although additional EventListeners registered at the same hierarchy level will still receive the event. Once an event's stopPropagation method has been called, further calls to that method have no additional effect. If no additional capturers exist and stopPropagation has not been called, the event triggers the appropriate EventListeners on the target itself.

Although event capture is similar to the delegation based event model in which all interested parties register their listeners directly on the target about which they wish to receive notifications, it is different in two important respects. First, event capture only allows interception of events which are targeted at descendants of the capturing EventTarget. It does not allow interception of events targeted to the capturer's ancestors, its siblings, or its sibling's descendants. Secondly, event capture is not specified for a single EventTarget, it is specified for a specific type of event. Once specified, event capture intercepts all events of the specified type targeted toward any of the capturer's descendants.

1.2.3. Event bubbling

Events which are designated as bubbling will initially proceed with the same event flow as non-bubbling events. The event is dispatched to its target EventTarget and any event listeners found there are triggered. Bubbling events will then trigger any additional event listeners found by following the EventTarget's parent chain upward, checking for any event listeners registered on each successive EventTarget. This upward propagation will continue up to and including the Document. EventListeners registered as capturers will not be triggered during this phase. The chain of EventTargets from the event target to the top of the tree is determined before the initial dispatch of the event. If modifications occur to the tree during event processing, event flow will proceed based on the initial state of the tree.

Any event handler may choose to prevent further event propagation by calling the stopPropagation method of the Event interface. If any EventListener calls this method, all additional EventListeners on the current EventTarget will be triggered but bubbling will cease at that level. Only one call to stopPropagation is required to prevent further bubbling.

1.2.4. Event cancelation

Some events are specified as cancelable. For these events, the DOM implementation generally has a default action associated with the event. An example of this is a hyperlink in a web browser. When the user clicks on the hyperlink the default action is generally to active that hyperlink. Before processing these events, the implementation must check for event listeners registered to receive the event and dispatch the event to those listeners. These listeners then have the option of canceling the implementation's default action or allowing the default action to proceed. In the case of the hyperlink in the browser, canceling the action would have the result of not activating the hyperlink.

Cancelation is accomplished by calling the Event's preventDefault method. If one or more EventListeners call preventDefault during any phase of event flow the default action will be canceled.

Different implementations will specify their own default actions, if any, associated with each event. The DOM does not attempt to specify these actions.

1.3. Event listener registration

1.3.1. Event registration interfaces

Interface EventTarget (introduced in DOM Level 2)

The EventTarget interface is implemented by all Nodes in an implementation which supports the DOM Event Model. Therefore, this interface can be obtained by using binding-specific casting methods on an instance of the Node interface. The interface allows registration and removal of EventListeners on an EventTarget and dispatch of events to that EventTarget.

IDL Definition
// Introduced in DOM Level 2:
interface EventTarget {
  void               addEventListener(in DOMString type,
                                      in EventListener listener,
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type,
                                         in EventListener listener,
                                         in boolean useCapture);
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
};

Methods
addEventListener
This method allows the registration of event listeners on the event target. If an EventListener is added to an EventTarget while it is processing an event, it will not be triggered by the current actions but may be triggered during a later stage of event flow, such as the bubbling phase.
If multiple identical EventListeners are registered on the same EventTarget with the same parameters the duplicate instances are discarded. They do not cause the EventListener to be called twice and since they are discarded they do not need to be removed with the removeEventListener method.
Parameters
type of type DOMString
The event type for which the user is registering
listener of type EventListener
The listener parameter takes an interface implemented by the user which contains the methods to be called when the event occurs.
useCapture of type boolean
If true, useCapture indicates that the user wishes to initiate capture. After initiating capture, all events of the specified type will be dispatched to the registered EventListener before being dispatched to any EventTargets beneath them in the tree. Events which are bubbling upward through the tree will not trigger an EventListener designated to use capture.
No Return Value
No Exceptions
dispatchEvent
This method allows the dispatch of events into the implementations event model. Events dispatched in this manner will have the same capturing and bubbling behavior as events dispatched directly by the implementation. The target of the event is the EventTarget on which dispatchEvent is called.
Parameters
evt of type Event
Specifies the event type, behavior, and contextual information to be used in processing the event.
Return Value

boolean

The return value of dispatchEvent indicates whether any of the listeners which handled the event called preventDefault. If preventDefault was called the value is false, else the value is true.
Exceptions

EventException

UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event's type was not specified by initializing the event before dispatchEvent was called. Specification of the Event's type as null or an empty string will also trigger this exception.
removeEventListener
This method allows the removal of event listeners from the event target. If an EventListener is removed from an EventTarget while it is processing an event, it will not be triggered by the current actions. EventListeners can never be invoked after being removed.
Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.
Parameters
type of type DOMString
Specifies the event type of the EventListener being removed.
listener of type EventListener
The EventListener parameter indicates the EventListener to be removed.
useCapture of type boolean
Specifies whether the EventListener being removed was registered as a capturing listener or not. If a listener was registered twice, one with capture and one without, each must be removed separately. Removal of a capturing listener does not affect a non-capturing version of the same listener, and vice versa.
No Return Value
No Exceptions
Interface EventListener (introduced in DOM Level 2)

The EventListener interface is the primary method for handling events. Users implement the EventListener interface and register their listener on an EventTarget using the AddEventListener method. The users should also remove their EventListener from its EventTarget after they have completed using the listener.

When a Node is copied using the cloneNode method the EventListeners attached to the source Node are not attached to the copied Node. If the user wishes the same EventListeners to be added to the newly created copy the user must add them manually.

IDL Definition
// Introduced in DOM Level 2:
interface EventListener {
  void               handleEvent(in Event evt);
};

Methods
handleEvent
This method is called whenever an event occurs of the type for which the EventListener interface was registered.
Parameters
evt of type Event
The Event contains contextual information about the event. It also contains the stopPropagation and preventDefault methods which are used in determining the event's flow and default action.
No Return Value
No Exceptions

1.3.2. Interaction with HTML 4.0 event listeners

In HTML 4.0, event listeners were specified as attributes of an element. As such, registration of a second event listener of the same type would replace the first listener. The DOM Event Model allows registration of multiple event listeners on a single EventTarget. To achieve this, event listeners are no longer stored as attribute values.

In order to achieve compatibility with HTML 4.0, implementors may view the setting of attributes which represent event handlers as the creation and registration of an EventListener on the EventTarget. The value of useCapture defaults to false. This EventListener behaves in the same manner as any other EventListeners which may be registered on the EventTarget. If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. No technique is provided to allow HTML 4.0 event listeners access to the context information defined for each event.

1.4. Event interface

Interface Event (introduced in DOM Level 2)

The Event interface is used to provide contextual information about an event to the handler processing the event. An object which implements the Event interface is generally passed as the first parameter to an event handler. More specific context information is passed to event handlers by deriving additional interfaces from Event which contain information directly relating to the type of event they accompany. These derived interfaces are also implemented by the object passed to the event listener.

IDL Definition
// Introduced in DOM Level 2:
interface Event {

  // PhaseType
  const unsigned short      CAPTURING_PHASE                = 1;
  const unsigned short      AT_TARGET                      = 2;
  const unsigned short      BUBBLING_PHASE                 = 3;

  readonly attribute DOMString        type;
  readonly attribute EventTarget      target;
  readonly attribute EventTarget      currentTarget;
  readonly attribute unsigned short   eventPhase;
  readonly attribute boolean          bubbles;
  readonly attribute boolean          cancelable;
  readonly attribute DOMTimeStamp     timeStamp;
  void               stopPropagation();
  void               preventDefault();
  void               initEvent(in DOMString eventTypeArg,
                               in boolean canBubbleArg,
                               in boolean cancelableArg);
};

Definition group PhaseType

An integer indicating which phase of event flow is being processed.

Defined Constants
AT_TARGET
The event is currently being evaluated at the target EventTarget.
BUBBLING_PHASE
The current event phase is the bubbling phase.
CAPTURING_PHASE
The current event phase is the capturing phase.
Attributes
bubbles of type boolean, readonly
Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, else the value is false.
cancelable of type boolean, readonly
Used to indicate whether or not an event can have its default action prevented. If the default action can be prevented the value is true, else the value is false.
currentTarget of type EventTarget, readonly
Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during capturing and bubbling.
eventPhase of type unsigned short, readonly
Used to indicate which phase of event flow is currently being evaluated.
target of type EventTarget, readonly
Used to indicate the EventTarget to which the event was originally dispatched.
timeStamp of type DOMTimeStamp, readonly
Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.
type of type DOMString, readonly
The name of the event (case-insensitive). The name must be an XML name.
Methods
initEvent
The initEvent method is used to initialize the value of an Event created through the DocumentEvent interface. This method may only be called before the Event has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times the final invocation takes precedence. If called from a subclass of Event interface only the values specified in the initEvent method are modified, all other attributes are left unchanged.
Parameters
eventTypeArg of type DOMString
Specifies the event type. This type may be any event type currently defined in this specification or a new event type.. The string must be an XML name.
Any new event type must not begin with any upper, lower, or mixed case version of the string "DOM". This prefix is reserved for future DOM event sets. It is also strongly recommended that third parties adding their own events use their own prefix to avoid confusion and lessen the probability of conflicts with other new events.
canBubbleArg of type boolean
Specifies whether or not the event can bubble.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented.
No Return Value
No Exceptions
preventDefault
If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur. If, during any stage of event flow, the preventDefault method is called the event is canceled. Any default action associated with the event will not occur. Calling this method for a non-cancelable event has no effect. Once preventDefault has been called it will remain in effect throughout the remainder of the event's propagation. This method may be used during any stage of event flow.
No Parameters
No Return Value
No Exceptions
stopPropagation
The stopPropagation method is used prevent further propagation of an event during event flow. If this method is called by any EventListener the event will cease propagating through the tree. The event will complete dispatch to all listeners on the current EventTarget before event flow stops. This method may be used during any stage of event flow.
No Parameters
No Return Value
No Exceptions
Exception EventException introduced in DOM Level 2

Event operations may throw an EventException as specified in their method descriptions.

IDL Definition
// Introduced in DOM Level 2:
exception EventException {
  unsigned short   code;
};
// EventExceptionCode
const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;

Definition group EventExceptionCode

An integer indicating the type of error generated.

Defined Constants
UNSPECIFIED_EVENT_TYPE_ERR
If the Event's type was not specified by initializing the event before the method was called. Specification of the Event's type as null or an empty string will also trigger this exception.

1.5. DocumentEvent interface

Interface DocumentEvent (introduced in DOM Level 2)

The DocumentEvent interface provides a mechanism by which the user can create an Event of a type supported by the implementation. It is expected that the DocumentEvent interface will be implemented on the same object which implements the Document interface in an implementation which supports the Event model.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentEvent {
  Event              createEvent(in DOMString eventType)
                                        raises(DOMException);
};

Methods
createEvent
Parameters
eventType of type DOMString
The eventType parameter specifies the type of Event interface to be created. If the Event interface specified is supported by the implementation this method will return a new Event of the interface type requested. If the Event is to be dispatched via the dispatchEvent method the appropriate event init method must be called after creation in order to initialize the Event's values. As an example, a user wishing to synthesize some kind of UIEvent would call createEvent with the parameter "UIEvents". The initUIEvent method could then be called on the newly created UIEvent to set the specific type of UIEvent to be dispatched and set its context information.
The createEvent method is used in creating Events when it is either inconvenient or unnecessary for the user to create an Event themselves. In cases where the implementation provided Event is insufficient, users may supply their own Event implementations for use with the dispatchEvent method.
Return Value

Event

The newly created Event
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the implementation does not support the type of Event interface requested

1.6. Event module definitions

The DOM Level 2 Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules as is required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM will define a module of user interface events including lower level device dependent events, a module of UI logical events, and a module of document mutation events. Any new event types defined by third parties must not begin with any upper, lower, or mixed case version of the string "DOM". This prefix is reserved for future DOM event modules. It is also strongly recommended that third parties adding their own events use their own prefix to avoid confusion and lessen the probability of conflicts with other new events.

1.6.1. User Interface event types

The User Interface event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "UIEvents" and "2.0" (respectively) to determine whether or not the User Interface event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification and the "Views" feature defined in the DOM Level 2 Views specification [DOM Level 2 Views]. Please, refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Note: To create an instance of the UIEvent interface, use the feature string "UIEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

Interface UIEvent (introduced in DOM Level 2)

The UIEvent interface provides specific contextual information associated with User Interface events.

IDL Definition
// Introduced in DOM Level 2:
interface UIEvent : Event {
  readonly attribute views::AbstractView  view;
  readonly attribute long             detail;
  void               initUIEvent(in DOMString typeArg,
                                 in boolean canBubbleArg,
                                 in boolean cancelableArg,
                                 in views::AbstractView viewArg,
                                 in long detailArg);
};

Attributes
detail of type long, readonly
Specifies some detail information about the Event, depending on the type of event.
view of type views::AbstractView, readonly
The view attribute identifies the AbstractView from which the event was generated.
Methods
initUIEvent
The initUIEvent method is used to initialize the value of a UIEvent created through the DocumentEvent interface. This method may only be called before the UIEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
Parameters
typeArg of type DOMString
Specifies the event type.
canBubbleArg of type boolean
Specifies whether or not the event can bubble.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented.
viewArg of type views::AbstractView
Specifies the Event's AbstractView.
detailArg of type long
Specifies the Event's detail.
No Return Value
No Exceptions

The different types of such events that can occur are:

DOMFocusIn
The DOMFocusIn event occurs when an EventTarget receives focus, for instance via a pointing device being moved onto an element or by tabbing navigation to the element. Unlike the HTML event focus, DOMFocusIn can be applied to any focusable EventTarget, not just FORM controls.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
DOMFocusOut
The DOMFocusOut event occurs when a EventTarget loses focus, for instance via a pointing device being moved out of an element or by tabbing navigation out of the element. Unlike the HTML event blur, DOMFocusOut can be applied to any focusable EventTarget, not just FORM controls.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
DOMActivate
The activate event occurs when an element is activated, for instance, thru a mouse click or a keypress. A numerical argument is provided to give an indication of the type of activation that occurs: 1 for a simple activation (e.g. a simple click or Enter), 2 for hyperactivation (for instance a double click or Shift Enter).
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: detail (the numerical value)

1.6.2. Mouse event types

The Mouse event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers. This event module is specifically designed for use with mouse input devices.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MouseEvents" and "2.0" (respectively) to determine whether or not the Mouse event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Note: To create an instance of the MouseEvent interface, use the feature string "MouseEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

Interface MouseEvent (introduced in DOM Level 2)

The MouseEvent interface provides specific contextual information associated with Mouse events.

The detail attribute inherited from UIEvent indicates the number of times a mouse button has been pressed and released over the same screen location during a user action. The attribute value is 1 when the user begins this action and increments by 1 for each full sequence of pressing and releasing. If the user moves the mouse between the mousedown and mouseup the value will be set to 0, indicating that no click is occurring.

In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements.

IDL Definition
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
  readonly attribute long             screenX;
  readonly attribute long             screenY;
  readonly attribute long             clientX;
  readonly attribute long             clientY;
  readonly attribute boolean          ctrlKey;
  readonly attribute boolean          shiftKey;
  readonly attribute boolean          altKey;
  readonly attribute boolean          metaKey;
  readonly attribute unsigned short   button;
  readonly attribute EventTarget      relatedTarget;
  void               initMouseEvent(in DOMString typeArg,
                                    in boolean canBubbleArg,
                                    in boolean cancelableArg,
                                    in views::AbstractView viewArg,
                                    in long detailArg,
                                    in long screenXArg,
                                    in long screenYArg,
                                    in long clientXArg,
                                    in long clientYArg,
                                    in boolean ctrlKeyArg,
                                    in boolean altKeyArg,
                                    in boolean shiftKeyArg,
                                    in boolean metaKeyArg,
                                    in unsigned short buttonArg,
                                    in EventTarget relatedTargetArg);
};

Attributes
altKey of type boolean, readonly
Used to indicate whether the 'alt' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.
button of type unsigned short, readonly
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. The values for button range from zero to indicate the left button of the mouse, one to indicate the middle button if present, and two to indicate the right button. For mice configured for left handed use in which the button actions are reversed the values are instead read from right to left.
clientX of type long, readonly
The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
clientY of type long, readonly
The vertical coordinate at which the event occurred relative to the DOM implementation's client area.
ctrlKey of type boolean, readonly
Used to indicate whether the 'ctrl' key was depressed during the firing of the event.
metaKey of type boolean, readonly
Used to indicate whether the 'meta' key was depressed during the firing of the event. On some platforms this key may map to an alternative key name.
relatedTarget of type EventTarget, readonly
Used to identify a secondary EventTarget related to a UI event. Currently this attribute is used with the mouseover event to indicate the EventTarget which the pointing device exited and with the mouseout event to indicate the EventTarget which the pointing device entered.
screenX of type long, readonly
The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.
screenY of type long, readonly
The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
shiftKey of type boolean, readonly
Used to indicate whether the 'shift' key was depressed during the firing of the event.
Methods
initMouseEvent
The initMouseEvent method is used to initialize the value of a MouseEvent created through the DocumentEvent interface. This method may only be called before the MouseEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
Parameters
typeArg of type DOMString
Specifies the event type.
canBubbleArg of type boolean
Specifies whether or not the event can bubble.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented.
viewArg of type views::AbstractView
Specifies the Event's AbstractView.
detailArg of type long
Specifies the Event's mouse click count.
screenXArg of type long
Specifies the Event's screen x coordinate
screenYArg of type long
Specifies the Event's screen y coordinate
clientXArg of type long
Specifies the Event's client x coordinate
clientYArg of type long
Specifies the Event's client y coordinate
ctrlKeyArg of type boolean
Specifies whether or not control key was depressed during the Event.
altKeyArg of type boolean
Specifies whether or not alt key was depressed during the Event.
shiftKeyArg of type boolean
Specifies whether or not shift key was depressed during the Event.
metaKeyArg of type boolean
Specifies whether or not meta key was depressed during the Event.
buttonArg of type unsigned short
Specifies the Event's mouse button.
relatedTargetArg of type EventTarget
Specifies the Event's related EventTarget.
No Return Value
No Exceptions

The different types of Mouse events that can occur are:

click
The click event occurs when the pointing device button is clicked over an element. A click is defined as a mousedown and mouseup over the same screen location. The sequence of these events is:
    mousedown
    mouseup
    click
If multiple clicks occur at the same screen location, the sequence repeats with the detail attribute incrementing with each repetition. This event is valid for most elements.
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail
mousedown
The mousedown event occurs when the pointing device button is pressed over an element. This event is valid for most elements.
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail
mouseup
The mouseup event occurs when the pointing device button is released over an element. This event is valid for most elements.
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, button, detail
mouseover
The mouseover event occurs when the pointing device is moved onto an element. This event is valid for most elements.
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, relatedTarget indicates the EventTarget the pointing device is exiting.
mousemove
The mousemove event occurs when the pointing device is moved while it is over an element. This event is valid for most elements.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey
mouseout
The mouseout event occurs when the pointing device is moved away from an element. This event is valid for most elements..
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: screenX, screenY, clientX, clientY, altKey, ctrlKey, shiftKey, metaKey, relatedTarget indicates the EventTarget the pointing device is entering.

1.6.3. Key events

The DOM Level 2 Event specification does not provide a key event module. An event module designed for use with keyboard input devices will be included in a later version of the DOM specification.

1.6.4. Mutation event types

The mutation event module is designed to allow notification of any changes to the structure of a document, including attr and text modifications. It may be noted that none of the mutation events listed are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the related event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.

Many single modifications of the tree can cause multiple mutation events to be fired. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationEvents" and "2.0" (respectively) to determine whether or not the Mutation event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Note: To create an instance of the MutationEvent interface, use the feature string "MutationEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

Interface MutationEvent (introduced in DOM Level 2)

The MutationEvent interface provides specific contextual information associated with Mutation events.

IDL Definition
// Introduced in DOM Level 2:
interface MutationEvent : Event {

  // attrChangeType
  const unsigned short      MODIFICATION                   = 1;
  const unsigned short      ADDITION                       = 2;
  const unsigned short      REMOVAL                        = 3;

  readonly attribute Node             relatedNode;
  readonly attribute DOMString        prevValue;
  readonly attribute DOMString        newValue;
  readonly attribute DOMString        attrName;
  readonly attribute unsigned short   attrChange;
  void               initMutationEvent(in DOMString typeArg,
                                       in boolean canBubbleArg,
                                       in boolean cancelableArg,
                                       in Node relatedNodeArg,
                                       in DOMString prevValueArg,
                                       in DOMString newValueArg,
                                       in DOMString attrNameArg,
                                       in unsigned short attrChangeArg);
};

Definition group attrChangeType

An integer indicating in which way the Attr was changed.

Defined Constants
ADDITION
The Attr was just added.
MODIFICATION
The Attr was modified in place.
REMOVAL
The Attr was just removed.
Attributes
attrChange of type unsigned short, readonly
attrChange indicates the type of change which triggered the DOMAttrModified event. The values can be MODIFICATION, ADDITION, or REMOVAL.
attrName of type DOMString, readonly
attrName indicates the name of the changed Attr node in a DOMAttrModified event.
newValue of type DOMString, readonly
newValue indicates the new value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharDataModified events.
prevValue of type DOMString, readonly
prevValue indicates the previous value of the Attr node in DOMAttrModified events, and of the CharacterData node in DOMCharDataModified events.
relatedNode of type Node, readonly
relatedNode is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the DOMAttrModified event it indicates the Attr node which was modified, added, or removed.
Methods
initMutationEvent
The initMutationEvent method is used to initialize the value of a MutationEvent created through the DocumentEvent interface. This method may only be called before the MutationEvent has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.
Parameters
typeArg of type DOMString
Specifies the event type.
canBubbleArg of type boolean
Specifies whether or not the event can bubble.
cancelableArg of type boolean
Specifies whether or not the event's default action can be prevented.
relatedNodeArg of type Node
Specifies the Event's related Node.
prevValueArg of type DOMString
Specifies the Event's prevValue attribute. This value may be null.
newValueArg of type DOMString
Specifies the Event's newValue attribute. This value may be null.
attrNameArg of type DOMString
Specifies the Event's attrName attribute. This value may be null.
attrChangeArg of type unsigned short
Specifies the Event's attrChange attribute
No Return Value
No Exceptions

The different types of Mutation events that can occur are:

DOMSubtreeModified
This is a general event for notification of all changes to the document. It can be used instead of the more specific events listed below. It may be fired after a single modification to the document or, at the implementation's discretion, after multiple changes have occurred. The latter use should generally be used to accomodate multiple changes which occur either simultaneously or in rapid succession. The target of this event is the lowest common parent of the changes which have taken place. This event is dispatched after any other events caused by the mutation have fired.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
DOMNodeInserted
Fired when a node has been added as a child of another node. This event is dispatched after the insertion has taken place. The target of this event is the node being inserted.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: relatedNode holds the parent node
DOMNodeRemoved
Fired when a node is being removed from its parent node. This event is dispatched before the node is removed from the tree. The target of this event is the node being removed.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: relatedNode holds the parent node
DOMNodeRemovedFromDocument
Fired when a node is being removed from a document, either through direct removal of the Node or removal of a subtree in which it is contained. This event is dispatched before the removal takes place. The target of this event is the Node being removed. If the Node is being directly removed the DOMNodeRemoved event will fire before the DOMNodeRemovedFromDocument event.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
DOMNodeInsertedIntoDocument
Fired when a node is being inserted into a document, either through direct insertion of the Node or insertion of a subtree in which it is contained. This event is dispatched after the insertion has taken place. The target of this event is the node being inserted. If the Node is being directly inserted the DOMNodeInserted event will fire before the DOMNodeInsertedIntoDocument event.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
DOMAttrModified
Fired after an Attr has been modified on a node. The target of this event is the Node whose Attr changed. The value of attrChange indicates whether the Attr was modified, added, or removed. The value of relatedNode indicates the Attr node whose value has been affected. It is expected that string based replacement of an Attr value will be viewed as a modification of the Attr since its identity does not change. Subsequently replacement of the Attr node with a different Attr node is viewed as the removal of the first Attr node and the addition of the second.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: attrName, attrChange, prevValue, newValue, relatedNode
DOMCharacterDataModified
Fired after CharacterData within a node has been modified but the node itself has not been inserted or deleted. This event is also triggered by modifications to PI elements. The target of this event is the CharacterData node.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: prevValue, newValue

1.6.5. HTML event types

The HTML event module is composed of events listed in HTML 4.0 and additional events which are supported in DOM Level 0 browsers.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTMLEvents" and "2.0" (respectively) to determine whether or not the HTML event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. Please, refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Note: To create an instance of the Event interface for the HTML event module, use the feature string "HTMLEvents" as the value of the input parameter used with the createEvent method of the DocumentEvent interface.

The HTML events use the base DOM Event interface to pass contextual information.

The different types of such events that can occur are:

load
The load event occurs when the DOM implementation finishes loading all content within a document, all frames within a FRAMESET, or an OBJECT element.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
unload
The unload event occurs when the DOM implementation removes a document from a window or frame. This event is valid for BODY and FRAMESET elements.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
abort
The abort event occurs when page loading is stopped before an image has been allowed to completely load. This event applies to OBJECT elements.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
error
The error event occurs when an image does not load properly or when an error occurs during script execution. This event is valid for OBJECT elements, BODY elements, and FRAMESET element.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
select
The select event occurs when a user selects some text in a text field. This event is valid for INPUT and TEXTAREA elements.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
change
The change event occurs when a control loses the input focus and its value has been modified since gaining focus. This event is valid for INPUT, SELECT, and TEXTAREA. element.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
submit
The submit event occurs when a form is submitted. This event only applies to the FORM element.
  • Bubbles: Yes
  • Cancelable: Yes
  • Context Info: None
reset
The reset event occurs when a form is reset. This event only applies to the FORM element.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
focus
The focus event occurs when an element receives focus either via a pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
blur
The blur event occurs when an element loses focus either via the pointing device or by tabbing navigation. This event is valid for the following elements: LABEL, INPUT, SELECT, TEXTAREA, and BUTTON.
  • Bubbles: No
  • Cancelable: No
  • Context Info: None
resize
The resize event occurs when a document view is resized.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
scroll
The scroll event occurs when a document view is scrolled.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: None
previous next contents index


IDL Definitions

previous next contents index

13 November, 2000

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Events definitions.

The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/idl.zip

events.idl:

// File: events.idl

#ifndef _EVENTS_IDL_
#define _EVENTS_IDL_

#include "dom.idl"
#include "views.idl"

#pragma prefix "dom.w3c.org"
module events
{

  typedef dom::DOMString DOMString;
  typedef dom::DOMTimeStamp DOMTimeStamp;
  typedef dom::Node Node;

  interface EventListener;
  interface Event;

  // Introduced in DOM Level 2:
  exception EventException {
    unsigned short   code;
  };
  // EventExceptionCode
  const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;

  // Introduced in DOM Level 2:
  interface EventTarget {
    void               addEventListener(in DOMString type,
                                        in EventListener listener,
                                        in boolean useCapture);
    void               removeEventListener(in DOMString type,
                                           in EventListener listener,
                                           in boolean useCapture);
    boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
  };

  // Introduced in DOM Level 2:
  interface EventListener {
    void               handleEvent(in Event evt);
  };

  // Introduced in DOM Level 2:
  interface Event {

    // PhaseType
    const unsigned short      CAPTURING_PHASE                = 1;
    const unsigned short      AT_TARGET                      = 2;
    const unsigned short      BUBBLING_PHASE                 = 3;

    readonly attribute DOMString        type;
    readonly attribute EventTarget      target;
    readonly attribute EventTarget      currentTarget;
    readonly attribute unsigned short   eventPhase;
    readonly attribute boolean          bubbles;
    readonly attribute boolean          cancelable;
    readonly attribute DOMTimeStamp     timeStamp;
    void               stopPropagation();
    void               preventDefault();
    void               initEvent(in DOMString eventTypeArg,
                                 in boolean canBubbleArg,
                                 in boolean cancelableArg);
  };

  // Introduced in DOM Level 2:
  interface DocumentEvent {
    Event              createEvent(in DOMString eventType)
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface UIEvent : Event {
    readonly attribute views::AbstractView  view;
    readonly attribute long             detail;
    void               initUIEvent(in DOMString typeArg,
                                   in boolean canBubbleArg,
                                   in boolean cancelableArg,
                                   in views::AbstractView viewArg,
                                   in long detailArg);
  };

  // Introduced in DOM Level 2:
  interface MouseEvent : UIEvent {
    readonly attribute long             screenX;
    readonly attribute long             screenY;
    readonly attribute long             clientX;
    readonly attribute long             clientY;
    readonly attribute boolean          ctrlKey;
    readonly attribute boolean          shiftKey;
    readonly attribute boolean          altKey;
    readonly attribute boolean          metaKey;
    readonly attribute unsigned short   button;
    readonly attribute EventTarget      relatedTarget;
    void               initMouseEvent(in DOMString typeArg,
                                      in boolean canBubbleArg,
                                      in boolean cancelableArg,
                                      in views::AbstractView viewArg,
                                      in long detailArg,
                                      in long screenXArg,
                                      in long screenYArg,
                                      in long clientXArg,
                                      in long clientYArg,
                                      in boolean ctrlKeyArg,
                                      in boolean altKeyArg,
                                      in boolean shiftKeyArg,
                                      in boolean metaKeyArg,
                                      in unsigned short buttonArg,
                                      in EventTarget relatedTargetArg);
  };

  // Introduced in DOM Level 2:
  interface MutationEvent : Event {

    // attrChangeType
    const unsigned short      MODIFICATION                   = 1;
    const unsigned short      ADDITION                       = 2;
    const unsigned short      REMOVAL                        = 3;

    readonly attribute Node             relatedNode;
    readonly attribute DOMString        prevValue;
    readonly attribute DOMString        newValue;
    readonly attribute DOMString        attrName;
    readonly attribute unsigned short   attrChange;
    void               initMutationEvent(in DOMString typeArg,
                                         in boolean canBubbleArg,
                                         in boolean cancelableArg,
                                         in Node relatedNodeArg,
                                         in DOMString prevValueArg,
                                         in DOMString newValueArg,
                                         in DOMString attrNameArg,
                                         in unsigned short attrChangeArg);
  };
};

#endif // _EVENTS_IDL_
previous next contents index


Java Language Binding

previous next contents index

13 November, 2000

Appendix B: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 2 Document Object Model Events.

The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/java-binding.zip

org/w3c/dom/events/EventException.java:

package org.w3c.dom.events;

public class EventException extends RuntimeException {
    public EventException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // EventExceptionCode
    public static final short UNSPECIFIED_EVENT_TYPE_ERR = 0;

}

org/w3c/dom/events/EventTarget.java:

package org.w3c.dom.events;

public interface EventTarget {
    public void addEventListener(String type,
                                 EventListener listener,
                                 boolean useCapture);

    public void removeEventListener(String type,
                                    EventListener listener,
                                    boolean useCapture);

    public boolean dispatchEvent(Event evt)
                                 throws EventException;

}

org/w3c/dom/events/EventListener.java:

package org.w3c.dom.events;

public interface EventListener {
    public void handleEvent(Event evt);

}

org/w3c/dom/events/Event.java:

package org.w3c.dom.events;

public interface Event {
    // PhaseType
    public static final short CAPTURING_PHASE           = 1;
    public static final short AT_TARGET                 = 2;
    public static final short BUBBLING_PHASE            = 3;

    public String getType();

    public EventTarget getTarget();

    public EventTarget getCurrentTarget();

    public short getEventPhase();

    public boolean getBubbles();

    public boolean getCancelable();

    public long getTimeStamp();

    public void stopPropagation();

    public void preventDefault();

    public void initEvent(String eventTypeArg,
                          boolean canBubbleArg,
                          boolean cancelableArg);

}

org/w3c/dom/events/DocumentEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.DOMException;

public interface DocumentEvent {
    public Event createEvent(String eventType)
                             throws DOMException;

}

org/w3c/dom/events/UIEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface UIEvent extends Event {
    public AbstractView getView();

    public int getDetail();

    public void initUIEvent(String typeArg,
                            boolean canBubbleArg,
                            boolean cancelableArg,
                            AbstractView viewArg,
                            int detailArg);

}

org/w3c/dom/events/MouseEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface MouseEvent extends UIEvent {
    public int getScreenX();

    public int getScreenY();

    public int getClientX();

    public int getClientY();

    public boolean getCtrlKey();

    public boolean getShiftKey();

    public boolean getAltKey();

    public boolean getMetaKey();

    public short getButton();

    public EventTarget getRelatedTarget();

    public void initMouseEvent(String typeArg,
                               boolean canBubbleArg,
                               boolean cancelableArg,
                               AbstractView viewArg,
                               int detailArg,
                               int screenXArg,
                               int screenYArg,
                               int clientXArg,
                               int clientYArg,
                               boolean ctrlKeyArg,
                               boolean altKeyArg,
                               boolean shiftKeyArg,
                               boolean metaKeyArg,
                               short buttonArg,
                               EventTarget relatedTargetArg);

}

org/w3c/dom/events/MutationEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.Node;

public interface MutationEvent extends Event {
    // attrChangeType
    public static final short MODIFICATION              = 1;
    public static final short ADDITION                  = 2;
    public static final short REMOVAL                   = 3;

    public Node getRelatedNode();

    public String getPrevValue();

    public String getNewValue();

    public String getAttrName();

    public short getAttrChange();

    public void initMutationEvent(String typeArg,
                                  boolean canBubbleArg,
                                  boolean cancelableArg,
                                  Node relatedNodeArg,
                                  String prevValueArg,
                                  String newValueArg,
                                  String attrNameArg,
                                  short attrChangeArg);

}
previous next contents index


ECMAScript Language Binding

previous next contents index

13 November, 2000

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Events definitions.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

Object EventTarget
The EventTarget object has the following methods:
addEventListener(type, listener, useCapture)
This method has no return value.
The type parameter is of type String.
The listener parameter is a EventListener object.
The useCapture parameter is of type Boolean.
removeEventListener(type, listener, useCapture)
This method has no return value.
The type parameter is of type String.
The listener parameter is a EventListener object.
The useCapture parameter is of type Boolean.
dispatchEvent(evt)
This method returns a Boolean.
The evt parameter is a Event object.
This method can raise a EventException object.
Object EventListener
This is an ECMAScript function reference. This method has no return value. The parameter is a Event object.
Prototype Object Event
The Event class has the following constants:
Event.CAPTURING_PHASE
This constant is of type Number and its value is 1.
Event.AT_TARGET
This constant is of type Number and its value is 2.
Event.BUBBLING_PHASE
This constant is of type Number and its value is 3.
Object Event
The Event object has the following properties:
type
This read-only property is of type String.
target
This read-only property is a EventTarget object.
currentTarget
This read-only property is a EventTarget object.
eventPhase
This read-only property is of type Number.
bubbles
This read-only property is of type Boolean.
cancelable
This read-only property is of type Boolean.
timeStamp
This read-only property is a Date object.
The Event object has the following methods:
stopPropagation()
This method has no return value.
preventDefault()
This method has no return value.
initEvent(eventTypeArg, canBubbleArg, cancelableArg)
This method has no return value.
The eventTypeArg parameter is of type String.
The canBubbleArg parameter is of type Boolean.
The cancelableArg parameter is of type Boolean.
Prototype Object EventException
The EventException class has the following constants:
EventException.UNSPECIFIED_EVENT_TYPE_ERR
This constant is of type Number and its value is 0.
Object EventException
The EventException object has the following properties:
code
This property is of type Number.
Object DocumentEvent
The DocumentEvent object has the following methods:
createEvent(eventType)
This method returns a Event object.
The eventType parameter is of type String.
This method can raise a DOMException object.
Object UIEvent
UIEvent has the all the properties and methods of the Event object as well as the properties and methods defined below.
The UIEvent object has the following properties:
view
This read-only property is a AbstractView object.
detail
This read-only property is a long object.
The UIEvent object has the following methods:
initUIEvent(typeArg, canBubbleArg, cancelableArg, viewArg, detailArg)
This method has no return value.
The typeArg parameter is of type String.
The canBubbleArg parameter is of type Boolean.
The cancelableArg parameter is of type Boolean.
The viewArg parameter is a AbstractView object.
The detailArg parameter is a long object.
Object MouseEvent
MouseEvent has the all the properties and methods of the UIEvent object as well as the properties and methods defined below.
The MouseEvent object has the following properties:
screenX
This read-only property is a long object.
screenY
This read-only property is a long object.
clientX
This read-only property is a long object.
clientY
This read-only property is a long object.
ctrlKey
This read-only property is of type Boolean.
shiftKey
This read-only property is of type Boolean.
altKey
This read-only property is of type Boolean.
metaKey
This read-only property is of type Boolean.
button
This read-only property is of type Number.
relatedTarget
This read-only property is a EventTarget object.
The MouseEvent object has the following methods:
initMouseEvent(typeArg, canBubbleArg, cancelableArg, viewArg, detailArg, screenXArg, screenYArg, clientXArg, clientYArg, ctrlKeyArg, altKeyArg, shiftKeyArg, metaKeyArg, buttonArg, relatedTargetArg)
This method has no return value.
The typeArg parameter is of type String.
The canBubbleArg parameter is of type Boolean.
The cancelableArg parameter is of type Boolean.
The viewArg parameter is a AbstractView object.
The detailArg parameter is a long object.
The screenXArg parameter is a long object.
The screenYArg parameter is a long object.
The clientXArg parameter is a long object.
The clientYArg parameter is a long object.
The ctrlKeyArg parameter is of type Boolean.
The altKeyArg parameter is of type Boolean.
The shiftKeyArg parameter is of type Boolean.
The metaKeyArg parameter is of type Boolean.
The buttonArg parameter is of type Number.
The relatedTargetArg parameter is a EventTarget object.
Prototype Object MutationEvent
The MutationEvent class has the following constants:
MutationEvent.MODIFICATION
This constant is of type Number and its value is 1.
MutationEvent.ADDITION
This constant is of type Number and its value is 2.
MutationEvent.REMOVAL
This constant is of type Number and its value is 3.
Object MutationEvent
MutationEvent has the all the properties and methods of the Event object as well as the properties and methods defined below.
The MutationEvent object has the following properties:
relatedNode
This read-only property is a Node object.
prevValue
This read-only property is of type String.
newValue
This read-only property is of type String.
attrName
This read-only property is of type String.
attrChange
This read-only property is of type Number.
The MutationEvent object has the following methods:
initMutationEvent(typeArg, canBubbleArg, cancelableArg, relatedNodeArg, prevValueArg, newValueArg, attrNameArg, attrChangeArg)
This method has no return value.
The typeArg parameter is of type String.
The canBubbleArg parameter is of type Boolean.
The cancelableArg parameter is of type Boolean.
The relatedNodeArg parameter is a Node object.
The prevValueArg parameter is of type String.
The newValueArg parameter is of type String.
The attrNameArg parameter is of type String.
The attrChangeArg parameter is of type Number.

The following example will add an ECMAScript based EventListener to the Node 'exampleNode':

  // Given the Node 'exampleNode'

  // Define the EventListener function
  function clickHandler(evt)
  {
    // Function contents
  }

  // The following line will add a non-capturing 'click' listener
  // to 'exampleNode'.
  exampleNode.addEventListener("click", clickHandler, false);
previous next contents index


Glossary

Editors
Arnaud Le Hors, IBM
Lauren Wood, SoftQuad Software Inc.
Robert S. Sutor, IBM (for DOM Level 1)

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

ancestor
An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root."
child
A child is an immediate descendant node of a node.
descendant
A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root."
DOM Level 0
The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".
sibling
Two nodes are siblings if and only if they have the same parent node.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
XML name
See XML name in the XML specification [XML].
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

F.1: Normative references

DOM Level 2 Core
W3C (World Wide Web Consortium) Document Object Model Level 2 Core Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
DOM Level 2 Views
W3C (World Wide Web Consortium) Document Object Model Level 2 Views Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113
XML
W3C (World Wide Web Consortium) Extensible Markup Language (XML) 1.0, February 1998. Available at http://www.w3.org/TR/1998/REC-xml-19980210
previous next contents index


Index

addEventListener | ADDITION | altKey
ancestor 1, 2, 3 | AT_TARGET | attrChange
attrName
bubbles | BUBBLING_PHASE | button
cancelable | CAPTURING_PHASE | child 1, 2
clientX | clientY | createEvent
ctrlKey | currentTarget
descendant 1, 2 | detail | dispatchEvent
DocumentEvent | DOM Level 0 1, 2, 3, 4, 5 | DOM Level 2 Core 1, 2, 3, 4, 5, 6
DOM Level 2 Views 1, 2
ECMAScript | Event | EventException
EventListener | eventPhase | EventTarget
handleEvent
initEvent | initMouseEvent | initMutationEvent
initUIEvent
Java
metaKey | MODIFICATION | MouseEvent
MutationEvent
newValue
OMGIDL
preventDefault | prevValue
relatedNode | relatedTarget | REMOVAL
removeEventListener
screenX | screenY | shiftKey
sibling 1, 2 | stopPropagation
target | timeStamp | tokenized
type
UIEvent | UNSPECIFIED_EVENT_TYPE_ERR
view
XML 1, 2 | XML name 1, 2, 3
previous contents


Document Object Model (DOM) Level 2 Style Specification

Version 1.0

W3C Recommendation 13 November, 2000

This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113
( PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Style
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Style-20000927
Editors:
Chris Wilson, Microsoft Corp.
Philippe Le Hégaret, W3C, team contact (from November 1999)
Vidur Apparao, Netscape Communications Corp.

Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Level 2 Style Sheets and Cascading Style Sheets (CSS), a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content and of style sheets documents. The Document Object Model Level 2 Style builds on the Document Object Model Level 2 Core [DOM Level 2 Core] and on the Document Object Model Level 2 Views [DOM Level 2 Views].

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members. Different modules of the Document Object Model have different editors.

Please send general comments about this document to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • Chapter 1: Document Object Model Style Sheets
  • Chapter 2: Document Object Model CSS
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • References
  • Index
next contents index


Document Object Model Style Sheets

previous next contents index

13 November, 2000

1. Document Object Model Style Sheets

Editors
Chris Wilson, Microsoft Corp.
Philippe Le Hégaret, W3C
Vidur Apparao, Netscape Communications Corp.

Table of contents

  • 1.1. Introduction
  • 1.2. Style Sheet Interfaces
    • StyleSheet, StyleSheetList, MediaList
  • 1.3. Document Extensions
    • LinkStyle, DocumentStyle
  • 1.4. Association between a style sheet and a document.

1.1. Introduction

The DOM Level 2 Style Sheet interfaces are base interfaces used to represent any type of style sheet. The expectation is that DOM modules that represent a specific style sheet language may contain interfaces that derive from these interfaces.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "StyleSheets" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined defined in the DOM 2 Core specification [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

1.2. Style Sheet Interfaces

This set of interfaces represents the generic notion of style sheets.

Interface StyleSheet (introduced in DOM Level 2)

The StyleSheet interface is the abstract base interface for any type of style sheet. It represents a single style sheet associated with a structured document. In HTML, the StyleSheet interface represents either an external style sheet, included via the HTML LINK element, or an inline STYLE element. In XML, this interface represents an external style sheet, included via a style sheet processing instruction.

IDL Definition
// Introduced in DOM Level 2:
interface StyleSheet {
  readonly attribute DOMString        type;
           attribute boolean          disabled;
  readonly attribute Node             ownerNode;
  readonly attribute StyleSheet       parentStyleSheet;
  readonly attribute DOMString        href;
  readonly attribute DOMString        title;
  readonly attribute MediaList        media;
};

Attributes
disabled of type boolean
false if the style sheet is applied to the document. true if it is not. Modifying this attribute may cause a new resolution of style for the document. A stylesheet only applies if both an appropriate medium definition is present and the disabled attribute is false. So, if the media doesn't apply to the current user agent, the disabled attribute is ignored.
href of type DOMString, readonly
If the style sheet is a linked style sheet, the value of its attribute is its location. For inline style sheets, the value of this attribute is null. See the href attribute definition for the LINK element in HTML 4.0, and the href pseudo-attribute for the XML style sheet processing instruction.
media of type MediaList, readonly
The intended destination media for style information. The media is often specified in the ownerNode. If no media has been specified, the MediaList will be empty. See the media attribute definition for the LINK element in HTML 4.0, and the media pseudo-attribute for the XML style sheet processing instruction . Modifying the media list may cause a change to the attribute disabled.
ownerNode of type Node, readonly
The node that associates this style sheet with the document. For HTML, this may be the corresponding LINK or STYLE element. For XML, it may be the linking processing instruction. For style sheets that are included by other style sheets, the value of this attribute is null.
parentStyleSheet of type StyleSheet, readonly
For style sheet languages that support the concept of style sheet inclusion, this attribute represents the including style sheet, if one exists. If the style sheet is a top-level style sheet, or the style sheet language does not support inclusion, the value of this attribute is null.
title of type DOMString, readonly
The advisory title. The title is often specified in the ownerNode. See the title attribute definition for the LINK element in HTML 4.0, and the title pseudo-attribute for the XML style sheet processing instruction.
type of type DOMString, readonly
This specifies the style sheet language for this style sheet. The style sheet language is specified as a content type (e.g. "text/css"). The content type is often specified in the ownerNode. Also see the type attribute definition for the LINK element in HTML 4.0, and the type pseudo-attribute for the XML style sheet processing instruction.
Interface StyleSheetList (introduced in DOM Level 2)

The StyleSheetList interface provides the abstraction of an ordered collection of style sheets.

The items in the StyleSheetList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 2:
interface StyleSheetList {
  readonly attribute unsigned long    length;
  StyleSheet         item(in unsigned long index);
};

Attributes
length of type unsigned long, readonly
The number of StyleSheets in the list. The range of valid child stylesheet indices is 0 to length-1 inclusive.
Methods
item
Used to retrieve a style sheet by ordinal index. If index is greater than or equal to the number of style sheets in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection
Return Value

StyleSheet

The style sheet at the index position in the StyleSheetList, or null if that is not a valid index.
No Exceptions
Interface MediaList (introduced in DOM Level 2)

The MediaList interface provides the abstraction of an ordered collection of media, without defining or constraining how this collection is implemented. An empty list is the same as a list that contains the medium "all".

The items in the MediaList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 2:
interface MediaList {
           attribute DOMString        mediaText;
                                        // raises(DOMException) on setting

  readonly attribute unsigned long    length;
  DOMString          item(in unsigned long index);
  void               deleteMedium(in DOMString oldMedium)
                                        raises(DOMException);
  void               appendMedium(in DOMString newMedium)
                                        raises(DOMException);
};

Attributes
length of type unsigned long, readonly
The number of media in the list. The range of valid media is 0 to length-1 inclusive.
mediaText of type DOMString
The parsable textual representation of the media list. This is a comma-separated list of media.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified string value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this media list is readonly.
Methods
appendMedium
Adds the medium newMedium to the end of the list. If the newMedium is already used, it is first removed.
Parameters
newMedium of type DOMString
The new medium to add.
Exceptions

DOMException

INVALID_CHARACTER_ERR: If the medium contains characters that are invalid in the underlying style language.

NO_MODIFICATION_ALLOWED_ERR: Raised if this list is readonly.
No Return Value
deleteMedium
Deletes the medium indicated by oldMedium from the list.
Parameters
oldMedium of type DOMString
The medium to delete in the media list.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this list is readonly.

NOT_FOUND_ERR: Raised if oldMedium is not in the list.
No Return Value
item
Returns the indexth in the list. If index is greater than or equal to the number of media in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

DOMString

The medium at the indexth position in the MediaList, or null if that is not a valid index.
No Exceptions

1.3. Document Extensions

Interface LinkStyle (introduced in DOM Level 2)

The LinkStyle interface provides a mechanism by which a style sheet can be retrieved from the node responsible for linking it into a document. An instance of the LinkStyle interface can be obtained using binding-specific casting methods on an instance of a linking node (HTMLLinkElement, HTMLStyleElement or ProcessingInstruction in DOM Level 2).

IDL Definition
// Introduced in DOM Level 2:
interface LinkStyle {
  readonly attribute StyleSheet       sheet;
};

Attributes
sheet of type StyleSheet, readonly
The style sheet.
Interface DocumentStyle (introduced in DOM Level 2)

The DocumentStyle interface provides a mechanism by which the style sheets embedded in a document can be retrieved. The expectation is that an instance of the DocumentStyle interface can be obtained by using binding-specific casting methods on an instance of the Document interface.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentStyle {
  readonly attribute StyleSheetList   styleSheets;
};

Attributes
styleSheets of type StyleSheetList, readonly
A list containing all the style sheets explicitly linked into or embedded in a document. For HTML documents, this includes external style sheets, included via the HTML LINK element, and inline STYLE elements. In XML, this includes external style sheets, included via style sheet processing instructions (see [XML-StyleSheet]).

1.4. Association between a style sheet and a document.

HTML and Style Sheet Creation
A style sheet can be associated with an HTMLDocument in one of two ways:
  • By creating a new LINK HTML element (see the HTMLLinkElement interface in the [DOM Level 2 HTML] and [HTML4.0]). The underlying style sheet will be created after the element is inserted into the document and both the href and the type attribute have been set in a way indicating that the linked object is a style sheet.
  • By creating a new STYLE HTML element (see the HTMLStyleElement interface in the [DOM Level 2 HTML] and [HTML4.0]). The underlying style sheet will be created after the element is inserted into the document and the type attribute is set in a way indicating that the element corresponds to a style sheet language interpreted by the user agent.
HTML and Style Sheet Removal
Removing a LINK HTML element or a STYLE HTML element removes the underlying style sheet from the style sheet collection associated with a document. Specifically, the removed style sheet is no longer applied to the presentation of the document.
XML and Style Sheet Creation
A new style sheet can be created and associated with an XML document by creating a processing instruction with the target 'xml-stylesheet' [XML-StyleSheet] and inserting it into the document.
XML and Style Sheet Removal
Removing a processing instruction with a target of 'xml-stylesheet' [XML-StyleSheet] removes the underlying style sheet from the style sheet collection associated with a document. Specifically, the removed style sheet is no longer applied to the presentation of the document.
previous next contents index


Document Object Model CSS

previous next contents index

13 November, 2000

2. Document Object Model CSS

Editors
Chris Wilson, Microsoft Corp.
Philippe Le Hégaret, W3C
Vidur Apparao, Netscape Communications Corp.

Table of contents

  • 2.1. Overview of the DOM Level 2 CSS Interfaces
  • 2.2. CSS Fundamental Interfaces
    • CSSStyleSheet, CSSRuleList, CSSRule, CSSStyleRule, CSSMediaRule, CSSFontFaceRule, CSSPageRule, CSSImportRule, CSSCharsetRule, CSSUnknownRule, CSSStyleDeclaration, CSSValue, CSSPrimitiveValue, CSSValueList, RGBColor, Rect, Counter
    • 2.2.1. Override and computed style sheet
      • ViewCSS, DocumentCSS
    • 2.2.2. Style sheet creation
      • DOMImplementationCSS
    • 2.2.3. Element with CSS inline style
      • ElementCSSInlineStyle
  • 2.3. CSS2 Extended Interface
    • CSS2Properties

2.1. Overview of the DOM Level 2 CSS Interfaces

The DOM Level 2 Cascading Style Sheets (CSS) interfaces are designed with the goal of exposing CSS constructs to object model consumers. Cascading Style Sheets is a declarative syntax for defining presentation rules, properties and ancillary constructs used to format and render Web documents. This document specifies a mechanism to programmatically access and modify the rich style and presentation control provided by CSS (specifically CSS level 2 [CSS2]). This augments CSS by providing a mechanism to dynamically control the inclusion and exclusion of individual style sheets, as well as manipulate CSS rules and properties.

The CSS interfaces are organized in a logical, rather than physical structure. A collection of all style sheets referenced by or embedded in the document is accessible on the document interface. Each item in this collection exposes the properties common to all style sheets referenced or embedded in HTML and XML documents; this interface is described in the Document Object Model Style Sheets. User style sheets are not accessible through this collection, in part due to potential privacy concerns (and certainly read-write issues).

For each CSS style sheet, an additional interface is exposed - the CSSStyleSheet interface. This interface allows access to the collection of rules within a CSS style sheet and methods to modify that collection. Interfaces are provided for each specific type of rule in CSS2 (e.g. style declarations, @import rules, or @font-face rules), as well as a shared generic CSSRule interface.

The most common type of rule is a style declaration. The CSSStyleRule interface that represents this type of rule provides string access to the CSS selector of the rule, and access to the property declarations through the CSSStyleDeclaration interface.

Finally, an optional CSS2Properties interface is described; this interface (if implemented) provides shortcuts to the string values of all the properties in CSS level 2.

All CSS objects in the DOM are "live", that is, a change in the style sheet is reflected in the computed and actual style.

2.2. CSS Fundamental Interfaces

The interfaces within this section are considered fundamental CSS interfaces, and must be supported by all conforming implementations of the CSS module. These interfaces represent CSS style sheets specifically.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "CSS" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined defined in the DOM Level 2 Core specification [DOM Level 2 Core] and the "Views" feature defined in the DOM Level 2 Views specification [DOM Level 2 Views]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Interface CSSStyleSheet (introduced in DOM Level 2)

The CSSStyleSheet interface is a concrete interface used to represent a CSS style sheet i.e., a style sheet whose content type is "text/css".

IDL Definition
// Introduced in DOM Level 2:
interface CSSStyleSheet : stylesheets::StyleSheet {
  readonly attribute CSSRule          ownerRule;
  readonly attribute CSSRuleList      cssRules;
  unsigned long      insertRule(in DOMString rule,
                                in unsigned long index)
                                        raises(DOMException);
  void               deleteRule(in unsigned long index)
                                        raises(DOMException);
};

Attributes
cssRules of type CSSRuleList, readonly
The list of all CSS rules contained within the style sheet. This includes both rule sets and at-rules.
ownerRule of type CSSRule, readonly
If this style sheet comes from an @import rule, the ownerRule attribute will contain the CSSImportRule. In that case, the ownerNode attribute in the StyleSheet interface will be null. If the style sheet comes from an element or a processing instruction, the ownerRule attribute will be null and the ownerNode attribute will contain the Node.
Methods
deleteRule
Used to delete a rule from the style sheet.
Parameters
index of type unsigned long
The index within the style sheet's rule list of the rule to remove.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index does not correspond to a rule in the style sheet's rule list.

NO_MODIFICATION_ALLOWED_ERR: Raised if this style sheet is readonly.
No Return Value
insertRule
Used to insert a new rule into the style sheet. The new rule now becomes part of the cascade.
Parameters
rule of type DOMString
The parsable text representing the rule. For rule sets this contains both the selector and the style declaration. For at-rules, this specifies both the at-identifier and the rule content.
index of type unsigned long
The index within the style sheet's rule list of the rule before which to insert the specified rule. If the specified index is equal to the length of the style sheet's rule collection, the rule will be added to the end of the style sheet.
Return Value

unsigned long

The index within the style sheet's rule collection of the newly inserted rule.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if the rule cannot be inserted at the specified index e.g. if an @import rule is inserted after a standard rule set or other at-rule.

INDEX_SIZE_ERR: Raised if the specified index is not a valid insertion point.

NO_MODIFICATION_ALLOWED_ERR: Raised if this style sheet is readonly.

SYNTAX_ERR: Raised if the specified rule has a syntax error and is unparsable.
Interface CSSRuleList (introduced in DOM Level 2)

The CSSRuleList interface provides the abstraction of an ordered collection of CSS rules.

The items in the CSSRuleList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 2:
interface CSSRuleList {
  readonly attribute unsigned long    length;
  CSSRule            item(in unsigned long index);
};

Attributes
length of type unsigned long, readonly
The number of CSSRules in the list. The range of valid child rule indices is 0 to length-1 inclusive.
Methods
item
Used to retrieve a CSS rule by ordinal index. The order in this collection represents the order of the rules in the CSS style sheet. If index is greater than or equal to the number of rules in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection
Return Value

CSSRule

The style rule at the index position in the CSSRuleList, or null if that is not a valid index.
No Exceptions
Interface CSSRule (introduced in DOM Level 2)

The CSSRule interface is the abstract base interface for any type of CSS statement. This includes both rule sets and at-rules. An implementation is expected to preserve all rules specified in a CSS style sheet, even if the rule is not recognized by the parser. Unrecognized rules are represented using the CSSUnknownRule interface.

IDL Definition
// Introduced in DOM Level 2:
interface CSSRule {

  // RuleType
  const unsigned short      UNKNOWN_RULE                   = 0;
  const unsigned short      STYLE_RULE                     = 1;
  const unsigned short      CHARSET_RULE                   = 2;
  const unsigned short      IMPORT_RULE                    = 3;
  const unsigned short      MEDIA_RULE                     = 4;
  const unsigned short      FONT_FACE_RULE                 = 5;
  const unsigned short      PAGE_RULE                      = 6;

  readonly attribute unsigned short   type;
           attribute DOMString        cssText;
                                        // raises(DOMException) on setting

  readonly attribute CSSStyleSheet    parentStyleSheet;
  readonly attribute CSSRule          parentRule;
};

Definition group RuleType

An integer indicating which type of rule this is.

Defined Constants
CHARSET_RULE
The rule is a CSSCharsetRule.
FONT_FACE_RULE
The rule is a CSSFontFaceRule.
IMPORT_RULE
The rule is a CSSImportRule.
MEDIA_RULE
The rule is a CSSMediaRule.
PAGE_RULE
The rule is a CSSPageRule.
STYLE_RULE
The rule is a CSSStyleRule.
UNKNOWN_RULE
The rule is a CSSUnknownRule.
Attributes
cssText of type DOMString
The parsable textual representation of the rule. This reflects the current state of the rule and not its initial value.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified CSS string value has a syntax error and is unparsable.

INVALID_MODIFICATION_ERR: Raised if the specified CSS string value represents a different type of rule than the current one.

HIERARCHY_REQUEST_ERR: Raised if the rule cannot be inserted at this point in the style sheet.

NO_MODIFICATION_ALLOWED_ERR: Raised if the rule is readonly.
parentRule of type CSSRule, readonly
If this rule is contained inside another rule (e.g. a style rule inside an @media block), this is the containing rule. If this rule is not nested inside any other rules, this returns null.
parentStyleSheet of type CSSStyleSheet, readonly
The style sheet that contains this rule.
type of type unsigned short, readonly
The type of the rule, as defined above. The expectation is that binding-specific casting methods can be used to cast down from an instance of the CSSRule interface to the specific derived interface implied by the type.
Interface CSSStyleRule (introduced in DOM Level 2)

The CSSStyleRule interface represents a single rule set in a CSS style sheet.

IDL Definition
// Introduced in DOM Level 2:
interface CSSStyleRule : CSSRule {
           attribute DOMString        selectorText;
                                        // raises(DOMException) on setting

  readonly attribute CSSStyleDeclaration  style;
};

Attributes
selectorText of type DOMString
The textual representation of the selector for the rule set. The implementation may have stripped out insignificant whitespace while parsing the selector.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified CSS string value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this rule is readonly.
style of type CSSStyleDeclaration, readonly
The declaration-block of this rule set.
Interface CSSMediaRule (introduced in DOM Level 2)

The CSSMediaRule interface represents a @media rule in a CSS style sheet. A @media rule can be used to delimit style rules for specific media types.

IDL Definition
// Introduced in DOM Level 2:
interface CSSMediaRule : CSSRule {
  readonly attribute stylesheets::MediaList  media;
  readonly attribute CSSRuleList      cssRules;
  unsigned long      insertRule(in DOMString rule,
                                in unsigned long index)
                                        raises(DOMException);
  void               deleteRule(in unsigned long index)
                                        raises(DOMException);
};

Attributes
cssRules of type CSSRuleList, readonly
A list of all CSS rules contained within the media block.
media of type stylesheets::MediaList, readonly
A list of media types for this rule.
Methods
deleteRule
Used to delete a rule from the media block.
Parameters
index of type unsigned long
The index within the media block's rule collection of the rule to remove.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index does not correspond to a rule in the media rule list.

NO_MODIFICATION_ALLOWED_ERR: Raised if this media rule is readonly.
No Return Value
insertRule
Used to insert a new rule into the media block.
Parameters
rule of type DOMString
The parsable text representing the rule. For rule sets this contains both the selector and the style declaration. For at-rules, this specifies both the at-identifier and the rule content.
index of type unsigned long
The index within the media block's rule collection of the rule before which to insert the specified rule. If the specified index is equal to the length of the media blocks's rule collection, the rule will be added to the end of the media block.
Return Value

unsigned long

The index within the media block's rule collection of the newly inserted rule.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if the rule cannot be inserted at the specified index, e.g., if an @import rule is inserted after a standard rule set or other at-rule.

INDEX_SIZE_ERR: Raised if the specified index is not a valid insertion point.

NO_MODIFICATION_ALLOWED_ERR: Raised if this media rule is readonly.

SYNTAX_ERR: Raised if the specified rule has a syntax error and is unparsable.
Interface CSSFontFaceRule (introduced in DOM Level 2)

The CSSFontFaceRule interface represents a @font-face rule in a CSS style sheet. The @font-face rule is used to hold a set of font descriptions.

IDL Definition
// Introduced in DOM Level 2:
interface CSSFontFaceRule : CSSRule {
  readonly attribute CSSStyleDeclaration  style;
};

Attributes
style of type CSSStyleDeclaration, readonly
The declaration-block of this rule.
Interface CSSPageRule (introduced in DOM Level 2)

The CSSPageRule interface represents a @page rule within a CSS style sheet. The @page rule is used to specify the dimensions, orientation, margins, etc. of a page box for paged media.

IDL Definition
// Introduced in DOM Level 2:
interface CSSPageRule : CSSRule {
           attribute DOMString        selectorText;
                                        // raises(DOMException) on setting

  readonly attribute CSSStyleDeclaration  style;
};

Attributes
selectorText of type DOMString
The parsable textual representation of the page selector for the rule.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified CSS string value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this rule is readonly.
style of type CSSStyleDeclaration, readonly
The declaration-block of this rule.
Interface CSSImportRule (introduced in DOM Level 2)

The CSSImportRule interface represents a @import rule within a CSS style sheet. The @import rule is used to import style rules from other style sheets.

IDL Definition
// Introduced in DOM Level 2:
interface CSSImportRule : CSSRule {
  readonly attribute DOMString        href;
  readonly attribute stylesheets::MediaList  media;
  readonly attribute CSSStyleSheet    styleSheet;
};

Attributes
href of type DOMString, readonly
The location of the style sheet to be imported. The attribute will not contain the "url(...)" specifier around the URI.
media of type stylesheets::MediaList, readonly
A list of media types for which this style sheet may be used.
styleSheet of type CSSStyleSheet, readonly
The style sheet referred to by this rule, if it has been loaded. The value of this attribute is null if the style sheet has not yet been loaded or if it will not be loaded (e.g. if the style sheet is for a media type not supported by the user agent).
Interface CSSCharsetRule (introduced in DOM Level 2)

The CSSCharsetRule interface represents a @charset rule in a CSS style sheet. The value of the encoding attribute does not affect the encoding of text data in the DOM objects; this encoding is always UTF-16. After a stylesheet is loaded, the value of the encoding attribute is the value found in the @charset rule. If there was no @charset in the original document, then no CSSCharsetRule is created. The value of the encoding attribute may also be used as a hint for the encoding used on serialization of the style sheet.

The value of the @charset rule (and therefore of the CSSCharsetRule) may not correspond to the encoding the document actually came in; character encoding information e.g. in an HTTP header, has priority (see CSS document representation) but this is not reflected in the CSSCharsetRule.

IDL Definition
// Introduced in DOM Level 2:
interface CSSCharsetRule : CSSRule {
           attribute DOMString        encoding;
                                        // raises(DOMException) on setting

};

Attributes
encoding of type DOMString
The encoding information used in this @charset rule.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified encoding value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this encoding rule is readonly.
Interface CSSUnknownRule (introduced in DOM Level 2)

The CSSUnknownRule interface represents an at-rule not supported by this user agent.

IDL Definition
// Introduced in DOM Level 2:
interface CSSUnknownRule : CSSRule {
};

Interface CSSStyleDeclaration (introduced in DOM Level 2)

The CSSStyleDeclaration interface represents a single CSS declaration block. This interface may be used to determine the style properties currently set in a block or to set style properties explicitly within the block.

While an implementation may not recognize all CSS properties within a CSS declaration block, it is expected to provide access to all specified properties in the style sheet through the CSSStyleDeclaration interface. Furthermore, implementations that support a specific level of CSS should correctly handle CSS shorthand properties for that level. For a further discussion of shorthand properties, see the CSS2Properties interface.

This interface is also used to provide a read-only access to the computed values of an element. See also the ViewCSS interface.

Note: The CSS Object Model doesn't provide an access to the specified or actual values of the CSS cascade.

IDL Definition
// Introduced in DOM Level 2:
interface CSSStyleDeclaration {
           attribute DOMString        cssText;
                                        // raises(DOMException) on setting

  DOMString          getPropertyValue(in DOMString propertyName);
  CSSValue           getPropertyCSSValue(in DOMString propertyName);
  DOMString          removeProperty(in DOMString propertyName)
                                        raises(DOMException);
  DOMString          getPropertyPriority(in DOMString propertyName);
  void               setProperty(in DOMString propertyName,
                                 in DOMString value,
                                 in DOMString priority)
                                        raises(DOMException);
  readonly attribute unsigned long    length;
  DOMString          item(in unsigned long index);
  readonly attribute CSSRule          parentRule;
};

Attributes
cssText of type DOMString
The parsable textual representation of the declaration block (excluding the surrounding curly braces). Setting this attribute will result in the parsing of the new value and resetting of all the properties in the declaration block including the removal or addition of properties.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified CSS string value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this declaration is readonly or a property is readonly.
length of type unsigned long, readonly
The number of properties that have been explicitly set in this declaration block. The range of valid indices is 0 to length-1 inclusive.
parentRule of type CSSRule, readonly
The CSS rule that contains this declaration block or null if this CSSStyleDeclaration is not attached to a CSSRule.
Methods
getPropertyCSSValue
Used to retrieve the object representation of the value of a CSS property if it has been explicitly set within this declaration block. This method returns null if the property is a shorthand property. Shorthand property values can only be accessed and modified as strings, using the getPropertyValue and setProperty methods.
Parameters
propertyName of type DOMString
The name of the CSS property. See the CSS property index.
Return Value

CSSValue

Returns the value of the property if it has been explicitly set for this declaration block. Returns null if the property has not been set.
No Exceptions
getPropertyPriority
Used to retrieve the priority of a CSS property (e.g. the "important" qualifier) if the property has been explicitly set in this declaration block.
Parameters
propertyName of type DOMString
The name of the CSS property. See the CSS property index.
Return Value

DOMString

A string representing the priority (e.g. "important") if one exists. The empty string if none exists.
No Exceptions
getPropertyValue
Used to retrieve the value of a CSS property if it has been explicitly set within this declaration block.
Parameters
propertyName of type DOMString
The name of the CSS property. See the CSS property index.
Return Value

DOMString

Returns the value of the property if it has been explicitly set for this declaration block. Returns the empty string if the property has not been set.
No Exceptions
item
Used to retrieve the properties that have been explicitly set in this declaration block. The order of the properties retrieved using this method does not have to be the order in which they were set. This method can be used to iterate over all properties in this declaration block.
Parameters
index of type unsigned long
Index of the property name to retrieve.
Return Value

DOMString

The name of the property at this ordinal position. The empty string if no property exists at this position.
No Exceptions
removeProperty
Used to remove a CSS property if it has been explicitly set within this declaration block.
Parameters
propertyName of type DOMString
The name of the CSS property. See the CSS property index.
Return Value

DOMString

Returns the value of the property if it has been explicitly set for this declaration block. Returns the empty string if the property has not been set or the property name does not correspond to a known CSS property.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this declaration is readonly or the property is readonly.
setProperty
Used to set a property value and priority within this declaration block.
Parameters
propertyName of type DOMString
The name of the CSS property. See the CSS property index.
value of type DOMString
The new value of the property.
priority of type DOMString
The new priority of the property (e.g. "important").
Exceptions

DOMException

SYNTAX_ERR: Raised if the specified value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this declaration is readonly or the property is readonly.
No Return Value
Interface CSSValue (introduced in DOM Level 2)

The CSSValue interface represents a simple or a complex value. A CSSValue object only occurs in a context of a CSS property.

IDL Definition
// Introduced in DOM Level 2:
interface CSSValue {

  // UnitTypes
  const unsigned short      CSS_INHERIT                    = 0;
  const unsigned short      CSS_PRIMITIVE_VALUE            = 1;
  const unsigned short      CSS_VALUE_LIST                 = 2;
  const unsigned short      CSS_CUSTOM                     = 3;

           attribute DOMString        cssText;
                                        // raises(DOMException) on setting

  readonly attribute unsigned short   cssValueType;
};

Definition group UnitTypes

An integer indicating which type of unit applies to the value.

Defined Constants
CSS_CUSTOM
The value is a custom value.
CSS_INHERIT
The value is inherited and the cssText contains "inherit".
CSS_PRIMITIVE_VALUE
The value is a primitive value and an instance of the CSSPrimitiveValue interface can be obtained by using binding-specific casting methods on this instance of the CSSValue interface.
CSS_VALUE_LIST
The value is a CSSValue list and an instance of the CSSValueList interface can be obtained by using binding-specific casting methods on this instance of the CSSValue interface.
Attributes
cssText of type DOMString
A string representation of the current value.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the specified CSS string value has a syntax error (according to the attached property) or is unparsable.

INVALID_MODIFICATION_ERR: Raised if the specified CSS string value represents a different type of values than the values allowed by the CSS property.

NO_MODIFICATION_ALLOWED_ERR: Raised if this value is readonly.
cssValueType of type unsigned short, readonly
A code defining the type of the value as defined above.
Interface CSSPrimitiveValue (introduced in DOM Level 2)

The CSSPrimitiveValue interface represents a single CSS value. This interface may be used to determine the value of a specific style property currently set in a block or to set a specific style property explicitly within the block. An instance of this interface might be obtained from the getPropertyCSSValue method of the CSSStyleDeclaration interface. A CSSPrimitiveValue object only occurs in a context of a CSS property.

Conversions are allowed between absolute values (from millimeters to centimeters, from degrees to radians, and so on) but not between relative values. (For example, a pixel value cannot be converted to a centimeter value.) Percentage values can't be converted since they are relative to the parent value (or another property value). There is one exception for color percentage values: since a color percentage value is relative to the range 0-255, a color percentage value can be converted to a number; (see also the RGBColor interface).

IDL Definition
// Introduced in DOM Level 2:
interface CSSPrimitiveValue : CSSValue {

  // UnitTypes
  const unsigned short      CSS_UNKNOWN                    = 0;
  const unsigned short      CSS_NUMBER                     = 1;
  const unsigned short      CSS_PERCENTAGE                 = 2;
  const unsigned short      CSS_EMS                        = 3;
  const unsigned short      CSS_EXS                        = 4;
  const unsigned short      CSS_PX                         = 5;
  const unsigned short      CSS_CM                         = 6;
  const unsigned short      CSS_MM                         = 7;
  const unsigned short      CSS_IN                         = 8;
  const unsigned short      CSS_PT                         = 9;
  const unsigned short      CSS_PC                         = 10;
  const unsigned short      CSS_DEG                        = 11;
  const unsigned short      CSS_RAD                        = 12;
  const unsigned short      CSS_GRAD                       = 13;
  const unsigned short      CSS_MS                         = 14;
  const unsigned short      CSS_S                          = 15;
  const unsigned short      CSS_HZ                         = 16;
  const unsigned short      CSS_KHZ                        = 17;
  const unsigned short      CSS_DIMENSION                  = 18;
  const unsigned short      CSS_STRING                     = 19;
  const unsigned short      CSS_URI                        = 20;
  const unsigned short      CSS_IDENT                      = 21;
  const unsigned short      CSS_ATTR                       = 22;
  const unsigned short      CSS_COUNTER                    = 23;
  const unsigned short      CSS_RECT                       = 24;
  const unsigned short      CSS_RGBCOLOR                   = 25;

  readonly attribute unsigned short   primitiveType;
  void               setFloatValue(in unsigned short unitType,
                                   in float floatValue)
                                        raises(DOMException);
  float              getFloatValue(in unsigned short unitType)
                                        raises(DOMException);
  void               setStringValue(in unsigned short stringType,
                                    in DOMString stringValue)
                                        raises(DOMException);
  DOMString          getStringValue()
                                        raises(DOMException);
  Counter            getCounterValue()
                                        raises(DOMException);
  Rect               getRectValue()
                                        raises(DOMException);
  RGBColor           getRGBColorValue()
                                        raises(DOMException);
};

Definition group UnitTypes

An integer indicating which type of unit applies to the value.

Defined Constants
CSS_ATTR
The value is a attribute function. The value can be obtained by using the getStringValue method.
CSS_CM
The value is a length (cm). The value can be obtained by using the getFloatValue method.
CSS_COUNTER
The value is a counter or counters function. The value can be obtained by using the getCounterValue method.
CSS_DEG
The value is an angle (deg). The value can be obtained by using the getFloatValue method.
CSS_DIMENSION
The value is a number with an unknown dimension. The value can be obtained by using the getFloatValue method.
CSS_EMS
The value is a length (ems). The value can be obtained by using the getFloatValue method.
CSS_EXS
The value is a length (exs). The value can be obtained by using the getFloatValue method.
CSS_GRAD
The value is an angle (grad). The value can be obtained by using the getFloatValue method.
CSS_HZ
The value is a frequency (Hz). The value can be obtained by using the getFloatValue method.
CSS_IDENT
The value is an identifier. The value can be obtained by using the getStringValue method.
CSS_IN
The value is a length (in). The value can be obtained by using the getFloatValue method.
CSS_KHZ
The value is a frequency (kHz). The value can be obtained by using the getFloatValue method.
CSS_MM
The value is a length (mm). The value can be obtained by using the getFloatValue method.
CSS_MS
The value is a time (ms). The value can be obtained by using the getFloatValue method.
CSS_NUMBER
The value is a simple number. The value can be obtained by using the getFloatValue method.
CSS_PC
The value is a length (pc). The value can be obtained by using the getFloatValue method.
CSS_PERCENTAGE
The value is a percentage. The value can be obtained by using the getFloatValue method.
CSS_PT
The value is a length (pt). The value can be obtained by using the getFloatValue method.
CSS_PX
The value is a length (px). The value can be obtained by using the getFloatValue method.
CSS_RAD
The value is an angle (rad). The value can be obtained by using the getFloatValue method.
CSS_RECT
The value is a rect function. The value can be obtained by using the getRectValue method.
CSS_RGBCOLOR
The value is a RGB color. The value can be obtained by using the getRGBColorValue method.
CSS_S
The value is a time (s). The value can be obtained by using the getFloatValue method.
CSS_STRING
The value is a STRING. The value can be obtained by using the getStringValue method.
CSS_UNKNOWN
The value is not a recognized CSS2 value. The value can only be obtained by using the cssText attribute.
CSS_URI
The value is a URI. The value can be obtained by using the getStringValue method.
Attributes
primitiveType of type unsigned short, readonly
The type of the value as defined by the constants specified above.
Methods
getCounterValue
This method is used to get the Counter value. If this CSS value doesn't contain a counter value, a DOMException is raised. Modification to the corresponding style property can be achieved using the Counter interface.
Return Value

Counter

The Counter value.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a Counter value (e.g. this is not CSS_COUNTER).
No Parameters
getFloatValue
This method is used to get a float value in a specified unit. If this CSS value doesn't contain a float value or can't be converted into the specified unit, a DOMException is raised.
Parameters
unitType of type unsigned short
A unit code to get the float value. The unit code can only be a float unit type (i.e. CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, CSS_DIMENSION).
Return Value

float

The float value in the specified unit.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a float value or if the float value can't be converted into the specified unit.
getRGBColorValue
This method is used to get the RGB color. If this CSS value doesn't contain a RGB color value, a DOMException is raised. Modification to the corresponding style property can be achieved using the RGBColor interface.
Return Value

RGBColor

the RGB color value.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the attached property can't return a RGB color value (e.g. this is not CSS_RGBCOLOR).
No Parameters
getRectValue
This method is used to get the Rect value. If this CSS value doesn't contain a rect value, a DOMException is raised. Modification to the corresponding style property can be achieved using the Rect interface.
Return Value

Rect

The Rect value.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a Rect value. (e.g. this is not CSS_RECT).
No Parameters
getStringValue
This method is used to get the string value. If the CSS value doesn't contain a string value, a DOMException is raised.

Note: Some properties (like 'font-family' or 'voice-family') convert a whitespace separated list of idents to a string.

Return Value

DOMString

The string value in the current unit. The current primitiveType can only be a string unit type (i.e. CSS_STRING, CSS_URI, CSS_IDENT and CSS_ATTR).
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a string value.
No Parameters
setFloatValue
A method to set the float value with a specified unit. If the property attached with this value can not accept the specified unit or the float value, the value will be unchanged and a DOMException will be raised.
Parameters
unitType of type unsigned short
A unit code as defined above. The unit code can only be a float unit type (i.e. CSS_NUMBER, CSS_PERCENTAGE, CSS_EMS, CSS_EXS, CSS_PX, CSS_CM, CSS_MM, CSS_IN, CSS_PT, CSS_PC, CSS_DEG, CSS_RAD, CSS_GRAD, CSS_MS, CSS_S, CSS_HZ, CSS_KHZ, CSS_DIMENSION).
floatValue of type float
The new float value.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the attached property doesn't support the float value or the unit type.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
No Return Value
setStringValue
A method to set the string value with the specified unit. If the property attached to this value can't accept the specified unit or the string value, the value will be unchanged and a DOMException will be raised.
Parameters
stringType of type unsigned short
A string code as defined above. The string code can only be a string unit type (i.e. CSS_STRING, CSS_URI, CSS_IDENT, and CSS_ATTR).
stringValue of type DOMString
The new string value.
Exceptions

DOMException

INVALID_ACCESS_ERR: Raised if the CSS value doesn't contain a string value or if the string value can't be converted into the specified unit.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
No Return Value
Interface CSSValueList (introduced in DOM Level 2)

The CSSValueList interface provides the abstraction of an ordered collection of CSS values.

Some properties allow an empty list into their syntax. In that case, these properties take the none identifier. So, an empty list means that the property has the value none.

The items in the CSSValueList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 2:
interface CSSValueList : CSSValue {
  readonly attribute unsigned long    length;
  CSSValue           item(in unsigned long index);
};

Attributes
length of type unsigned long, readonly
The number of CSSValues in the list. The range of valid values of the indices is 0 to length-1 inclusive.
Methods
item
Used to retrieve a CSSValue by ordinal index. The order in this collection represents the order of the values in the CSS style property. If index is greater than or equal to the number of values in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

CSSValue

The CSSValue at the index position in the CSSValueList, or null if that is not a valid index.
No Exceptions
Interface RGBColor (introduced in DOM Level 2)

The RGBColor interface is used to represent any RGB color value. This interface reflects the values in the underlying style property. Hence, modifications made to the CSSPrimitiveValue objects modify the style property.

A specified RGB color is not clipped (even if the number is outside the range 0-255 or 0%-100%). A computed RGB color is clipped depending on the device.

Even if a style sheet can only contain an integer for a color value, the internal storage of this integer is a float, and this can be used as a float in the specified or the computed style.

A color percentage value can always be converted to a number and vice versa.

IDL Definition
// Introduced in DOM Level 2:
interface RGBColor {
  readonly attribute CSSPrimitiveValue  red;
  readonly attribute CSSPrimitiveValue  green;
  readonly attribute CSSPrimitiveValue  blue;
};

Attributes
blue of type CSSPrimitiveValue, readonly
This attribute is used for the blue value of the RGB color.
green of type CSSPrimitiveValue, readonly
This attribute is used for the green value of the RGB color.
red of type CSSPrimitiveValue, readonly
This attribute is used for the red value of the RGB color.
Interface Rect (introduced in DOM Level 2)

The Rect interface is used to represent any rect value. This interface reflects the values in the underlying style property. Hence, modifications made to the CSSPrimitiveValue objects modify the style property.

IDL Definition
// Introduced in DOM Level 2:
interface Rect {
  readonly attribute CSSPrimitiveValue  top;
  readonly attribute CSSPrimitiveValue  right;
  readonly attribute CSSPrimitiveValue  bottom;
  readonly attribute CSSPrimitiveValue  left;
};

Attributes
bottom of type CSSPrimitiveValue, readonly
This attribute is used for the bottom of the rect.
left of type CSSPrimitiveValue, readonly
This attribute is used for the left of the rect.
right of type CSSPrimitiveValue, readonly
This attribute is used for the right of the rect.
top of type CSSPrimitiveValue, readonly
This attribute is used for the top of the rect.
Interface Counter (introduced in DOM Level 2)

The Counter interface is used to represent any counter or counters function value. This interface reflects the values in the underlying style property.

IDL Definition
// Introduced in DOM Level 2:
interface Counter {
  readonly attribute DOMString        identifier;
  readonly attribute DOMString        listStyle;
  readonly attribute DOMString        separator;
};

Attributes
identifier of type DOMString, readonly
This attribute is used for the identifier of the counter.
listStyle of type DOMString, readonly
This attribute is used for the style of the list.
separator of type DOMString, readonly
This attribute is used for the separator of the nested counters.

2.2.1. Override and computed style sheet

Interface ViewCSS (introduced in DOM Level 2)

This interface represents a CSS view. The getComputedStyle method provides a read only access to the computed values of an element.

The expectation is that an instance of the ViewCSS interface can be obtained by using binding-specific casting methods on an instance of the AbstractView interface.

Since a computed style is related to an Element node, if this element is removed from the document, the associated CSSStyleDeclaration and CSSValue related to this declaration are no longer valid.

IDL Definition
// Introduced in DOM Level 2:
interface ViewCSS : views::AbstractView {
  CSSStyleDeclaration getComputedStyle(in Element elt,
                                       in DOMString pseudoElt);
};

Methods
getComputedStyle
This method is used to get the computed style as it is defined in [CSS2].
Parameters
elt of type Element
The element whose style is to be computed. This parameter cannot be null.
pseudoElt of type DOMString
The pseudo-element or null if none.
Return Value

CSSStyleDeclaration

The computed style. The CSSStyleDeclaration is read-only and contains only absolute values.
No Exceptions
Interface DocumentCSS (introduced in DOM Level 2)

This interface represents a document with a CSS view.

The getOverrideStyle method provides a mechanism through which a DOM author could effect immediate change to the style of an element without modifying the explicitly linked style sheets of a document or the inline style of elements in the style sheets. This style sheet comes after the author style sheet in the cascade algorithm and is called override style sheet. The override style sheet takes precedence over author style sheets. An "!important" declaration still takes precedence over a normal declaration. Override, author, and user style sheets all may contain "!important" declarations. User "!important" rules take precedence over both override and author "!important" rules, and override "!important" rules take precedence over author "!important" rules.

The expectation is that an instance of the DocumentCSS interface can be obtained by using binding-specific casting methods on an instance of the Document interface.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentCSS : stylesheets::DocumentStyle {
  CSSStyleDeclaration getOverrideStyle(in Element elt,
                                       in DOMString pseudoElt);
};

Methods
getOverrideStyle
This method is used to retrieve the override style declaration for a specified element and a specified pseudo-element.
Parameters
elt of type Element
The element whose style is to be modified. This parameter cannot be null.
pseudoElt of type DOMString
The pseudo-element or null if none.
Return Value

CSSStyleDeclaration

The override style declaration.
No Exceptions

2.2.2. Style sheet creation

Interface DOMImplementationCSS (introduced in DOM Level 2)

This interface allows the DOM user to create a CSSStyleSheet outside the context of a document. There is no way to associate the new CSSStyleSheet with a document in DOM Level 2.

IDL Definition
// Introduced in DOM   Level 2:
interface DOMImplementationCSS : DOMImplementation {
  CSSStyleSheet      createCSSStyleSheet(in DOMString title,
                                         in DOMString media)
                                        raises(DOMException);
};

Methods
createCSSStyleSheet
Creates a new CSSStyleSheet.
Parameters
title of type DOMString
The advisory title. See also the Style Sheet Interfaces section.
media of type DOMString
The comma-separated list of media associated with the new style sheet. See also the Style Sheet Interfaces section.
Return Value

CSSStyleSheet

A new CSS style sheet.
Exceptions

DOMException

SYNTAX_ERR: Raised if the specified media string value has a syntax error and is unparsable.

2.2.3. Element with CSS inline style

Interface ElementCSSInlineStyle (introduced in DOM Level 2)

Inline style information attached to elements is exposed through the style attribute. This represents the contents of the STYLE attribute for HTML elements (or elements in other schemas or DTDs which use the STYLE attribute in the same way). The expectation is that an instance of the ElementCSSInlineStyle interface can be obtained by using binding-specific casting methods on an instance of the Element interface when the element supports inline CSS style informations.

IDL Definition
// Introduced in DOM Level 2:
interface ElementCSSInlineStyle {
  readonly attribute CSSStyleDeclaration  style;
};

Attributes
style of type CSSStyleDeclaration, readonly
The style attribute.

2.3. CSS2 Extended Interface

The interface found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "CSS2" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "CSS" feature defined defined in CSS Fundamental Interfaces. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

Interface CSS2Properties (introduced in DOM Level 2)

The CSS2Properties interface represents a convenience mechanism for retrieving and setting properties within a CSSStyleDeclaration. The attributes of this interface correspond to all the properties specified in CSS2. Getting an attribute of this interface is equivalent to calling the getPropertyValue method of the CSSStyleDeclaration interface. Setting an attribute of this interface is equivalent to calling the setProperty method of the CSSStyleDeclaration interface.

A conformant implementation of the CSS module is not required to implement the CSS2Properties interface. If an implementation does implement this interface, the expectation is that language-specific methods can be used to cast from an instance of the CSSStyleDeclaration interface to the CSS2Properties interface.

If an implementation does implement this interface, it is expected to understand the specific syntax of the shorthand properties, and apply their semantics; when the margin property is set, for example, the marginTop, marginRight, marginBottom and marginLeft properties are actually being set by the underlying implementation.

When dealing with CSS "shorthand" properties, the shorthand properties should be decomposed into their component longhand properties as appropriate, and when querying for their value, the form returned should be the shortest form exactly equivalent to the declarations made in the ruleset. However, if there is no shorthand declaration that could be added to the ruleset without changing in any way the rules already declared in the ruleset (i.e., by adding longhand rules that were previously not declared in the ruleset), then the empty string should be returned for the shorthand property.

For example, querying for the font property should not return "normal normal normal 14pt/normal Arial, sans-serif", when "14pt Arial, sans-serif" suffices. (The normals are initial values, and are implied by use of the longhand property.)

If the values for all the longhand properties that compose a particular string are the initial values, then a string consisting of all the initial values should be returned (e.g. a border-width value of "medium" should be returned as such, not as "").

For some shorthand properties that take missing values from other sides, such as the margin, padding, and border-[width|style|color] properties, the minimum number of sides possible should be used; i.e., "0px 10px" will be returned instead of "0px 10px 0px 10px".

If the value of a shorthand property can not be decomposed into its component longhand properties, as is the case for the font property with a value of "menu", querying for the values of the component longhand properties should return the empty string.

IDL Definition
// Introduced in DOM Level 2:
interface CSS2Properties {
           attribute DOMString        azimuth;
                                        // raises(DOMException) on setting

           attribute DOMString        background;
                                        // raises(DOMException) on setting

           attribute DOMString        backgroundAttachment;
                                        // raises(DOMException) on setting

           attribute DOMString        backgroundColor;
                                        // raises(DOMException) on setting

           attribute DOMString        backgroundImage;
                                        // raises(DOMException) on setting

           attribute DOMString        backgroundPosition;
                                        // raises(DOMException) on setting

           attribute DOMString        backgroundRepeat;
                                        // raises(DOMException) on setting

           attribute DOMString        border;
                                        // raises(DOMException) on setting

           attribute DOMString        borderCollapse;
                                        // raises(DOMException) on setting

           attribute DOMString        borderColor;
                                        // raises(DOMException) on setting

           attribute DOMString        borderSpacing;
                                        // raises(DOMException) on setting

           attribute DOMString        borderStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        borderTop;
                                        // raises(DOMException) on setting

           attribute DOMString        borderRight;
                                        // raises(DOMException) on setting

           attribute DOMString        borderBottom;
                                        // raises(DOMException) on setting

           attribute DOMString        borderLeft;
                                        // raises(DOMException) on setting

           attribute DOMString        borderTopColor;
                                        // raises(DOMException) on setting

           attribute DOMString        borderRightColor;
                                        // raises(DOMException) on setting

           attribute DOMString        borderBottomColor;
                                        // raises(DOMException) on setting

           attribute DOMString        borderLeftColor;
                                        // raises(DOMException) on setting

           attribute DOMString        borderTopStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        borderRightStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        borderBottomStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        borderLeftStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        borderTopWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        borderRightWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        borderBottomWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        borderLeftWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        borderWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        bottom;
                                        // raises(DOMException) on setting

           attribute DOMString        captionSide;
                                        // raises(DOMException) on setting

           attribute DOMString        clear;
                                        // raises(DOMException) on setting

           attribute DOMString        clip;
                                        // raises(DOMException) on setting

           attribute DOMString        color;
                                        // raises(DOMException) on setting

           attribute DOMString        content;
                                        // raises(DOMException) on setting

           attribute DOMString        counterIncrement;
                                        // raises(DOMException) on setting

           attribute DOMString        counterReset;
                                        // raises(DOMException) on setting

           attribute DOMString        cue;
                                        // raises(DOMException) on setting

           attribute DOMString        cueAfter;
                                        // raises(DOMException) on setting

           attribute DOMString        cueBefore;
                                        // raises(DOMException) on setting

           attribute DOMString        cursor;
                                        // raises(DOMException) on setting

           attribute DOMString        direction;
                                        // raises(DOMException) on setting

           attribute DOMString        display;
                                        // raises(DOMException) on setting

           attribute DOMString        elevation;
                                        // raises(DOMException) on setting

           attribute DOMString        emptyCells;
                                        // raises(DOMException) on setting

           attribute DOMString        cssFloat;
                                        // raises(DOMException) on setting

           attribute DOMString        font;
                                        // raises(DOMException) on setting

           attribute DOMString        fontFamily;
                                        // raises(DOMException) on setting

           attribute DOMString        fontSize;
                                        // raises(DOMException) on setting

           attribute DOMString        fontSizeAdjust;
                                        // raises(DOMException) on setting

           attribute DOMString        fontStretch;
                                        // raises(DOMException) on setting

           attribute DOMString        fontStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        fontVariant;
                                        // raises(DOMException) on setting

           attribute DOMString        fontWeight;
                                        // raises(DOMException) on setting

           attribute DOMString        height;
                                        // raises(DOMException) on setting

           attribute DOMString        left;
                                        // raises(DOMException) on setting

           attribute DOMString        letterSpacing;
                                        // raises(DOMException) on setting

           attribute DOMString        lineHeight;
                                        // raises(DOMException) on setting

           attribute DOMString        listStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        listStyleImage;
                                        // raises(DOMException) on setting

           attribute DOMString        listStylePosition;
                                        // raises(DOMException) on setting

           attribute DOMString        listStyleType;
                                        // raises(DOMException) on setting

           attribute DOMString        margin;
                                        // raises(DOMException) on setting

           attribute DOMString        marginTop;
                                        // raises(DOMException) on setting

           attribute DOMString        marginRight;
                                        // raises(DOMException) on setting

           attribute DOMString        marginBottom;
                                        // raises(DOMException) on setting

           attribute DOMString        marginLeft;
                                        // raises(DOMException) on setting

           attribute DOMString        markerOffset;
                                        // raises(DOMException) on setting

           attribute DOMString        marks;
                                        // raises(DOMException) on setting

           attribute DOMString        maxHeight;
                                        // raises(DOMException) on setting

           attribute DOMString        maxWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        minHeight;
                                        // raises(DOMException) on setting

           attribute DOMString        minWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        orphans;
                                        // raises(DOMException) on setting

           attribute DOMString        outline;
                                        // raises(DOMException) on setting

           attribute DOMString        outlineColor;
                                        // raises(DOMException) on setting

           attribute DOMString        outlineStyle;
                                        // raises(DOMException) on setting

           attribute DOMString        outlineWidth;
                                        // raises(DOMException) on setting

           attribute DOMString        overflow;
                                        // raises(DOMException) on setting

           attribute DOMString        padding;
                                        // raises(DOMException) on setting

           attribute DOMString        paddingTop;
                                        // raises(DOMException) on setting

           attribute DOMString        paddingRight;
                                        // raises(DOMException) on setting

           attribute DOMString        paddingBottom;
                                        // raises(DOMException) on setting

           attribute DOMString        paddingLeft;
                                        // raises(DOMException) on setting

           attribute DOMString        page;
                                        // raises(DOMException) on setting

           attribute DOMString        pageBreakAfter;
                                        // raises(DOMException) on setting

           attribute DOMString        pageBreakBefore;
                                        // raises(DOMException) on setting

           attribute DOMString        pageBreakInside;
                                        // raises(DOMException) on setting

           attribute DOMString        pause;
                                        // raises(DOMException) on setting

           attribute DOMString        pauseAfter;
                                        // raises(DOMException) on setting

           attribute DOMString        pauseBefore;
                                        // raises(DOMException) on setting

           attribute DOMString        pitch;
                                        // raises(DOMException) on setting

           attribute DOMString        pitchRange;
                                        // raises(DOMException) on setting

           attribute DOMString        playDuring;
                                        // raises(DOMException) on setting

           attribute DOMString        position;
                                        // raises(DOMException) on setting

           attribute DOMString        quotes;
                                        // raises(DOMException) on setting

           attribute DOMString        richness;
                                        // raises(DOMException) on setting

           attribute DOMString        right;
                                        // raises(DOMException) on setting

           attribute DOMString        size;
                                        // raises(DOMException) on setting

           attribute DOMString        speak;
                                        // raises(DOMException) on setting

           attribute DOMString        speakHeader;
                                        // raises(DOMException) on setting

           attribute DOMString        speakNumeral;
                                        // raises(DOMException) on setting

           attribute DOMString        speakPunctuation;
                                        // raises(DOMException) on setting

           attribute DOMString        speechRate;
                                        // raises(DOMException) on setting

           attribute DOMString        stress;
                                        // raises(DOMException) on setting

           attribute DOMString        tableLayout;
                                        // raises(DOMException) on setting

           attribute DOMString        textAlign;
                                        // raises(DOMException) on setting

           attribute DOMString        textDecoration;
                                        // raises(DOMException) on setting

           attribute DOMString        textIndent;
                                        // raises(DOMException) on setting

           attribute DOMString        textShadow;
                                        // raises(DOMException) on setting

           attribute DOMString        textTransform;
                                        // raises(DOMException) on setting

           attribute DOMString        top;
                                        // raises(DOMException) on setting

           attribute DOMString        unicodeBidi;
                                        // raises(DOMException) on setting

           attribute DOMString        verticalAlign;
                                        // raises(DOMException) on setting

           attribute DOMString        visibility;
                                        // raises(DOMException) on setting

           attribute DOMString        voiceFamily;
                                        // raises(DOMException) on setting

           attribute DOMString        volume;
                                        // raises(DOMException) on setting

           attribute DOMString        whiteSpace;
                                        // raises(DOMException) on setting

           attribute DOMString        widows;
                                        // raises(DOMException) on setting

           attribute DOMString        width;
                                        // raises(DOMException) on setting

           attribute DOMString        wordSpacing;
                                        // raises(DOMException) on setting

           attribute DOMString        zIndex;
                                        // raises(DOMException) on setting

};

Attributes
azimuth of type DOMString
See the azimuth property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
background of type DOMString
See the background property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
backgroundAttachment of type DOMString
See the background-attachment property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
backgroundColor of type DOMString
See the background-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
backgroundImage of type DOMString
See the background-image property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
backgroundPosition of type DOMString
See the background-position property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
backgroundRepeat of type DOMString
See the background-repeat property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
border of type DOMString
See the border property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderBottom of type DOMString
See the border-bottom property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderBottomColor of type DOMString
See the border-bottom-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderBottomStyle of type DOMString
See the border-bottom-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderBottomWidth of type DOMString
See the border-bottom-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderCollapse of type DOMString
See the border-collapse property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderColor of type DOMString
See the border-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderLeft of type DOMString
See the border-left property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderLeftColor of type DOMString
See the border-left-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderLeftStyle of type DOMString
See the border-left-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderLeftWidth of type DOMString
See the border-left-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderRight of type DOMString
See the border-right property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderRightColor of type DOMString
See the border-right-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderRightStyle of type DOMString
See the border-right-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderRightWidth of type DOMString
See the border-right-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderSpacing of type DOMString
See the border-spacing property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderStyle of type DOMString
See the border-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderTop of type DOMString
See the border-top property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderTopColor of type DOMString
See the border-top-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderTopStyle of type DOMString
See the border-top-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderTopWidth of type DOMString
See the border-top-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
borderWidth of type DOMString
See the border-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
bottom of type DOMString
See the bottom property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
captionSide of type DOMString
See the caption-side property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
clear of type DOMString
See the clear property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
clip of type DOMString
See the clip property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
color of type DOMString
See the color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
content of type DOMString
See the content property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
counterIncrement of type DOMString
See the counter-increment property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
counterReset of type DOMString
See the counter-reset property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
cssFloat of type DOMString
See the float property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
cue of type DOMString
See the cue property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
cueAfter of type DOMString
See the cue-after property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
cueBefore of type DOMString
See the cue-before property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
cursor of type DOMString
See the cursor property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
direction of type DOMString
See the direction property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
display of type DOMString
See the display property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
elevation of type DOMString
See the elevation property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
emptyCells of type DOMString
See the empty-cells property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
font of type DOMString
See the font property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontFamily of type DOMString
See the font-family property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontSize of type DOMString
See the font-size property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontSizeAdjust of type DOMString
See the font-size-adjust property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontStretch of type DOMString
See the font-stretch property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontStyle of type DOMString
See the font-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontVariant of type DOMString
See the font-variant property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
fontWeight of type DOMString
See the font-weight property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
height of type DOMString
See the height property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
left of type DOMString
See the left property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
letterSpacing of type DOMString
See the letter-spacing property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
lineHeight of type DOMString
See the line-height property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
listStyle of type DOMString
See the list-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
listStyleImage of type DOMString
See the list-style-image property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
listStylePosition of type DOMString
See the list-style-position property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
listStyleType of type DOMString
See the list-style-type property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
margin of type DOMString
See the margin property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
marginBottom of type DOMString
See the margin-bottom property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
marginLeft of type DOMString
See the margin-left property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
marginRight of type DOMString
See the margin-right property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
marginTop of type DOMString
See the margin-top property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
markerOffset of type DOMString
See the marker-offset property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
marks of type DOMString
See the marks property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
maxHeight of type DOMString
See the max-height property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
maxWidth of type DOMString
See the max-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
minHeight of type DOMString
See the min-height property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
minWidth of type DOMString
See the min-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
orphans of type DOMString
See the orphans property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
outline of type DOMString
See the outline property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
outlineColor of type DOMString
See the outline-color property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
outlineStyle of type DOMString
See the outline-style property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
outlineWidth of type DOMString
See the outline-width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
overflow of type DOMString
See the overflow property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
padding of type DOMString
See the padding property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
paddingBottom of type DOMString
See the padding-bottom property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
paddingLeft of type DOMString
See the padding-left property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
paddingRight of type DOMString
See the padding-right property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
paddingTop of type DOMString
See the padding-top property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
page of type DOMString
See the page property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pageBreakAfter of type DOMString
See the page-break-after property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pageBreakBefore of type DOMString
See the page-break-before property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pageBreakInside of type DOMString
See the page-break-inside property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pause of type DOMString
See the pause property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pauseAfter of type DOMString
See the pause-after property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pauseBefore of type DOMString
See the pause-before property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pitch of type DOMString
See the pitch property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
pitchRange of type DOMString
See the pitch-range property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
playDuring of type DOMString
See the play-during property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
position of type DOMString
See the position property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
quotes of type DOMString
See the quotes property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
richness of type DOMString
See the richness property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
right of type DOMString
See the right property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
size of type DOMString
See the size property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
speak of type DOMString
See the speak property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
speakHeader of type DOMString
See the speak-header property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
speakNumeral of type DOMString
See the speak-numeral property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
speakPunctuation of type DOMString
See the speak-punctuation property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
speechRate of type DOMString
See the speech-rate property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
stress of type DOMString
See the stress property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
tableLayout of type DOMString
See the table-layout property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
textAlign of type DOMString
See the text-align property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
textDecoration of type DOMString
See the text-decoration property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
textIndent of type DOMString
See the text-indent property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
textShadow of type DOMString
See the text-shadow property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
textTransform of type DOMString
See the text-transform property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
top of type DOMString
See the top property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
unicodeBidi of type DOMString
See the unicode-bidi property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
verticalAlign of type DOMString
See the vertical-align property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
visibility of type DOMString
See the visibility property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
voiceFamily of type DOMString
See the voice-family property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
volume of type DOMString
See the volume property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
whiteSpace of type DOMString
See the white-space property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
widows of type DOMString
See the widows property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
width of type DOMString
See the width property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
wordSpacing of type DOMString
See the word-spacing property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
zIndex of type DOMString
See the z-index property definition in CSS2.
Exceptions on setting

DOMException

SYNTAX_ERR: Raised if the new value has a syntax error and is unparsable.

NO_MODIFICATION_ALLOWED_ERR: Raised if this property is readonly.
previous next contents index


IDL Definitions

previous next contents index

13 November, 2000

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Style definitions. The definitions are divided into Stylesheets and CSS.

The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/idl.zip

A.1: Document Object Model Style Sheets

stylesheets.idl:

// File: stylesheets.idl

#ifndef _STYLESHEETS_IDL_
#define _STYLESHEETS_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module stylesheets
{

  typedef dom::DOMString DOMString;
  typedef dom::Node Node;

  interface MediaList;

  // Introduced in DOM Level 2:
  interface StyleSheet {
    readonly attribute DOMString        type;
             attribute boolean          disabled;
    readonly attribute Node             ownerNode;
    readonly attribute StyleSheet       parentStyleSheet;
    readonly attribute DOMString        href;
    readonly attribute DOMString        title;
    readonly attribute MediaList        media;
  };

  // Introduced in DOM Level 2:
  interface StyleSheetList {
    readonly attribute unsigned long    length;
    StyleSheet         item(in unsigned long index);
  };

  // Introduced in DOM Level 2:
  interface MediaList {
             attribute DOMString        mediaText;
                                        // raises(dom::DOMException) on setting

    readonly attribute unsigned long    length;
    DOMString          item(in unsigned long index);
    void               deleteMedium(in DOMString oldMedium)
                                        raises(dom::DOMException);
    void               appendMedium(in DOMString newMedium)
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface LinkStyle {
    readonly attribute StyleSheet       sheet;
  };

  // Introduced in DOM Level 2:
  interface DocumentStyle {
    readonly attribute StyleSheetList   styleSheets;
  };
};

#endif // _STYLESHEETS_IDL_

A.2: Document Object Model CSS

css.idl:

// File: css.idl

#ifndef _CSS_IDL_
#define _CSS_IDL_

#include "dom.idl"
#include "stylesheets.idl"
#include "views.idl"

#pragma prefix "dom.w3c.org"
module css
{

  typedef dom::DOMString DOMString;
  typedef dom::Element Element;
  typedef dom::DOMImplementation DOMImplementation;

  interface CSSRule;
  interface CSSStyleSheet;
  interface CSSStyleDeclaration;
  interface CSSValue;
  interface Counter;
  interface Rect;
  interface RGBColor;

  // Introduced in DOM Level 2:
  interface CSSRuleList {
    readonly attribute unsigned long    length;
    CSSRule            item(in unsigned long index);
  };

  // Introduced in DOM Level 2:
  interface CSSRule {

    // RuleType
    const unsigned short      UNKNOWN_RULE                   = 0;
    const unsigned short      STYLE_RULE                     = 1;
    const unsigned short      CHARSET_RULE                   = 2;
    const unsigned short      IMPORT_RULE                    = 3;
    const unsigned short      MEDIA_RULE                     = 4;
    const unsigned short      FONT_FACE_RULE                 = 5;
    const unsigned short      PAGE_RULE                      = 6;

    readonly attribute unsigned short   type;
             attribute DOMString        cssText;
                                        // raises(dom::DOMException) on setting

    readonly attribute CSSStyleSheet    parentStyleSheet;
    readonly attribute CSSRule          parentRule;
  };

  // Introduced in DOM Level 2:
  interface CSSStyleRule : CSSRule {
             attribute DOMString        selectorText;
                                        // raises(dom::DOMException) on setting

    readonly attribute CSSStyleDeclaration  style;
  };

  // Introduced in DOM Level 2:
  interface CSSMediaRule : CSSRule {
    readonly attribute stylesheets::MediaList  media;
    readonly attribute CSSRuleList      cssRules;
    unsigned long      insertRule(in DOMString rule,
                                  in unsigned long index)
                                        raises(dom::DOMException);
    void               deleteRule(in unsigned long index)
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface CSSFontFaceRule : CSSRule {
    readonly attribute CSSStyleDeclaration  style;
  };

  // Introduced in DOM Level 2:
  interface CSSPageRule : CSSRule {
             attribute DOMString        selectorText;
                                        // raises(dom::DOMException) on setting

    readonly attribute CSSStyleDeclaration  style;
  };

  // Introduced in DOM Level 2:
  interface CSSImportRule : CSSRule {
    readonly attribute DOMString        href;
    readonly attribute stylesheets::MediaList  media;
    readonly attribute CSSStyleSheet    styleSheet;
  };

  // Introduced in DOM Level 2:
  interface CSSCharsetRule : CSSRule {
             attribute DOMString        encoding;
                                        // raises(dom::DOMException) on setting

  };

  // Introduced in DOM Level 2:
  interface CSSUnknownRule : CSSRule {
  };

  // Introduced in DOM Level 2:
  interface CSSStyleDeclaration {
             attribute DOMString        cssText;
                                        // raises(dom::DOMException) on setting

    DOMString          getPropertyValue(in DOMString propertyName);
    CSSValue           getPropertyCSSValue(in DOMString propertyName);
    DOMString          removeProperty(in DOMString propertyName)
                                        raises(dom::DOMException);
    DOMString          getPropertyPriority(in DOMString propertyName);
    void               setProperty(in DOMString propertyName,
                                   in DOMString value,
                                   in DOMString priority)
                                        raises(dom::DOMException);
    readonly attribute unsigned long    length;
    DOMString          item(in unsigned long index);
    readonly attribute CSSRule          parentRule;
  };

  // Introduced in DOM Level 2:
  interface CSSValue {

    // UnitTypes
    const unsigned short      CSS_INHERIT                    = 0;
    const unsigned short      CSS_PRIMITIVE_VALUE            = 1;
    const unsigned short      CSS_VALUE_LIST                 = 2;
    const unsigned short      CSS_CUSTOM                     = 3;

             attribute DOMString        cssText;
                                        // raises(dom::DOMException) on setting

    readonly attribute unsigned short   cssValueType;
  };

  // Introduced in DOM Level 2:
  interface CSSPrimitiveValue : CSSValue {

    // UnitTypes
    const unsigned short      CSS_UNKNOWN                    = 0;
    const unsigned short      CSS_NUMBER                     = 1;
    const unsigned short      CSS_PERCENTAGE                 = 2;
    const unsigned short      CSS_EMS                        = 3;
    const unsigned short      CSS_EXS                        = 4;
    const unsigned short      CSS_PX                         = 5;
    const unsigned short      CSS_CM                         = 6;
    const unsigned short      CSS_MM                         = 7;
    const unsigned short      CSS_IN                         = 8;
    const unsigned short      CSS_PT                         = 9;
    const unsigned short      CSS_PC                         = 10;
    const unsigned short      CSS_DEG                        = 11;
    const unsigned short      CSS_RAD                        = 12;
    const unsigned short      CSS_GRAD                       = 13;
    const unsigned short      CSS_MS                         = 14;
    const unsigned short      CSS_S                          = 15;
    const unsigned short      CSS_HZ                         = 16;
    const unsigned short      CSS_KHZ                        = 17;
    const unsigned short      CSS_DIMENSION                  = 18;
    const unsigned short      CSS_STRING                     = 19;
    const unsigned short      CSS_URI                        = 20;
    const unsigned short      CSS_IDENT                      = 21;
    const unsigned short      CSS_ATTR                       = 22;
    const unsigned short      CSS_COUNTER                    = 23;
    const unsigned short      CSS_RECT                       = 24;
    const unsigned short      CSS_RGBCOLOR                   = 25;

    readonly attribute unsigned short   primitiveType;
    void               setFloatValue(in unsigned short unitType,
                                     in float floatValue)
                                        raises(dom::DOMException);
    float              getFloatValue(in unsigned short unitType)
                                        raises(dom::DOMException);
    void               setStringValue(in unsigned short stringType,
                                      in DOMString stringValue)
                                        raises(dom::DOMException);
    DOMString          getStringValue()
                                        raises(dom::DOMException);
    Counter            getCounterValue()
                                        raises(dom::DOMException);
    Rect               getRectValue()
                                        raises(dom::DOMException);
    RGBColor           getRGBColorValue()
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface CSSValueList : CSSValue {
    readonly attribute unsigned long    length;
    CSSValue           item(in unsigned long index);
  };

  // Introduced in DOM Level 2:
  interface RGBColor {
    readonly attribute CSSPrimitiveValue  red;
    readonly attribute CSSPrimitiveValue  green;
    readonly attribute CSSPrimitiveValue  blue;
  };

  // Introduced in DOM Level 2:
  interface Rect {
    readonly attribute CSSPrimitiveValue  top;
    readonly attribute CSSPrimitiveValue  right;
    readonly attribute CSSPrimitiveValue  bottom;
    readonly attribute CSSPrimitiveValue  left;
  };

  // Introduced in DOM Level 2:
  interface Counter {
    readonly attribute DOMString        identifier;
    readonly attribute DOMString        listStyle;
    readonly attribute DOMString        separator;
  };

  // Introduced in DOM Level 2:
  interface ElementCSSInlineStyle {
    readonly attribute CSSStyleDeclaration  style;
  };

  // Introduced in DOM Level 2:
  interface CSS2Properties {
             attribute DOMString        azimuth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        background;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        backgroundAttachment;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        backgroundColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        backgroundImage;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        backgroundPosition;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        backgroundRepeat;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        border;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderCollapse;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderSpacing;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderTop;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderRight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderBottom;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderLeft;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderTopColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderRightColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderBottomColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderLeftColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderTopStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderRightStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderBottomStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderLeftStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderTopWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderRightWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderBottomWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderLeftWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        borderWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        bottom;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        captionSide;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        clear;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        clip;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        color;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        content;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        counterIncrement;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        counterReset;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        cue;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        cueAfter;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        cueBefore;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        cursor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        direction;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        display;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        elevation;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        emptyCells;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        cssFloat;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        font;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontFamily;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontSize;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontSizeAdjust;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontStretch;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontVariant;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        fontWeight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        height;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        left;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        letterSpacing;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        lineHeight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        listStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        listStyleImage;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        listStylePosition;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        listStyleType;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        margin;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        marginTop;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        marginRight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        marginBottom;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        marginLeft;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        markerOffset;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        marks;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        maxHeight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        maxWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        minHeight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        minWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        orphans;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        outline;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        outlineColor;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        outlineStyle;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        outlineWidth;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        overflow;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        padding;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        paddingTop;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        paddingRight;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        paddingBottom;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        paddingLeft;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        page;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pageBreakAfter;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pageBreakBefore;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pageBreakInside;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pause;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pauseAfter;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pauseBefore;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pitch;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        pitchRange;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        playDuring;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        position;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        quotes;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        richness;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        right;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        size;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        speak;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        speakHeader;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        speakNumeral;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        speakPunctuation;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        speechRate;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        stress;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        tableLayout;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        textAlign;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        textDecoration;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        textIndent;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        textShadow;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        textTransform;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        top;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        unicodeBidi;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        verticalAlign;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        visibility;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        voiceFamily;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        volume;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        whiteSpace;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        widows;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        width;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        wordSpacing;
                                        // raises(dom::DOMException) on setting

             attribute DOMString        zIndex;
                                        // raises(dom::DOMException) on setting

  };

  // Introduced in DOM Level 2:
  interface CSSStyleSheet : stylesheets::StyleSheet {
    readonly attribute CSSRule          ownerRule;
    readonly attribute CSSRuleList      cssRules;
    unsigned long      insertRule(in DOMString rule,
                                  in unsigned long index)
                                        raises(dom::DOMException);
    void               deleteRule(in unsigned long index)
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface ViewCSS : views::AbstractView {
    CSSStyleDeclaration getComputedStyle(in Element elt,
                                         in DOMString pseudoElt);
  };

  // Introduced in DOM Level 2:
  interface DocumentCSS : stylesheets::DocumentStyle {
    CSSStyleDeclaration getOverrideStyle(in Element elt,
                                         in DOMString pseudoElt);
  };

  // Introduced in DOM   Level 2:
  interface DOMImplementationCSS : DOMImplementation {
    CSSStyleSheet      createCSSStyleSheet(in DOMString title,
                                           in DOMString media)
                                        raises(dom::DOMException);
  };
};

#endif // _CSS_IDL_
previous next contents index


Java Language Binding

previous next contents index

13 November, 2000

Appendix B: Java Language Binding

This appendix contains the complete Java Language [Java] binding for the Level 2 Document Object Model Style. The definitions are divided into StyleSheets and CSS.

The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/java-binding.zip

B.1: Document Object Model Style Sheets

org/w3c/dom/stylesheets/StyleSheet.java:

package org.w3c.dom.stylesheets;

import org.w3c.dom.Node;

public interface StyleSheet {
    public String getType();

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public Node getOwnerNode();

    public StyleSheet getParentStyleSheet();

    public String getHref();

    public String getTitle();

    public MediaList getMedia();

}

org/w3c/dom/stylesheets/StyleSheetList.java:

package org.w3c.dom.stylesheets;

public interface StyleSheetList {
    public int getLength();

    public StyleSheet item(int index);

}

org/w3c/dom/stylesheets/MediaList.java:

package org.w3c.dom.stylesheets;

import org.w3c.dom.DOMException;

public interface MediaList {
    public String getMediaText();
    public void setMediaText(String mediaText)
                           throws DOMException;

    public int getLength();

    public String item(int index);

    public void deleteMedium(String oldMedium)
                             throws DOMException;

    public void appendMedium(String newMedium)
                             throws DOMException;

}

org/w3c/dom/stylesheets/LinkStyle.java:

package org.w3c.dom.stylesheets;

public interface LinkStyle {
    public StyleSheet getSheet();

}

org/w3c/dom/stylesheets/DocumentStyle.java:

package org.w3c.dom.stylesheets;

public interface DocumentStyle {
    public StyleSheetList getStyleSheets();

}

B.2: Document Object Model CSS

org/w3c/dom/css/CSSStyleSheet.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;
import org.w3c.dom.stylesheets.StyleSheet;

public interface CSSStyleSheet extends StyleSheet {
    public CSSRule getOwnerRule();

    public CSSRuleList getCssRules();

    public int insertRule(String rule,
                          int index)
                          throws DOMException;

    public void deleteRule(int index)
                           throws DOMException;

}

org/w3c/dom/css/CSSRuleList.java:

package org.w3c.dom.css;

public interface CSSRuleList {
    public int getLength();

    public CSSRule item(int index);

}

org/w3c/dom/css/CSSRule.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSRule {
    // RuleType
    public static final short UNKNOWN_RULE              = 0;
    public static final short STYLE_RULE                = 1;
    public static final short CHARSET_RULE              = 2;
    public static final short IMPORT_RULE               = 3;
    public static final short MEDIA_RULE                = 4;
    public static final short FONT_FACE_RULE            = 5;
    public static final short PAGE_RULE                 = 6;

    public short getType();

    public String getCssText();
    public void setCssText(String cssText)
                        throws DOMException;

    public CSSStyleSheet getParentStyleSheet();

    public CSSRule getParentRule();

}

org/w3c/dom/css/CSSStyleRule.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSStyleRule extends CSSRule {
    public String getSelectorText();
    public void setSelectorText(String selectorText)
                        throws DOMException;

    public CSSStyleDeclaration getStyle();

}

org/w3c/dom/css/CSSMediaRule.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;
import org.w3c.dom.stylesheets.MediaList;

public interface CSSMediaRule extends CSSRule {
    public MediaList getMedia();

    public CSSRuleList getCssRules();

    public int insertRule(String rule,
                          int index)
                          throws DOMException;

    public void deleteRule(int index)
                           throws DOMException;

}

org/w3c/dom/css/CSSFontFaceRule.java:

package org.w3c.dom.css;

public interface CSSFontFaceRule extends CSSRule {
    public CSSStyleDeclaration getStyle();

}

org/w3c/dom/css/CSSPageRule.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSPageRule extends CSSRule {
    public String getSelectorText();
    public void setSelectorText(String selectorText)
                           throws DOMException;

    public CSSStyleDeclaration getStyle();

}

org/w3c/dom/css/CSSImportRule.java:

package org.w3c.dom.css;

import org.w3c.dom.stylesheets.MediaList;

public interface CSSImportRule extends CSSRule {
    public String getHref();

    public MediaList getMedia();

    public CSSStyleSheet getStyleSheet();

}

org/w3c/dom/css/CSSCharsetRule.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSCharsetRule extends CSSRule {
    public String getEncoding();
    public void setEncoding(String encoding)
                           throws DOMException;

}

org/w3c/dom/css/CSSUnknownRule.java:

package org.w3c.dom.css;

public interface CSSUnknownRule extends CSSRule {
}

org/w3c/dom/css/CSSStyleDeclaration.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSStyleDeclaration {
    public String getCssText();
    public void setCssText(String cssText)
                           throws DOMException;

    public String getPropertyValue(String propertyName);

    public CSSValue getPropertyCSSValue(String propertyName);

    public String removeProperty(String propertyName)
                                 throws DOMException;

    public String getPropertyPriority(String propertyName);

    public void setProperty(String propertyName,
                            String value,
                            String priority)
                            throws DOMException;

    public int getLength();

    public String item(int index);

    public CSSRule getParentRule();

}

org/w3c/dom/css/CSSValue.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSValue {
    // UnitTypes
    public static final short CSS_INHERIT               = 0;
    public static final short CSS_PRIMITIVE_VALUE       = 1;
    public static final short CSS_VALUE_LIST            = 2;
    public static final short CSS_CUSTOM                = 3;

    public String getCssText();
    public void setCssText(String cssText)
                       throws DOMException;

    public short getCssValueType();

}

org/w3c/dom/css/CSSPrimitiveValue.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSSPrimitiveValue extends CSSValue {
    // UnitTypes
    public static final short CSS_UNKNOWN               = 0;
    public static final short CSS_NUMBER                = 1;
    public static final short CSS_PERCENTAGE            = 2;
    public static final short CSS_EMS                   = 3;
    public static final short CSS_EXS                   = 4;
    public static final short CSS_PX                    = 5;
    public static final short CSS_CM                    = 6;
    public static final short CSS_MM                    = 7;
    public static final short CSS_IN                    = 8;
    public static final short CSS_PT                    = 9;
    public static final short CSS_PC                    = 10;
    public static final short CSS_DEG                   = 11;
    public static final short CSS_RAD                   = 12;
    public static final short CSS_GRAD                  = 13;
    public static final short CSS_MS                    = 14;
    public static final short CSS_S                     = 15;
    public static final short CSS_HZ                    = 16;
    public static final short CSS_KHZ                   = 17;
    public static final short CSS_DIMENSION             = 18;
    public static final short CSS_STRING                = 19;
    public static final short CSS_URI                   = 20;
    public static final short CSS_IDENT                 = 21;
    public static final short CSS_ATTR                  = 22;
    public static final short CSS_COUNTER               = 23;
    public static final short CSS_RECT                  = 24;
    public static final short CSS_RGBCOLOR              = 25;

    public short getPrimitiveType();

    public void setFloatValue(short unitType,
                              float floatValue)
                              throws DOMException;

    public float getFloatValue(short unitType)
                               throws DOMException;

    public void setStringValue(short stringType,
                               String stringValue)
                               throws DOMException;

    public String getStringValue()
                                 throws DOMException;

    public Counter getCounterValue()
                                   throws DOMException;

    public Rect getRectValue()
                             throws DOMException;

    public RGBColor getRGBColorValue()
                                     throws DOMException;

}

org/w3c/dom/css/CSSValueList.java:

package org.w3c.dom.css;

public interface CSSValueList extends CSSValue {
    public int getLength();

    public CSSValue item(int index);

}

org/w3c/dom/css/RGBColor.java:

package org.w3c.dom.css;

public interface RGBColor {
    public CSSPrimitiveValue getRed();

    public CSSPrimitiveValue getGreen();

    public CSSPrimitiveValue getBlue();

}

org/w3c/dom/css/Rect.java:

package org.w3c.dom.css;

public interface Rect {
    public CSSPrimitiveValue getTop();

    public CSSPrimitiveValue getRight();

    public CSSPrimitiveValue getBottom();

    public CSSPrimitiveValue getLeft();

}

org/w3c/dom/css/Counter.java:

package org.w3c.dom.css;

public interface Counter {
    public String getIdentifier();

    public String getListStyle();

    public String getSeparator();

}

org/w3c/dom/css/ViewCSS.java:

package org.w3c.dom.css;

import org.w3c.dom.views.AbstractView;
import org.w3c.dom.Element;

public interface ViewCSS extends AbstractView {
    public CSSStyleDeclaration getComputedStyle(Element elt,
                                                String pseudoElt);

}

org/w3c/dom/css/DocumentCSS.java:

package org.w3c.dom.css;

import org.w3c.dom.stylesheets.DocumentStyle;
import org.w3c.dom.Element;

public interface DocumentCSS extends DocumentStyle {
    public CSSStyleDeclaration getOverrideStyle(Element elt,
                                                String pseudoElt);

}

org/w3c/dom/css/DOMImplementationCSS.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMImplementation;
import org.w3c.dom.DOMException;

public interface DOMImplementationCSS extends DOMImplementation {
    public CSSStyleSheet createCSSStyleSheet(String title,
                                             String media)
                                             throws DOMException;

}

org/w3c/dom/css/ElementCSSInlineStyle.java:

package org.w3c.dom.css;

public interface ElementCSSInlineStyle {
    public CSSStyleDeclaration getStyle();

}

org/w3c/dom/css/CSS2Properties.java:

package org.w3c.dom.css;

import org.w3c.dom.DOMException;

public interface CSS2Properties {
    public String getAzimuth();
    public void setAzimuth(String azimuth)
                                             throws DOMException;

    public String getBackground();
    public void setBackground(String background)
                                             throws DOMException;

    public String getBackgroundAttachment();
    public void setBackgroundAttachment(String backgroundAttachment)
                                             throws DOMException;

    public String getBackgroundColor();
    public void setBackgroundColor(String backgroundColor)
                                             throws DOMException;

    public String getBackgroundImage();
    public void setBackgroundImage(String backgroundImage)
                                             throws DOMException;

    public String getBackgroundPosition();
    public void setBackgroundPosition(String backgroundPosition)
                                             throws DOMException;

    public String getBackgroundRepeat();
    public void setBackgroundRepeat(String backgroundRepeat)
                                             throws DOMException;

    public String getBorder();
    public void setBorder(String border)
                                             throws DOMException;

    public String getBorderCollapse();
    public void setBorderCollapse(String borderCollapse)
                                             throws DOMException;

    public String getBorderColor();
    public void setBorderColor(String borderColor)
                                             throws DOMException;

    public String getBorderSpacing();
    public void setBorderSpacing(String borderSpacing)
                                             throws DOMException;

    public String getBorderStyle();
    public void setBorderStyle(String borderStyle)
                                             throws DOMException;

    public String getBorderTop();
    public void setBorderTop(String borderTop)
                                             throws DOMException;

    public String getBorderRight();
    public void setBorderRight(String borderRight)
                                             throws DOMException;

    public String getBorderBottom();
    public void setBorderBottom(String borderBottom)
                                             throws DOMException;

    public String getBorderLeft();
    public void setBorderLeft(String borderLeft)
                                             throws DOMException;

    public String getBorderTopColor();
    public void setBorderTopColor(String borderTopColor)
                                             throws DOMException;

    public String getBorderRightColor();
    public void setBorderRightColor(String borderRightColor)
                                             throws DOMException;

    public String getBorderBottomColor();
    public void setBorderBottomColor(String borderBottomColor)
                                             throws DOMException;

    public String getBorderLeftColor();
    public void setBorderLeftColor(String borderLeftColor)
                                             throws DOMException;

    public String getBorderTopStyle();
    public void setBorderTopStyle(String borderTopStyle)
                                             throws DOMException;

    public String getBorderRightStyle();
    public void setBorderRightStyle(String borderRightStyle)
                                             throws DOMException;

    public String getBorderBottomStyle();
    public void setBorderBottomStyle(String borderBottomStyle)
                                             throws DOMException;

    public String getBorderLeftStyle();
    public void setBorderLeftStyle(String borderLeftStyle)
                                             throws DOMException;

    public String getBorderTopWidth();
    public void setBorderTopWidth(String borderTopWidth)
                                             throws DOMException;

    public String getBorderRightWidth();
    public void setBorderRightWidth(String borderRightWidth)
                                             throws DOMException;

    public String getBorderBottomWidth();
    public void setBorderBottomWidth(String borderBottomWidth)
                                             throws DOMException;

    public String getBorderLeftWidth();
    public void setBorderLeftWidth(String borderLeftWidth)
                                             throws DOMException;

    public String getBorderWidth();
    public void setBorderWidth(String borderWidth)
                                             throws DOMException;

    public String getBottom();
    public void setBottom(String bottom)
                                             throws DOMException;

    public String getCaptionSide();
    public void setCaptionSide(String captionSide)
                                             throws DOMException;

    public String getClear();
    public void setClear(String clear)
                                             throws DOMException;

    public String getClip();
    public void setClip(String clip)
                                             throws DOMException;

    public String getColor();
    public void setColor(String color)
                                             throws DOMException;

    public String getContent();
    public void setContent(String content)
                                             throws DOMException;

    public String getCounterIncrement();
    public void setCounterIncrement(String counterIncrement)
                                             throws DOMException;

    public String getCounterReset();
    public void setCounterReset(String counterReset)
                                             throws DOMException;

    public String getCue();
    public void setCue(String cue)
                                             throws DOMException;

    public String getCueAfter();
    public void setCueAfter(String cueAfter)
                                             throws DOMException;

    public String getCueBefore();
    public void setCueBefore(String cueBefore)
                                             throws DOMException;

    public String getCursor();
    public void setCursor(String cursor)
                                             throws DOMException;

    public String getDirection();
    public void setDirection(String direction)
                                             throws DOMException;

    public String getDisplay();
    public void setDisplay(String display)
                                             throws DOMException;

    public String getElevation();
    public void setElevation(String elevation)
                                             throws DOMException;

    public String getEmptyCells();
    public void setEmptyCells(String emptyCells)
                                             throws DOMException;

    public String getCssFloat();
    public void setCssFloat(String cssFloat)
                                             throws DOMException;

    public String getFont();
    public void setFont(String font)
                                             throws DOMException;

    public String getFontFamily();
    public void setFontFamily(String fontFamily)
                                             throws DOMException;

    public String getFontSize();
    public void setFontSize(String fontSize)
                                             throws DOMException;

    public String getFontSizeAdjust();
    public void setFontSizeAdjust(String fontSizeAdjust)
                                             throws DOMException;

    public String getFontStretch();
    public void setFontStretch(String fontStretch)
                                             throws DOMException;

    public String getFontStyle();
    public void setFontStyle(String fontStyle)
                                             throws DOMException;

    public String getFontVariant();
    public void setFontVariant(String fontVariant)
                                             throws DOMException;

    public String getFontWeight();
    public void setFontWeight(String fontWeight)
                                             throws DOMException;

    public String getHeight();
    public void setHeight(String height)
                                             throws DOMException;

    public String getLeft();
    public void setLeft(String left)
                                             throws DOMException;

    public String getLetterSpacing();
    public void setLetterSpacing(String letterSpacing)
                                             throws DOMException;

    public String getLineHeight();
    public void setLineHeight(String lineHeight)
                                             throws DOMException;

    public String getListStyle();
    public void setListStyle(String listStyle)
                                             throws DOMException;

    public String getListStyleImage();
    public void setListStyleImage(String listStyleImage)
                                             throws DOMException;

    public String getListStylePosition();
    public void setListStylePosition(String listStylePosition)
                                             throws DOMException;

    public String getListStyleType();
    public void setListStyleType(String listStyleType)
                                             throws DOMException;

    public String getMargin();
    public void setMargin(String margin)
                                             throws DOMException;

    public String getMarginTop();
    public void setMarginTop(String marginTop)
                                             throws DOMException;

    public String getMarginRight();
    public void setMarginRight(String marginRight)
                                             throws DOMException;

    public String getMarginBottom();
    public void setMarginBottom(String marginBottom)
                                             throws DOMException;

    public String getMarginLeft();
    public void setMarginLeft(String marginLeft)
                                             throws DOMException;

    public String getMarkerOffset();
    public void setMarkerOffset(String markerOffset)
                                             throws DOMException;

    public String getMarks();
    public void setMarks(String marks)
                                             throws DOMException;

    public String getMaxHeight();
    public void setMaxHeight(String maxHeight)
                                             throws DOMException;

    public String getMaxWidth();
    public void setMaxWidth(String maxWidth)
                                             throws DOMException;

    public String getMinHeight();
    public void setMinHeight(String minHeight)
                                             throws DOMException;

    public String getMinWidth();
    public void setMinWidth(String minWidth)
                                             throws DOMException;

    public String getOrphans();
    public void setOrphans(String orphans)
                                             throws DOMException;

    public String getOutline();
    public void setOutline(String outline)
                                             throws DOMException;

    public String getOutlineColor();
    public void setOutlineColor(String outlineColor)
                                             throws DOMException;

    public String getOutlineStyle();
    public void setOutlineStyle(String outlineStyle)
                                             throws DOMException;

    public String getOutlineWidth();
    public void setOutlineWidth(String outlineWidth)
                                             throws DOMException;

    public String getOverflow();
    public void setOverflow(String overflow)
                                             throws DOMException;

    public String getPadding();
    public void setPadding(String padding)
                                             throws DOMException;

    public String getPaddingTop();
    public void setPaddingTop(String paddingTop)
                                             throws DOMException;

    public String getPaddingRight();
    public void setPaddingRight(String paddingRight)
                                             throws DOMException;

    public String getPaddingBottom();
    public void setPaddingBottom(String paddingBottom)
                                             throws DOMException;

    public String getPaddingLeft();
    public void setPaddingLeft(String paddingLeft)
                                             throws DOMException;

    public String getPage();
    public void setPage(String page)
                                             throws DOMException;

    public String getPageBreakAfter();
    public void setPageBreakAfter(String pageBreakAfter)
                                             throws DOMException;

    public String getPageBreakBefore();
    public void setPageBreakBefore(String pageBreakBefore)
                                             throws DOMException;

    public String getPageBreakInside();
    public void setPageBreakInside(String pageBreakInside)
                                             throws DOMException;

    public String getPause();
    public void setPause(String pause)
                                             throws DOMException;

    public String getPauseAfter();
    public void setPauseAfter(String pauseAfter)
                                             throws DOMException;

    public String getPauseBefore();
    public void setPauseBefore(String pauseBefore)
                                             throws DOMException;

    public String getPitch();
    public void setPitch(String pitch)
                                             throws DOMException;

    public String getPitchRange();
    public void setPitchRange(String pitchRange)
                                             throws DOMException;

    public String getPlayDuring();
    public void setPlayDuring(String playDuring)
                                             throws DOMException;

    public String getPosition();
    public void setPosition(String position)
                                             throws DOMException;

    public String getQuotes();
    public void setQuotes(String quotes)
                                             throws DOMException;

    public String getRichness();
    public void setRichness(String richness)
                                             throws DOMException;

    public String getRight();
    public void setRight(String right)
                                             throws DOMException;

    public String getSize();
    public void setSize(String size)
                                             throws DOMException;

    public String getSpeak();
    public void setSpeak(String speak)
                                             throws DOMException;

    public String getSpeakHeader();
    public void setSpeakHeader(String speakHeader)
                                             throws DOMException;

    public String getSpeakNumeral();
    public void setSpeakNumeral(String speakNumeral)
                                             throws DOMException;

    public String getSpeakPunctuation();
    public void setSpeakPunctuation(String speakPunctuation)
                                             throws DOMException;

    public String getSpeechRate();
    public void setSpeechRate(String speechRate)
                                             throws DOMException;

    public String getStress();
    public void setStress(String stress)
                                             throws DOMException;

    public String getTableLayout();
    public void setTableLayout(String tableLayout)
                                             throws DOMException;

    public String getTextAlign();
    public void setTextAlign(String textAlign)
                                             throws DOMException;

    public String getTextDecoration();
    public void setTextDecoration(String textDecoration)
                                             throws DOMException;

    public String getTextIndent();
    public void setTextIndent(String textIndent)
                                             throws DOMException;

    public String getTextShadow();
    public void setTextShadow(String textShadow)
                                             throws DOMException;

    public String getTextTransform();
    public void setTextTransform(String textTransform)
                                             throws DOMException;

    public String getTop();
    public void setTop(String top)
                                             throws DOMException;

    public String getUnicodeBidi();
    public void setUnicodeBidi(String unicodeBidi)
                                             throws DOMException;

    public String getVerticalAlign();
    public void setVerticalAlign(String verticalAlign)
                                             throws DOMException;

    public String getVisibility();
    public void setVisibility(String visibility)
                                             throws DOMException;

    public String getVoiceFamily();
    public void setVoiceFamily(String voiceFamily)
                                             throws DOMException;

    public String getVolume();
    public void setVolume(String volume)
                                             throws DOMException;

    public String getWhiteSpace();
    public void setWhiteSpace(String whiteSpace)
                                             throws DOMException;

    public String getWidows();
    public void setWidows(String widows)
                                             throws DOMException;

    public String getWidth();
    public void setWidth(String width)
                                             throws DOMException;

    public String getWordSpacing();
    public void setWordSpacing(String wordSpacing)
                                             throws DOMException;

    public String getZIndex();
    public void setZIndex(String zIndex)
                                             throws DOMException;

}
previous next contents index


ECMAScript Language Binding

previous next contents index

13 November, 2000

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Style definitions. The definitions are divided into StyleSheets and CSS.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

C.1: Document Object Model StyleSheets

Object StyleSheet
The StyleSheet object has the following properties:
type
This read-only property is of type String.
disabled
This property is of type Boolean.
ownerNode
This read-only property is a Node object.
parentStyleSheet
This read-only property is a StyleSheet object.
href
This read-only property is of type String.
title
This read-only property is of type String.
media
This read-only property is a MediaList object.
Object StyleSheetList
The StyleSheetList object has the following properties:
length
This read-only property is of type Number.
The StyleSheetList object has the following methods:
item(index)
This method returns a StyleSheet object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Object MediaList
The MediaList object has the following properties:
mediaText
This property is of type String and can raise a DOMException object on setting.
length
This read-only property is of type Number.
The MediaList object has the following methods:
item(index)
This method returns a String.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
deleteMedium(oldMedium)
This method has no return value.
The oldMedium parameter is of type String.
This method can raise a DOMException object.
appendMedium(newMedium)
This method has no return value.
The newMedium parameter is of type String.
This method can raise a DOMException object.
Object LinkStyle
The LinkStyle object has the following properties:
sheet
This read-only property is a StyleSheet object.
Object DocumentStyle
The DocumentStyle object has the following properties:
styleSheets
This read-only property is a StyleSheetList object.

C.2: Document Object Model CSS

Object CSSStyleSheet
CSSStyleSheet has the all the properties and methods of the StyleSheet object as well as the properties and methods defined below.
The CSSStyleSheet object has the following properties:
ownerRule
This read-only property is a CSSRule object.
cssRules
This read-only property is a CSSRuleList object.
The CSSStyleSheet object has the following methods:
insertRule(rule, index)
This method returns a Number.
The rule parameter is of type String.
The index parameter is of type Number.
This method can raise a DOMException object.
deleteRule(index)
This method has no return value.
The index parameter is of type Number.
This method can raise a DOMException object.
Object CSSRuleList
The CSSRuleList object has the following properties:
length
This read-only property is of type Number.
The CSSRuleList object has the following methods:
item(index)
This method returns a CSSRule object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Prototype Object CSSRule
The CSSRule class has the following constants:
CSSRule.UNKNOWN_RULE
This constant is of type Number and its value is 0.
CSSRule.STYLE_RULE
This constant is of type Number and its value is 1.
CSSRule.CHARSET_RULE
This constant is of type Number and its value is 2.
CSSRule.IMPORT_RULE
This constant is of type Number and its value is 3.
CSSRule.MEDIA_RULE
This constant is of type Number and its value is 4.
CSSRule.FONT_FACE_RULE
This constant is of type Number and its value is 5.
CSSRule.PAGE_RULE
This constant is of type Number and its value is 6.
Object CSSRule
The CSSRule object has the following properties:
type
This read-only property is of type Number.
cssText
This property is of type String and can raise a DOMException object on setting.
parentStyleSheet
This read-only property is a CSSStyleSheet object.
parentRule
This read-only property is a CSSRule object.
Object CSSStyleRule
CSSStyleRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSStyleRule object has the following properties:
selectorText
This property is of type String and can raise a DOMException object on setting.
style
This read-only property is a CSSStyleDeclaration object.
Object CSSMediaRule
CSSMediaRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSMediaRule object has the following properties:
media
This read-only property is a MediaList object.
cssRules
This read-only property is a CSSRuleList object.
The CSSMediaRule object has the following methods:
insertRule(rule, index)
This method returns a Number.
The rule parameter is of type String.
The index parameter is of type Number.
This method can raise a DOMException object.
deleteRule(index)
This method has no return value.
The index parameter is of type Number.
This method can raise a DOMException object.
Object CSSFontFaceRule
CSSFontFaceRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSFontFaceRule object has the following properties:
style
This read-only property is a CSSStyleDeclaration object.
Object CSSPageRule
CSSPageRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSPageRule object has the following properties:
selectorText
This property is of type String and can raise a DOMException object on setting.
style
This read-only property is a CSSStyleDeclaration object.
Object CSSImportRule
CSSImportRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSImportRule object has the following properties:
href
This read-only property is of type String.
media
This read-only property is a MediaList object.
styleSheet
This read-only property is a CSSStyleSheet object.
Object CSSCharsetRule
CSSCharsetRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
The CSSCharsetRule object has the following properties:
encoding
This property is of type String and can raise a DOMException object on setting.
Object CSSUnknownRule
CSSUnknownRule has the all the properties and methods of the CSSRule object as well as the properties and methods defined below.
Object CSSStyleDeclaration
The CSSStyleDeclaration object has the following properties:
cssText
This property is of type String and can raise a DOMException object on setting.
length
This read-only property is of type Number.
parentRule
This read-only property is a CSSRule object.
The CSSStyleDeclaration object has the following methods:
getPropertyValue(propertyName)
This method returns a String.
The propertyName parameter is of type String.
getPropertyCSSValue(propertyName)
This method returns a CSSValue object.
The propertyName parameter is of type String.
removeProperty(propertyName)
This method returns a String.
The propertyName parameter is of type String.
This method can raise a DOMException object.
getPropertyPriority(propertyName)
This method returns a String.
The propertyName parameter is of type String.
setProperty(propertyName, value, priority)
This method has no return value.
The propertyName parameter is of type String.
The value parameter is of type String.
The priority parameter is of type String.
This method can raise a DOMException object.
item(index)
This method returns a String.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Prototype Object CSSValue
The CSSValue class has the following constants:
CSSValue.CSS_INHERIT
This constant is of type Number and its value is 0.
CSSValue.CSS_PRIMITIVE_VALUE
This constant is of type Number and its value is 1.
CSSValue.CSS_VALUE_LIST
This constant is of type Number and its value is 2.
CSSValue.CSS_CUSTOM
This constant is of type Number and its value is 3.
Object CSSValue
The CSSValue object has the following properties:
cssText
This property is of type String and can raise a DOMException object on setting.
cssValueType
This read-only property is of type Number.
Prototype Object CSSPrimitiveValue
The CSSPrimitiveValue class has the following constants:
CSSPrimitiveValue.CSS_UNKNOWN
This constant is of type Number and its value is 0.
CSSPrimitiveValue.CSS_NUMBER
This constant is of type Number and its value is 1.
CSSPrimitiveValue.CSS_PERCENTAGE
This constant is of type Number and its value is 2.
CSSPrimitiveValue.CSS_EMS
This constant is of type Number and its value is 3.
CSSPrimitiveValue.CSS_EXS
This constant is of type Number and its value is 4.
CSSPrimitiveValue.CSS_PX
This constant is of type Number and its value is 5.
CSSPrimitiveValue.CSS_CM
This constant is of type Number and its value is 6.
CSSPrimitiveValue.CSS_MM
This constant is of type Number and its value is 7.
CSSPrimitiveValue.CSS_IN
This constant is of type Number and its value is 8.
CSSPrimitiveValue.CSS_PT
This constant is of type Number and its value is 9.
CSSPrimitiveValue.CSS_PC
This constant is of type Number and its value is 10.
CSSPrimitiveValue.CSS_DEG
This constant is of type Number and its value is 11.
CSSPrimitiveValue.CSS_RAD
This constant is of type Number and its value is 12.
CSSPrimitiveValue.CSS_GRAD
This constant is of type Number and its value is 13.
CSSPrimitiveValue.CSS_MS
This constant is of type Number and its value is 14.
CSSPrimitiveValue.CSS_S
This constant is of type Number and its value is 15.
CSSPrimitiveValue.CSS_HZ
This constant is of type Number and its value is 16.
CSSPrimitiveValue.CSS_KHZ
This constant is of type Number and its value is 17.
CSSPrimitiveValue.CSS_DIMENSION
This constant is of type Number and its value is 18.
CSSPrimitiveValue.CSS_STRING
This constant is of type Number and its value is 19.
CSSPrimitiveValue.CSS_URI
This constant is of type Number and its value is 20.
CSSPrimitiveValue.CSS_IDENT
This constant is of type Number and its value is 21.
CSSPrimitiveValue.CSS_ATTR
This constant is of type Number and its value is 22.
CSSPrimitiveValue.CSS_COUNTER
This constant is of type Number and its value is 23.
CSSPrimitiveValue.CSS_RECT
This constant is of type Number and its value is 24.
CSSPrimitiveValue.CSS_RGBCOLOR
This constant is of type Number and its value is 25.
Object CSSPrimitiveValue
CSSPrimitiveValue has the all the properties and methods of the CSSValue object as well as the properties and methods defined below.
The CSSPrimitiveValue object has the following properties:
primitiveType
This read-only property is of type Number.
The CSSPrimitiveValue object has the following methods:
setFloatValue(unitType, floatValue)
This method has no return value.
The unitType parameter is of type Number.
The floatValue parameter is a float object.
This method can raise a DOMException object.
getFloatValue(unitType)
This method returns a float object.
The unitType parameter is of type Number.
This method can raise a DOMException object.
setStringValue(stringType, stringValue)
This method has no return value.
The stringType parameter is of type Number.
The stringValue parameter is of type String.
This method can raise a DOMException object.
getStringValue()
This method returns a String.
This method can raise a DOMException object.
getCounterValue()
This method returns a Counter object.
This method can raise a DOMException object.
getRectValue()
This method returns a Rect object.
This method can raise a DOMException object.
getRGBColorValue()
This method returns a RGBColor object.
This method can raise a DOMException object.
Object CSSValueList
CSSValueList has the all the properties and methods of the CSSValue object as well as the properties and methods defined below.
The CSSValueList object has the following properties:
length
This read-only property is of type Number.
The CSSValueList object has the following methods:
item(index)
This method returns a CSSValue object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Object RGBColor
The RGBColor object has the following properties:
red
This read-only property is a CSSPrimitiveValue object.
green
This read-only property is a CSSPrimitiveValue object.
blue
This read-only property is a CSSPrimitiveValue object.
Object Rect
The Rect object has the following properties:
top
This read-only property is a CSSPrimitiveValue object.
right
This read-only property is a CSSPrimitiveValue object.
bottom
This read-only property is a CSSPrimitiveValue object.
left
This read-only property is a CSSPrimitiveValue object.
Object Counter
The Counter object has the following properties:
identifier
This read-only property is of type String.
listStyle
This read-only property is of type String.
separator
This read-only property is of type String.
Object ViewCSS
ViewCSS has the all the properties and methods of the AbstractView object as well as the properties and methods defined below.
The ViewCSS object has the following methods:
getComputedStyle(elt, pseudoElt)
This method returns a CSSStyleDeclaration object.
The elt parameter is a Element object.
The pseudoElt parameter is of type String.
Object DocumentCSS
DocumentCSS has the all the properties and methods of the DocumentStyle object as well as the properties and methods defined below.
The DocumentCSS object has the following methods:
getOverrideStyle(elt, pseudoElt)
This method returns a CSSStyleDeclaration object.
The elt parameter is a Element object.
The pseudoElt parameter is of type String.
Object DOMImplementationCSS
DOMImplementationCSS has the all the properties and methods of the DOMImplementation object as well as the properties and methods defined below.
The DOMImplementationCSS object has the following methods:
createCSSStyleSheet(title, media)
This method returns a CSSStyleSheet object.
The title parameter is of type String.
The media parameter is of type String.
This method can raise a DOMException object.
Object ElementCSSInlineStyle
The ElementCSSInlineStyle object has the following properties:
style
This read-only property is a CSSStyleDeclaration object.
Object CSS2Properties
The CSS2Properties object has the following properties:
azimuth
This property is of type String and can raise a DOMException object on setting.
background
This property is of type String and can raise a DOMException object on setting.
backgroundAttachment
This property is of type String and can raise a DOMException object on setting.
backgroundColor
This property is of type String and can raise a DOMException object on setting.
backgroundImage
This property is of type String and can raise a DOMException object on setting.
backgroundPosition
This property is of type String and can raise a DOMException object on setting.
backgroundRepeat
This property is of type String and can raise a DOMException object on setting.
border
This property is of type String and can raise a DOMException object on setting.
borderCollapse
This property is of type String and can raise a DOMException object on setting.
borderColor
This property is of type String and can raise a DOMException object on setting.
borderSpacing
This property is of type String and can raise a DOMException object on setting.
borderStyle
This property is of type String and can raise a DOMException object on setting.
borderTop
This property is of type String and can raise a DOMException object on setting.
borderRight
This property is of type String and can raise a DOMException object on setting.
borderBottom
This property is of type String and can raise a DOMException object on setting.
borderLeft
This property is of type String and can raise a DOMException object on setting.
borderTopColor
This property is of type String and can raise a DOMException object on setting.
borderRightColor
This property is of type String and can raise a DOMException object on setting.
borderBottomColor
This property is of type String and can raise a DOMException object on setting.
borderLeftColor
This property is of type String and can raise a DOMException object on setting.
borderTopStyle
This property is of type String and can raise a DOMException object on setting.
borderRightStyle
This property is of type String and can raise a DOMException object on setting.
borderBottomStyle
This property is of type String and can raise a DOMException object on setting.
borderLeftStyle
This property is of type String and can raise a DOMException object on setting.
borderTopWidth
This property is of type String and can raise a DOMException object on setting.
borderRightWidth
This property is of type String and can raise a DOMException object on setting.
borderBottomWidth
This property is of type String and can raise a DOMException object on setting.
borderLeftWidth
This property is of type String and can raise a DOMException object on setting.
borderWidth
This property is of type String and can raise a DOMException object on setting.
bottom
This property is of type String and can raise a DOMException object on setting.
captionSide
This property is of type String and can raise a DOMException object on setting.
clear
This property is of type String and can raise a DOMException object on setting.
clip
This property is of type String and can raise a DOMException object on setting.
color
This property is of type String and can raise a DOMException object on setting.
content
This property is of type String and can raise a DOMException object on setting.
counterIncrement
This property is of type String and can raise a DOMException object on setting.
counterReset
This property is of type String and can raise a DOMException object on setting.
cue
This property is of type String and can raise a DOMException object on setting.
cueAfter
This property is of type String and can raise a DOMException object on setting.
cueBefore
This property is of type String and can raise a DOMException object on setting.
cursor
This property is of type String and can raise a DOMException object on setting.
direction
This property is of type String and can raise a DOMException object on setting.
display
This property is of type String and can raise a DOMException object on setting.
elevation
This property is of type String and can raise a DOMException object on setting.
emptyCells
This property is of type String and can raise a DOMException object on setting.
cssFloat
This property is of type String and can raise a DOMException object on setting.
font
This property is of type String and can raise a DOMException object on setting.
fontFamily
This property is of type String and can raise a DOMException object on setting.
fontSize
This property is of type String and can raise a DOMException object on setting.
fontSizeAdjust
This property is of type String and can raise a DOMException object on setting.
fontStretch
This property is of type String and can raise a DOMException object on setting.
fontStyle
This property is of type String and can raise a DOMException object on setting.
fontVariant
This property is of type String and can raise a DOMException object on setting.
fontWeight
This property is of type String and can raise a DOMException object on setting.
height
This property is of type String and can raise a DOMException object on setting.
left
This property is of type String and can raise a DOMException object on setting.
letterSpacing
This property is of type String and can raise a DOMException object on setting.
lineHeight
This property is of type String and can raise a DOMException object on setting.
listStyle
This property is of type String and can raise a DOMException object on setting.
listStyleImage
This property is of type String and can raise a DOMException object on setting.
listStylePosition
This property is of type String and can raise a DOMException object on setting.
listStyleType
This property is of type String and can raise a DOMException object on setting.
margin
This property is of type String and can raise a DOMException object on setting.
marginTop
This property is of type String and can raise a DOMException object on setting.
marginRight
This property is of type String and can raise a DOMException object on setting.
marginBottom
This property is of type String and can raise a DOMException object on setting.
marginLeft
This property is of type String and can raise a DOMException object on setting.
markerOffset
This property is of type String and can raise a DOMException object on setting.
marks
This property is of type String and can raise a DOMException object on setting.
maxHeight
This property is of type String and can raise a DOMException object on setting.
maxWidth
This property is of type String and can raise a DOMException object on setting.
minHeight
This property is of type String and can raise a DOMException object on setting.
minWidth
This property is of type String and can raise a DOMException object on setting.
orphans
This property is of type String and can raise a DOMException object on setting.
outline
This property is of type String and can raise a DOMException object on setting.
outlineColor
This property is of type String and can raise a DOMException object on setting.
outlineStyle
This property is of type String and can raise a DOMException object on setting.
outlineWidth
This property is of type String and can raise a DOMException object on setting.
overflow
This property is of type String and can raise a DOMException object on setting.
padding
This property is of type String and can raise a DOMException object on setting.
paddingTop
This property is of type String and can raise a DOMException object on setting.
paddingRight
This property is of type String and can raise a DOMException object on setting.
paddingBottom
This property is of type String and can raise a DOMException object on setting.
paddingLeft
This property is of type String and can raise a DOMException object on setting.
page
This property is of type String and can raise a DOMException object on setting.
pageBreakAfter
This property is of type String and can raise a DOMException object on setting.
pageBreakBefore
This property is of type String and can raise a DOMException object on setting.
pageBreakInside
This property is of type String and can raise a DOMException object on setting.
pause
This property is of type String and can raise a DOMException object on setting.
pauseAfter
This property is of type String and can raise a DOMException object on setting.
pauseBefore
This property is of type String and can raise a DOMException object on setting.
pitch
This property is of type String and can raise a DOMException object on setting.
pitchRange
This property is of type String and can raise a DOMException object on setting.
playDuring
This property is of type String and can raise a DOMException object on setting.
position
This property is of type String and can raise a DOMException object on setting.
quotes
This property is of type String and can raise a DOMException object on setting.
richness
This property is of type String and can raise a DOMException object on setting.
right
This property is of type String and can raise a DOMException object on setting.
size
This property is of type String and can raise a DOMException object on setting.
speak
This property is of type String and can raise a DOMException object on setting.
speakHeader
This property is of type String and can raise a DOMException object on setting.
speakNumeral
This property is of type String and can raise a DOMException object on setting.
speakPunctuation
This property is of type String and can raise a DOMException object on setting.
speechRate
This property is of type String and can raise a DOMException object on setting.
stress
This property is of type String and can raise a DOMException object on setting.
tableLayout
This property is of type String and can raise a DOMException object on setting.
textAlign
This property is of type String and can raise a DOMException object on setting.
textDecoration
This property is of type String and can raise a DOMException object on setting.
textIndent
This property is of type String and can raise a DOMException object on setting.
textShadow
This property is of type String and can raise a DOMException object on setting.
textTransform
This property is of type String and can raise a DOMException object on setting.
top
This property is of type String and can raise a DOMException object on setting.
unicodeBidi
This property is of type String and can raise a DOMException object on setting.
verticalAlign
This property is of type String and can raise a DOMException object on setting.
visibility
This property is of type String and can raise a DOMException object on setting.
voiceFamily
This property is of type String and can raise a DOMException object on setting.
volume
This property is of type String and can raise a DOMException object on setting.
whiteSpace
This property is of type String and can raise a DOMException object on setting.
widows
This property is of type String and can raise a DOMException object on setting.
width
This property is of type String and can raise a DOMException object on setting.
wordSpacing
This property is of type String and can raise a DOMException object on setting.
zIndex
This property is of type String and can raise a DOMException object on setting.
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

E.1: Normative references

DOM Level 2 Core
W3C (World Wide Web Consortium) Document Object Model Level 2 Core Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113
CSS2
W3C (World Wide Web Consortium) Cascading Style Sheets, level 2 Specification, May 1998. Available at http://www.w3.org/TR/1998/REC-CSS2-19980512
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
HTML4.0
W3C (World Wide Web Consortium) HTML 4.0 Specification, April 1998. Available at http://www.w3.org/TR/1998/REC-html40-19980424
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
DOM Level 2 Views
W3C (World Wide Web Consortium) Document Object Model Level 2 Views Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113
XML-StyleSheet
W3C (World Wide Web Consortium) Associating Style Sheets with XML documents Version 1.0, June 1999. Available at http://www.w3.org/1999/06/REC-xml-stylesheet-19990629.

E.2: Informative references

DOM Level 2 HTML
W3C (World Wide Web Consortium) Document Object Model Level 2 HTML Specification. Available at http://www.w3.org/TR/DOM-Level-2-HTML
previous next contents index


Index

appendMedium | azimuth
background | backgroundAttachment | backgroundColor
backgroundImage | backgroundPosition | backgroundRepeat
blue | border | borderBottom
borderBottomColor | borderBottomStyle | borderBottomWidth
borderCollapse | borderColor | borderLeft
borderLeftColor | borderLeftStyle | borderLeftWidth
borderRight | borderRightColor | borderRightStyle
borderRightWidth | borderSpacing | borderStyle
borderTop | borderTopColor | borderTopStyle
borderTopWidth | borderWidth | bottom 1, 2
captionSide | CHARSET_RULE | clear
clip | color | content
Counter | counterIncrement | counterReset
createCSSStyleSheet | CSS2 1, 2, 3 | CSS2Properties
CSS_ATTR | CSS_CM | CSS_COUNTER
CSS_CUSTOM | CSS_DEG | CSS_DIMENSION
CSS_EMS | CSS_EXS | CSS_GRAD
CSS_HZ | CSS_IDENT | CSS_IN
CSS_INHERIT | CSS_KHZ | CSS_MM
CSS_MS | CSS_NUMBER | CSS_PC
CSS_PERCENTAGE | CSS_PRIMITIVE_VALUE | CSS_PT
CSS_PX | CSS_RAD | CSS_RECT
CSS_RGBCOLOR | CSS_S | CSS_STRING
CSS_UNKNOWN | CSS_URI | CSS_VALUE_LIST
CSSCharsetRule | cssFloat | CSSFontFaceRule
CSSImportRule | CSSMediaRule | CSSPageRule
CSSPrimitiveValue | CSSRule | CSSRuleList
cssRules 1, 2 | CSSStyleDeclaration | CSSStyleRule
CSSStyleSheet | cssText 1, 2, 3 | CSSUnknownRule
CSSValue | CSSValueList | cssValueType
cue | cueAfter | cueBefore
cursor
deleteMedium | deleteRule 1, 2 | direction
disabled | display | DocumentCSS
DocumentStyle | DOM Level 2 Core 1, 2, 3, 4 | DOM Level 2 HTML 1, 2
DOM Level 2 Views 1, 2 | DOMImplementationCSS
ECMAScript | ElementCSSInlineStyle | elevation
emptyCells | encoding
font | FONT_FACE_RULE | fontFamily
fontSize | fontSizeAdjust | fontStretch
fontStyle | fontVariant | fontWeight
getComputedStyle | getCounterValue | getFloatValue
getOverrideStyle | getPropertyCSSValue | getPropertyPriority
getPropertyValue | getRectValue | getRGBColorValue
getStringValue | green
height | href 1, 2 | HTML4.0 1, 2
identifier | IMPORT_RULE | insertRule 1, 2
item 1, 2, 3, 4, 5
Java
left 1, 2 | length 1, 2, 3, 4, 5 | letterSpacing
lineHeight | LinkStyle | listStyle 1, 2
listStyleImage | listStylePosition | listStyleType
margin | marginBottom | marginLeft
marginRight | marginTop | markerOffset
marks | maxHeight | maxWidth
media 1, 2, 3 | MEDIA_RULE | MediaList
mediaText | minHeight | minWidth
OMGIDL | orphans | outline
outlineColor | outlineStyle | outlineWidth
overflow | ownerNode | ownerRule
padding | paddingBottom | paddingLeft
paddingRight | paddingTop | page
PAGE_RULE | pageBreakAfter | pageBreakBefore
pageBreakInside | parentRule 1, 2 | parentStyleSheet 1, 2
pause | pauseAfter | pauseBefore
pitch | pitchRange | playDuring
position | primitiveType
quotes
Rect | red | removeProperty
RGBColor | richness | right 1, 2
selectorText 1, 2 | separator | setFloatValue
setProperty | setStringValue | sheet
size | speak | speakHeader
speakNumeral | speakPunctuation | speechRate
stress | style 1, 2, 3, 4 | STYLE_RULE
StyleSheet 1, 2 | StyleSheetList | styleSheets
tableLayout | textAlign | textDecoration
textIndent | textShadow | textTransform
title | top 1, 2 | type 1, 2
unicodeBidi | UNKNOWN_RULE
verticalAlign | ViewCSS | visibility
voiceFamily | volume
whiteSpace | widows | width
wordSpacing
XML-StyleSheet 1, 2, 3
zIndex
previous contents


Document Object Model (DOM) Level 2 Traversal and Range Specification

Version 1.0

W3C Recommendation 13 November, 2000

This version:
http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113
( PostScript file , PDF file , plain text , ZIP file)
Latest version:
http://www.w3.org/TR/DOM-Level-2-Traversal-Range
Previous version:
http://www.w3.org/TR/2000/PR-DOM-Level-2-Traversal-Range-20000927
Editors:
Joe Kesselman, IBM
Jonathan Robie, Texcel Research and Software AG
Mike Champion, Arbortext and Software AG
Peter Sharpe, SoftQuad Software Inc.
Vidur Apparao, Netscape Communications Corp.
Lauren Wood, SoftQuad Software Inc., WG Chair

Copyright © 2000 W3C ® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Level 2 Traversal and Range, platform- and language-neutral interfaces that allow programs and scripts to dynamically traverse and identify a range of content in a document. The Document Object Model Level 2 Traversal and Range build on the Document Object Model Level 2 Core [DOM Level 2 Core].

The DOM Level 2 Traversal and Range specification is composed of two modules. The two modules contain specialized interfaces dedicated to traversing the document structure and identifying and manipulating a range in a document.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members. Different modules of the Document Object Model have different editors.

Please send general comments about this document to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • Chapter 1: Document Object Model Traversal
  • Chapter 2: Document Object Model Range
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • Glossary
  • References
  • Index
next contents index


Document Object Model Traversal

previous next contents index

13 November, 2000

1. Document Object Model Traversal

Editors
Joe Kesselman, IBM
Jonathan Robie, Software AG
Mike Champion, Software AG

Table of contents

  • 1.1. Overview
    • 1.1.1. NodeIterators
    • 1.1.2. NodeFilters
    • 1.1.3. TreeWalker
  • 1.2. Formal Interface Definition
    • NodeIterator, NodeFilter, TreeWalker, DocumentTraversal

1.1. Overview

This chapter describes the optional DOM Level 2 Traversal feature. Its TreeWalker, NodeIterator, and NodeFilter interfaces provide easy-to-use, robust, selective traversal of a document's contents.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Traversal" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined defined in the DOM Level 2 Core specification [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

NodeIterators and TreeWalkers are two different ways of representing the nodes of a document subtree and a position within the nodes they present. A NodeIterator presents a flattened view of the subtree as an ordered sequence of nodes, presented in document order. Because this view is presented without respect to hierarchy, iterators have methods to move forward and backward, but not to move up and down. Conversely, a TreeWalker maintains the hierarchical relationships of the subtree, allowing navigation of this hierarchy. In general, TreeWalkers are better for tasks in which the structure of the document around selected nodes will be manipulated, while NodeIterators are better for tasks that focus on the content of each selected node.

NodeIterators and TreeWalkers each present a view of a document subtree that may not contain all nodes found in the subtree. In this specification, we refer to this as the logical view to distinguish it from the physical view, which corresponds to the document subtree per se. When an iterator or TreeWalker is created, it may be associated with a NodeFilter, which examines each node and determines whether it should appear in the logical view. In addition, flags may be used to specify which node types should occur in the logical view.

NodeIterators and TreeWalkers are dynamic - the logical view changes to reflect changes made to the underlying document. However, they differ in how they respond to those changes. NodeIterators, which present the nodes sequentially, attempt to maintain their location relative to a position in that sequence when the sequence's contents change. TreeWalkers, which present the nodes as a filtered tree, maintain their location relative to their current node and remain attached to that node if it is moved to a new context. We will discuss these behaviors in greater detail below.

1.1.1. NodeIterators

A NodeIterator allows the members of a list of nodes to be returned sequentially. In the current DOM interfaces, this list will always consist of the nodes of a subtree, presented in document order. When an iterator is first created, calling its nextNode() method returns the first node in the logical view of the subtree; in most cases, this is the root of the subtree. Each successive call advances the NodeIterator through the list, returning the next node available in the logical view. When no more nodes are visible, nextNode() returns null.

NodeIterators are created using the createNodeIterator method found in the DocumentTraversal interface. When a NodeIterator is created, flags can be used to determine which node types will be "visible" and which nodes will be "invisible" while traversing the tree; these flags can be combined using the OR operator. Nodes that are "invisible" are skipped over by the iterator as though they did not exist.

The following code creates an iterator, then calls a function to print the name of each element:

    NodeIterator iter=
     ((DocumentTraversal)document).createNodeIterator(
          root, NodeFilter.SHOW_ELEMENT, null);

    while (Node n = iter.nextNode())
        printMe(n);

1.1.1.1. Moving Forward and Backward

NodeIterators present nodes as an ordered list, and move forward and backward within this list. The iterator's position is always either between two nodes, before the first node, or after the last node. When an iterator is first created, the position is set before the first item. The following diagram shows the list view that an iterator might provide for a particular subtree, with the position indicated by an asterisk '*' :

 * A B C D E F G H I

Each call to nextNode() returns the next node and advances the position. For instance, if we start with the above position, the first call to nextNode() returns "A" and advances the iterator:

 [A] * B C D E F G H I

The position of a NodeIterator can best be described with respect to the last node returned, which we will call the reference node. When an iterator is created, the first node is the reference node, and the iterator is positioned before the reference node. In these diagrams, we use square brackets to indicate the reference node.

A call to previousNode() returns the previous node and moves the position backward. For instance, if we start with the NodeIterator between "A" and "B", it would return "A" and move to the position shown below:

 * [A] B C D E F G H I

If nextNode() is called at the end of a list, or previousNode() is called at the beginning of a list, it returns null and does not change the position of the iterator. When a NodeIterator is first created, the reference node is the first node:

 * [A] B C D E F G H I

1.1.1.2. Robustness

A NodeIterator may be active while the data structure it navigates is being edited, so an iterator must behave gracefully in the face of change. Additions and removals in the underlying data structure do not invalidate a NodeIterator; in fact, a NodeIterator is never invalidated unless its detach() method is invoked. To make this possible, the iterator uses the reference node to maintain its position. The state of an iterator also depends on whether the iterator is positioned before or after the reference node.

If changes to the iterated list do not remove the reference node, they do not affect the state of the NodeIterator. For instance, the iterator's state is not affected by inserting new nodes in the vicinity of the iterator or removing nodes other than the reference node. Suppose we start from the following position:

A B C [D] * E F G H I

Now let's remove "E". The resulting state is:

A B C [D] * F G H I

If a new node is inserted, the NodeIterator stays close to the reference node, so if a node is inserted between "D" and "F", it will occur between the iterator and "F":

A B C [D] * X F G H I

Moving a node is equivalent to a removal followed by an insertion. If we move "I" to the position before "X" the result is:

A B C [D] * I X F G H

If the reference node is removed from the list being iterated over, a different node is selected as the reference node. If the reference node's position is before that of the NodeIterator, which is usually the case after nextNode() has been called, the nearest node before the iterator is chosen as the new reference node. Suppose we remove the "D" node, starting from the following state:

A B C [D] * F G H I

The "C" node becomes the new reference node, since it is the nearest node to the NodeIterator that is before the iterator:

A B [C] * F G H I

If the reference node is after the NodeIterator, which is usually the case after previousNode() has been called, the nearest node after the iterator is chosen as the new reference node. Suppose we remove "E", starting from the following state:

A B C D * [E] F G H I

The "F" node becomes the new reference node, since it is the nearest node to the NodeIterator that is after the iterator:

A B C D * [F] G H I

As noted above, moving a node is equivalent to a removal followed by an insertion. Suppose we wish to move the "D" node to the end of the list, starting from the following state:

A B C [D] * F G H I C

The resulting state is as follows:

A B [C] * F G H I D

One special case arises when the reference node is the last node in the list and the reference node is removed. Suppose we remove node "C", starting from the following state:

A B * [C]

According to the rules we have given, the new reference node should be the nearest node after the NodeIterator, but there are no further nodes after "C". The same situation can arise when previousNode() has just returned the first node in the list, which is then removed. Hence: If there is no node in the original direction of the reference node, the nearest node in the opposite direction is selected as the reference node:

A [B] *

If the NodeIterator is positioned within a block of nodes that is removed, the above rules clearly indicate what is to be done. For instance, suppose "C" is the parent node of "D", "E", and "F", and we remove "C", starting with the following state:

A B C [D] * E F G H I D

The resulting state is as follows:

A [B] * G H I D

Finally, note that removing a NodeIterator's root node from its parent does not alter the list being iterated over, and thus does not change the iterator's state.

1.1.1.3. Visibility of Nodes

The underlying data structure that is being iterated may contain nodes that are not part of the logical view, and therefore will not be returned by the NodeIterator. If nodes that are to be excluded because of the value of the whatToShow flag, nextNode() returns the next visible node, skipping over the excluded "invisible" nodes. If a NodeFilter is present, it is applied before returning a node; if the filter does not accept the node, the process is repeated until a node is accepted by the filter and is returned. If no visible nodes are encountered, a null is returned and the iterator is positioned at the end of the list. In this case, the reference node is the last node in the list, whether or not it is visible. The same approach is taken, in the opposite direction, for previousNode().

In the following examples, we will use lowercase letters to represent nodes that are in the data structure, but which are not in the logical view. For instance, consider the following list:

A [B] * c d E F G

A call to nextNode() returns E and advances to the following position:

A B c d [E] * F G

Nodes that are not visible may nevertheless be used as reference nodes if a reference node is removed. Suppose node "E" is removed, started from the state given above. The resulting state is:

A B c [d] * F G

Suppose a new node "X", which is visible, is inserted before "d". The resulting state is:

A B c X [d] * F G

Note that a call to previousNode() now returns node X. It is important not to skip over invisible nodes when the reference node is removed, because there are cases, like the one just given above, where the wrong results will be returned. When "E" was removed, if the new reference node had been "B" rather than "d", calling previousNode() would not return "X".

1.1.2. NodeFilters

NodeFilters allow the user to create objects that "filter out" nodes. Each filter contains a user-written function that looks at a node and determines whether or not it should be presented as part of the traversal's logical view of the document. To use a NodeFilter, you create a NodeIterator or a TreeWalker that uses the filter. The traversal engine applies the filter to each node, and if the filter does not accept the node, traversal skips over the node as though it were not present in the document. NodeFilters need not know how to navigate the structure that contains the nodes on which they operate.

Filters will be consulted when a traversal operation is performed, or when a NodeIterator's reference node is removed from the subtree being iterated over and it must select a new one. However, the exact timing of these filter calls may vary from one DOM implementation to another. For that reason, NodeFilters should not attempt to maintain state based on the history of past invocations; the resulting behavior may not be portable.

Similarly, TreeWalkers and NodeIterators should behave as if they have no memory of past filter results, and no anticipation of future results. If the conditions a NodeFilter is examining have changed (e.g., an attribute which it tests has been added or removed) since the last time the traversal logic examined this node, this change in visibility will be discovered only when the next traversal operation is performed. For example: if the filtering for the current node changes from FILTER_SHOW to FILTER_SKIP, a TreeWalker will be able to navigate off that node in any direction, but not back to it unless the filtering conditions change again. NodeFilters which change during a traversal can be written, but their behavior may be confusing and they should be avoided when possible.

1.1.2.1. Using NodeFilters

A NodeFilter contains one method named acceptNode(), which allows a NodeIterator or TreeWalker to pass a Node to a filter and ask whether it should be present in the logical view. The acceptNode() function returns one of three values to state how the Node should be treated. If acceptNode() returns FILTER_ACCEPT, the Node will be present in the logical view; if it returns FILTER_SKIP, the Node will not be present in the logical view, but the children of the Node may; if it returns FILTER_REJECT, neither the Node nor its descendants will be present in the logical view. Since iterators present nodes as an ordered list, without hierarchy, FILTER_REJECT and FILTER_SKIP are synonyms for NodeIterators, skipping only the single current node.

Consider a filter that accepts the named anchors in an HTML document. In HTML, an HREF can refer to any A element that has a NAME attribute. Here is a NodeFilter in Java that looks at a node and determines whether it is a named anchor:

    class NamedAnchorFilter implements NodeFilter
    {
     short acceptNode(Node n) {
      if (n.getNodeType()==Node.ELEMENT_NODE) {
       Element e = (Element)n;
       if (! e.getNodeName().equals("A"))
        return FILTER_SKIP;
      if (e.getAttributeNode("NAME") != null)
        return FILTER_ACCEPT;
       }
        return FILTER_SKIP;
      }
    }

If the above NodeFilter were to be used only with NodeIterators, it could have used FILTER_REJECT wherever FILTER_SKIP is used, and the behavior would not change. For TreeWalker, though, FILTER_REJECT would reject the children of any element that is not a named anchor, and since named anchors are always contained within other elements, this would have meant that no named anchors would be found. FILTER_SKIP rejects the given node, but continues to examine the children; therefore, the above filter will work with either a NodeIterator or a TreeWalker.

To use this filter, the user would create an instance of the NodeFilter and create a NodeIterator using it:

NamedAnchorFilter myFilter = new NamedAnchorFilter();
NodeIterator iter=
     ((DocumentTraversal)document).createNodeIterator(
          node, NodeFilter.SHOW_ELEMENT, myFilter);

Note that the use of the SHOW_ELEMENT flag is not strictly necessary in this example, since our sample NodeFilter tests the nodeType. However, some implementations of the Traversal interfaces may be able to improve whatToShow performance by taking advantage of knowledge of the document's structure, which makes the use of SHOW_ELEMENT worthwhile. Conversely, while we could remove the nodeType test from our filter, that would make it dependent upon whatToShow to distinguish between Elements, Attr's, and ProcessingInstructions.

1.1.2.2. NodeFilters and Exceptions

When writing a NodeFilter, users should avoid writing code that can throw an exception. However, because a DOM implementation can not prevent exceptions from being thrown, it is important that the behavior of filters that throw an exception be well-defined. A TreeWalker or NodeIterator does not catch or alter an exception thrown by a filter, but lets it propagate up to the user's code. The following functions may invoke a NodeFilter, and may therefore propagate an exception if one is thrown by a filter:

  1. NodeIterator .nextNode()
  2. NodeIterator .previousNode()
  3. TreeWalker .firstChild()
  4. TreeWalker .lastChild()
  5. TreeWalker .nextSibling()
  6. TreeWalker .previousSibling()
  7. TreeWalker .nextNode()
  8. TreeWalker .previousNode()
  9. TreeWalker .parentNode()

1.1.2.3. NodeFilters and Document Mutation

Well-designed NodeFilters should not have to modify the underlying structure of the document. But a DOM implementation can not prevent a user from writing filter code that does alter the document structure. Traversal does not provide any special processing to handle this case. For instance, if a NodeFilter removes a node from a document, it can still accept the node, which means that the node may be returned by the NodeIterator or TreeWalker even though it is no longer in the subtree being traversed. In general, this may lead to inconsistent, confusing results, so we encourage users to write NodeFilters that make no changes to document structures. Instead, do your editing in the loop controlled by the traversal object.

1.1.2.4. NodeFilters and whatToShow flags

NodeIterator and TreeWalker apply their whatToShow flags before applying filters. If a node is skipped by the active whatToShow flags, a NodeFilter will not be called to evaluate that node. Please note that this behavior is similar to that of FILTER_SKIP; children of that node will be considered, and filters may be called to evaluate them. Also note that it will in fact be a "skip" even if the NodeFilter would have preferred to reject the entire subtree; if this would cause a problem in your application, consider setting whatToShow to SHOW_ALL and performing the nodeType test inside your filter.

1.1.3. TreeWalker

The TreeWalker interface provides many of the same benefits as the NodeIterator interface. The main difference between these two interfaces is that the TreeWalker presents a tree-oriented view of the nodes in a subtree, rather than the iterator's list-oriented view. In other words, an iterator allows you to move forward or back, but a TreeWalker allows you to also move to the parent of a node, to one of its children, or to a sibling.

Using a TreeWalker is quite similar to navigation using the Node directly, and the navigation methods for the two interfaces are analogous. For instance, here is a function that recursively walks over a tree of nodes in document order, taking separate actions when first entering a node and after processing any children:

processMe(Node n) {
   nodeStartActions(n);
   for (Node child=n.firstChild();
        child != null;
        child=child.nextSibling()) {
      processMe(child);
   }
   nodeEndActions(n);
}

Doing the same thing using a TreeWalker is quite similar. There is one difference: since navigation on the TreeWalker changes the current position, the position at the end of the function has changed. A read/write attribute named currentNode allows the current node for a TreeWalker to be both queried and set. We will use this to ensure that the position of the TreeWalker is restored when this function is completed:

processMe(TreeWalker tw) {
   Node n = tw.getCurrentNode();
   nodeStartActions(tw);
   for (Node child=tw.firstChild();
        child!=null;
        child=tw.nextSibling()) {
      processMe(tw);
   }

   tw.setCurrentNode(n);
   nodeEndActions(tw);
}

The advantage of using a TreeWalker instead of direct Node navigation is that the TreeWalker allows the user to choose an appropriate view of the tree. Flags may be used to show or hide Comments or ProcessingInstructions; entities may be expanded or shown as EntityReference nodes. In addition, NodeFilters may be used to present a custom view of the tree. Suppose a program needs a view of a document that shows which tables occur in each chapter, listed by chapter. In this view, only the chapter elements and the tables that they contain are seen. The first step is to write an appropriate filter:

class TablesInChapters implements NodeFilter {

   short acceptNode(Node n) {
      if (n.getNodeType()==Node.ELEMENT_NODE) {

          if (n.getNodeName().equals("CHAPTER"))
             return FILTER_ACCEPT;

          if (n.getNodeName().equals("TABLE"))
             return FILTER_ACCEPT;

          if (n.getNodeName().equals("SECT1")
              || n.getNodeName().equals("SECT2")
              || n.getNodeName().equals("SECT3")
              || n.getNodeName().equals("SECT4")
              || n.getNodeName().equals("SECT5")
              || n.getNodeName().equals("SECT6")
              || n.getNodeName().equals("SECT7"))
             return FILTER_SKIP;

      }

      return FILTER_REJECT;
    }
}

This filter assumes that TABLE elements are contained directly in CHAPTER or SECTn elements. If another kind of element is encountered, it and its children are rejected. If a SECTn element is encountered, it is skipped, but its children are explored to see if they contain any TABLE elements.

Now the program can create an instance of this NodeFilter, create a TreeWalker that uses it, and pass this TreeWalker to our ProcessMe() function:

TablesInChapters tablesInChapters  = new TablesInChapters();
TreeWalker tw  =
     ((DocumentTraversal)document).createTreeWalker(
          root, NodeFilter.SHOW_ELEMENT, tablesInChapters);
processMe(tw);

(Again, we've chosen to both test the nodeType in the filter's logic and use SHOW_ELEMENT, for the reasons discussed in the earlier NodeIterator example.)

Without making any changes to the above ProcessMe() function, it now processes only the CHAPTER and TABLE elements. The programmer can write other filters or set other flags to choose different sets of nodes; if functions use TreeWalker to navigate, they will support any view of the document defined with a TreeWalker.

Note that the structure of a TreeWalker's filtered view of a document may differ significantly from that of the document itself. For example, a TreeWalker with only SHOW_TEXT specified in its whatToShow parameter would present all the Text nodes as if they were siblings of each other yet had no parent.

1.1.3.1. Robustness

As with NodeIterators, a TreeWalker may be active while the data structure it navigates is being edited, and must behave gracefully in the face of change. Additions and removals in the underlying data structure do not invalidate a TreeWalker; in fact, a TreeWalker is never invalidated.

But a TreeWalker's response to these changes is quite different from that of a NodeIterator. While NodeIterators respond to editing by maintaining their position within the list that they are iterating over, TreeWalkers will instead remain attached to their currentNode. All the TreeWalker's navigation methods operate in terms of the context of the currentNode at the time they are invoked, no matter what has happened to, or around, that node since the last time the TreeWalker was accessed. This remains true even if the currentNode is moved out of its original subtree.

As an example, consider the following document fragment:

    ...
    <subtree>
        <twRoot>
            <currentNode/>
            <anotherNode/>
        </twRoot>
    </subtree>
    ...

Let's say we have created a TreeWalker whose root node is the <twRoot/> element and whose currentNode is the <currentNode/> element. For this illustration, we will assume that all the nodes shown above are accepted by the TreeWalker's whatToShow and filter settings.

If we use removeChild() to remove the <currentNode/> element from its parent, that element remains the TreeWalker's currentNode, even though it is no longer within the root node's subtree. We can still use the TreeWalker to navigate through any children that the orphaned currentNode may have, but are no longer able to navigate outward from the currentNode since there is no parent available.

If we use insertBefore() or appendChild() to give the <currentNode/> a new parent, then TreeWalker navigation will operate from the currentNode's new location. For example, if we inserted the <currentNode/> immediately after the <anotherNode/> element, the TreeWalker's previousSibling() operation would move it back to the <anotherNode/>, and calling parentNode() would move it up to the <twRoot/>.

If we instead insert the currentNode into the <subtree/> element, like so:

    ...
    <subtree>
        <currentNode/>
        <twRoot>
            <anotherNode/>
        </twRoot>
    </subtree>
    ...

we have moved the currentNode out from under the TreeWalker's root node. This does not invalidate the TreeWalker; it may still be used to navigate relative to the currentNode. Calling its parentNode() operation, for example, would move it to the <subtree/> element, even though that too is outside the original root node. However, if the TreeWalker's navigation should take it back into the original root node's subtree -- for example, if rather than calling parentNode() we called nextNode(), moving the TreeWalker to the <twRoot/> element -- the root node will "recapture" the TreeWalker, and prevent it from traversing back out.

This becomes a bit more complicated when filters are in use. Relocation of the currentNode -- or explicit selection of a new currentNode, or changes in the conditions that the NodeFilter is basing its decisions on -- can result in a TreeWalker having a currentNode which would not otherwise be visible in the filtered (logical) view of the document. This node can be thought of as a "transient member" of that view. When you ask the TreeWalker to navigate off this node the result will be just as if it had been visible, but you may be unable to navigate back to it unless conditions change to make it visible again.

In particular: If the currentNode becomes part of a subtree that would otherwise have been Rejected by the filter, that entire subtree may be added as transient members of the logical view. You will be able to navigate within that subtree (subject to all the usual filtering) until you move upward past the Rejected ancestor. The behavior is as if the Rejected node had only been Skipped (since we somehow wound up inside its subtree) until we leave it; thereafter, standard filtering applies.

1.2. Formal Interface Definition

Interface NodeIterator (introduced in DOM Level 2)

Iterators are used to step through a set of nodes, e.g. the set of nodes in a NodeList, the document subtree governed by a particular Node, the results of a query, or any other set of nodes. The set of nodes to be iterated is determined by the implementation of the NodeIterator. DOM Level 2 specifies a single NodeIterator implementation for document-order traversal of a document subtree. Instances of these iterators are created by calling DocumentTraversal .createNodeIterator().

IDL Definition
// Introduced in DOM Level 2:
interface NodeIterator {
  readonly attribute Node             root;
  readonly attribute unsigned long    whatToShow;
  readonly attribute NodeFilter       filter;
  readonly attribute boolean          expandEntityReferences;
  Node               nextNode()
                                        raises(DOMException);
  Node               previousNode()
                                        raises(DOMException);
  void               detach();
};

Attributes
expandEntityReferences of type boolean, readonly
The value of this flag determines whether the children of entity reference nodes are visible to the iterator. If false, they and their descendants will be rejected. Note that this rejection takes precedence over whatToShow and the filter. Also note that this is currently the only situation where NodeIterators may reject a complete subtree rather than skipping individual nodes.

To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the whatToShow flags to hide the entity reference node and set expandEntityReferences to true when creating the iterator. To produce a view of the document that has entity reference nodes but no entity expansion, use the whatToShow flags to show the entity reference node and set expandEntityReferences to false.
filter of type NodeFilter, readonly
The NodeFilter used to screen nodes.
root of type Node, readonly
The root node of the NodeIterator, as specified when it was created.
whatToShow of type unsigned long, readonly
This attribute determines which node types are presented via the iterator. The available set of constants is defined in the NodeFilter interface. Nodes not accepted by whatToShow will be skipped, but their children may still be considered. Note that this skip takes precedence over the filter, if any.
Methods
detach
Detaches the NodeIterator from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state. After detach has been invoked, calls to nextNode or previousNode will raise the exception INVALID_STATE_ERR.
No Parameters
No Return Value
No Exceptions
nextNode
Returns the next node in the set and advances the position of the iterator in the set. After a NodeIterator is created, the first call to nextNode() returns the first node in the set.
Return Value

Node

The next Node in the set being iterated over, or null if there are no more members in that set.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if this method is called after the detach method was invoked.
No Parameters
previousNode
Returns the previous node in the set and moves the position of the NodeIterator backwards in the set.
Return Value

Node

The previous Node in the set being iterated over, or null if there are no more members in that set.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if this method is called after the detach method was invoked.
No Parameters
Interface NodeFilter (introduced in DOM Level 2)

Filters are objects that know how to "filter out" nodes. If a NodeIterator or TreeWalker is given a NodeFilter, it applies the filter before it returns the next node. If the filter says to accept the node, the traversal logic returns it; otherwise, traversal looks for the next node and pretends that the node that was rejected was not there.

The DOM does not provide any filters. NodeFilter is just an interface that users can implement to provide their own filters.

NodeFilters do not need to know how to traverse from node to node, nor do they need to know anything about the data structure that is being traversed. This makes it very easy to write filters, since the only thing they have to know how to do is evaluate a single node. One filter may be used with a number of different kinds of traversals, encouraging code reuse.

IDL Definition
// Introduced in DOM Level 2:
interface NodeFilter {

  // Constants returned by acceptNode
  const short               FILTER_ACCEPT                  = 1;
  const short               FILTER_REJECT                  = 2;
  const short               FILTER_SKIP                    = 3;

  // Constants for whatToShow
  const unsigned long       SHOW_ALL                       = 0xFFFFFFFF;
  const unsigned long       SHOW_ELEMENT                   = 0x00000001;
  const unsigned long       SHOW_ATTRIBUTE                 = 0x00000002;
  const unsigned long       SHOW_TEXT                      = 0x00000004;
  const unsigned long       SHOW_CDATA_SECTION             = 0x00000008;
  const unsigned long       SHOW_ENTITY_REFERENCE          = 0x00000010;
  const unsigned long       SHOW_ENTITY                    = 0x00000020;
  const unsigned long       SHOW_PROCESSING_INSTRUCTION    = 0x00000040;
  const unsigned long       SHOW_COMMENT                   = 0x00000080;
  const unsigned long       SHOW_DOCUMENT                  = 0x00000100;
  const unsigned long       SHOW_DOCUMENT_TYPE             = 0x00000200;
  const unsigned long       SHOW_DOCUMENT_FRAGMENT         = 0x00000400;
  const unsigned long       SHOW_NOTATION                  = 0x00000800;

  short              acceptNode(in Node n);
};

Definition group Constants returned by acceptNode

The following constants are returned by the acceptNode() method:

Defined Constants
FILTER_ACCEPT
Accept the node. Navigation methods defined for NodeIterator or TreeWalker will return this node.
FILTER_REJECT
Reject the node. Navigation methods defined for NodeIterator or TreeWalker will not return this node. For TreeWalker, the children of this node will also be rejected. NodeIterators treat this as a synonym for FILTER_SKIP.
FILTER_SKIP
Skip this single node. Navigation methods defined for NodeIterator or TreeWalker will not return this node. For both NodeIterator and TreeWalker, the children of this node will still be considered.
Definition group Constants for whatToShow

These are the available values for the whatToShow parameter used in TreeWalkers and NodeIterators. They are the same as the set of possible types for Node, and their values are derived by using a bit position corresponding to the value of nodeType for the equivalent node type. If a bit in whatToShow is set false, that will be taken as a request to skip over this type of node; the behavior in that case is similar to that of FILTER_SKIP.

Note that if node types greater than 32 are ever introduced, they may not be individually testable via whatToShow. If that need should arise, it can be handled by selecting SHOW_ALL together with an appropriate NodeFilter.

Defined Constants
SHOW_ALL
Show all Nodes.
SHOW_ATTRIBUTE
Show Attr nodes. This is meaningful only when creating an iterator or tree-walker with an attribute node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.
SHOW_CDATA_SECTION
Show CDATASection nodes.
SHOW_COMMENT
Show Comment nodes.
SHOW_DOCUMENT
Show Document nodes.
SHOW_DOCUMENT_FRAGMENT
Show DocumentFragment nodes.
SHOW_DOCUMENT_TYPE
Show DocumentType nodes.
SHOW_ELEMENT
Show Element nodes.
SHOW_ENTITY
Show Entity nodes. This is meaningful only when creating an iterator or tree-walker with an Entity node as its root; in this case, it means that the Entity node will appear in the first position of the traversal. Since entities are not part of the document tree, they do not appear when traversing over the document tree.
SHOW_ENTITY_REFERENCE
Show EntityReference nodes.
SHOW_NOTATION
Show Notation nodes. This is meaningful only when creating an iterator or tree-walker with a Notation node as its root; in this case, it means that the Notation node will appear in the first position of the traversal. Since notations are not part of the document tree, they do not appear when traversing over the document tree.
SHOW_PROCESSING_INSTRUCTION
Show ProcessingInstruction nodes.
SHOW_TEXT
Show Text nodes.
Methods
acceptNode
Test whether a specified node is visible in the logical view of a TreeWalker or NodeIterator. This function will be called by the implementation of TreeWalker and NodeIterator; it is not normally called directly from user code. (Though you could do so if you wanted to use the same filter to guide your own application logic.)
Parameters
n of type Node
The node to check to see if it passes the filter or not.
Return Value

short

a constant to determine whether the node is accepted, rejected, or skipped, as defined above.
No Exceptions
Interface TreeWalker (introduced in DOM Level 2)

TreeWalker objects are used to navigate a document tree or subtree using the view of the document defined by their whatToShow flags and filter (if any). Any function which performs navigation using a TreeWalker will automatically support any view defined by a TreeWalker.

Omitting nodes from the logical view of a subtree can result in a structure that is substantially different from the same subtree in the complete, unfiltered document. Nodes that are siblings in the TreeWalker view may be children of different, widely separated nodes in the original view. For instance, consider a NodeFilter that skips all nodes except for Text nodes and the root node of a document. In the logical view that results, all text nodes will be siblings and appear as direct children of the root node, no matter how deeply nested the structure of the original document.

IDL Definition
// Introduced in DOM Level 2:
interface TreeWalker {
  readonly attribute Node             root;
  readonly attribute unsigned long    whatToShow;
  readonly attribute NodeFilter       filter;
  readonly attribute boolean          expandEntityReferences;
           attribute Node             currentNode;
                                        // raises(DOMException) on setting

  Node               parentNode();
  Node               firstChild();
  Node               lastChild();
  Node               previousSibling();
  Node               nextSibling();
  Node               previousNode();
  Node               nextNode();
};

Attributes
currentNode of type Node
The node at which the TreeWalker is currently positioned.
Alterations to the DOM tree may cause the current node to no longer be accepted by the TreeWalker's associated filter. currentNode may also be explicitly set to any node, whether or not it is within the subtree specified by the root node or would be accepted by the filter and whatToShow flags. Further traversal occurs relative to currentNode even if it is not part of the current view, by applying the filters in the requested direction; if no traversal is possible, currentNode is not changed.
Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: Raised if an attempt is made to set currentNode to null.
expandEntityReferences of type boolean, readonly
The value of this flag determines whether the children of entity reference nodes are visible to the TreeWalker. If false, they and their descendants will be rejected. Note that this rejection takes precedence over whatToShow and the filter, if any.
To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the whatToShow flags to hide the entity reference node and set expandEntityReferences to true when creating the TreeWalker. To produce a view of the document that has entity reference nodes but no entity expansion, use the whatToShow flags to show the entity reference node and set expandEntityReferences to false.
filter of type NodeFilter, readonly
The filter used to screen nodes.
root of type Node, readonly
The root node of the TreeWalker, as specified when it was created.
whatToShow of type unsigned long, readonly
This attribute determines which node types are presented via the TreeWalker. The available set of constants is defined in the NodeFilter interface. Nodes not accepted by whatToShow will be skipped, but their children may still be considered. Note that this skip takes precedence over the filter, if any.
Methods
firstChild
Moves the TreeWalker to the first visible child of the current node, and returns the new node. If the current node has no visible children, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no visible children in the TreeWalker's logical view.
No Parameters
No Exceptions
lastChild
Moves the TreeWalker to the last visible child of the current node, and returns the new node. If the current node has no visible children, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no children in the TreeWalker's logical view.
No Parameters
No Exceptions
nextNode
Moves the TreeWalker to the next visible node in document order relative to the current node, and returns the new node. If the current node has no next node, or if the search for nextNode attempts to step upward from the TreeWalker's root node, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no next node in the TreeWalker's logical view.
No Parameters
No Exceptions
nextSibling
Moves the TreeWalker to the next sibling of the current node, and returns the new node. If the current node has no visible next sibling, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no next sibling. in the TreeWalker's logical view.
No Parameters
No Exceptions
parentNode
Moves to and returns the closest visible ancestor node of the current node. If the search for parentNode attempts to step upward from the TreeWalker's root node, or if it fails to find a visible ancestor node, this method retains the current position and returns null.
Return Value

Node

The new parent node, or null if the current node has no parent in the TreeWalker's logical view.
No Parameters
No Exceptions
previousNode
Moves the TreeWalker to the previous visible node in document order relative to the current node, and returns the new node. If the current node has no previous node, or if the search for previousNode attempts to step upward from the TreeWalker's root node, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no previous node in the TreeWalker's logical view.
No Parameters
No Exceptions
previousSibling
Moves the TreeWalker to the previous sibling of the current node, and returns the new node. If the current node has no visible previous sibling, returns null, and retains the current node.
Return Value

Node

The new node, or null if the current node has no previous sibling. in the TreeWalker's logical view.
No Parameters
No Exceptions
Interface DocumentTraversal (introduced in DOM Level 2)

DocumentTraversal contains methods that create iterators and tree-walkers to traverse a node and its children in document order (depth first, pre-order traversal, which is equivalent to the order in which the start tags occur in the text representation of the document). In DOMs which support the Traversal feature, DocumentTraversal will be implemented by the same objects that implement the Document interface.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentTraversal {
  NodeIterator       createNodeIterator(in Node root,
                                        in unsigned long whatToShow,
                                        in NodeFilter filter,
                                        in boolean entityReferenceExpansion)
                                        raises(DOMException);
  TreeWalker         createTreeWalker(in Node root,
                                      in unsigned long whatToShow,
                                      in NodeFilter filter,
                                      in boolean entityReferenceExpansion)
                                        raises(DOMException);
};

Methods
createNodeIterator
Create a new NodeIterator over the subtree rooted at the specified node.
Parameters
root of type Node
The node which will be iterated together with its children. The iterator is initially positioned just before this node. The whatToShow flags and the filter, if any, are not considered when setting this position. The root must not be null.
whatToShow of type unsigned long
This flag specifies which node types may appear in the logical view of the tree presented by the iterator. See the description of NodeFilter for the set of possible SHOW_ values.
These flags can be combined using OR.
filter of type NodeFilter
The NodeFilter to be used with this TreeWalker, or null to indicate no filter.
entityReferenceExpansion of type boolean
The value of this flag determines whether entity reference nodes are expanded.
Return Value

NodeIterator

The newly created NodeIterator.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the specified root is null.
createTreeWalker
Create a new TreeWalker over the subtree rooted at the specified node.
Parameters
root of type Node
The node which will serve as the root for the TreeWalker. The whatToShow flags and the NodeFilter are not considered when setting this value; any node type will be accepted as the root. The currentNode of the TreeWalker is initialized to this node, whether or not it is visible. The root functions as a stopping point for traversal methods that look upward in the document structure, such as parentNode and nextNode. The root must not be null.
whatToShow of type unsigned long
This flag specifies which node types may appear in the logical view of the tree presented by the tree-walker. See the description of NodeFilter for the set of possible SHOW_ values.
These flags can be combined using OR.
filter of type NodeFilter
The NodeFilter to be used with this TreeWalker, or null to indicate no filter.
entityReferenceExpansion of type boolean
If this flag is false, the contents of EntityReference nodes are not presented in the logical view.
Return Value

TreeWalker

The newly created TreeWalker.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the specified root is null.
previous next contents index


Document Object Model Range

previous next contents index

13 November, 2000

2. Document Object Model Range

Editors
Peter Sharpe, SoftQuad Software Inc.
Vidur Apparao, Netscape Communications Corp.
Lauren Wood, SoftQuad Software Inc.

Table of contents

  • 2.1. Introduction
  • 2.2. Definitions and Notation
    • 2.2.1. Position
    • 2.2.2. Selection and Partial Selection
    • 2.2.3. Notation
  • 2.3. Creating a Range
  • 2.4. Changing a Range's Position
  • 2.5. Comparing Range Boundary-Points
  • 2.6. Deleting Content with a Range
  • 2.7. Extracting Content
  • 2.8. Cloning Content
  • 2.9. Inserting Content
  • 2.10. Surrounding Content
  • 2.11. Miscellaneous Members
  • 2.12. Range modification under document mutation
    • 2.12.1. Insertions
    • 2.12.2. Deletions
  • 2.13. Formal Description of the Range Interface
    • Range, DocumentRange, RangeException, RangeExceptionCode

2.1. Introduction

A Range identifies a range of content in a Document, DocumentFragment or Attr. It is contiguous in the sense that it can be characterized as selecting all of the content between a pair of boundary-points.

Note: In a text editor or a word processor, a user can make a selection by pressing down the mouse at one point in a document, moving the mouse to another point, and releasing the mouse. The resulting selection is contiguous and consists of the content between the two points.

The term 'selecting' does not mean that every Range corresponds to a selection made by a GUI user; however, such a selection can be returned to a DOM user as a Range.

Note: In bidirectional writing (Arabic, Hebrew), a range may correspond to a logical selection that is not necessarily contiguous when displayed. A visually contiguous selection, also used in some cases, may not correspond to a single logical selection, and may therefore have to be represented by more than one range.

The Range interface provides methods for accessing and manipulating the document tree at a higher level than similar methods in the Node interface. The expectation is that each of the methods provided by the Range interface for the insertion, deletion and copying of content can be directly mapped to a series of Node editing operations enabled by DOM Core. In this sense, the Range operations can be viewed as convenience methods that also enable the implementation to optimize common editing patterns.

This chapter describes the Range interface, including methods for creating and moving a Range and methods for manipulating content with Ranges.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Range" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined defined in the DOM Level 2 Core specification [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

2.2. Definitions and Notation

2.2.1. Position

This chapter refers to two different representations of a document: the text or source form that includes the document markup and the tree representation similar to the one described in the introduction section of the DOM Level 2 Core [DOM Level 2 Core].

A Range consists of two boundary-points corresponding to the start and the end of the Range. A boundary-point's position in a Document or DocumentFragment tree can be characterized by a node and an offset. The node is called the container of the boundary-point and of its position. The container and its ancestors are the ancestor containers of the boundary-point and of its position. The offset within the node is called the offset of the boundary-point and its position. If the container is an Attr, Document, DocumentFragment, Element or EntityReference node, the offset is between its child nodes. If the container is a CharacterData, Comment or ProcessingInstruction node, the offset is between the 16-bit units of the UTF-16 encoded string contained by it.

The boundary-points of a Range must have a common ancestor container which is either a Document, DocumentFragment or Attr node. That is, the content of a Range must be entirely within the subtree rooted by a single Document, DocumentFragment or Attr Node. This common ancestor container is known as the root container of the Range. The tree rooted by the root container is known as the Range's context tree.

The container of a boundary-point of a Range must be an Element, Comment, ProcessingInstruction, EntityReference, CDATASection, Document, DocumentFragment, Attr, or Text node. None of the ancestor containers of the boundary-point of a Range can be a DocumentType, Entity or Notation node.

In terms of the text representation of a document, the boundary-points of a Range can only be on token boundaries. That is, the boundary-point of the text range cannot be in the middle of a start- or end-tag of an element or within the name of an entity or character reference. A Range locates a contiguous portion of the content of the structure model.

The relationship between locations in a text representation of the document and in the Node tree interface of the DOM is illustrated in the following diagram:

Range Example
Range Example

In this diagram, four different Ranges are illustrated. The boundary-points of each Range are labelled with s# (the start of the Range) and e# (the end of the Range), where # is the number of the Range. For Range 2, the start is in the BODY element and is immediately after the H1 element and immediately before the P element, so its position is between the H1 and P children of BODY. The offset of a boundary-point whose container is not a CharacterData node is 0 if it is before the first child, 1 if between the first and second child, and so on. So, for the start of the Range 2, the container is BODY and the offset is 1. The offset of a boundary-point whose container is a CharacterData node is obtained similarly but using 16-bit unit positions instead. For example, the boundary-point labelled s1 of the Range 1 has a Text node (the one containing "Title") as its container and an offset of 2 since it is between the second and third 16-bit unit.

Notice that the boundary-points of Ranges 3 and 4 correspond to the same location in the text representation. An important feature of the Range is that a boundary-point of a Range can unambiguously represent every position within the document tree.

The containers and offsets of the boundary-points can be obtained through the following read-only Range attributes:

  readonly attribute Node startContainer;
  readonly attribute long startOffset;
  readonly attribute Node endContainer;
  readonly attribute long endOffset;

If the boundary-points of a Range have the same containers and offsets, the Range is said to be a collapsed Range. (This is often referred to as an insertion point in a user agent.)

2.2.2. Selection and Partial Selection

A node or 16-bit unit unit is said to be selected by a Range if it is between the two boundary-points of the Range, that is, if the position immediately before the node or 16-bit unit is before the end of the Range and the position immediately after the node or 16-bit unit is after the start of the range. For example, in terms of a text representation of the document, an element would be selected by a Range if its corresponding start-tag was located after the start of the Range and its end-tag was located before the end of the Range. In the examples in the above diagram, the Range 2 selects the P node and the Range 3 selects the text node containing the text "Blah xyz."

A node is said to be partially selected by a Range if it is an ancestor container of exactly one boundary-point of the Range. For example, consider Range 1 in the above diagram. The element H1 is partially selected by that Range since the start of the Range is within one of its children.

2.2.3. Notation

Many of the examples in this chapter are illustrated using a text representation of a document. The boundary-points of a Range are indicated by displaying the characters (be they markup or data characters) between the two boundary-points in bold, as in

    <FOO>ABC<BAR>DEF</BAR></FOO>

When both boundary-points are at the same position, they are indicated with a bold caret ('^'), as in

    <FOO>A^BC<BAR>DEF</BAR></FOO>

2.3. Creating a Range

A Range is created by calling the createRange() method on the DocumentRange interface. This interface can be obtained from the object implementing the Document interface using binding-specific casting methods.

  interface DocumentRange {
    Range createRange();
  }

The initial state of the Range returned from this method is such that both of its boundary-points are positioned at the beginning of the corresponding Document, before any content. In other words, the container of each boundary-point is the Document node and the offset within that node is 0.

Like some objects created using methods in the Document interface (such as Nodes and DocumentFragments), Ranges created via a particular document instance can select only content associated with that Document, or with DocumentFragments and Attrs for which that Document is the ownerDocument. Such Ranges, then, can not be used with other Document instances.

2.4. Changing a Range's Position

A Range's position can be specified by setting the container and offset of each boundary-point with the setStart and setEnd methods.

  void setStart(in Node parent, in long offset)
                        raises(RangeException);
  void setEnd(in Node parent, in long offset)
                raises(RangeException);

If one boundary-point of a Range is set to have a root container other than the current one for the Range, the Range is collapsed to the new position. This enforces the restriction that both boundary-points of a Range must have the same root container.

The start position of a Range is guaranteed to never be after the end position. To enforce this restriction, if the start is set to be at a position after the end, the Range is collapsed to that position. Similarly, if the end is set to be at a position before the start, the Range is collapsed to that position.

It is also possible to set a Range's position relative to nodes in the tree:

  void setStartBefore(in Node node);
                              raises(RangeException);
  void setStartAfter(in Node node);
                       raises(RangeException);
  void setEndBefore(in Node node);
                      raises(RangeException);
  void setEndAfter(in Node node);
                     raises(RangeException);

The parent of the node becomes the container of the boundary-point and the Range is subject to the same restrictions as given above in the description of setStart()and setEnd().

A Range can be collapsed to either boundary-point:

  void collapse(in boolean toStart);

Passing TRUE as the parameter toStart will collapse the Range to its start, FALSE to its end.

Testing whether a Range is collapsed can be done by examining the collapsed attribute:

  readonly attribute boolean collapsed;

The following methods can be used to make a Range select the contents of a node or the node itself.

  void selectNode(in Node n);
  void selectNodeContents(in Node n);

The following examples demonstrate the operation of the methods selectNode and selectNodeContents:

Before:
  ^<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
After Range.selectNodeContents(FOO):
  <BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>
(In this case, FOO is the parent of both boundary-points)
After Range.selectNode(FOO):

<BAR><FOO>A<MOO>B</MOO>C</FOO></BAR>

2.5. Comparing Range Boundary-Points

It is possible to compare two Ranges by comparing their boundary-points:

  short compareBoundaryPoints(in CompareHow how, in Range sourceRange) raises(RangeException);

where CompareHow is one of four values: START_TO_START, START_TO_END, END_TO_END and END_TO_START. The return value is -1, 0 or 1 depending on whether the corresponding boundary-point of the Range is before, equal to, or after the corresponding boundary-point of sourceRange. An exception is thrown if the two Ranges have different root containers.

The result of comparing two boundary-points (or positions) is specified below. An informal but not always correct specification is that an boundary-point is before, equal to, or after another if it corresponds to a location in a text representation before, equal to, or after the other's corresponding location.

Let A and B be two boundary-points or positions. Then one of the following holds: A is before B, A is equal to B, or A is after B. Which one holds is specified in the following by examining four cases:

In the first case the boundary-points have the same container. A is before B if its offset is less than the offset of B, A is equal to B if its offset is equal to the offset of B, and A is after B if its offset is greater than the offset of B.

In the second case a child node C of the container of A is an ancestor container of B. In this case, A is before B if the offset of A is less than or equal to the index of the child node C and A is after B otherwise.

In the third case a child node C of the container of B is an ancestor container of A. In this case, A is before B if the index of the child node C is less than the offset of B and A is after B otherwise.

In the fourth case, none of three other cases hold: the containers of A and B are siblings or descendants of sibling nodes. In this case, A is before B if the container of A is before the container of B in a pre-order traversal of the Ranges' context tree and A is after B otherwise.

Note that because the same location in a text representation of the document can correspond to two different positions in the DOM tree, it is possible for two boundary-points to not compare equal even though they would be equal in the text representation. For this reason, the informal definition above can sometimes be incorrect.

2.6. Deleting Content with a Range

One can delete the contents selected by a Range with:

  void deleteContents();

deleteContents() deletes all nodes and characters selected by the Range. All other nodes and characters remain in the context tree of the Range. Some examples of this deletion operation are:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
<FOO>A^CD</FOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<FOO>A<MOO>B</MOO>^E</FOO>

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
<FOO>X^<BAR>W</BAR>Q</FOO>

(4) <FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO>
-->  <FOO><BAR1>A</BAR1>^<BAR3>D</BAR3>

After deleteContents() is invoked on a Range, the Range is collapsed. If no node was partially selected by the Range, then it is collapsed to its original start point, as in example (1). If a node was partially selected by the Range and was an ancestor container of the start of the Range and no ancestor of the node satisfies these two conditions, then the Range is collapsed to the position immediately after the node, as in examples (2) and (4). If a node was partially selected by the Range and was an ancestor container of the end of the Range and no ancestor of the node satisfies these two conditions, then the Range is collapsed to the position immediately before the node, as in examples (3) and (4).

Note that if deletion of a Range leaves adjacent Text nodes, they are not automatically merged, and empty Text nodes are not automatically removed. Two Text nodes should be joined only if each is the container of one of the boundary-points of a Range whose contents are deleted. To merge adjacent Text nodes, or remove empty text nodes, the normalize() method on the Node interface should be used.

2.7. Extracting Content

If the contents of a Range need to be extracted rather than deleted, the following method may be used:

  DocumentFragment extractContents();

The extractContents() method removes nodes from the Range's context tree similarly to the deleteContents() method. In addition, it places the deleted contents in a new DocumentFragment. The following examples illustrate the contents of the returned DocumentFragment:

(1) <FOO>AB<MOO>CD</MOO>CD</FOO>  -->
B<MOO>CD</MOO>

(2) <FOO>A<MOO>BC</MOO>DE</FOO>  -->
<MOO>C<MOO>D

(3) <FOO>XY<BAR>ZW</BAR>Q</FOO>  -->
Y<BAR>Z</BAR>

(4)
<FOO><BAR1>AB</BAR1><BAR2/><BAR3>CD</BAR3></FOO> -->
<BAR1>B</BAR1><BAR2/><BAR3>C</BAR3>

It is important to note that nodes that are partially selected by the Range are cloned. Since part of such a node's contents must remain in the Range's context tree and part of the contents must be moved to the new DocumentFragment, a clone of the partially selected node is included in the new DocumentFragment. Note that cloning does not take place for selected elements; these nodes are moved to the new DocumentFragment.

2.8. Cloning Content

The contents of a Range may be duplicated using the following method:

  DocumentFragment cloneContents();

This method returns a DocumentFragment that is similar to the one returned by the method extractContents(). However, in this case, the original nodes and character data in the Range are not removed from the Range's context tree. Instead, all of the nodes and text content within the returned DocumentFragment are cloned.

2.9. Inserting Content

A node may be inserted into a Range using the following method:

  void insertNode(in Node n) raises(RangeException);

The insertNode() method inserts the specified node into the Range's context tree. The node is inserted at the start boundary-point of the Range, without modifying it.

If the start boundary point of the Range is in a Text node, the insertNode operation splits the Text node at the boundary point. If the node to be inserted is also a Text node, the resulting adjacent Text nodes are not normalized automatically; this operation is left to the application.

The Node passed into this method can be a DocumentFragment. In that case, the contents of the DocumentFragment are inserted at the start boundary-point of the Range, but the DocumentFragment itself is not. Note that if the Node represents the root of a sub-tree, the entire sub-tree is inserted.

The same rules that apply to the insertBefore() method on the Node interface apply here. Specifically, the Node passed in, if it already has a parent, will be removed from its existing position.

2.10. Surrounding Content

The insertion of a single node to subsume the content selected by a Range can be performed with:

  void surroundContents(in Node newParent);

The surroundContents() method causes all of the content selected by the Range to be rooted by the specified node. The nodes may not be Attr, Entity, DocumentType, Notation, Document, or DocumentFragment nodes. Calling surroundContents() with the Element node FOO in the following examples yields:

     Before:
       <BAR>AB<MOO>C</MOO>DE</BAR>

     After surroundContents(FOO):

<BAR>A<FOO>B<MOO>C</MOO>D</FOO>E</BAR>

Another way of describing the effect of this method on the Range's context tree is to decompose it in terms of other operations:

  1. Remove the contents selected by the Range with a call to extractContents().
  2. Insert the node newParent where the Range is collapsed (after the extraction) with insertNode().
  3. Insert the entire contents of the extracted DocumentFragment into newParent. Specifically, invoke the appendChild() on newParent passing in the DocumentFragment returned as a result of the call to extractContents()
  4. Select newParent and all of its contents with selectNode().

The surroundContents() method raises an exception if the Range partially selects a non-Text node. An example of a Range for which surroundContents()raises an exception is:

     <FOO>AB<BAR>CD</BAR>E</FOO>

If the node newParent has any children, those children are removed before its insertion. Also, if the node newParent already has a parent, it is removed from the original parent's childNodes list.

2.11. Miscellaneous Members

One can clone a Range:

  Range cloneRange();

This creates a new Range which selects exactly the same content as that selected by the Range on which the method cloneRange was invoked. No content is affected by this operation.

Because the boundary-points of a Range do not necessarily have the same containers, use:

  readonly attribute Node commonAncestorContainer;

to get the ancestor container of both boundary-points that is furthest down from the Range's root container

One can get a copy of all the character data selected or partially selected by a Range with:

  DOMString toString();

This does nothing more than simply concatenate all the character data selected by the Range. This includes character data in both Text and CDATASection nodes.

2.12. Range modification under document mutation

As a document is modified, the Ranges within the document need to be updated. For example, if one boundary-point of a Range is within a node and that node is removed from the document, then the Range would be invalid unless it is fixed up in some way. This section describes how Ranges are modified under document mutations so that they remain valid.

There are two general principles which apply to Ranges under document mutation: The first is that all Ranges in a document will remain valid after any mutation operation and the second is that, as much as possible, all Ranges will select the same portion of the document after any mutation operation.

Any mutation of the document tree which affect Ranges can be considered to be a combination of basic deletion and insertion operations. In fact, it can be convenient to think of those operations as being accomplished using the deleteContents() and insertNode() Range methods and, in the case of Text mutations, the splitText() and normalize() methods.

2.12.1. Insertions

An insertion occurs at a single point, the insertion point, in the document. For any Range in the document tree, consider each boundary-point. The only case in which the boundary-point will be changed after the insertion is when the boundary-point and the insertion point have the same container and the offset of the insertion point is strictly less than the offset of the Range's boundary-point. In that case the offset of the Range's boundary-point will be increased so that it is between the same nodes or characters as it was before the insertion.

Note that when content is inserted at a boundary-point, it is ambiguous as to where the boundary-point should be repositioned if its relative position is to be maintained. There are two possibilities: at the start or at the end of the newly inserted content. We have chosen that in this case neither the container nor offset of the boundary-point is changed. As a result, the boundary-point will be positioned at the start of the newly inserted content.

Examples:

Suppose the Range selects the following:

<P>Abcd efgh XY blah ijkl</P>

Consider the insertion of the text "inserted text" at the following positions:

1. Before the 'X':

<P>Abcd efgh inserted textXY blah ijkl</P>

2. After the 'X':

<P>Abcd efgh Xinserted textY blah ijkl</P>

3. After the 'Y':

<P>Abcd efgh XYinserted text blah ijkl</P>

4. After the 'h' in "Y blah":

<P>Abcd efgh XY blahinserted text ijkl</P>

2.12.2. Deletions

Any deletion from the document tree can be considered as a sequence of deleteContents() operations applied to a minimal set of disjoint Ranges. To specify how a Range is modified under deletions we need only consider what happens to a Range under a single deleteContents()operation of another Range. And, in fact, we need only consider what happens to a single boundary-point of the Range since both boundary-points are modified using the same algorithm.

If a boundary-point of the original Range is within the content being deleted, then after the deletion it will be at the same position as the resulting boundary-point of the (now collapsed) Range used to delete the contents.

If a boundary-point is after the content being deleted then it is not affected by the deletion unless its container is also the container of one of the boundary-points of the Range being deleted. If there is such a common container, then the index of the boundary-point is modified so that the boundary-point maintains its position relative to the content of the container.

If a boundary-point is before the content being deleted then it is not affected by the deletion at all.

Examples:

In these examples, the Range on which deleteContents()is invoked is indicated by the underline.

Example 1.

Before:

<P>Abcd efgh The Range ijkl</P>

After:

<P>Abcd Range ijkl</P>

Example 2.

Before:

<p>Abcd efgh The Range ijkl</p>

After:

<p>Abcd ^kl</p>

Example 3.

Before:

<P>ABCD efgh The <EM>Range</EM> ijkl</P>

After:

<P>ABCD <EM>ange</EM> ijkl</P>

In this example, the container of the start boundary-point after the deletion is the Text node holding the string "ange".

Example 4.

Before:

<P>Abcd efgh The Range ijkl</P>

After:

<P>Abcd he Range ijkl</P>

Example 5.

Before:

<P>Abcd <EM>efgh The Range ij</EM>kl</P>

After:

<P>Abcd ^kl</P>

2.13. Formal Description of the Range Interface

To summarize, the complete, formal description of the Range interface is given below:

Interface Range (introduced in DOM Level 2)

IDL Definition
// Introduced in DOM Level 2:
interface Range {
  readonly attribute Node             startContainer;
                                        // raises(DOMException) on retrieval

  readonly attribute long             startOffset;
                                        // raises(DOMException) on retrieval

  readonly attribute Node             endContainer;
                                        // raises(DOMException) on retrieval

  readonly attribute long             endOffset;
                                        // raises(DOMException) on retrieval

  readonly attribute boolean          collapsed;
                                        // raises(DOMException) on retrieval

  readonly attribute Node             commonAncestorContainer;
                                        // raises(DOMException) on retrieval

  void               setStart(in Node refNode,
                              in long offset)
                                        raises(RangeException,
                                               DOMException);
  void               setEnd(in Node refNode,
                            in long offset)
                                        raises(RangeException,
                                               DOMException);
  void               setStartBefore(in Node refNode)
                                        raises(RangeException,
                                               DOMException);
  void               setStartAfter(in Node refNode)
                                        raises(RangeException,
                                               DOMException);
  void               setEndBefore(in Node refNode)
                                        raises(RangeException,
                                               DOMException);
  void               setEndAfter(in Node refNode)
                                        raises(RangeException,
                                               DOMException);
  void               collapse(in boolean toStart)
                                        raises(DOMException);
  void               selectNode(in Node refNode)
                                        raises(RangeException,
                                               DOMException);
  void               selectNodeContents(in Node refNode)
                                        raises(RangeException,
                                               DOMException);

  // CompareHow
  const unsigned short      START_TO_START                 = 0;
  const unsigned short      START_TO_END                   = 1;
  const unsigned short      END_TO_END                     = 2;
  const unsigned short      END_TO_START                   = 3;

  short              compareBoundaryPoints(in unsigned short how,
                                           in Range sourceRange)
                                        raises(DOMException);
  void               deleteContents()
                                        raises(DOMException);
  DocumentFragment   extractContents()
                                        raises(DOMException);
  DocumentFragment   cloneContents()
                                        raises(DOMException);
  void               insertNode(in Node newNode)
                                        raises(DOMException,
                                               RangeException);
  void               surroundContents(in Node newParent)
                                        raises(DOMException,
                                               RangeException);
  Range              cloneRange()
                                        raises(DOMException);
  DOMString          toString()
                                        raises(DOMException);
  void               detach()
                                        raises(DOMException);
};

Definition group CompareHow

Passed as a parameter to the compareBoundaryPoints method.

Defined Constants
END_TO_END
Compare end boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked.
END_TO_START
Compare end boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked.
START_TO_END
Compare start boundary-point of sourceRange to end boundary-point of Range on which compareBoundaryPoints is invoked.
START_TO_START
Compare start boundary-point of sourceRange to start boundary-point of Range on which compareBoundaryPoints is invoked.
Attributes
collapsed of type boolean, readonly
TRUE if the Range is collapsed
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
commonAncestorContainer of type Node, readonly
The deepest common ancestor container of the Range's two boundary-points.
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
endContainer of type Node, readonly
Node within which the Range ends
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
endOffset of type long, readonly
Offset within the ending node of the Range.
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
startContainer of type Node, readonly
Node within which the Range begins
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
startOffset of type long, readonly
Offset within the starting node of the Range.
Exceptions on retrieval

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
Methods
cloneContents
Duplicates the contents of a Range
Return Value

DocumentFragment

A DocumentFragment that contains content equivalent to this Range.
Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
cloneRange
Produces a new Range whose boundary-points are equal to the boundary-points of the Range.
Return Value

Range

The duplicated Range.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
collapse
Collapse a Range onto one of its boundary-points
Parameters
toStart of type boolean
If TRUE, collapses the Range onto its start; if FALSE, collapses it onto its end.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
compareBoundaryPoints
Compare the boundary-points of two Ranges in a document.
Parameters
how of type unsigned short
A code representing the type of comparison, as defined above.
sourceRange of type Range
The Range on which this current Range is compared to.
Return Value

short

-1, 0 or 1 depending on whether the corresponding boundary-point of the Range is respectively before, equal to, or after the corresponding boundary-point of sourceRange.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if the two Ranges are not in the same Document or DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
deleteContents
Removes the contents of a Range from the containing document or document fragment without returning a reference to the removed content.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes that contain any of the content of the Range are read-only.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
No Return Value
detach
Called to indicate that the Range is no longer in use and that the implementation may relinquish any resources associated with this Range. Subsequent calls to any methods or attribute getters on this Range will result in a DOMException being thrown with an error code of INVALID_STATE_ERR.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
No Return Value
extractContents
Moves the contents of a Range from the containing document or document fragment to a new DocumentFragment.
Return Value

DocumentFragment

A DocumentFragment containing the extracted contents.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if any portion of the content of the Range is read-only or any of the nodes which contain any of the content of the Range are read-only.

HIERARCHY_REQUEST_ERR: Raised if a DocumentType node would be extracted into the new DocumentFragment.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
insertNode
Inserts a node into the Document or DocumentFragment at the start of the Range. If the container is a Text node, this will be split at the start of the Range (as if the Text node's splitText method was performed at the insertion point) and the insertion will occur between the two resulting Text nodes. Adjacent Text nodes will not be automatically merged. If the node to be inserted is a DocumentFragment node, the children will be inserted rather than the DocumentFragment node itself.
Parameters
newNode of type Node
The node to insert at the start of the Range
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of the start of the Range is read-only.

WRONG_DOCUMENT_ERR: Raised if newNode and the container of the start of the Range were not created from the same document.

HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newNode or if newNode is an ancestor of the container.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

RangeException

INVALID_NODE_TYPE_ERR: Raised if newNode is an Attr, Entity, Notation, or Document node.
No Return Value
selectNode
Select a node and its contents
Parameters
refNode of type Node
The node to select.
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if an ancestor of refNode is an Entity, Notation or DocumentType node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
selectNodeContents
Select the contents within a node
Parameters
refNode of type Node
Node to select from
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation or DocumentType node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setEnd
Sets the attributes describing the end of a Range.
Parameters
refNode of type Node
The refNode value. This parameter must be different from null.
offset of type long
The endOffset value.
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node.

DOMException

INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of child units in refNode. Child units are 16-bit units if refNode is a type of CharacterData node (e.g., a Text or Comment node) or a ProcessingInstruction node. Child units are Nodes in all other cases.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setEndAfter
Sets the end of a Range to be after a node
Parameters
refNode of type Node
Range ends after refNode.
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setEndBefore
Sets the end position to be before a node.
Parameters
refNode of type Node
Range ends before refNode
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setStart
Sets the attributes describing the start of the Range.
Parameters
refNode of type Node
The refNode value. This parameter must be different from null.
offset of type long
The startOffset value.
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if refNode or an ancestor of refNode is an Entity, Notation, or DocumentType node.

DOMException

INDEX_SIZE_ERR: Raised if offset is negative or greater than the number of child units in refNode. Child units are 16-bit units if refNode is a type of CharacterData node (e.g., a Text or Comment node) or a ProcessingInstruction node. Child units are Nodes in all other cases.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setStartAfter
Sets the start position to be after a node
Parameters
refNode of type Node
Range starts after refNode
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
setStartBefore
Sets the start position to be before a node
Parameters
refNode of type Node
Range starts before refNode
Exceptions

RangeException

INVALID_NODE_TYPE_ERR: Raised if the root container of refNode is not an Attr, Document, or DocumentFragment node or if refNode is a Document, DocumentFragment, Attr, Entity, or Notation node.

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Return Value
surroundContents
Reparents the contents of the Range to the given node and inserts the node at the position of the start of the Range.
Parameters
newParent of type Node
The node to surround the contents with.
Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if an ancestor container of either boundary-point of the Range is read-only.

WRONG_DOCUMENT_ERR: Raised if newParent and the container of the start of the Range were not created from the same document.

HIERARCHY_REQUEST_ERR: Raised if the container of the start of the Range is of a type that does not allow children of the type of newParent or if newParent is an ancestor of the container or if node would end up with a child node of a type not allowed by the type of node.

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.

RangeException

BAD_BOUNDARYPOINTS_ERR: Raised if the Range partially selects a non-text node.

INVALID_NODE_TYPE_ERR: Raised if node is an Attr, Entity, DocumentType, Notation, Document, or DocumentFragment node.
No Return Value
toString
Returns the contents of a Range as a string. This string contains only the data characters, not any markup.
Return Value

DOMString

The contents of the Range.
Exceptions

DOMException

INVALID_STATE_ERR: Raised if detach() has already been invoked on this object.
No Parameters
Interface DocumentRange (introduced in DOM Level 2)

IDL Definition
// Introduced in DOM Level 2:
interface DocumentRange {
  Range              createRange();
};

Methods
createRange
This interface can be obtained from the object implementing the Document interface using binding-specific casting methods.
Return Value

Range

The initial state of the Range returned from this method is such that both of its boundary-points are positioned at the beginning of the corresponding Document, before any content. The Range returned can only be used to select content associated with this Document, or with DocumentFragments and Attrs for which this Document is the ownerDocument.
No Parameters
No Exceptions
Exception RangeException introduced in DOM Level 2

Range operations may throw a RangeException as specified in their method descriptions.

IDL Definition
// Introduced in DOM Level 2:
exception RangeException {
  unsigned short   code;
};
// RangeExceptionCode
const unsigned short      BAD_BOUNDARYPOINTS_ERR         = 1;
const unsigned short      INVALID_NODE_TYPE_ERR          = 2;

Definition group RangeExceptionCode

An integer indicating the type of error generated.

Defined Constants
BAD_BOUNDARYPOINTS_ERR
If the boundary-points of a Range do not meet specific requirements.
INVALID_NODE_TYPE_ERR
If the container of an boundary-point of a Range is being set to either a node of an invalid type or a node with an ancestor of an invalid type.
previous next contents index


IDL Definitions

previous next contents index

13 November, 2000

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMGIDL] for the Level 2 Document Object Model Traversal and Range definitions. The definitions are divided into Traversal, and Range.

The IDL files are also available as: http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/idl.zip

A.1: Document Object Model Traversal

traversal.idl:

// File: traversal.idl

#ifndef _TRAVERSAL_IDL_
#define _TRAVERSAL_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module traversal
{

  typedef dom::Node Node;

  interface NodeFilter;

  // Introduced in DOM Level 2:
  interface NodeIterator {
    readonly attribute Node             root;
    readonly attribute unsigned long    whatToShow;
    readonly attribute NodeFilter       filter;
    readonly attribute boolean          expandEntityReferences;
    Node               nextNode()
                                        raises(dom::DOMException);
    Node               previousNode()
                                        raises(dom::DOMException);
    void               detach();
  };

  // Introduced in DOM Level 2:
  interface NodeFilter {

    // Constants returned by acceptNode
    const short               FILTER_ACCEPT                  = 1;
    const short               FILTER_REJECT                  = 2;
    const short               FILTER_SKIP                    = 3;

    // Constants for whatToShow
    const unsigned long       SHOW_ALL                       = 0xFFFFFFFF;
    const unsigned long       SHOW_ELEMENT                   = 0x00000001;
    const unsigned long       SHOW_ATTRIBUTE                 = 0x00000002;
    const unsigned long       SHOW_TEXT                      = 0x00000004;
    const unsigned long       SHOW_CDATA_SECTION             = 0x00000008;
    const unsigned long       SHOW_ENTITY_REFERENCE          = 0x00000010;
    const unsigned long       SHOW_ENTITY                    = 0x00000020;
    const unsigned long       SHOW_PROCESSING_INSTRUCTION    = 0x00000040;
    const unsigned long       SHOW_COMMENT                   = 0x00000080;
    const unsigned long       SHOW_DOCUMENT                  = 0x00000100;
    const unsigned long       SHOW_DOCUMENT_TYPE             = 0x00000200;
    const unsigned long       SHOW_DOCUMENT_FRAGMENT         = 0x00000400;
    const unsigned long       SHOW_NOTATION                  = 0x00000800;

    short              acceptNode(in Node n);
  };

  // Introduced in DOM Level 2:
  interface TreeWalker {
    readonly attribute Node             root;
    readonly attribute unsigned long    whatToShow;
    readonly attribute NodeFilter       filter;
    readonly attribute boolean          expandEntityReferences;
             attribute Node             currentNode;
                                        // raises(dom::DOMException) on setting

    Node               parentNode();
    Node               firstChild();
    Node               lastChild();
    Node               previousSibling();
    Node               nextSibling();
    Node               previousNode();
    Node               nextNode();
  };

  // Introduced in DOM Level 2:
  interface DocumentTraversal {
    NodeIterator       createNodeIterator(in Node root,
                                          in unsigned long whatToShow,
                                          in NodeFilter filter,
                                          in boolean entityReferenceExpansion)
                                        raises(dom::DOMException);
    TreeWalker         createTreeWalker(in Node root,
                                        in unsigned long whatToShow,
                                        in NodeFilter filter,
                                        in boolean entityReferenceExpansion)
                                        raises(dom::DOMException);
  };
};

#endif // _TRAVERSAL_IDL_

A.2: Document Object Model Range

ranges.idl:

// File: ranges.idl

#ifndef _RANGES_IDL_
#define _RANGES_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module ranges
{

  typedef dom::Node Node;
  typedef dom::DocumentFragment DocumentFragment;
  typedef dom::DOMString DOMString;

  // Introduced in DOM Level 2:
  exception RangeException {
    unsigned short   code;
  };
  // RangeExceptionCode
  const unsigned short      BAD_BOUNDARYPOINTS_ERR         = 1;
  const unsigned short      INVALID_NODE_TYPE_ERR          = 2;

  // Introduced in DOM Level 2:
  interface Range {
    readonly attribute Node             startContainer;
                                        // raises(dom::DOMException) on retrieval

    readonly attribute long             startOffset;
                                        // raises(dom::DOMException) on retrieval

    readonly attribute Node             endContainer;
                                        // raises(dom::DOMException) on retrieval

    readonly attribute long             endOffset;
                                        // raises(dom::DOMException) on retrieval

    readonly attribute boolean          collapsed;
                                        // raises(dom::DOMException) on retrieval

    readonly attribute Node             commonAncestorContainer;
                                        // raises(dom::DOMException) on retrieval

    void               setStart(in Node refNode,
                                in long offset)
                                        raises(RangeException,
                                               dom::DOMException);
    void               setEnd(in Node refNode,
                              in long offset)
                                        raises(RangeException,
                                               dom::DOMException);
    void               setStartBefore(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);
    void               setStartAfter(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);
    void               setEndBefore(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);
    void               setEndAfter(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);
    void               collapse(in boolean toStart)
                                        raises(dom::DOMException);
    void               selectNode(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);
    void               selectNodeContents(in Node refNode)
                                        raises(RangeException,
                                               dom::DOMException);

    // CompareHow
    const unsigned short      START_TO_START                 = 0;
    const unsigned short      START_TO_END                   = 1;
    const unsigned short      END_TO_END                     = 2;
    const unsigned short      END_TO_START                   = 3;

    short              compareBoundaryPoints(in unsigned short how,
                                             in Range sourceRange)
                                        raises(dom::DOMException);
    void               deleteContents()
                                        raises(dom::DOMException);
    DocumentFragment   extractContents()
                                        raises(dom::DOMException);
    DocumentFragment   cloneContents()
                                        raises(dom::DOMException);
    void               insertNode(in Node newNode)
                                        raises(dom::DOMException,
                                               RangeException);
    void               surroundContents(in Node newParent)
                                        raises(dom::DOMException,
                                               RangeException);
    Range              cloneRange()
                                        raises(dom::DOMException);
    DOMString          toString()
                                        raises(dom::DOMException);
    void               detach()
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 2:
  interface DocumentRange {
    Range              createRange();
  };
};

#endif // _RANGES_IDL_
previous next contents index


Java Language Binding

previous next contents index

13 November, 2000

Appendix B: Java Language Binding

This appendix contains the complete Java Language [Java] binding for the Level 2 Document Object Model Traversal and Range. The definitions are divided into Traversal, and Range.

The Java files are also available as http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113/java-binding.zip

B.1: Document Object Model Traversal

org/w3c/dom/traversal/NodeIterator.java:

package org.w3c.dom.traversal;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface NodeIterator {
    public Node getRoot();

    public int getWhatToShow();

    public NodeFilter getFilter();

    public boolean getExpandEntityReferences();

    public Node nextNode()
                         throws DOMException;

    public Node previousNode()
                             throws DOMException;

    public void detach();

}

org/w3c/dom/traversal/NodeFilter.java:

package org.w3c.dom.traversal;

import org.w3c.dom.Node;

public interface NodeFilter {
    // Constants returned by acceptNode
    public static final short FILTER_ACCEPT             = 1;
    public static final short FILTER_REJECT             = 2;
    public static final short FILTER_SKIP               = 3;

    // Constants for whatToShow
    public static final int SHOW_ALL                  = 0xFFFFFFFF;
    public static final int SHOW_ELEMENT              = 0x00000001;
    public static final int SHOW_ATTRIBUTE            = 0x00000002;
    public static final int SHOW_TEXT                 = 0x00000004;
    public static final int SHOW_CDATA_SECTION        = 0x00000008;
    public static final int SHOW_ENTITY_REFERENCE     = 0x00000010;
    public static final int SHOW_ENTITY               = 0x00000020;
    public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
    public static final int SHOW_COMMENT              = 0x00000080;
    public static final int SHOW_DOCUMENT             = 0x00000100;
    public static final int SHOW_DOCUMENT_TYPE        = 0x00000200;
    public static final int SHOW_DOCUMENT_FRAGMENT    = 0x00000400;
    public static final int SHOW_NOTATION             = 0x00000800;

    public short acceptNode(Node n);

}

org/w3c/dom/traversal/TreeWalker.java:

package org.w3c.dom.traversal;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface TreeWalker {
    public Node getRoot();

    public int getWhatToShow();

    public NodeFilter getFilter();

    public boolean getExpandEntityReferences();

    public Node getCurrentNode();
    public void setCurrentNode(Node currentNode)
                            throws DOMException;

    public Node parentNode();

    public Node firstChild();

    public Node lastChild();

    public Node previousSibling();

    public Node nextSibling();

    public Node previousNode();

    public Node nextNode();

}

org/w3c/dom/traversal/DocumentTraversal.java:

package org.w3c.dom.traversal;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface DocumentTraversal {
    public NodeIterator createNodeIterator(Node root,
                                           int whatToShow,
                                           NodeFilter filter,
                                           boolean entityReferenceExpansion)
                                           throws DOMException;

    public TreeWalker createTreeWalker(Node root,
                                       int whatToShow,
                                       NodeFilter filter,
                                       boolean entityReferenceExpansion)
                                       throws DOMException;

}

B.2: Document Object Model Range

org/w3c/dom/ranges/RangeException.java:

package org.w3c.dom.ranges;

public class RangeException extends RuntimeException {
    public RangeException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // RangeExceptionCode
    public static final short BAD_BOUNDARYPOINTS_ERR    = 1;
    public static final short INVALID_NODE_TYPE_ERR     = 2;

}

org/w3c/dom/ranges/Range.java:

package org.w3c.dom.ranges;

import org.w3c.dom.Node;
import org.w3c.dom.DocumentFragment;
import org.w3c.dom.DOMException;

public interface Range {
    public Node getStartContainer()
                                       throws DOMException;

    public int getStartOffset()
                                       throws DOMException;

    public Node getEndContainer()
                                       throws DOMException;

    public int getEndOffset()
                                       throws DOMException;

    public boolean getCollapsed()
                                       throws DOMException;

    public Node getCommonAncestorContainer()
                                       throws DOMException;

    public void setStart(Node refNode,
                         int offset)
                         throws RangeException, DOMException;

    public void setEnd(Node refNode,
                       int offset)
                       throws RangeException, DOMException;

    public void setStartBefore(Node refNode)
                               throws RangeException, DOMException;

    public void setStartAfter(Node refNode)
                              throws RangeException, DOMException;

    public void setEndBefore(Node refNode)
                             throws RangeException, DOMException;

    public void setEndAfter(Node refNode)
                            throws RangeException, DOMException;

    public void collapse(boolean toStart)
                         throws DOMException;

    public void selectNode(Node refNode)
                           throws RangeException, DOMException;

    public void selectNodeContents(Node refNode)
                                   throws RangeException, DOMException;

    // CompareHow
    public static final short START_TO_START            = 0;
    public static final short START_TO_END              = 1;
    public static final short END_TO_END                = 2;
    public static final short END_TO_START              = 3;

    public short compareBoundaryPoints(short how,
                                       Range sourceRange)
                                       throws DOMException;

    public void deleteContents()
                               throws DOMException;

    public DocumentFragment extractContents()
                                            throws DOMException;

    public DocumentFragment cloneContents()
                                          throws DOMException;

    public void insertNode(Node newNode)
                           throws DOMException, RangeException;

    public void surroundContents(Node newParent)
                                 throws DOMException, RangeException;

    public Range cloneRange()
                            throws DOMException;

    public String toString()
                           throws DOMException;

    public void detach()
                       throws DOMException;

}

org/w3c/dom/ranges/DocumentRange.java:

package org.w3c.dom.ranges;

public interface DocumentRange {
    public Range createRange();

}
previous next contents index


ECMAScript Language Binding

previous next contents index

13 November, 2000

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model Traversal and Range definitions. The definitions are divided into Traversal, and Range.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

C.1: Document Object Model Traversal

Object NodeIterator
The NodeIterator object has the following properties:
root
This read-only property is a Node object.
whatToShow
This read-only property is of type Number.
filter
This read-only property is a NodeFilter object.
expandEntityReferences
This read-only property is of type Boolean.
The NodeIterator object has the following methods:
nextNode()
This method returns a Node object.
This method can raise a DOMException object.
previousNode()
This method returns a Node object.
This method can raise a DOMException object.
detach()
This method has no return value.
Prototype Object NodeFilter
The NodeFilter class has the following constants:
NodeFilter.FILTER_ACCEPT
This constant is of type short and its value is 1.
NodeFilter.FILTER_REJECT
This constant is of type short and its value is 2.
NodeFilter.FILTER_SKIP
This constant is of type short and its value is 3.
NodeFilter.SHOW_ALL
This constant is of type Number and its value is 0xFFFFFFFF.
NodeFilter.SHOW_ELEMENT
This constant is of type Number and its value is 0x00000001.
NodeFilter.SHOW_ATTRIBUTE
This constant is of type Number and its value is 0x00000002.
NodeFilter.SHOW_TEXT
This constant is of type Number and its value is 0x00000004.
NodeFilter.SHOW_CDATA_SECTION
This constant is of type Number and its value is 0x00000008.
NodeFilter.SHOW_ENTITY_REFERENCE
This constant is of type Number and its value is 0x00000010.
NodeFilter.SHOW_ENTITY
This constant is of type Number and its value is 0x00000020.
NodeFilter.SHOW_PROCESSING_INSTRUCTION
This constant is of type Number and its value is 0x00000040.
NodeFilter.SHOW_COMMENT
This constant is of type Number and its value is 0x00000080.
NodeFilter.SHOW_DOCUMENT
This constant is of type Number and its value is 0x00000100.
NodeFilter.SHOW_DOCUMENT_TYPE
This constant is of type Number and its value is 0x00000200.
NodeFilter.SHOW_DOCUMENT_FRAGMENT
This constant is of type Number and its value is 0x00000400.
NodeFilter.SHOW_NOTATION
This constant is of type Number and its value is 0x00000800.
Object NodeFilter
This is an ECMAScript function reference. This method returns a Number. The parameter is a Node object.
Object TreeWalker
The TreeWalker object has the following properties:
root
This read-only property is a Node object.
whatToShow
This read-only property is of type Number.
filter
This read-only property is a NodeFilter object.
expandEntityReferences
This read-only property is of type Boolean.
currentNode
This property is a Node object and can raise a DOMException object on setting.
The TreeWalker object has the following methods:
parentNode()
This method returns a Node object.
firstChild()
This method returns a Node object.
lastChild()
This method returns a Node object.
previousSibling()
This method returns a Node object.
nextSibling()
This method returns a Node object.
previousNode()
This method returns a Node object.
nextNode()
This method returns a Node object.
Object DocumentTraversal
The DocumentTraversal object has the following methods:
createNodeIterator(root, whatToShow, filter, entityReferenceExpansion)
This method returns a NodeIterator object.
The root parameter is a Node object.
The whatToShow parameter is of type Number.
The filter parameter is a NodeFilter object.
The entityReferenceExpansion parameter is of type Boolean.
This method can raise a DOMException object.
createTreeWalker(root, whatToShow, filter, entityReferenceExpansion)
This method returns a TreeWalker object.
The root parameter is a Node object.
The whatToShow parameter is of type Number.
The filter parameter is a NodeFilter object.
The entityReferenceExpansion parameter is of type Boolean.
This method can raise a DOMException object.

C.2: Document Object Model Range

Prototype Object Range
The Range class has the following constants:
Range.START_TO_START
This constant is of type Number and its value is 0.
Range.START_TO_END
This constant is of type Number and its value is 1.
Range.END_TO_END
This constant is of type Number and its value is 2.
Range.END_TO_START
This constant is of type Number and its value is 3.
Object Range
The Range object has the following properties:
startContainer
This read-only property is a Node object and can raise a DOMException object on retrieval.
startOffset
This read-only property is a long object and can raise a DOMException object on retrieval.
endContainer
This read-only property is a Node object and can raise a DOMException object on retrieval.
endOffset
This read-only property is a long object and can raise a DOMException object on retrieval.
collapsed
This read-only property is of type Boolean and can raise a DOMException object on retrieval.
commonAncestorContainer
This read-only property is a Node object and can raise a DOMException object on retrieval.
The Range object has the following methods:
setStart(refNode, offset)
This method has no return value.
The refNode parameter is a Node object.
The offset parameter is a long object.
This method can raise a RangeException object or a DOMException object.
setEnd(refNode, offset)
This method has no return value.
The refNode parameter is a Node object.
The offset parameter is a long object.
This method can raise a RangeException object or a DOMException object.
setStartBefore(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
setStartAfter(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
setEndBefore(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
setEndAfter(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
collapse(toStart)
This method has no return value.
The toStart parameter is of type Boolean.
This method can raise a DOMException object.
selectNode(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
selectNodeContents(refNode)
This method has no return value.
The refNode parameter is a Node object.
This method can raise a RangeException object or a DOMException object.
compareBoundaryPoints(how, sourceRange)
This method returns a short object.
The how parameter is of type Number.
The sourceRange parameter is a Range object.
This method can raise a DOMException object.
deleteContents()
This method has no return value.
This method can raise a DOMException object.
extractContents()
This method returns a DocumentFragment object.
This method can raise a DOMException object.
cloneContents()
This method returns a DocumentFragment object.
This method can raise a DOMException object.
insertNode(newNode)
This method has no return value.
The newNode parameter is a Node object.
This method can raise a DOMException object or a RangeException object.
surroundContents(newParent)
This method has no return value.
The newParent parameter is a Node object.
This method can raise a DOMException object or a RangeException object.
cloneRange()
This method returns a Range object.
This method can raise a DOMException object.
toString()
This method returns a String.
This method can raise a DOMException object.
detach()
This method has no return value.
This method can raise a DOMException object.
Object DocumentRange
The DocumentRange object has the following methods:
createRange()
This method returns a Range object.
Prototype Object RangeException
The RangeException class has the following constants:
RangeException.BAD_BOUNDARYPOINTS_ERR
This constant is of type Number and its value is 1.
RangeException.INVALID_NODE_TYPE_ERR
This constant is of type Number and its value is 2.
Object RangeException
The RangeException object has the following properties:
code
This property is of type Number.
previous next contents index


Glossary

Editors
Arnaud Le Hors, IBM
Lauren Wood, SoftQuad Software Inc.
Robert S. Sutor, IBM (for DOM Level 1)

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

16-bit unit
The base unit of a DOMString. This indicates that indexing on a DOMString occurs in units of 16 bits. This must not be misunderstood to mean that a DOMString can store arbitrary 16-bit units. A DOMString is a character string encoded in UTF-16; this means that the restrictions of UTF-16 as well as the other relevant restrictions on character strings must be maintained. A single character, for example in the form of a numeric character reference, may correspond to one or two 16-bit units.
For more information, see [Unicode] and [ISO/IEC 10646].
ancestor
An ancestor node of any node A is any node above A in a tree model of a document, where "above" means "toward the root."
child
A child is an immediate descendant node of a node.
deepest
The deepest element is that element which is furthest from the root or document element in a tree model of the document.
document order
The term document order has the same meaning as depth first, pre-order traversal, which is equivalent to the order in which the start tags occur in the text representation of the document.
descendant
A descendant node of any node A is any node below A in a tree model of a document, where "above" means "toward the root."
parent
A parent is an immediate ancestor node of a node.
sibling
Two nodes are siblings if and only if they have the same parent node.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

F.1: Normative references

DOM Level 2 Core
W3C (World Wide Web Consortium) Document Object Model Level 2 Core Specification, November 2000. Available at http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113
ECMAScript
ECMA (European Computer Manufacturers Association) ECMAScript Language Specification. Available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
ISO/IEC 10646
ISO (International Organization for Standardization). ISO/IEC 10646-1:2000 (E). Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization.
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org/
Unicode
The Unicode Consortium. The Unicode Standard, Version 3.0., February 2000. Available at http://www.unicode.org/unicode/standard/versions/Unicode3.0.html.
previous next contents index


Index

16-bit unit 1, 2, 3, 4, 5
acceptNode | ancestor 1, 2, 3, 4 | ancestor container 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
BAD_BOUNDARYPOINTS_ERR | before/after/equal to | boundary-point 1, 2, 3, 4, 5, 6, 7, 8, 9
child 1, 2, 3, 4 | cloneContents | cloneRange
collapse | collapsed 1, 2, 3, 4, 5 | commonAncestorContainer
compareBoundaryPoints | container 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 | context tree 1, 2, 3, 4, 5, 6, 7
createNodeIterator | createRange | createTreeWalker
currentNode
deepest 1, 2 | deleteContents | descendant 1, 2, 3, 4, 5
detach 1, 2 | document order 1, 2 | DocumentRange
DocumentTraversal | DOM Level 2 Core 1, 2, 3, 4
ECMAScript | END_TO_END | END_TO_START
endContainer | endOffset | expandEntityReferences 1, 2
extractContents
filter 1, 2 | FILTER_ACCEPT | FILTER_REJECT
FILTER_SKIP | firstChild
insertNode | INVALID_NODE_TYPE_ERR | ISO/IEC 10646 1, 2
Java
lastChild
nextNode 1, 2 | nextSibling | NodeFilter
NodeIterator
offset 1, 2, 3, 4, 5, 6 | OMGIDL
parent 1, 2, 3, 4, 5, 6 | parentNode | partially selected 1, 2, 3, 4, 5, 6
previousNode 1, 2 | previousSibling
Range | RangeException | root 1, 2
root container 1, 2, 3, 4, 5
selected 1, 2, 3 | selectNode | selectNodeContents
setEnd | setEndAfter | setEndBefore
setStart | setStartAfter | setStartBefore
SHOW_ALL | SHOW_ATTRIBUTE | SHOW_CDATA_SECTION
SHOW_COMMENT | SHOW_DOCUMENT | SHOW_DOCUMENT_FRAGMENT
SHOW_DOCUMENT_TYPE | SHOW_ELEMENT | SHOW_ENTITY
SHOW_ENTITY_REFERENCE | SHOW_NOTATION | SHOW_PROCESSING_INSTRUCTION
SHOW_TEXT | sibling 1, 2, 3, 4, 5, 6 | START_TO_END
START_TO_START | startContainer | startOffset
surroundContents
tokenized | toString | TreeWalker
Unicode 1, 2
whatToShow 1, 2
previous contents


Document Object Model (DOM) Level 2 HTML Specification

Version 1.0

W3C Recommendation 09 January 2003

This version:
http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109
Latest version:
http://www.w3.org/TR/DOM-Level-2-HTML
Previous version:
http://www.w3.org/TR/2002/PR-DOM-Level-2-HTML-20021108
Editors:
Johnny Stenback, Netscape
Philippe Le Hégaret, W3C
Arnaud Le Hors, W3C and IBM (until November 2000)

Please refer to the errata for this document, which may include some normative corrections.

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

See also translations of this document.

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

Abstract

This specification defines the Document Object Model Level 2 HTML, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content and structure of [HTML 4.01] and [XHTML 1.0] documents. The Document Object Model Level 2 HTML builds on the Document Object Model Level 2 Core [DOM Level 2 Core] and is not backward compatible with DOM Level 1 HTML [DOM Level 1].

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This is the 09 January 2003 of "DOM Level 2 HTML". This document has been reviewed by W3C Members, software developers, and other W3C groups and interested parties, and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This document enhances the interoperability of the Web.

Patent disclosures relevant to this specification may be found on the Working Group's public patent disclosure page.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group participants.

The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2000/11/DOM-Level-2-translations.

The list of known errors in this document is available at http://www.w3.org/2000/11/DOM-Level-2-errata

Comments on this document are invited and are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

An implementation report, based on the DOM Test Suite work, is available at http://www.w3.org/2002/11/DOM-Level-2-HTML-Results.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Note:This specification renders the DOM Level 1 HTML Recommendation obsolete given that some changes from DOM Level 1 HTML are incompatible with that specification but represent more accurately the state of deployed software. W3C strongly suggests that developers and authors conform to DOM Level 2 HTML instead.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • 1. Document Object Model HTML
  • Appendix A: Changes
  • Appendix B: IDL Definitions
  • Appendix C: Java language Binding
  • Appendix D: ECMAScript Language Binding
  • Appendix E: Acknowledgements
  • Glossary
  • References
  • Index
next contents index


Copyright Notice

Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

This document is published under the W3C Document Copyright Notice and License. The bindings within this document are published under the W3C Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java Language binding, the package names can no longer be in the 'org.w3c' package.

W3C Document Copyright Notice and License

Note: This section is a copy of the W3C Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-documents-19990405.

Copyright © 1994-2003 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice of the form: "Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/" (Hypertext is preferred, but a textual representation is permitted.)
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

W3C Software Copyright Notice and License

Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720

Copyright © 1994-2003 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers. If none exist, then a notice of the following form: "Copyright © [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/."
  3. Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

previous next contents index


Document Object Model HTML

previous next contents index

09 January 2003

1. Document Object Model HTML

Editors:
Johnny Stenback, Netscape
Philippe Le Hégaret, W3C
Arnaud Le Hors, W3C and IBM (until November 2000)

Table of contents

  • 1.1. Introduction
  • 1.2. HTML Application of Core DOM
    • 1.2.1. Naming Conventions
  • 1.3. XHTML and the HTML DOM
  • 1.4. Miscellaneous Object Definitions
    • HTMLCollection, HTMLOptionsCollection
  • 1.5. Objects related to HTML documents
    • HTMLDocument
  • 1.6. HTML Elements
    • 1.6.1. Property Attributes
    • 1.6.2. Naming Exceptions
    • 1.6.3. Exposing Element Type Names (tagName, (nodeName))
    • 1.6.4. The HTMLElement interface
      • HTMLElement
    • 1.6.5. Object definitions
      • HTMLHtmlElement, HTMLHeadElement, HTMLLinkElement, HTMLTitleElement, HTMLMetaElement, HTMLBaseElement, HTMLIsIndexElement, HTMLStyleElement, HTMLBodyElement, HTMLFormElement, HTMLSelectElement, HTMLOptGroupElement, HTMLOptionElement, HTMLInputElement, HTMLTextAreaElement, HTMLButtonElement, HTMLLabelElement, HTMLFieldSetElement, HTMLLegendElement, HTMLUListElement, HTMLOListElement, HTMLDListElement, HTMLDirectoryElement, HTMLMenuElement, HTMLLIElement, HTMLDivElement, HTMLParagraphElement, HTMLHeadingElement, HTMLQuoteElement, HTMLPreElement, HTMLBRElement, HTMLBaseFontElement, HTMLFontElement, HTMLHRElement, HTMLModElement, HTMLAnchorElement, HTMLImageElement, HTMLObjectElement, HTMLParamElement, HTMLAppletElement, HTMLMapElement, HTMLAreaElement, HTMLScriptElement, HTMLTableElement, HTMLTableCaptionElement, HTMLTableColElement, HTMLTableSectionElement, HTMLTableRowElement, HTMLTableCellElement, HTMLFrameSetElement, HTMLFrameElement, HTMLIFrameElement

1.1. Introduction

This section extends the DOM Level 2 Core API [DOM Level 2 Core] to describe objects and methods specific to HTML documents [HTML 4.01], and XHTML documents [XHTML 1.0]. In general, the functionality needed to manipulate hierarchical document structures, elements, and attributes will be found in the core section; functionality that depends on the specific elements defined in HTML will be found in this section.

The goals of the HTML-specific DOM API are:

  • to specialize and add functionality that relates specifically to HTML documents and elements.
  • to address issues of backwards compatibility with the DOM Level 0.
  • to provide convenience mechanisms, where appropriate, for common and frequent operations on HTML documents.

The key differences between the core DOM and the HTML application of DOM is that the HTML Document Object Model exposes a number of convenience methods and properties that are consistent with the existing models and are more appropriate to script writers. In many cases, these enhancements are not applicable to a general DOM because they rely on the presence of a predefined DTD. The transitional or frameset DTD for HTML 4.01, or the XHTML 1.0 DTDs are assumed. Interoperability between implementations is only guaranteed for elements and attributes that are specified in the HTML 4.01 and XHTML 1.0 DTDs.

More specifically, this document includes the following specializations for HTML:

  • An HTMLDocument interface, derived from the core Document interface. HTMLDocument specifies the operations and queries that can be made on a HTML document.
  • An HTMLElement interface, derived from the core Element interface. HTMLElement specifies the operations and queries that can be made on any HTML element. Methods on HTMLElement include those that allow for the retrieval and modification of attributes that apply to all HTML elements.
  • Specializations for all HTML elements that have attributes that extend beyond those specified in the HTMLElement interface. For all such attributes, the derived interface for the element contains explicit methods for setting and getting the values.

The DOM Level 2 includes mechanisms to access and modify style specified through CSS and defines an event model that can be used with HTML documents.

The interfaces found within this section are not mandatory. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTML" and "2.0" (respectively) to determine whether or not this module is supported by the implementation. In addition to the feature string "HTML", the feature string "XHTML" (version string "2.0") can be used to check if the implementation supports XHTML (this is equivalent to checking the features "XML" and "HTML"). In order to fully support this module, an implementation must also support the "Core" feature defined [DOM Level 2 Core]. Please refer to additional information about conformance in the DOM Level 2 Core specification [DOM Level 2 Core].

A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether they are supported or not. The feature string for all the interfaces listed in this section is "HTML" and the version is "2.0". In order to fully support this feature, an implementation needs also to support the "Core" feature defined in the Document Object Model Level 2 Core [DOM Level 2 Core] (see also Conformance).

The interfaces in this specification are designed for [HTML 4.01] documents, as well as for [XHTML 1.0] documents.

Note: This specification does not intend to define exactly how a user agent will respond to a change to any attribute on an element that directly or indirectly references external data, such elements are HTMLAppletElement, HTMLFrameElement, HTMLFrameSetElement, HTMLIFrameElement, HTMLImageElement, HTMLLinkElement, HTMLObjectElement, HTMLParamElement, and HTMLScriptElement.

1.2. HTML Application of Core DOM

1.2.1. Naming Conventions

The HTML DOM follows a naming convention for properties, methods, events, collections, and data types. All names are defined as one or more English words concatenated together to form a single string.

1.2.1.1. Properties and Methods

The property or method name starts with the initial keyword in lowercase, and each subsequent word starts with a capital letter. For example, a property that returns document meta information such as the date the file was created might be named "fileDateCreated". In the ECMAScript binding, properties are exposed as properties of a given object. In Java, properties are exposed with get and set methods.

1.2.1.2. Non-HTML 4.0 interfaces and attributes

While most of the interfaces defined below can be mapped directly to elements defined in the HTML 4.01 Recommendation, some of them cannot. Similarly, not all attributes listed below have counterparts in the HTML 4.01 specification (and some do, but have been renamed to avoid conflicts with scripting languages). Interfaces and attribute definitions that have links to the HTML 4.0 specification have corresponding element and attribute definitions there; all others are added by this specification, either for convenience or backwards compatibility with DOM Level 0 implementations.

1.3. XHTML and the HTML DOM

The DOM HTML Level 1 API [DOM Level 1] were originally intended to be used only for HTML 4.01 documents [HTML 4.01]. The APIs were defined well before XHTML 1.0 [XHTML 1.0] became a specification, or before it was worked on by the HTML Working Group.

From the DOM point of view, The biggest difference between HTML 4.01 (and earlier) and XHTML 1.0 is that XHTML is case sensitive, whereas HTML 4.01 is case insensitive. The HTML case insensitivity is also reflected in the DOM HTML API. For instance, element and attribute names are exposed as all uppercase (for consistency) when used on an HTML document, regardless of the character case used in the markup. Since XHTML is based on XML, in XHTML everything is case sensitive, and element and attribute names must be lowercase in the markup.

Developers need to take two things into account when writing code that works on both HTML and XHTML documents. When comparing element or attribute names to strings, the string compare needs to be case insensitive, or the element or attribute name needs to be converted into lowercase before comparing against a lowercase string. Second, when calling methods that are case insensitive when used on a HTML document (such as getElementsByTagName() and namedItem()), the string that is passed in should be lowercase.

Note: The interfaces provided in this document are only for [HTML 4.01] and [XHTML 1.0] documents and are not guaranteed to work with any future version of XHTML.

1.4. Miscellaneous Object Definitions

Interface HTMLCollection

An HTMLCollection is a list of nodes. An individual node may be accessed by either ordinal index or the node's name or id attributes.

Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

IDL Definition
interface HTMLCollection {
  readonly attribute unsigned long   length;
  Node               item(in unsigned long index);
  Node               namedItem(in DOMString name);
};

Attributes
length of type unsigned long, readonly
This attribute specifies the length or size of the list.
Methods
item
This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).
Parameters
index of type unsigned long
The index of the node to be fetched. The index origin is 0.
Return Value

Node

The Node at the corresponding position upon success. A value of null is returned if the index is out of range.
No Exceptions
namedItem
This method retrieves a Node using a name. With [HTML 4.01] documents, it first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute. With [XHTML 1.0] documents, this method only searches for Nodes with a matching id attribute. This method is case insensitive in HTML documents and case sensitive in XHTML documents.
Parameters
name of type DOMString
The name of the Node to be fetched.
Return Value

Node

The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.
No Exceptions
Interface HTMLOptionsCollection (introduced in DOM Level 2)

An HTMLOptionsCollection is a list of nodes representing HTML option element. An individual node may be accessed by either ordinal index or the node's name or id attributes.

Note: Collections in the HTML DOM are assumed to be live meaning that they are automatically updated when the underlying document is changed.

IDL Definition
// Introduced in DOM Level 2:
interface HTMLOptionsCollection {
           attribute unsigned long   length;
                                        // raises(DOMException) on setting

  Node               item(in unsigned long index);
  Node               namedItem(in DOMString name);
};

Attributes
length of type unsigned long
This attribute specifies the length or size of the list.
Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: if setting the length is not allowed by the implementation.
Methods
item
This method retrieves a node specified by ordinal index. Nodes are numbered in tree order (depth-first traversal order).
Parameters
index of type unsigned long
The index of the node to be fetched. The index origin is 0.
Return Value

Node

The Node at the corresponding position upon success. A value of null is returned if the index is out of range.
No Exceptions
namedItem
This method retrieves a Node using a name. It first searches for a Node with a matching id attribute. If it doesn't find one, it then searches for a Node with a matching name attribute, but only on those elements that are allowed a name attribute. This method is case insensitive in HTML documents and case sensitive in XHTML documents.
Parameters
name of type DOMString
The name of the Node to be fetched.
Return Value

Node

The Node with a name or id attribute whose value corresponds to the specified string. Upon failure (e.g., no node with this name exists), returns null.
No Exceptions

1.5. Objects related to HTML documents

Interface HTMLDocument

An HTMLDocument is the root of the HTML hierarchy and holds the entire content. Besides providing access to the hierarchy, it also provides some convenience methods for accessing certain sets of information from the document.

The following properties have been deprecated in favor of the corresponding ones for the BODY element:

  • alinkColor
  • background
  • bgColor
  • fgColor
  • linkColor
  • vlinkColor

Note: In DOM Level 2, the method getElementById is inherited from the Document interface where it was moved to.

IDL Definition
interface HTMLDocument : Document {
           attribute DOMString       title;
  readonly attribute DOMString       referrer;
  readonly attribute DOMString       domain;
  readonly attribute DOMString       URL;
           attribute HTMLElement     body;
  readonly attribute HTMLCollection  images;
  readonly attribute HTMLCollection  applets;
  readonly attribute HTMLCollection  links;
  readonly attribute HTMLCollection  forms;
  readonly attribute HTMLCollection  anchors;
           attribute DOMString       cookie;
                                        // raises(DOMException) on setting

  void               open();
  void               close();
  void               write(in DOMString text);
  void               writeln(in DOMString text);
  NodeList           getElementsByName(in DOMString elementName);
};

Attributes
URL of type DOMString, readonly
The absolute URI [IETF RFC 2396] of the document.
anchors of type HTMLCollection, readonly
A collection of all the anchor (A) elements in a document with a value for the name attribute.

Note: For reasons of backward compatibility, the returned set of anchors only contains those anchors created with the name attribute, not those created with the id attribute. Note that in [XHTML 1.0], the name attribute (see section 4.10) has no semantics and is only present for legacy user agents: the id attribute is used instead. Users should prefer the iterator mechanisms provided by [DOM Level 2 Traversal] instead.

applets of type HTMLCollection, readonly
A collection of all the OBJECT elements that include applets and APPLET (deprecated) elements in a document.
body of type HTMLElement
The element that contains the content for the document. In documents with BODY contents, returns the BODY element. In frameset documents, this returns the outermost FRAMESET element.
cookie of type DOMString
This mutable string attribute denotes persistent state information that (1) is associated with the current frame or document and (2) is composed of information described by the cookies non-terminal of [IETF RFC 2965], Section 4.2.2.
If no persistent state information is available for the current frame or document document, then this property's value is an empty string.
When this attribute is read, all cookies are returned as a single string, with each cookie's name-value pair concatenated into a list of name-value pairs, each list item being separated by a ';' (semicolon).
When this attribute is set, the value it is set to should be a string that adheres to the cookie non-terminal of [IETF RFC 2965]; that is, it should be a single name-value pair followed by zero or more cookie attribute values. If no domain attribute is specified, then the domain attribute for the new value defaults to the host portion of an absolute URI [IETF RFC 2396] of the current frame or document. If no path attribute is specified, then the path attribute for the new value defaults to the absolute path portion of the URI [IETF RFC 2396] of the current frame or document. If no max-age attribute is specified, then the max-age attribute for the new value defaults to a user agent defined value. If a cookie with the specified name is already associated with the current frame or document, then the new value as well as the new attributes replace the old value and attributes. If a max-age attribute of 0 is specified for the new value, then any existing cookies of the specified name are removed from the cookie storage.

Note: See [IETF RFC 2965] for the semantics of persistent state item attribute value pairs.

Note: The precise nature of a user agent session is not defined by this specification.

Exceptions on setting

DOMException

SYNTAX_ERR: If the new value does not adhere to the cookie syntax specified by [IETF RFC 2965].
domain of type DOMString, readonly
The domain name of the server that served the document, or null if the server cannot be identified by a domain name.
forms of type HTMLCollection, readonly
A collection of all the forms of a document.
images of type HTMLCollection, readonly
A collection of all the IMG elements in a document. The behavior is limited to IMG elements for backwards compatibility.

Note: As suggested by [HTML 4.01], to include images, authors may use the OBJECT element or the IMG element. Therefore, it is recommended not to use this attribute to find the images in the document but getElementsByTagName with HTML 4.01 or getElementsByTagNameNS with XHTML 1.0.

links of type HTMLCollection, readonly
A collection of all AREA elements and anchor (A) elements in a document with a value for the href attribute.
referrer of type DOMString, readonly
Returns the URI [IETF RFC 2396] of the page that linked to this page. The value is an empty string if the user navigated to the page directly (not through a link, but, for example, via a bookmark).
title of type DOMString
The title of a document as specified by the TITLE element in the head of the document.
Methods
close
Closes a document stream opened by open() and forces rendering.
No Parameters
No Return Value
No Exceptions
getElementsByName
With [HTML 4.01] documents, this method returns the (possibly empty) collection of elements whose name value is given by elementName. In [XHTML 1.0] documents, this methods only return the (possibly empty) collection of form controls with matching name. This method is case sensitive.
Parameters
elementName of type DOMString
The name attribute value for an element.
Return Value

NodeList

The matching elements.
No Exceptions
open
Open a document stream for writing. If a document exists in the target, this method clears it.

Note: This method and the ones following allow a user to add to or replace the structure model of a document using strings of unparsed HTML. At the time of writing alternate methods for providing similar functionality for both HTML and XML documents were being considered (see [DOM Level 3 Load and Save]).

No Parameters
No Return Value
No Exceptions
write
Write a string of text to a document stream opened by open(). Note that the function will produce a document which is not necessarily driven by a DTD and therefore might be produce an invalid result in the context of the document.
Parameters
text of type DOMString
The string to be parsed into some structure in the document structure model.
No Return Value
No Exceptions
writeln
Write a string of text followed by a newline character to a document stream opened by open(). Note that the function will produce a document which is not necessarily driven by a DTD and therefore might be produce an invalid result in the context of the document
Parameters
text of type DOMString
The string to be parsed into some structure in the document structure model.
No Return Value
No Exceptions

1.6. HTML Elements

1.6.1. Property Attributes

HTML attributes are exposed as properties on the element object. The DOM naming conventions always determine the name of the exposed property, and are independent of the case of the attribute in the source document. The data type of the property is in general determined by the type of the attribute as determined by the HTML 4.01 (transitional and frameset) and XHTML 1.0 DTDs. The attributes have the semantics (including case-sensitivity) given in the [HTML 4.01] and [XHTML 1.0] specifications.

The attributes are exposed as properties for compatibility with DOM Level 0. This usage is deprecated because it can not be generalized to all possible attribute names for XML. We recommend the use of generic methods on the core Element interface for setting, getting and removing attributes.

DTD Data Type | Object Model Data Type
CDATA | DOMString
Value list (e.g., (left | right | center)) | DOMString
one-value Value list (e.g., (disabled)) | boolean
Number | long int

In an HTML document the return value of an attribute that has a data type that is a value list is normalized to lowercase (independent of the case of the value in the source document).

For example, if the value of the align attribute on a P element is "Left" (which is not a valid value in XHTML due to the case sensitivity of XHTML) then the value is returned as "left". For attributes with the CDATA data type, the case of the return value is that given in the source document.

The return value of an attribute that is unspecified and does not have a default value is the empty string if the return type is a DOMString, false if the return type is a boolean and 0 if the return type is a number.

1.6.2. Naming Exceptions

To avoid namespace conflicts, two attributes with the same name as a keyword in one of our chosen binding languages were prefixed. The for attribute of the LABEL and SCRIPT elements collides with loop construct naming conventions and is renamed htmlFor. The class attribute of the HTML elements collides with class definitions naming conventions and is renamed className.

1.6.3. Exposing Element Type Names (tagName, (nodeName))

If the document is an HTML 4.01 document the element type names exposed through a property are in uppercase. For example, the body element type name is exposed through the tagName property as BODY. If the document is an XHTML 1.0 document the element name is exposed as it is written in the XHTML file. This means that the element type names are exposed in lowercase for XHTML documents since the XHTML 1.0 DTDs defines element type names as lowercase, and XHTML, being derived from XML, is case sensitive.

1.6.4. The HTMLElement interface

Interface HTMLElement

All HTML element interfaces derive from this class. Elements that only expose the HTML core attributes are represented by the base HTMLElement interface. These elements are as follows:

  • special: SUB, SUP, SPAN, BDO
  • font: TT, I, B, U, S, STRIKE, BIG, SMALL
  • phrase: EM, STRONG, DFN, CODE, SAMP, KBD, VAR, CITE, ACRONYM, ABBR
  • list: DD, DT
  • NOFRAMES, NOSCRIPT
  • ADDRESS, CENTER

Note: The style attribute of an HTML element is accessible through the ElementCSSInlineStyle interface which is defined in the CSS module [DOM Level 2 Style Sheets and CSS].

IDL Definition
interface HTMLElement : Element {
           attribute DOMString       id;
           attribute DOMString       title;
           attribute DOMString       lang;
           attribute DOMString       dir;
           attribute DOMString       className;
};

Attributes
className of type DOMString
The class attribute of the element. This attribute has been renamed due to conflicts with the "class" keyword exposed by many languages. See the class attribute definition in HTML 4.01.
dir of type DOMString
Specifies the base direction of directionally neutral text and the directionality of tables. See the dir attribute definition in HTML 4.01.
id of type DOMString
The element's identifier. See the id attribute definition in HTML 4.01.
lang of type DOMString
Language code defined in RFC 1766. See the lang attribute definition in HTML 4.01.
title of type DOMString
The element's advisory title. See the title attribute definition in HTML 4.01.

1.6.5. Object definitions

Interface HTMLHtmlElement

Root of an HTML document. See the HTML element definition in HTML 4.01.

IDL Definition
interface HTMLHtmlElement : HTMLElement {
           attribute DOMString       version;
};

Attributes
version of type DOMString
Version information about the document's DTD. See the version attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLHeadElement

Document head information. See the HEAD element definition in HTML 4.01.

IDL Definition
interface HTMLHeadElement : HTMLElement {
           attribute DOMString       profile;
};

Attributes
profile of type DOMString
URI [IETF RFC 2396] designating a metadata profile. See the profile attribute definition in HTML 4.01.
Interface HTMLLinkElement

The LINK element specifies a link to an external resource, and defines this document's relationship to that resource (or vice versa). See the LINK element definition in HTML 4.01 (see also the LinkStyle interface in the StyleSheet module [DOM Level 2 Style Sheets and CSS]).

IDL Definition
interface HTMLLinkElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       charset;
           attribute DOMString       href;
           attribute DOMString       hreflang;
           attribute DOMString       media;
           attribute DOMString       rel;
           attribute DOMString       rev;
           attribute DOMString       target;
           attribute DOMString       type;
};

Attributes
charset of type DOMString
The character encoding of the resource being linked to. See the charset attribute definition in HTML 4.01.
disabled of type boolean
Enables/disables the link. This is currently only used for style sheet links, and may be used to activate or deactivate style sheets.
href of type DOMString
The URI [IETF RFC 2396] of the linked resource. See the href attribute definition in HTML 4.01.
hreflang of type DOMString
Language code of the linked resource. See the hreflang attribute definition in HTML 4.01.
media of type DOMString
Designed for use with one or more target media. See the media attribute definition in HTML 4.01.
rel of type DOMString
Forward link type. See the rel attribute definition in HTML 4.01.
rev of type DOMString
Reverse link type. See the rev attribute definition in HTML 4.01.
target of type DOMString
Frame to render the resource in. See the target attribute definition in HTML 4.01.
type of type DOMString
Advisory content type. See the type attribute definition in HTML 4.01.
Interface HTMLTitleElement

The document title. See the TITLE element definition in HTML 4.01.

IDL Definition
interface HTMLTitleElement : HTMLElement {
           attribute DOMString       text;
};

Attributes
text of type DOMString
The specified title as a string.
Interface HTMLMetaElement

This contains generic meta-information about the document. See the META element definition in HTML 4.01.

IDL Definition
interface HTMLMetaElement : HTMLElement {
           attribute DOMString       content;
           attribute DOMString       httpEquiv;
           attribute DOMString       name;
           attribute DOMString       scheme;
};

Attributes
content of type DOMString
Associated information. See the content attribute definition in HTML 4.01.
httpEquiv of type DOMString
HTTP response header name [IETF RFC 2616]. See the http-equiv attribute definition in HTML 4.01.
name of type DOMString
Meta information name. See the name attribute definition in HTML 4.01.
scheme of type DOMString
Select form of content. See the scheme attribute definition in HTML 4.01.
Interface HTMLBaseElement

Document base URI [IETF RFC 2396]. See the BASE element definition in HTML 4.01.

IDL Definition
interface HTMLBaseElement : HTMLElement {
           attribute DOMString       href;
           attribute DOMString       target;
};

Attributes
href of type DOMString
The base URI [IETF RFC 2396]. See the href attribute definition in HTML 4.01.
target of type DOMString
The default target frame. See the target attribute definition in HTML 4.01.
Interface HTMLIsIndexElement

This element is used for single-line text input. See the ISINDEX element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLIsIndexElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       prompt;
};

Attributes
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
prompt of type DOMString
The prompt message. See the prompt attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLStyleElement

Style information. See the STYLE element definition in HTML 4.01, the CSS module [DOM Level 2 Style Sheets and CSS] and the LinkStyle interface in the StyleSheets module [DOM Level 2 Style Sheets and CSS].

IDL Definition
interface HTMLStyleElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       media;
           attribute DOMString       type;
};

Attributes
disabled of type boolean
Enables/disables the style sheet.
media of type DOMString
Designed for use with one or more target media. See the media attribute definition in HTML 4.01.
type of type DOMString
The content type of the style sheet language. See the type attribute definition in HTML 4.01.
Interface HTMLBodyElement

The HTML document body. This element is always present in the DOM API, even if the tags are not present in the source document. See the BODY element definition in HTML 4.01.

IDL Definition
interface HTMLBodyElement : HTMLElement {
           attribute DOMString       aLink;
           attribute DOMString       background;
           attribute DOMString       bgColor;
           attribute DOMString       link;
           attribute DOMString       text;
           attribute DOMString       vLink;
};

Attributes
aLink of type DOMString
Color of active links (after mouse-button down, but before mouse-button up). See the alink attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
background of type DOMString
URI [IETF RFC 2396] of the background texture tile image. See the background attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
bgColor of type DOMString
Document background color. See the bgcolor attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
link of type DOMString
Color of links that are not active and unvisited. See the link attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
text of type DOMString
Document text color. See the text attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
vLink of type DOMString
Color of links that have been visited by the user. See the vlink attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLFormElement

The FORM element encompasses behavior similar to a collection and an element. It provides direct access to the contained form controls as well as the attributes of the form element. See the FORM element definition in HTML 4.01.

IDL Definition
interface HTMLFormElement : HTMLElement {
  readonly attribute HTMLCollection  elements;
  readonly attribute long            length;
           attribute DOMString       name;
           attribute DOMString       acceptCharset;
           attribute DOMString       action;
           attribute DOMString       enctype;
           attribute DOMString       method;
           attribute DOMString       target;
  void               submit();
  void               reset();
};

Attributes
acceptCharset of type DOMString
List of character sets supported by the server. See the accept-charset attribute definition in HTML 4.01.
action of type DOMString
Server-side form handler. See the action attribute definition in HTML 4.01.
elements of type HTMLCollection, readonly
Returns a collection of all form control elements in the form.
enctype of type DOMString
The content type of the submitted form, generally "application/x-www-form-urlencoded". See the enctype attribute definition in HTML 4.01.

Note: The onsubmit even handler is not guaranteed to be triggered when invoking this method. The behavior is inconsistent for historical reasons and authors should not rely on a particular one.

length of type long, readonly
The number of form controls in the form.
method of type DOMString
HTTP method [IETF RFC 2616] used to submit form. See the method attribute definition in HTML 4.01.
name of type DOMString
Names the form.
target of type DOMString
Frame to render the resource in. See the target attribute definition in HTML 4.01.
Methods
reset
Restores a form element's default values. It performs the same action as a reset button.
No Parameters
No Return Value
No Exceptions
submit
Submits the form. It performs the same action as a submit button.
No Parameters
No Return Value
No Exceptions
Interface HTMLSelectElement

The select element allows the selection of an option. The contained options can be directly accessed through the select element as a collection. See the SELECT element definition in HTML 4.01.

IDL Definition
interface HTMLSelectElement : HTMLElement {
  readonly attribute DOMString       type;
           attribute long            selectedIndex;
           attribute DOMString       value;
  // Modified in DOM Level 2:
           attribute unsigned long   length;
                                        // raises(DOMException) on setting

  readonly attribute HTMLFormElement form;
  // Modified in DOM Level 2:
  readonly attribute HTMLOptionsCollection options;
           attribute boolean         disabled;
           attribute boolean         multiple;
           attribute DOMString       name;
           attribute long            size;
           attribute long            tabIndex;
  void               add(in HTMLElement element,
                         in HTMLElement before)
                                        raises(DOMException);
  void               remove(in long index);
  void               blur();
  void               focus();
};

Attributes
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
length of type unsigned long, modified in DOM Level 2
The number of options in this SELECT.
Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: if setting the length is not allowed by the implementation.
multiple of type boolean
If true, multiple OPTION elements may be selected in this SELECT. See the multiple attribute definition in HTML 4.01.
name of type DOMString
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
options of type HTMLOptionsCollection, readonly, modified in DOM Level 2
The collection of OPTION elements contained by this element.
selectedIndex of type long
The ordinal index of the selected option, starting from 0. The value -1 is returned if no element is selected. If multiple options are selected, the index of the first selected option is returned.
size of type long
Number of visible rows. See the size attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, readonly
The type of this form control. This is the string "select-multiple" when the multiple attribute is true and the string "select-one" when false.
value of type DOMString
The current form control value (i.e. the value of the currently selected option), if multiple options are selected this is the value of the first selected option.
Methods
add
Add a new element to the collection of OPTION elements for this SELECT. This method is the equivalent of the appendChild method of the Node interface if the before parameter is null. It is equivalent to the insertBefore method on the parent of before in all other cases. This method may have no effect if the new element is not an OPTION or an OPTGROUP.
Parameters
element of type HTMLElement
The element to add.
before of type HTMLElement
The element to insert before, or null for the tail of the list.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if before is not a descendant of the SELECT element.
No Return Value
blur
Removes keyboard focus from this element.
No Parameters
No Return Value
No Exceptions
focus
Gives keyboard focus to this element.
No Parameters
No Return Value
No Exceptions
remove
Remove an element from the collection of OPTION elements for this SELECT. Does nothing if no element has the given index.
Parameters
index of type long
The index of the item to remove, starting from 0.
No Return Value
No Exceptions
Interface HTMLOptGroupElement

Group options together in logical subdivisions. See the OPTGROUP element definition in HTML 4.01.

IDL Definition
interface HTMLOptGroupElement : HTMLElement {
           attribute boolean         disabled;
           attribute DOMString       label;
};

Attributes
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
label of type DOMString
Assigns a label to this option group. See the label attribute definition in HTML 4.01.
Interface HTMLOptionElement

A selectable choice. See the OPTION element definition in HTML 4.01.

IDL Definition
interface HTMLOptionElement : HTMLElement {
  readonly attribute HTMLFormElement form;
  // Modified in DOM Level 2:
           attribute boolean         defaultSelected;
  readonly attribute DOMString       text;
  // Modified in DOM Level 2:
  readonly attribute long            index;
           attribute boolean         disabled;
           attribute DOMString       label;
           attribute boolean         selected;
           attribute DOMString       value;
};

Attributes
defaultSelected of type boolean, modified in DOM Level 2
Represents the value of the HTML selected attribute. The value of this attribute does not change if the state of the corresponding form control, in an interactive user agent, changes. See the selected attribute definition in HTML 4.01.
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
index of type long, readonly, modified in DOM Level 2
The index of this OPTION in its parent SELECT, starting from 0.
label of type DOMString
Option label for use in hierarchical menus. See the label attribute definition in HTML 4.01.
selected of type boolean
Represents the current state of the corresponding form control, in an interactive user agent. Changing this attribute changes the state of the form control, but does not change the value of the HTML selected attribute of the element.
text of type DOMString, readonly
The text contained within the option element.
value of type DOMString
The current form control value. See the value attribute definition in HTML 4.01.
Interface HTMLInputElement

Form control.

Note: Depending upon the environment in which the page is being viewed, the value property may be read-only for the file upload input type. For the "password" input type, the actual value returned may be masked to prevent unauthorized use. See the INPUT element definition in [HTML 4.01].

IDL Definition
interface HTMLInputElement : HTMLElement {
           attribute DOMString       defaultValue;
           attribute boolean         defaultChecked;
  readonly attribute HTMLFormElement form;
           attribute DOMString       accept;
           attribute DOMString       accessKey;
           attribute DOMString       align;
           attribute DOMString       alt;
           attribute boolean         checked;
           attribute boolean         disabled;
           attribute long            maxLength;
           attribute DOMString       name;
           attribute boolean         readOnly;
  // Modified in DOM Level 2:
           attribute unsigned long   size;
           attribute DOMString       src;
           attribute long            tabIndex;
  // Modified in DOM Level 2:
           attribute DOMString       type;
           attribute DOMString       useMap;
           attribute DOMString       value;
  void               blur();
  void               focus();
  void               select();
  void               click();
};

Attributes
accept of type DOMString
A comma-separated list of content types that a server processing this form will handle correctly. See the accept attribute definition in HTML 4.01.
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
align of type DOMString
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
alt of type DOMString
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.01.
checked of type boolean
When the type attribute of the element has the value "radio" or "checkbox", this represents the current state of the form control, in an interactive user agent. Changes to this attribute change the state of the form control, but do not change the value of the HTML checked attribute of the INPUT element.

Note: During the handling of a click event on an input element with a type attribute that has the value "radio" or "checkbox", some implementations may change the value of this property before the event is being dispatched in the document. If the default action of the event is canceled, the value of the property may be changed back to its original value. This means that the value of this property during the handling of click events is implementation dependent.

defaultChecked of type boolean
When type has the value "radio" or "checkbox", this represents the HTML checked attribute of the element. The value of this attribute does not change if the state of the corresponding form control, in an interactive user agent, changes. See the checked attribute definition in HTML 4.01.
defaultValue of type DOMString
When the type attribute of the element has the value "text", "file" or "password", this represents the HTML value attribute of the element. The value of this attribute does not change if the contents of the corresponding form control, in an interactive user agent, changes. See the value attribute definition in HTML 4.01.
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
maxLength of type long
Maximum number of characters for text fields, when type has the value "text" or "password". See the maxlength attribute definition in HTML 4.01.
name of type DOMString
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
readOnly of type boolean
This control is read-only. Relevant only when type has the value "text" or "password". See the readonly attribute definition in HTML 4.01.
size of type unsigned long, modified in DOM Level 2
Size information. The precise meaning is specific to each type of field. See the size attribute definition in HTML 4.01.
src of type DOMString
When the type attribute has the value "image", this attribute specifies the location of the image to be used to decorate the graphical submit button. See the src attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, modified in DOM Level 2
The type of control created (all lower case). See the type attribute definition in HTML 4.01.
useMap of type DOMString
Use client-side image map. See the usemap attribute definition in HTML 4.01.
value of type DOMString
When the type attribute of the element has the value "text", "file" or "password", this represents the current contents of the corresponding form control, in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the value of the HTML value attribute of the element. When the type attribute of the element has the value "button", "hidden", "submit", "reset", "image", "checkbox" or "radio", this represents the HTML value attribute of the element. See the value attribute definition in HTML 4.01.
Methods
blur
Removes keyboard focus from this element.
No Parameters
No Return Value
No Exceptions
click
Simulate a mouse-click. For INPUT elements whose type attribute has one of the following values: "button", "checkbox", "radio", "reset", or "submit".
No Parameters
No Return Value
No Exceptions
focus
Gives keyboard focus to this element.
No Parameters
No Return Value
No Exceptions
select
Select the contents of the text area. For INPUT elements whose type attribute has one of the following values: "text", "file", or "password".
No Parameters
No Return Value
No Exceptions
Interface HTMLTextAreaElement

Multi-line text field. See the TEXTAREA element definition in HTML 4.01.

IDL Definition
interface HTMLTextAreaElement : HTMLElement {
  // Modified in DOM Level 2:
           attribute DOMString       defaultValue;
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute long            cols;
           attribute boolean         disabled;
           attribute DOMString       name;
           attribute boolean         readOnly;
           attribute long            rows;
           attribute long            tabIndex;
  readonly attribute DOMString       type;
           attribute DOMString       value;
  void               blur();
  void               focus();
  void               select();
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
cols of type long
Width of control (in characters). See the cols attribute definition in HTML 4.01.
defaultValue of type DOMString, modified in DOM Level 2
Represents the contents of the element. The value of this attribute does not change if the contents of the corresponding form control, in an interactive user agent, changes.
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
name of type DOMString
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
readOnly of type boolean
This control is read-only. See the readonly attribute definition in HTML 4.01.
rows of type long
Number of text rows. See the rows attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, readonly
The type of this form control. This the string "textarea".
value of type DOMString
Represents the current contents of the corresponding form control, in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the contents of the element. If the entirety of the data can not fit into a single DOMString, the implementation may truncate the data.
Methods
blur
Removes keyboard focus from this element.
No Parameters
No Return Value
No Exceptions
focus
Gives keyboard focus to this element.
No Parameters
No Return Value
No Exceptions
select
Select the contents of the TEXTAREA.
No Parameters
No Return Value
No Exceptions
Interface HTMLButtonElement

Push button. See the BUTTON element definition in HTML 4.01.

IDL Definition
interface HTMLButtonElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute boolean         disabled;
           attribute DOMString       name;
           attribute long            tabIndex;
  readonly attribute DOMString       type;
           attribute DOMString       value;
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
disabled of type boolean
The control is unavailable in this context. See the disabled attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
name of type DOMString
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString, readonly
The type of button (all lower case). See the type attribute definition in HTML 4.01.
value of type DOMString
The current form control value. See the value attribute definition in HTML 4.01.
Interface HTMLLabelElement

Form field label text. See the LABEL element definition in HTML 4.01.

IDL Definition
interface HTMLLabelElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute DOMString       htmlFor;
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
htmlFor of type DOMString
This attribute links this label with another form control by id attribute. See the for attribute definition in HTML 4.01.
Interface HTMLFieldSetElement

Organizes form controls into logical groups. See the FIELDSET element definition in HTML 4.01.

IDL Definition
interface HTMLFieldSetElement : HTMLElement {
  readonly attribute HTMLFormElement form;
};

Attributes
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
Interface HTMLLegendElement

Provides a caption for a FIELDSET grouping. See the LEGEND element definition in HTML 4.01.

IDL Definition
interface HTMLLegendElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       accessKey;
           attribute DOMString       align;
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
align of type DOMString
Text alignment relative to FIELDSET. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
Interface HTMLUListElement

Unordered list. See the UL element definition in HTML 4.01.

IDL Definition
interface HTMLUListElement : HTMLElement {
           attribute boolean         compact;
           attribute DOMString       type;
};

Attributes
compact of type boolean
Reduce spacing between list items. See the compact attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
type of type DOMString
Bullet style. See the type attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLOListElement

Ordered list. See the OL element definition in HTML 4.01.

IDL Definition
interface HTMLOListElement : HTMLElement {
           attribute boolean         compact;
           attribute long            start;
           attribute DOMString       type;
};

Attributes
compact of type boolean
Reduce spacing between list items. See the compact attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
start of type long
Starting sequence number. See the start attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
type of type DOMString
Numbering style. See the type attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLDListElement

Definition list. See the DL element definition in HTML 4.01.

IDL Definition
interface HTMLDListElement : HTMLElement {
           attribute boolean         compact;
};

Attributes
compact of type boolean
Reduce spacing between list items. See the compact attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLDirectoryElement

Directory list. See the DIR element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLDirectoryElement : HTMLElement {
           attribute boolean         compact;
};

Attributes
compact of type boolean
Reduce spacing between list items. See the compact attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLMenuElement

Menu list. See the MENU element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLMenuElement : HTMLElement {
           attribute boolean         compact;
};

Attributes
compact of type boolean
Reduce spacing between list items. See the compact attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLLIElement

List item. See the LI element definition in HTML 4.01.

IDL Definition
interface HTMLLIElement : HTMLElement {
           attribute DOMString       type;
           attribute long            value;
};

Attributes
type of type DOMString
List item bullet style. See the type attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
value of type long
Reset sequence number when used in OL. See the value attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLDivElement

Generic block container. See the DIV element definition in HTML 4.01.

IDL Definition
interface HTMLDivElement : HTMLElement {
           attribute DOMString       align;
};

Attributes
align of type DOMString
Horizontal text alignment. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLParagraphElement

Paragraphs. See the P element definition in HTML 4.01.

IDL Definition
interface HTMLParagraphElement : HTMLElement {
           attribute DOMString       align;
};

Attributes
align of type DOMString
Horizontal text alignment. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLHeadingElement

For the H1 to H6 elements. See the H1 element definition in HTML 4.01.

IDL Definition
interface HTMLHeadingElement : HTMLElement {
           attribute DOMString       align;
};

Attributes
align of type DOMString
Horizontal text alignment. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLQuoteElement

For the Q and BLOCKQUOTE elements. See the Q element definition in HTML 4.01.

IDL Definition
interface HTMLQuoteElement : HTMLElement {
           attribute DOMString       cite;
};

Attributes
cite of type DOMString
A URI [IETF RFC 2396] designating a source document or message. See the cite attribute definition in HTML 4.01.
Interface HTMLPreElement

Preformatted text. See the PRE element definition in HTML 4.01.

IDL Definition
interface HTMLPreElement : HTMLElement {
           attribute long            width;
};

Attributes
width of type long
Fixed width for content. See the width attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLBRElement

Force a line break. See the BR element definition in HTML 4.01.

IDL Definition
interface HTMLBRElement : HTMLElement {
           attribute DOMString       clear;
};

Attributes
clear of type DOMString
Control flow of text around floats. See the clear attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLBaseFontElement

Base font. See the BASEFONT element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLBaseFontElement : HTMLElement {
           attribute DOMString       color;
           attribute DOMString       face;
  // Modified in DOM Level 2:
           attribute long            size;
};

Attributes
color of type DOMString
Font color. See the color attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
face of type DOMString
Font face identifier. See the face attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
size of type long, modified in DOM Level 2
Computed font size. See the size attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLFontElement

Local change to font. See the FONT element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLFontElement : HTMLElement {
           attribute DOMString       color;
           attribute DOMString       face;
           attribute DOMString       size;
};

Attributes
color of type DOMString
Font color. See the color attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
face of type DOMString
Font face identifier. See the face attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
size of type DOMString
Font size. See the size attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLHRElement

Create a horizontal rule. See the HR element definition in HTML 4.01.

IDL Definition
interface HTMLHRElement : HTMLElement {
           attribute DOMString       align;
           attribute boolean         noShade;
           attribute DOMString       size;
           attribute DOMString       width;
};

Attributes
align of type DOMString
Align the rule on the page. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
noShade of type boolean
Indicates to the user agent that there should be no shading in the rendering of this element. See the noshade attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
size of type DOMString
The height of the rule. See the size attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
width of type DOMString
The width of the rule. See the width attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLModElement

Notice of modification to part of a document. See the INS and DEL element definitions in HTML 4.01.

IDL Definition
interface HTMLModElement : HTMLElement {
           attribute DOMString       cite;
           attribute DOMString       dateTime;
};

Attributes
cite of type DOMString
A URI [IETF RFC 2396] designating a document that describes the reason for the change. See the cite attribute definition in HTML 4.01.
dateTime of type DOMString
The date and time of the change. See the datetime attribute definition in HTML 4.01.
Interface HTMLAnchorElement

The anchor element. See the A element definition in HTML 4.01.

IDL Definition
interface HTMLAnchorElement : HTMLElement {
           attribute DOMString       accessKey;
           attribute DOMString       charset;
           attribute DOMString       coords;
           attribute DOMString       href;
           attribute DOMString       hreflang;
           attribute DOMString       name;
           attribute DOMString       rel;
           attribute DOMString       rev;
           attribute DOMString       shape;
           attribute long            tabIndex;
           attribute DOMString       target;
           attribute DOMString       type;
  void               blur();
  void               focus();
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
charset of type DOMString
The character encoding of the linked resource. See the charset attribute definition in HTML 4.01.
coords of type DOMString
Comma-separated list of lengths, defining an active region geometry. See also shape for the shape of the region. See the coords attribute definition in HTML 4.01.
href of type DOMString
The absolute URI [IETF RFC 2396] of the linked resource. See the href attribute definition in HTML 4.01.
hreflang of type DOMString
Language code of the linked resource. See the hreflang attribute definition in HTML 4.01.
name of type DOMString
Anchor name. See the name attribute definition in HTML 4.01.
rel of type DOMString
Forward link type. See the rel attribute definition in HTML 4.01.
rev of type DOMString
Reverse link type. See the rev attribute definition in HTML 4.01.
shape of type DOMString
The shape of the active area. The coordinates are given by coords. See the shape attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
target of type DOMString
Frame to render the resource in. See the target attribute definition in HTML 4.01.
type of type DOMString
Advisory content type. See the type attribute definition in HTML 4.01.
Methods
blur
Removes keyboard focus from this element.
No Parameters
No Return Value
No Exceptions
focus
Gives keyboard focus to this element.
No Parameters
No Return Value
No Exceptions
Interface HTMLImageElement

Embedded image. See the IMG element definition in HTML 4.01.

IDL Definition
interface HTMLImageElement : HTMLElement {
           attribute DOMString       name;
           attribute DOMString       align;
           attribute DOMString       alt;
           attribute DOMString       border;
  // Modified in DOM Level 2:
           attribute long            height;
  // Modified in DOM Level 2:
           attribute long            hspace;
           attribute boolean         isMap;
           attribute DOMString       longDesc;
           attribute DOMString       src;
           attribute DOMString       useMap;
  // Modified in DOM Level 2:
           attribute long            vspace;
  // Modified in DOM Level 2:
           attribute long            width;
};

Attributes
align of type DOMString
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
alt of type DOMString
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.01.
border of type DOMString
Width of border around image. See the border attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01. Note that the type of this attribute was DOMString in DOM Level 1 HTML [DOM Level 1].
height of type long, modified in DOM Level 2
Height of the image in pixels. See the height attribute definition in HTML 4.01. Note that the type of this attribute was DOMString in DOM Level 1 HTML [DOM Level 1].
hspace of type long, modified in DOM Level 2
Horizontal space to the left and right of this image in pixels. See the hspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01. Note that the type of this attribute was DOMString in DOM Level 1 HTML [DOM Level 1].
isMap of type boolean
Use server-side image map. See the ismap attribute definition in HTML 4.01.
longDesc of type DOMString
URI [IETF RFC 2396] designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.01.
name of type DOMString
The name of the element (for backwards compatibility).
src of type DOMString
URI [IETF RFC 2396] designating the source of this image. See the src attribute definition in HTML 4.01.
useMap of type DOMString
Use client-side image map. See the usemap attribute definition in HTML 4.01.
vspace of type long, modified in DOM Level 2
Vertical space above and below this image in pixels. See the vspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01. Note that the type of this attribute was "DOMString" in DOM Level 1 HTML [DOM Level 1].
width of type long, modified in DOM Level 2
The width of the image in pixels. See the width attribute definition in HTML 4.01. Note that the type of this attribute was DOMString in DOM Level 1 HTML [DOM Level 1].
Interface HTMLObjectElement

Generic embedded object.

Note: In principle, all properties on the object element are read-write but in some environments some properties may be read-only once the underlying object is instantiated. See the OBJECT element definition in [HTML 4.01].

IDL Definition
interface HTMLObjectElement : HTMLElement {
  readonly attribute HTMLFormElement form;
           attribute DOMString       code;
           attribute DOMString       align;
           attribute DOMString       archive;
           attribute DOMString       border;
           attribute DOMString       codeBase;
           attribute DOMString       codeType;
           attribute DOMString       data;
           attribute boolean         declare;
           attribute DOMString       height;
           attribute long            hspace;
           attribute DOMString       name;
           attribute DOMString       standby;
           attribute long            tabIndex;
           attribute DOMString       type;
           attribute DOMString       useMap;
           attribute long            vspace;
           attribute DOMString       width;
  // Introduced in DOM Level 2:
  readonly attribute Document        contentDocument;
};

Attributes
align of type DOMString
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
archive of type DOMString
Space-separated list of archives. See the archive attribute definition in HTML 4.01.
border of type DOMString
Width of border around the object. See the border attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
code of type DOMString
Applet class file. See the code attribute for HTMLAppletElement.
codeBase of type DOMString
Base URI [IETF RFC 2396] for classid, data, and archive attributes. See the codebase attribute definition in HTML 4.01.
codeType of type DOMString
Content type for data downloaded via classid attribute. See the codetype attribute definition in HTML 4.01.
contentDocument of type Document, readonly, introduced in DOM Level 2
The document this object contains, if there is any and it is available, or null otherwise.
data of type DOMString
A URI [IETF RFC 2396] specifying the location of the object's data. See the data attribute definition in HTML 4.01.
declare of type boolean
Declare (for future reference), but do not instantiate, this object. See the declare attribute definition in HTML 4.01.
form of type HTMLFormElement, readonly
Returns the FORM element containing this control. Returns null if this control is not within the context of a form.
height of type DOMString
Override height. See the height attribute definition in HTML 4.01.
hspace of type long
Horizontal space, in pixels, to the left and right of this image, applet, or object. See the hspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
name of type DOMString
Form control or object name when submitted with a form. See the name attribute definition in HTML 4.01.
standby of type DOMString
Message to render while loading the object. See the standby attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
type of type DOMString
Content type for data downloaded via data attribute. See the type attribute definition in HTML 4.01.
useMap of type DOMString
Use client-side image map. See the usemap attribute definition in HTML 4.01.
vspace of type long
Vertical space, in pixels, above and below this image, applet, or object. See the vspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
width of type DOMString
Override width. See the width attribute definition in HTML 4.01.
Interface HTMLParamElement

Parameters fed to the OBJECT element. See the PARAM element definition in HTML 4.01.

IDL Definition
interface HTMLParamElement : HTMLElement {
           attribute DOMString       name;
           attribute DOMString       type;
           attribute DOMString       value;
           attribute DOMString       valueType;
};

Attributes
name of type DOMString
The name of a run-time parameter. See the name attribute definition in HTML 4.01.
type of type DOMString
Content type for the value attribute when valuetype has the value "ref". See the type attribute definition in HTML 4.01.
value of type DOMString
The value of a run-time parameter. See the value attribute definition in HTML 4.01.
valueType of type DOMString
Information about the meaning of the value attribute value. See the valuetype attribute definition in HTML 4.01.
Interface HTMLAppletElement

An embedded Java applet. See the APPLET element definition in HTML 4.01. This element is deprecated in HTML 4.01.

IDL Definition
interface HTMLAppletElement : HTMLElement {
           attribute DOMString       align;
           attribute DOMString       alt;
           attribute DOMString       archive;
           attribute DOMString       code;
           attribute DOMString       codeBase;
           attribute DOMString       height;
  // Modified in DOM Level 2:
           attribute long            hspace;
           attribute DOMString       name;
  // Modified in DOM Level 2:
           attribute DOMString       object;
  // Modified in DOM Level 2:
           attribute long            vspace;
           attribute DOMString       width;
};

Attributes
align of type DOMString
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
alt of type DOMString
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
archive of type DOMString
Comma-separated archive list. See the archive attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
code of type DOMString
Applet class file. See the code attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
codeBase of type DOMString
Optional base URI [IETF RFC 2396] for applet. See the codebase attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
height of type DOMString
Override height. See the height attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
hspace of type long, modified in DOM Level 2
Horizontal space, in pixels, to the left and right of this image, applet, or object. See the hspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
name of type DOMString
The name of the applet. See the name attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
object of type DOMString, modified in DOM Level 2
The value of the "object" attribute. See the object attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
vspace of type long, modified in DOM Level 2
Vertical space, in pixels, above and below this image, applet, or object. See the vspace attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
width of type DOMString
Override width. See the width attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLMapElement

Client-side image map. See the MAP element definition in HTML 4.01.

IDL Definition
interface HTMLMapElement : HTMLElement {
  readonly attribute HTMLCollection  areas;
           attribute DOMString       name;
};

Attributes
areas of type HTMLCollection, readonly
The list of areas defined for the image map.
name of type DOMString
Names the map (for use with usemap). See the name attribute definition in HTML 4.01.
Interface HTMLAreaElement

Client-side image map area definition. See the AREA element definition in HTML 4.01.

IDL Definition
interface HTMLAreaElement : HTMLElement {
           attribute DOMString       accessKey;
           attribute DOMString       alt;
           attribute DOMString       coords;
           attribute DOMString       href;
           attribute boolean         noHref;
           attribute DOMString       shape;
           attribute long            tabIndex;
           attribute DOMString       target;
};

Attributes
accessKey of type DOMString
A single character access key to give access to the form control. See the accesskey attribute definition in HTML 4.01.
alt of type DOMString
Alternate text for user agents not rendering the normal content of this element. See the alt attribute definition in HTML 4.01.
coords of type DOMString
Comma-separated list of lengths, defining an active region geometry. See also shape for the shape of the region. See the coords attribute definition in HTML 4.01.
href of type DOMString
The URI [IETF RFC 2396] of the linked resource. See the href attribute definition in HTML 4.01.
noHref of type boolean
Specifies that this area is inactive, i.e., has no associated action. See the nohref attribute definition in HTML 4.01.
shape of type DOMString
The shape of the active area. The coordinates are given by coords. See the shape attribute definition in HTML 4.01.
tabIndex of type long
Index that represents the element's position in the tabbing order. See the tabindex attribute definition in HTML 4.01.
target of type DOMString
Frame to render the resource in. See the target attribute definition in HTML 4.01.
Interface HTMLScriptElement

Script statements. See the SCRIPT element definition in HTML 4.01.

IDL Definition
interface HTMLScriptElement : HTMLElement {
           attribute DOMString       text;
           attribute DOMString       htmlFor;
           attribute DOMString       event;
           attribute DOMString       charset;
           attribute boolean         defer;
           attribute DOMString       src;
           attribute DOMString       type;
};

Attributes
charset of type DOMString
The character encoding of the linked resource. See the charset attribute definition in HTML 4.01.
defer of type boolean
Indicates that the user agent can defer processing of the script. See the defer attribute definition in HTML 4.01.
event of type DOMString
Reserved for future use.
htmlFor of type DOMString
Reserved for future use.
src of type DOMString
URI [IETF RFC 2396] designating an external script. See the src attribute definition in HTML 4.01.
text of type DOMString
The script content of the element.
type of type DOMString
The content type of the script language. See the type attribute definition in HTML 4.01.
Interface HTMLTableElement

The create* and delete* methods on the table allow authors to construct and modify tables. [HTML 4.01] specifies that only one of each of the CAPTION, THEAD, and TFOOT elements may exist in a table. Therefore, if one exists, and the createTHead() or createTFoot() method is called, the method returns the existing THead or TFoot element. See the TABLE element definition in HTML 4.01.

IDL Definition
interface HTMLTableElement : HTMLElement {
  // Modified in DOM Level 2:
           attribute HTMLTableCaptionElement caption;
                                        // raises(DOMException) on setting

  // Modified in DOM Level 2:
           attribute HTMLTableSectionElement tHead;
                                        // raises(DOMException) on setting

  // Modified in DOM Level 2:
           attribute HTMLTableSectionElement tFoot;
                                        // raises(DOMException) on setting

  readonly attribute HTMLCollection  rows;
  readonly attribute HTMLCollection  tBodies;
           attribute DOMString       align;
           attribute DOMString       bgColor;
           attribute DOMString       border;
           attribute DOMString       cellPadding;
           attribute DOMString       cellSpacing;
           attribute DOMString       frame;
           attribute DOMString       rules;
           attribute DOMString       summary;
           attribute DOMString       width;
  HTMLElement        createTHead();
  void               deleteTHead();
  HTMLElement        createTFoot();
  void               deleteTFoot();
  HTMLElement        createCaption();
  void               deleteCaption();
  // Modified in DOM Level 2:
  HTMLElement        insertRow(in long index)
                                        raises(DOMException);
  // Modified in DOM Level 2:
  void               deleteRow(in long index)
                                        raises(DOMException);
};

Attributes
align of type DOMString
Specifies the table's position with respect to the rest of the document. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
bgColor of type DOMString
Cell background color. See the bgcolor attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
border of type DOMString
The width of the border around the table. See the border attribute definition in HTML 4.01.
caption of type HTMLTableCaptionElement, modified in DOM Level 2
Returns the table's CAPTION, or void if none exists.
Exceptions on setting

DOMException

HIERARCHY_REQUEST_ERR: if the element is not a CAPTION.
cellPadding of type DOMString
Specifies the horizontal and vertical space between cell content and cell borders. See the cellpadding attribute definition in HTML 4.01.
cellSpacing of type DOMString
Specifies the horizontal and vertical separation between cells. See the cellspacing attribute definition in HTML 4.01.
frame of type DOMString
Specifies which external table borders to render. See the frame attribute definition in HTML 4.01.
rows of type HTMLCollection, readonly
Returns a collection of all the rows in the table, including all in THEAD, TFOOT, all TBODY elements.
rules of type DOMString
Specifies which internal table borders to render. See the rules attribute definition in HTML 4.01.
summary of type DOMString
Description about the purpose or structure of a table. See the summary attribute definition in HTML 4.01.
tBodies of type HTMLCollection, readonly
Returns a collection of the table bodies (including implicit ones).
tFoot of type HTMLTableSectionElement, modified in DOM Level 2
Returns the table's TFOOT, or null if none exists.
Exceptions on setting

DOMException

HIERARCHY_REQUEST_ERR: if the element is not a TFOOT.
tHead of type HTMLTableSectionElement, modified in DOM Level 2
Returns the table's THEAD, or null if none exists.
Exceptions on setting

DOMException

HIERARCHY_REQUEST_ERR: if the element is not a THEAD.
width of type DOMString
Specifies the desired table width. See the width attribute definition in HTML 4.01.
Methods
createCaption
Create a new table caption object or return an existing one.
Return Value

HTMLElement

A CAPTION element.
No Parameters
No Exceptions
createTFoot
Create a table footer row or return an existing one.
Return Value

HTMLElement

A footer element (TFOOT).
No Parameters
No Exceptions
createTHead
Create a table header row or return an existing one.
Return Value

HTMLElement

A new table header element (THEAD).
No Parameters
No Exceptions
deleteCaption
Delete the table caption, if one exists.
No Parameters
No Return Value
No Exceptions
deleteRow modified in DOM Level 2
Delete a table row.
Parameters
index of type long
The index of the row to be deleted. This index starts from 0 and is relative to the logical order (not document order) of all the rows contained inside the table. If the index is -1 the last row in the table is deleted.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than or equal to the number of rows or if the index is a negative number other than -1.
No Return Value
deleteTFoot
Delete the footer from the table, if one exists.
No Parameters
No Return Value
No Exceptions
deleteTHead
Delete the header from the table, if one exists.
No Parameters
No Return Value
No Exceptions
insertRow modified in DOM Level 2
Insert a new empty row in the table. The new row is inserted immediately before and in the same section as the current indexth row in the table. If index is -1 or equal to the number of rows, the new row is appended. In addition, when the table is empty the row is inserted into a TBODY which is created and inserted into the table.

Note: A table row cannot be empty according to [HTML 4.01].

Parameters
index of type long
The row number where to insert a new row. This index starts from 0 and is relative to the logical order (not document order) of all the rows contained inside the table.
Return Value

HTMLElement

The newly created row.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than the number of rows or if the index is a negative number other than -1.
Interface HTMLTableCaptionElement

Table caption See the CAPTION element definition in HTML 4.01.

IDL Definition
interface HTMLTableCaptionElement : HTMLElement {
           attribute DOMString       align;
};

Attributes
align of type DOMString
Caption alignment with respect to the table. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLTableColElement

Regroups the COL and COLGROUP elements. See the COL element definition in HTML 4.01.

IDL Definition
interface HTMLTableColElement : HTMLElement {
           attribute DOMString       align;
           attribute DOMString       ch;
           attribute DOMString       chOff;
           attribute long            span;
           attribute DOMString       vAlign;
           attribute DOMString       width;
};

Attributes
align of type DOMString
Horizontal alignment of cell data in column. See the align attribute definition in HTML 4.01.
ch of type DOMString
Alignment character for cells in a column. See the char attribute definition in HTML 4.01.
chOff of type DOMString
Offset of alignment character. See the charoff attribute definition in HTML 4.01.
span of type long
Indicates the number of columns in a group or affected by a grouping. See the span attribute definition in HTML 4.01.
vAlign of type DOMString
Vertical alignment of cell data in column. See the valign attribute definition in HTML 4.01.
width of type DOMString
Default column width. See the width attribute definition in HTML 4.01.
Interface HTMLTableSectionElement

The THEAD, TFOOT, and TBODY elements.

IDL Definition
interface HTMLTableSectionElement : HTMLElement {
           attribute DOMString       align;
           attribute DOMString       ch;
           attribute DOMString       chOff;
           attribute DOMString       vAlign;
  readonly attribute HTMLCollection  rows;
  // Modified in DOM Level 2:
  HTMLElement        insertRow(in long index)
                                        raises(DOMException);
  // Modified in DOM Level 2:
  void               deleteRow(in long index)
                                        raises(DOMException);
};

Attributes
align of type DOMString
Horizontal alignment of data in cells. See the align attribute for HTMLTheadElement for details.
ch of type DOMString
Alignment character for cells in a column. See the char attribute definition in HTML 4.01.
chOff of type DOMString
Offset of alignment character. See the charoff attribute definition in HTML 4.01.
rows of type HTMLCollection, readonly
The collection of rows in this table section.
vAlign of type DOMString
Vertical alignment of data in cells. See the valign attribute for HTMLTheadElement for details.
Methods
deleteRow modified in DOM Level 2
Delete a row from this section.
Parameters
index of type long
The index of the row to be deleted, or -1 to delete the last row. This index starts from 0 and is relative only to the rows contained inside this section, not all the rows in the table.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than or equal to the number of rows or if the index is a negative number other than -1.
No Return Value
insertRow modified in DOM Level 2
Insert a row into this section. The new row is inserted immediately before the current indexth row in this section. If index is -1 or equal to the number of rows in this section, the new row is appended.
Parameters
index of type long
The row number where to insert a new row. This index starts from 0 and is relative only to the rows contained inside this section, not all the rows in the table.
Return Value

HTMLElement

The newly created row.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than the number of rows of if the index is a negative number other than -1.
Interface HTMLTableRowElement

A row in a table. See the TR element definition in HTML 4.01.

IDL Definition
interface HTMLTableRowElement : HTMLElement {
  // Modified in DOM Level 2:
  readonly attribute long            rowIndex;
  // Modified in DOM Level 2:
  readonly attribute long            sectionRowIndex;
  // Modified in DOM Level 2:
  readonly attribute HTMLCollection  cells;
           attribute DOMString       align;
           attribute DOMString       bgColor;
           attribute DOMString       ch;
           attribute DOMString       chOff;
           attribute DOMString       vAlign;
  // Modified in DOM Level 2:
  HTMLElement        insertCell(in long index)
                                        raises(DOMException);
  // Modified in DOM Level 2:
  void               deleteCell(in long index)
                                        raises(DOMException);
};

Attributes
align of type DOMString
Horizontal alignment of data within cells of this row. See the align attribute definition in HTML 4.01.
bgColor of type DOMString
Background color for rows. See the bgcolor attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
cells of type HTMLCollection, readonly, modified in DOM Level 2
The collection of cells in this row.
ch of type DOMString
Alignment character for cells in a column. See the char attribute definition in HTML 4.01.
chOff of type DOMString
Offset of alignment character. See the charoff attribute definition in HTML 4.01.
rowIndex of type long, readonly, modified in DOM Level 2
This is in logical order and not in document order. The rowIndex does take into account sections (THEAD, TFOOT, or TBODY) within the table, placing THEAD rows first in the index, followed by TBODY rows, followed by TFOOT rows.
sectionRowIndex of type long, readonly, modified in DOM Level 2
The index of this row, relative to the current section (THEAD, TFOOT, or TBODY), starting from 0.
vAlign of type DOMString
Vertical alignment of data within cells of this row. See the valign attribute definition in HTML 4.01.
Methods
deleteCell modified in DOM Level 2
Delete a cell from the current row.
Parameters
index of type long
The index of the cell to delete, starting from 0. If the index is -1 the last cell in the row is deleted.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than or equal to the number of cells or if the index is a negative number other than -1.
No Return Value
insertCell modified in DOM Level 2
Insert an empty TD cell into this row. If index is -1 or equal to the number of cells, the new cell is appended.
Parameters
index of type long
The place to insert the cell, starting from 0.
Return Value

HTMLElement

The newly created cell.
Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified index is greater than the number of cells or if the index is a negative number other than -1.
Interface HTMLTableCellElement

The object used to represent the TH and TD elements. See the TD element definition in HTML 4.01.

IDL Definition
interface HTMLTableCellElement : HTMLElement {
  readonly attribute long            cellIndex;
           attribute DOMString       abbr;
           attribute DOMString       align;
           attribute DOMString       axis;
           attribute DOMString       bgColor;
           attribute DOMString       ch;
           attribute DOMString       chOff;
           attribute long            colSpan;
           attribute DOMString       headers;
           attribute DOMString       height;
           attribute boolean         noWrap;
           attribute long            rowSpan;
           attribute DOMString       scope;
           attribute DOMString       vAlign;
           attribute DOMString       width;
};

Attributes
abbr of type DOMString
Abbreviation for header cells. See the abbr attribute definition in HTML 4.01.
align of type DOMString
Horizontal alignment of data in cell. See the align attribute definition in HTML 4.01.
axis of type DOMString
Names group of related headers. See the axis attribute definition in HTML 4.01.
bgColor of type DOMString
Cell background color. See the bgcolor attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
cellIndex of type long, readonly
The index of this cell in the row, starting from 0. This index is in document tree order and not display order.
ch of type DOMString
Alignment character for cells in a column. See the char attribute definition in HTML 4.01.
chOff of type DOMString
Offset of alignment character. See the charoff attribute definition in HTML 4.01.
colSpan of type long
Number of columns spanned by cell. See the colspan attribute definition in HTML 4.01.
headers of type DOMString
List of id attribute values for header cells. See the headers attribute definition in HTML 4.01.
height of type DOMString
Cell height. See the height attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
noWrap of type boolean
Suppress word wrapping. See the nowrap attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
rowSpan of type long
Number of rows spanned by cell. See the rowspan attribute definition in HTML 4.01.
scope of type DOMString
Scope covered by header cells. See the scope attribute definition in HTML 4.01.
vAlign of type DOMString
Vertical alignment of data in cell. See the valign attribute definition in HTML 4.01.
width of type DOMString
Cell width. See the width attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
Interface HTMLFrameSetElement

Create a grid of frames. See the FRAMESET element definition in HTML 4.01.

IDL Definition
interface HTMLFrameSetElement : HTMLElement {
           attribute DOMString       cols;
           attribute DOMString       rows;
};

Attributes
cols of type DOMString
The number of columns of frames in the frameset. See the cols attribute definition in HTML 4.01.
rows of type DOMString
The number of rows of frames in the frameset. See the rows attribute definition in HTML 4.01.
Interface HTMLFrameElement

Create a frame. See the FRAME element definition in HTML 4.01.

IDL Definition
interface HTMLFrameElement : HTMLElement {
           attribute DOMString       frameBorder;
           attribute DOMString       longDesc;
           attribute DOMString       marginHeight;
           attribute DOMString       marginWidth;
           attribute DOMString       name;
           attribute boolean         noResize;
           attribute DOMString       scrolling;
           attribute DOMString       src;
  // Introduced in DOM Level 2:
  readonly attribute Document        contentDocument;
};

Attributes
contentDocument of type Document, readonly, introduced in DOM Level 2
The document this frame contains, if there is any and it is available, or null otherwise.
frameBorder of type DOMString
Request frame borders. See the frameborder attribute definition in HTML 4.01.
longDesc of type DOMString
URI [IETF RFC 2396] designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.01.
marginHeight of type DOMString
Frame margin height, in pixels. See the marginheight attribute definition in HTML 4.01.
marginWidth of type DOMString
Frame margin width, in pixels. See the marginwidth attribute definition in HTML 4.01.
name of type DOMString
The frame name (object of the target attribute). See the name attribute definition in HTML 4.01.
noResize of type boolean
When true, forbid user from resizing frame. See the noresize attribute definition in HTML 4.01.
scrolling of type DOMString
Specify whether or not the frame should have scrollbars. See the scrolling attribute definition in HTML 4.01.
src of type DOMString
A URI [IETF RFC 2396] designating the initial frame contents. See the src attribute definition in HTML 4.01.
Interface HTMLIFrameElement

Inline subwindows. See the IFRAME element definition in HTML 4.01.

IDL Definition
interface HTMLIFrameElement : HTMLElement {
           attribute DOMString       align;
           attribute DOMString       frameBorder;
           attribute DOMString       height;
           attribute DOMString       longDesc;
           attribute DOMString       marginHeight;
           attribute DOMString       marginWidth;
           attribute DOMString       name;
           attribute DOMString       scrolling;
           attribute DOMString       src;
           attribute DOMString       width;
  // Introduced in DOM Level 2:
  readonly attribute Document        contentDocument;
};

Attributes
align of type DOMString
Aligns this object (vertically or horizontally) with respect to its surrounding text. See the align attribute definition in HTML 4.01. This attribute is deprecated in HTML 4.01.
contentDocument of type Document, readonly, introduced in DOM Level 2
The document this frame contains, if there is any and it is available, or null otherwise.
frameBorder of type DOMString
Request frame borders. See the frameborder attribute definition in HTML 4.01.
height of type DOMString
Frame height. See the height attribute definition in HTML 4.01.
longDesc of type DOMString
URI [IETF RFC 2396] designating a long description of this image or frame. See the longdesc attribute definition in HTML 4.01.
marginHeight of type DOMString
Frame margin height, in pixels. See the marginheight attribute definition in HTML 4.01.
marginWidth of type DOMString
Frame margin width, in pixels. See the marginwidth attribute definition in HTML 4.01.
name of type DOMString
The frame name (object of the target attribute). See the name attribute definition in HTML 4.01.
scrolling of type DOMString
Specify whether or not the frame should have scrollbars. See the scrolling attribute definition in HTML 4.01.
src of type DOMString
A URI [IETF RFC 2396] designating the initial frame contents. See the src attribute definition in HTML 4.01.
width of type DOMString
Frame width. See the width attribute definition in HTML 4.01.
previous next contents index


Changes

previous next contents index

09 January 2003

Appendix A: Changes

Editor:
Philippe Le Hégaret, W3C

A.1: Changes between DOM Level 1 and DOM Level 2

Note: The DOM Level 2 HTML module is not backward compatible with the DOM Level 1 HTML module.

OMG IDL
The DOM Level 2 specifications use CORBA 2.3.1 instead of CORBA 2.2.
XHTML 1.0 support
The DOM Level 2 HTML module supports HTML 4 as well as XHTML 1.0 documents. Therefore, case sensitivity in methods depends on Document support for the feature "XML" as well as "HTML".

A.1.1: Changes to DOM Level 1 interfaces and exceptions

Interface HTMLDocument
the method getElementById is now inherited from the Document interface [DOM Level 2 Core] where it was moved.
Interface HTMLSelectElement
The type of the attribute options was changed from HTMLCollection to HTMLOptionsCollection.
The attribute length is no longer readonly and is now unsigned.
Interface HTMLOptionElement
Changing the defaultSelected attribute does not reset the state of the form control.
index is readonly.
Interface HTMLInputElement
the attribute type is no longer read only.
The type of the attribute size was changed from DOMString to unsigned long.
Interface HTMLTextAreaElement
Changing the defaultValue attribute does not reset the contents of the form control.
Interface HTMLBlockquoteElement
this interface has been removed. BLOCKQUOTE elements are now supported by the HTMLQuoteElement interface.
Interface HTMLBaseFontElement
The attribute size is of type long.
Interface HTMLImageElement
The lowSrc attribute was removed.
The types of the attributes height, hspace, width and vspace were changed from DOMString to long.
Interface HTMLObjectElement
The attribute contentDocument was added.
Interface HTMLAppletElement
The types of the attributes hspace and vspace were changed from DOMString to long.
The attribute object returns the value of the HTML object attribute.
Interface HTMLTableElement
caption, tHead, tFoot, insertRow, and deleteRow may raise exceptions.
index uses a logical order, and not a document order.
Interface HTMLTableSectionElement
The methods insertRow and deleteRow may raise exceptions.
Interface HTMLTableRowElement
The attributes rowIndex, sectionRowIndex, and cells are readonly.
The methods insertCell and deleteCell may raise exceptions.
rowIndex uses a logical order, and not a document order.
Interface HTMLFrameElement
the attribute contentDocument was added.
Interface HTMLIFrameElement
the attribute contentDocument was added.
Module and package name
The module name used in the OMG IDL is now html2.
The package name used in the Java bindings is now org.w3c.dom.html2.

A.1.2: New Interfaces

Interface HTMLOptionsCollection
The HTMLOptionsCollection interface was added to the HTML module.
previous next contents index


IDL Definitions

previous next contents index

09 January 2003

Appendix B: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 2 Document Object Model HTML definitions.

Unfortunately the OMG IDL in this appendix is not conformant due to problems in the validator that was used to validate Level 1. The readOnly attribute on the HTMLInputElement and HTMLTextAreaElement interfaces, as well as the object attribute on the HTMLAppletElement interface, are not conformant with OMG IDL 2.2. The valueType attribute on the HTMLParamElement interface is not conformant with OMG IDL 2.3.1, which hadn't been released when DOM Level 1 [DOM Level 1] was published.

The IDL files are also available as: http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109/idl.zip

html2.idl:

// File: html2.idl

#ifndef _HTML2_IDL_
#define _HTML2_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module html2
{

  typedef dom::DOMString DOMString;
  typedef dom::Node Node;
  typedef dom::Document Document;
  typedef dom::NodeList NodeList;
  typedef dom::Element Element;

  interface HTMLElement;
  interface HTMLFormElement;
  interface HTMLTableCaptionElement;
  interface HTMLTableSectionElement;

  interface HTMLCollection {
    readonly attribute unsigned long   length;
    Node               item(in unsigned long index);
    Node               namedItem(in DOMString name);
  };

  // Introduced in DOM Level 2:
  interface HTMLOptionsCollection {
             attribute unsigned long   length;
                                        // raises(dom::DOMException) on setting

    Node               item(in unsigned long index);
    Node               namedItem(in DOMString name);
  };

  interface HTMLDocument : Document {
             attribute DOMString       title;
    readonly attribute DOMString       referrer;
    readonly attribute DOMString       domain;
    readonly attribute DOMString       URL;
             attribute HTMLElement     body;
    readonly attribute HTMLCollection  images;
    readonly attribute HTMLCollection  applets;
    readonly attribute HTMLCollection  links;
    readonly attribute HTMLCollection  forms;
    readonly attribute HTMLCollection  anchors;
             attribute DOMString       cookie;
                                        // raises(dom::DOMException) on setting

    void               open();
    void               close();
    void               write(in DOMString text);
    void               writeln(in DOMString text);
    NodeList           getElementsByName(in DOMString elementName);
  };

  interface HTMLElement : Element {
             attribute DOMString       id;
             attribute DOMString       title;
             attribute DOMString       lang;
             attribute DOMString       dir;
             attribute DOMString       className;
  };

  interface HTMLHtmlElement : HTMLElement {
             attribute DOMString       version;
  };

  interface HTMLHeadElement : HTMLElement {
             attribute DOMString       profile;
  };

  interface HTMLLinkElement : HTMLElement {
             attribute boolean         disabled;
             attribute DOMString       charset;
             attribute DOMString       href;
             attribute DOMString       hreflang;
             attribute DOMString       media;
             attribute DOMString       rel;
             attribute DOMString       rev;
             attribute DOMString       target;
             attribute DOMString       type;
  };

  interface HTMLTitleElement : HTMLElement {
             attribute DOMString       text;
  };

  interface HTMLMetaElement : HTMLElement {
             attribute DOMString       content;
             attribute DOMString       httpEquiv;
             attribute DOMString       name;
             attribute DOMString       scheme;
  };

  interface HTMLBaseElement : HTMLElement {
             attribute DOMString       href;
             attribute DOMString       target;
  };

  interface HTMLIsIndexElement : HTMLElement {
    readonly attribute HTMLFormElement form;
             attribute DOMString       prompt;
  };

  interface HTMLStyleElement : HTMLElement {
             attribute boolean         disabled;
             attribute DOMString       media;
             attribute DOMString       type;
  };

  interface HTMLBodyElement : HTMLElement {
             attribute DOMString       aLink;
             attribute DOMString       background;
             attribute DOMString       bgColor;
             attribute DOMString       link;
             attribute DOMString       text;
             attribute DOMString       vLink;
  };

  interface HTMLFormElement : HTMLElement {
    readonly attribute HTMLCollection  elements;
    readonly attribute long            length;
             attribute DOMString       name;
             attribute DOMString       acceptCharset;
             attribute DOMString       action;
             attribute DOMString       enctype;
             attribute DOMString       method;
             attribute DOMString       target;
    void               submit();
    void               reset();
  };

  interface HTMLSelectElement : HTMLElement {
    readonly attribute DOMString       type;
             attribute long            selectedIndex;
             attribute DOMString       value;
    // Modified in DOM Level 2:
             attribute unsigned long   length;
                                        // raises(dom::DOMException) on setting

    readonly attribute HTMLFormElement form;
    // Modified in DOM Level 2:
    readonly attribute HTMLOptionsCollection options;
             attribute boolean         disabled;
             attribute boolean         multiple;
             attribute DOMString       name;
             attribute long            size;
             attribute long            tabIndex;
    void               add(in HTMLElement element,
                           in HTMLElement before)
                                        raises(dom::DOMException);
    void               remove(in long index);
    void               blur();
    void               focus();
  };

  interface HTMLOptGroupElement : HTMLElement {
             attribute boolean         disabled;
             attribute DOMString       label;
  };

  interface HTMLOptionElement : HTMLElement {
    readonly attribute HTMLFormElement form;
    // Modified in DOM Level 2:
             attribute boolean         defaultSelected;
    readonly attribute DOMString       text;
    // Modified in DOM Level 2:
    readonly attribute long            index;
             attribute boolean         disabled;
             attribute DOMString       label;
             attribute boolean         selected;
             attribute DOMString       value;
  };

  interface HTMLInputElement : HTMLElement {
             attribute DOMString       defaultValue;
             attribute boolean         defaultChecked;
    readonly attribute HTMLFormElement form;
             attribute DOMString       accept;
             attribute DOMString       accessKey;
             attribute DOMString       align;
             attribute DOMString       alt;
             attribute boolean         checked;
             attribute boolean         disabled;
             attribute long            maxLength;
             attribute DOMString       name;
             attribute boolean         readOnly;
    // Modified in DOM Level 2:
             attribute unsigned long   size;
             attribute DOMString       src;
             attribute long            tabIndex;
    // Modified in DOM Level 2:
             attribute DOMString       type;
             attribute DOMString       useMap;
             attribute DOMString       value;
    void               blur();
    void               focus();
    void               select();
    void               click();
  };

  interface HTMLTextAreaElement : HTMLElement {
    // Modified in DOM Level 2:
             attribute DOMString       defaultValue;
    readonly attribute HTMLFormElement form;
             attribute DOMString       accessKey;
             attribute long            cols;
             attribute boolean         disabled;
             attribute DOMString       name;
             attribute boolean         readOnly;
             attribute long            rows;
             attribute long            tabIndex;
    readonly attribute DOMString       type;
             attribute DOMString       value;
    void               blur();
    void               focus();
    void               select();
  };

  interface HTMLButtonElement : HTMLElement {
    readonly attribute HTMLFormElement form;
             attribute DOMString       accessKey;
             attribute boolean         disabled;
             attribute DOMString       name;
             attribute long            tabIndex;
    readonly attribute DOMString       type;
             attribute DOMString       value;
  };

  interface HTMLLabelElement : HTMLElement {
    readonly attribute HTMLFormElement form;
             attribute DOMString       accessKey;
             attribute DOMString       htmlFor;
  };

  interface HTMLFieldSetElement : HTMLElement {
    readonly attribute HTMLFormElement form;
  };

  interface HTMLLegendElement : HTMLElement {
    readonly attribute HTMLFormElement form;
             attribute DOMString       accessKey;
             attribute DOMString       align;
  };

  interface HTMLUListElement : HTMLElement {
             attribute boolean         compact;
             attribute DOMString       type;
  };

  interface HTMLOListElement : HTMLElement {
             attribute boolean         compact;
             attribute long            start;
             attribute DOMString       type;
  };

  interface HTMLDListElement : HTMLElement {
             attribute boolean         compact;
  };

  interface HTMLDirectoryElement : HTMLElement {
             attribute boolean         compact;
  };

  interface HTMLMenuElement : HTMLElement {
             attribute boolean         compact;
  };

  interface HTMLLIElement : HTMLElement {
             attribute DOMString       type;
             attribute long            value;
  };

  interface HTMLDivElement : HTMLElement {
             attribute DOMString       align;
  };

  interface HTMLParagraphElement : HTMLElement {
             attribute DOMString       align;
  };

  interface HTMLHeadingElement : HTMLElement {
             attribute DOMString       align;
  };

  interface HTMLQuoteElement : HTMLElement {
             attribute DOMString       cite;
  };

  interface HTMLPreElement : HTMLElement {
             attribute long            width;
  };

  interface HTMLBRElement : HTMLElement {
             attribute DOMString       clear;
  };

  interface HTMLBaseFontElement : HTMLElement {
             attribute DOMString       color;
             attribute DOMString       face;
    // Modified in DOM Level 2:
             attribute long            size;
  };

  interface HTMLFontElement : HTMLElement {
             attribute DOMString       color;
             attribute DOMString       face;
             attribute DOMString       size;
  };

  interface HTMLHRElement : HTMLElement {
             attribute DOMString       align;
             attribute boolean         noShade;
             attribute DOMString       size;
             attribute DOMString       width;
  };

  interface HTMLModElement : HTMLElement {
             attribute DOMString       cite;
             attribute DOMString       dateTime;
  };

  interface HTMLAnchorElement : HTMLElement {
             attribute DOMString       accessKey;
             attribute DOMString       charset;
             attribute DOMString       coords;
             attribute DOMString       href;
             attribute DOMString       hreflang;
             attribute DOMString       name;
             attribute DOMString       rel;
             attribute DOMString       rev;
             attribute DOMString       shape;
             attribute long            tabIndex;
             attribute DOMString       target;
             attribute DOMString       type;
    void               blur();
    void               focus();
  };

  interface HTMLImageElement : HTMLElement {
             attribute DOMString       name;
             attribute DOMString       align;
             attribute DOMString       alt;
             attribute DOMString       border;
    // Modified in DOM Level 2:
             attribute long            height;
    // Modified in DOM Level 2:
             attribute long            hspace;
             attribute boolean         isMap;
             attribute DOMString       longDesc;
             attribute DOMString       src;
             attribute DOMString       useMap;
    // Modified in DOM Level 2:
             attribute long            vspace;
    // Modified in DOM Level 2:
             attribute long            width;
  };

  interface HTMLObjectElement : HTMLElement {
    readonly attribute HTMLFormElement form;
             attribute DOMString       code;
             attribute DOMString       align;
             attribute DOMString       archive;
             attribute DOMString       border;
             attribute DOMString       codeBase;
             attribute DOMString       codeType;
             attribute DOMString       data;
             attribute boolean         declare;
             attribute DOMString       height;
             attribute long            hspace;
             attribute DOMString       name;
             attribute DOMString       standby;
             attribute long            tabIndex;
             attribute DOMString       type;
             attribute DOMString       useMap;
             attribute long            vspace;
             attribute DOMString       width;
    // Introduced in DOM Level 2:
    readonly attribute Document        contentDocument;
  };

  interface HTMLParamElement : HTMLElement {
             attribute DOMString       name;
             attribute DOMString       type;
             attribute DOMString       value;
             attribute DOMString       valueType;
  };

  interface HTMLAppletElement : HTMLElement {
             attribute DOMString       align;
             attribute DOMString       alt;
             attribute DOMString       archive;
             attribute DOMString       code;
             attribute DOMString       codeBase;
             attribute DOMString       height;
    // Modified in DOM Level 2:
             attribute long            hspace;
             attribute DOMString       name;
    // Modified in DOM Level 2:
             attribute DOMString       object;
    // Modified in DOM Level 2:
             attribute long            vspace;
             attribute DOMString       width;
  };

  interface HTMLMapElement : HTMLElement {
    readonly attribute HTMLCollection  areas;
             attribute DOMString       name;
  };

  interface HTMLAreaElement : HTMLElement {
             attribute DOMString       accessKey;
             attribute DOMString       alt;
             attribute DOMString       coords;
             attribute DOMString       href;
             attribute boolean         noHref;
             attribute DOMString       shape;
             attribute long            tabIndex;
             attribute DOMString       target;
  };

  interface HTMLScriptElement : HTMLElement {
             attribute DOMString       text;
             attribute DOMString       htmlFor;
             attribute DOMString       event;
             attribute DOMString       charset;
             attribute boolean         defer;
             attribute DOMString       src;
             attribute DOMString       type;
  };

  interface HTMLTableElement : HTMLElement {
    // Modified in DOM Level 2:
             attribute HTMLTableCaptionElement caption;
                                        // raises(dom::DOMException) on setting

    // Modified in DOM Level 2:
             attribute HTMLTableSectionElement tHead;
                                        // raises(dom::DOMException) on setting

    // Modified in DOM Level 2:
             attribute HTMLTableSectionElement tFoot;
                                        // raises(dom::DOMException) on setting

    readonly attribute HTMLCollection  rows;
    readonly attribute HTMLCollection  tBodies;
             attribute DOMString       align;
             attribute DOMString       bgColor;
             attribute DOMString       border;
             attribute DOMString       cellPadding;
             attribute DOMString       cellSpacing;
             attribute DOMString       frame;
             attribute DOMString       rules;
             attribute DOMString       summary;
             attribute DOMString       width;
    HTMLElement        createTHead();
    void               deleteTHead();
    HTMLElement        createTFoot();
    void               deleteTFoot();
    HTMLElement        createCaption();
    void               deleteCaption();
    // Modified in DOM Level 2:
    HTMLElement        insertRow(in long index)
                                        raises(dom::DOMException);
    // Modified in DOM Level 2:
    void               deleteRow(in long index)
                                        raises(dom::DOMException);
  };

  interface HTMLTableCaptionElement : HTMLElement {
             attribute DOMString       align;
  };

  interface HTMLTableColElement : HTMLElement {
             attribute DOMString       align;
             attribute DOMString       ch;
             attribute DOMString       chOff;
             attribute long            span;
             attribute DOMString       vAlign;
             attribute DOMString       width;
  };

  interface HTMLTableSectionElement : HTMLElement {
             attribute DOMString       align;
             attribute DOMString       ch;
             attribute DOMString       chOff;
             attribute DOMString       vAlign;
    readonly attribute HTMLCollection  rows;
    // Modified in DOM Level 2:
    HTMLElement        insertRow(in long index)
                                        raises(dom::DOMException);
    // Modified in DOM Level 2:
    void               deleteRow(in long index)
                                        raises(dom::DOMException);
  };

  interface HTMLTableRowElement : HTMLElement {
    // Modified in DOM Level 2:
    readonly attribute long            rowIndex;
    // Modified in DOM Level 2:
    readonly attribute long            sectionRowIndex;
    // Modified in DOM Level 2:
    readonly attribute HTMLCollection  cells;
             attribute DOMString       align;
             attribute DOMString       bgColor;
             attribute DOMString       ch;
             attribute DOMString       chOff;
             attribute DOMString       vAlign;
    // Modified in DOM Level 2:
    HTMLElement        insertCell(in long index)
                                        raises(dom::DOMException);
    // Modified in DOM Level 2:
    void               deleteCell(in long index)
                                        raises(dom::DOMException);
  };

  interface HTMLTableCellElement : HTMLElement {
    readonly attribute long            cellIndex;
             attribute DOMString       abbr;
             attribute DOMString       align;
             attribute DOMString       axis;
             attribute DOMString       bgColor;
             attribute DOMString       ch;
             attribute DOMString       chOff;
             attribute long            colSpan;
             attribute DOMString       headers;
             attribute DOMString       height;
             attribute boolean         noWrap;
             attribute long            rowSpan;
             attribute DOMString       scope;
             attribute DOMString       vAlign;
             attribute DOMString       width;
  };

  interface HTMLFrameSetElement : HTMLElement {
             attribute DOMString       cols;
             attribute DOMString       rows;
  };

  interface HTMLFrameElement : HTMLElement {
             attribute DOMString       frameBorder;
             attribute DOMString       longDesc;
             attribute DOMString       marginHeight;
             attribute DOMString       marginWidth;
             attribute DOMString       name;
             attribute boolean         noResize;
             attribute DOMString       scrolling;
             attribute DOMString       src;
    // Introduced in DOM Level 2:
    readonly attribute Document        contentDocument;
  };

  interface HTMLIFrameElement : HTMLElement {
             attribute DOMString       align;
             attribute DOMString       frameBorder;
             attribute DOMString       height;
             attribute DOMString       longDesc;
             attribute DOMString       marginHeight;
             attribute DOMString       marginWidth;
             attribute DOMString       name;
             attribute DOMString       scrolling;
             attribute DOMString       src;
             attribute DOMString       width;
    // Introduced in DOM Level 2:
    readonly attribute Document        contentDocument;
  };
};

#endif // _HTML2_IDL_
previous next contents index


Java language Binding

previous next contents index

09 January 2003

Appendix C: Java language Binding

This appendix contains the complete Java language [Java] binding for the Level 2 Document Object Model HTML.

The Java files are also available as http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109/java-binding.zip

org/w3c/dom/html2/HTMLCollection.java:

package org.w3c.dom.html2;

import org.w3c.dom.Node;

public interface HTMLCollection {
    public int getLength();

    public Node item(int index);

    public Node namedItem(String name);

}

org/w3c/dom/html2/HTMLOptionsCollection.java:

package org.w3c.dom.html2;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface HTMLOptionsCollection {
    public int getLength();
    public void setLength(int length)
                          throws DOMException;

    public Node item(int index);

    public Node namedItem(String name);

}

org/w3c/dom/html2/HTMLDocument.java:

package org.w3c.dom.html2;

import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import org.w3c.dom.DOMException;

public interface HTMLDocument extends Document {
    public String getTitle();
    public void setTitle(String title);

    public String getReferrer();

    public String getDomain();

    public String getURL();

    public HTMLElement getBody();
    public void setBody(HTMLElement body);

    public HTMLCollection getImages();

    public HTMLCollection getApplets();

    public HTMLCollection getLinks();

    public HTMLCollection getForms();

    public HTMLCollection getAnchors();

    public String getCookie();
    public void setCookie(String cookie)
                          throws DOMException;

    public void open();

    public void close();

    public void write(String text);

    public void writeln(String text);

    public NodeList getElementsByName(String elementName);

}

org/w3c/dom/html2/HTMLElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.Element;

public interface HTMLElement extends Element {
    public String getId();
    public void setId(String id);

    public String getTitle();
    public void setTitle(String title);

    public String getLang();
    public void setLang(String lang);

    public String getDir();
    public void setDir(String dir);

    public String getClassName();
    public void setClassName(String className);

}

org/w3c/dom/html2/HTMLHtmlElement.java:

package org.w3c.dom.html2;

public interface HTMLHtmlElement extends HTMLElement {
    public String getVersion();
    public void setVersion(String version);

}

org/w3c/dom/html2/HTMLHeadElement.java:

package org.w3c.dom.html2;

public interface HTMLHeadElement extends HTMLElement {
    public String getProfile();
    public void setProfile(String profile);

}

org/w3c/dom/html2/HTMLLinkElement.java:

package org.w3c.dom.html2;

public interface HTMLLinkElement extends HTMLElement {
    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getCharset();
    public void setCharset(String charset);

    public String getHref();
    public void setHref(String href);

    public String getHreflang();
    public void setHreflang(String hreflang);

    public String getMedia();
    public void setMedia(String media);

    public String getRel();
    public void setRel(String rel);

    public String getRev();
    public void setRev(String rev);

    public String getTarget();
    public void setTarget(String target);

    public String getType();
    public void setType(String type);

}

org/w3c/dom/html2/HTMLTitleElement.java:

package org.w3c.dom.html2;

public interface HTMLTitleElement extends HTMLElement {
    public String getText();
    public void setText(String text);

}

org/w3c/dom/html2/HTMLMetaElement.java:

package org.w3c.dom.html2;

public interface HTMLMetaElement extends HTMLElement {
    public String getContent();
    public void setContent(String content);

    public String getHttpEquiv();
    public void setHttpEquiv(String httpEquiv);

    public String getName();
    public void setName(String name);

    public String getScheme();
    public void setScheme(String scheme);

}

org/w3c/dom/html2/HTMLBaseElement.java:

package org.w3c.dom.html2;

public interface HTMLBaseElement extends HTMLElement {
    public String getHref();
    public void setHref(String href);

    public String getTarget();
    public void setTarget(String target);

}

org/w3c/dom/html2/HTMLIsIndexElement.java:

package org.w3c.dom.html2;

public interface HTMLIsIndexElement extends HTMLElement {
    public HTMLFormElement getForm();

    public String getPrompt();
    public void setPrompt(String prompt);

}

org/w3c/dom/html2/HTMLStyleElement.java:

package org.w3c.dom.html2;

public interface HTMLStyleElement extends HTMLElement {
    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getMedia();
    public void setMedia(String media);

    public String getType();
    public void setType(String type);

}

org/w3c/dom/html2/HTMLBodyElement.java:

package org.w3c.dom.html2;

public interface HTMLBodyElement extends HTMLElement {
    public String getALink();
    public void setALink(String aLink);

    public String getBackground();
    public void setBackground(String background);

    public String getBgColor();
    public void setBgColor(String bgColor);

    public String getLink();
    public void setLink(String link);

    public String getText();
    public void setText(String text);

    public String getVLink();
    public void setVLink(String vLink);

}

org/w3c/dom/html2/HTMLFormElement.java:

package org.w3c.dom.html2;

public interface HTMLFormElement extends HTMLElement {
    public HTMLCollection getElements();

    public int getLength();

    public String getName();
    public void setName(String name);

    public String getAcceptCharset();
    public void setAcceptCharset(String acceptCharset);

    public String getAction();
    public void setAction(String action);

    public String getEnctype();
    public void setEnctype(String enctype);

    public String getMethod();
    public void setMethod(String method);

    public String getTarget();
    public void setTarget(String target);

    public void submit();

    public void reset();

}

org/w3c/dom/html2/HTMLSelectElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.DOMException;

public interface HTMLSelectElement extends HTMLElement {
    public String getType();

    public int getSelectedIndex();
    public void setSelectedIndex(int selectedIndex);

    public String getValue();
    public void setValue(String value);

    public int getLength();
    public void setLength(int length)
                      throws DOMException;

    public HTMLFormElement getForm();

    public HTMLOptionsCollection getOptions();

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public boolean getMultiple();
    public void setMultiple(boolean multiple);

    public String getName();
    public void setName(String name);

    public int getSize();
    public void setSize(int size);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public void add(HTMLElement element,
                    HTMLElement before)
                    throws DOMException;

    public void remove(int index);

    public void blur();

    public void focus();

}

org/w3c/dom/html2/HTMLOptGroupElement.java:

package org.w3c.dom.html2;

public interface HTMLOptGroupElement extends HTMLElement {
    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getLabel();
    public void setLabel(String label);

}

org/w3c/dom/html2/HTMLOptionElement.java:

package org.w3c.dom.html2;

public interface HTMLOptionElement extends HTMLElement {
    public HTMLFormElement getForm();

    public boolean getDefaultSelected();
    public void setDefaultSelected(boolean defaultSelected);

    public String getText();

    public int getIndex();

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getLabel();
    public void setLabel(String label);

    public boolean getSelected();
    public void setSelected(boolean selected);

    public String getValue();
    public void setValue(String value);

}

org/w3c/dom/html2/HTMLInputElement.java:

package org.w3c.dom.html2;

public interface HTMLInputElement extends HTMLElement {
    public String getDefaultValue();
    public void setDefaultValue(String defaultValue);

    public boolean getDefaultChecked();
    public void setDefaultChecked(boolean defaultChecked);

    public HTMLFormElement getForm();

    public String getAccept();
    public void setAccept(String accept);

    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public String getAlign();
    public void setAlign(String align);

    public String getAlt();
    public void setAlt(String alt);

    public boolean getChecked();
    public void setChecked(boolean checked);

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public int getMaxLength();
    public void setMaxLength(int maxLength);

    public String getName();
    public void setName(String name);

    public boolean getReadOnly();
    public void setReadOnly(boolean readOnly);

    public int getSize();
    public void setSize(int size);

    public String getSrc();
    public void setSrc(String src);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getType();
    public void setType(String type);

    public String getUseMap();
    public void setUseMap(String useMap);

    public String getValue();
    public void setValue(String value);

    public void blur();

    public void focus();

    public void select();

    public void click();

}

org/w3c/dom/html2/HTMLTextAreaElement.java:

package org.w3c.dom.html2;

public interface HTMLTextAreaElement extends HTMLElement {
    public String getDefaultValue();
    public void setDefaultValue(String defaultValue);

    public HTMLFormElement getForm();

    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public int getCols();
    public void setCols(int cols);

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getName();
    public void setName(String name);

    public boolean getReadOnly();
    public void setReadOnly(boolean readOnly);

    public int getRows();
    public void setRows(int rows);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getType();

    public String getValue();
    public void setValue(String value);

    public void blur();

    public void focus();

    public void select();

}

org/w3c/dom/html2/HTMLButtonElement.java:

package org.w3c.dom.html2;

public interface HTMLButtonElement extends HTMLElement {
    public HTMLFormElement getForm();

    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public boolean getDisabled();
    public void setDisabled(boolean disabled);

    public String getName();
    public void setName(String name);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getType();

    public String getValue();
    public void setValue(String value);

}

org/w3c/dom/html2/HTMLLabelElement.java:

package org.w3c.dom.html2;

public interface HTMLLabelElement extends HTMLElement {
    public HTMLFormElement getForm();

    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public String getHtmlFor();
    public void setHtmlFor(String htmlFor);

}

org/w3c/dom/html2/HTMLFieldSetElement.java:

package org.w3c.dom.html2;

public interface HTMLFieldSetElement extends HTMLElement {
    public HTMLFormElement getForm();

}

org/w3c/dom/html2/HTMLLegendElement.java:

package org.w3c.dom.html2;

public interface HTMLLegendElement extends HTMLElement {
    public HTMLFormElement getForm();

    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public String getAlign();
    public void setAlign(String align);

}

org/w3c/dom/html2/HTMLUListElement.java:

package org.w3c.dom.html2;

public interface HTMLUListElement extends HTMLElement {
    public boolean getCompact();
    public void setCompact(boolean compact);

    public String getType();
    public void setType(String type);

}

org/w3c/dom/html2/HTMLOListElement.java:

package org.w3c.dom.html2;

public interface HTMLOListElement extends HTMLElement {
    public boolean getCompact();
    public void setCompact(boolean compact);

    public int getStart();
    public void setStart(int start);

    public String getType();
    public void setType(String type);

}

org/w3c/dom/html2/HTMLDListElement.java:

package org.w3c.dom.html2;

public interface HTMLDListElement extends HTMLElement {
    public boolean getCompact();
    public void setCompact(boolean compact);

}

org/w3c/dom/html2/HTMLDirectoryElement.java:

package org.w3c.dom.html2;

public interface HTMLDirectoryElement extends HTMLElement {
    public boolean getCompact();
    public void setCompact(boolean compact);

}

org/w3c/dom/html2/HTMLMenuElement.java:

package org.w3c.dom.html2;

public interface HTMLMenuElement extends HTMLElement {
    public boolean getCompact();
    public void setCompact(boolean compact);

}

org/w3c/dom/html2/HTMLLIElement.java:

package org.w3c.dom.html2;

public interface HTMLLIElement extends HTMLElement {
    public String getType();
    public void setType(String type);

    public int getValue();
    public void setValue(int value);

}

org/w3c/dom/html2/HTMLDivElement.java:

package org.w3c.dom.html2;

public interface HTMLDivElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

}

org/w3c/dom/html2/HTMLParagraphElement.java:

package org.w3c.dom.html2;

public interface HTMLParagraphElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

}

org/w3c/dom/html2/HTMLHeadingElement.java:

package org.w3c.dom.html2;

public interface HTMLHeadingElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

}

org/w3c/dom/html2/HTMLQuoteElement.java:

package org.w3c.dom.html2;

public interface HTMLQuoteElement extends HTMLElement {
    public String getCite();
    public void setCite(String cite);

}

org/w3c/dom/html2/HTMLPreElement.java:

package org.w3c.dom.html2;

public interface HTMLPreElement extends HTMLElement {
    public int getWidth();
    public void setWidth(int width);

}

org/w3c/dom/html2/HTMLBRElement.java:

package org.w3c.dom.html2;

public interface HTMLBRElement extends HTMLElement {
    public String getClear();
    public void setClear(String clear);

}

org/w3c/dom/html2/HTMLBaseFontElement.java:

package org.w3c.dom.html2;

public interface HTMLBaseFontElement extends HTMLElement {
    public String getColor();
    public void setColor(String color);

    public String getFace();
    public void setFace(String face);

    public int getSize();
    public void setSize(int size);

}

org/w3c/dom/html2/HTMLFontElement.java:

package org.w3c.dom.html2;

public interface HTMLFontElement extends HTMLElement {
    public String getColor();
    public void setColor(String color);

    public String getFace();
    public void setFace(String face);

    public String getSize();
    public void setSize(String size);

}

org/w3c/dom/html2/HTMLHRElement.java:

package org.w3c.dom.html2;

public interface HTMLHRElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

    public boolean getNoShade();
    public void setNoShade(boolean noShade);

    public String getSize();
    public void setSize(String size);

    public String getWidth();
    public void setWidth(String width);

}

org/w3c/dom/html2/HTMLModElement.java:

package org.w3c.dom.html2;

public interface HTMLModElement extends HTMLElement {
    public String getCite();
    public void setCite(String cite);

    public String getDateTime();
    public void setDateTime(String dateTime);

}

org/w3c/dom/html2/HTMLAnchorElement.java:

package org.w3c.dom.html2;

public interface HTMLAnchorElement extends HTMLElement {
    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public String getCharset();
    public void setCharset(String charset);

    public String getCoords();
    public void setCoords(String coords);

    public String getHref();
    public void setHref(String href);

    public String getHreflang();
    public void setHreflang(String hreflang);

    public String getName();
    public void setName(String name);

    public String getRel();
    public void setRel(String rel);

    public String getRev();
    public void setRev(String rev);

    public String getShape();
    public void setShape(String shape);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getTarget();
    public void setTarget(String target);

    public String getType();
    public void setType(String type);

    public void blur();

    public void focus();

}

org/w3c/dom/html2/HTMLImageElement.java:

package org.w3c.dom.html2;

public interface HTMLImageElement extends HTMLElement {
    public String getName();
    public void setName(String name);

    public String getAlign();
    public void setAlign(String align);

    public String getAlt();
    public void setAlt(String alt);

    public String getBorder();
    public void setBorder(String border);

    public int getHeight();
    public void setHeight(int height);

    public int getHspace();
    public void setHspace(int hspace);

    public boolean getIsMap();
    public void setIsMap(boolean isMap);

    public String getLongDesc();
    public void setLongDesc(String longDesc);

    public String getSrc();
    public void setSrc(String src);

    public String getUseMap();
    public void setUseMap(String useMap);

    public int getVspace();
    public void setVspace(int vspace);

    public int getWidth();
    public void setWidth(int width);

}

org/w3c/dom/html2/HTMLObjectElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.Document;

public interface HTMLObjectElement extends HTMLElement {
    public HTMLFormElement getForm();

    public String getCode();
    public void setCode(String code);

    public String getAlign();
    public void setAlign(String align);

    public String getArchive();
    public void setArchive(String archive);

    public String getBorder();
    public void setBorder(String border);

    public String getCodeBase();
    public void setCodeBase(String codeBase);

    public String getCodeType();
    public void setCodeType(String codeType);

    public String getData();
    public void setData(String data);

    public boolean getDeclare();
    public void setDeclare(boolean declare);

    public String getHeight();
    public void setHeight(String height);

    public int getHspace();
    public void setHspace(int hspace);

    public String getName();
    public void setName(String name);

    public String getStandby();
    public void setStandby(String standby);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getType();
    public void setType(String type);

    public String getUseMap();
    public void setUseMap(String useMap);

    public int getVspace();
    public void setVspace(int vspace);

    public String getWidth();
    public void setWidth(String width);

    public Document getContentDocument();

}

org/w3c/dom/html2/HTMLParamElement.java:

package org.w3c.dom.html2;

public interface HTMLParamElement extends HTMLElement {
    public String getName();
    public void setName(String name);

    public String getType();
    public void setType(String type);

    public String getValue();
    public void setValue(String value);

    public String getValueType();
    public void setValueType(String valueType);

}

org/w3c/dom/html2/HTMLAppletElement.java:

package org.w3c.dom.html2;

public interface HTMLAppletElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

    public String getAlt();
    public void setAlt(String alt);

    public String getArchive();
    public void setArchive(String archive);

    public String getCode();
    public void setCode(String code);

    public String getCodeBase();
    public void setCodeBase(String codeBase);

    public String getHeight();
    public void setHeight(String height);

    public int getHspace();
    public void setHspace(int hspace);

    public String getName();
    public void setName(String name);

    public String getObject();
    public void setObject(String object);

    public int getVspace();
    public void setVspace(int vspace);

    public String getWidth();
    public void setWidth(String width);

}

org/w3c/dom/html2/HTMLMapElement.java:

package org.w3c.dom.html2;

public interface HTMLMapElement extends HTMLElement {
    public HTMLCollection getAreas();

    public String getName();
    public void setName(String name);

}

org/w3c/dom/html2/HTMLAreaElement.java:

package org.w3c.dom.html2;

public interface HTMLAreaElement extends HTMLElement {
    public String getAccessKey();
    public void setAccessKey(String accessKey);

    public String getAlt();
    public void setAlt(String alt);

    public String getCoords();
    public void setCoords(String coords);

    public String getHref();
    public void setHref(String href);

    public boolean getNoHref();
    public void setNoHref(boolean noHref);

    public String getShape();
    public void setShape(String shape);

    public int getTabIndex();
    public void setTabIndex(int tabIndex);

    public String getTarget();
    public void setTarget(String target);

}

org/w3c/dom/html2/HTMLScriptElement.java:

package org.w3c.dom.html2;

public interface HTMLScriptElement extends HTMLElement {
    public String getText();
    public void setText(String text);

    public String getHtmlFor();
    public void setHtmlFor(String htmlFor);

    public String getEvent();
    public void setEvent(String event);

    public String getCharset();
    public void setCharset(String charset);

    public boolean getDefer();
    public void setDefer(boolean defer);

    public String getSrc();
    public void setSrc(String src);

    public String getType();
    public void setType(String type);

}

org/w3c/dom/html2/HTMLTableElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.DOMException;

public interface HTMLTableElement extends HTMLElement {
    public HTMLTableCaptionElement getCaption();
    public void setCaption(HTMLTableCaptionElement caption)
                      throws DOMException;

    public HTMLTableSectionElement getTHead();
    public void setTHead(HTMLTableSectionElement tHead)
                      throws DOMException;

    public HTMLTableSectionElement getTFoot();
    public void setTFoot(HTMLTableSectionElement tFoot)
                      throws DOMException;

    public HTMLCollection getRows();

    public HTMLCollection getTBodies();

    public String getAlign();
    public void setAlign(String align);

    public String getBgColor();
    public void setBgColor(String bgColor);

    public String getBorder();
    public void setBorder(String border);

    public String getCellPadding();
    public void setCellPadding(String cellPadding);

    public String getCellSpacing();
    public void setCellSpacing(String cellSpacing);

    public String getFrame();
    public void setFrame(String frame);

    public String getRules();
    public void setRules(String rules);

    public String getSummary();
    public void setSummary(String summary);

    public String getWidth();
    public void setWidth(String width);

    public HTMLElement createTHead();

    public void deleteTHead();

    public HTMLElement createTFoot();

    public void deleteTFoot();

    public HTMLElement createCaption();

    public void deleteCaption();

    public HTMLElement insertRow(int index)
                                 throws DOMException;

    public void deleteRow(int index)
                          throws DOMException;

}

org/w3c/dom/html2/HTMLTableCaptionElement.java:

package org.w3c.dom.html2;

public interface HTMLTableCaptionElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

}

org/w3c/dom/html2/HTMLTableColElement.java:

package org.w3c.dom.html2;

public interface HTMLTableColElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

    public String getCh();
    public void setCh(String ch);

    public String getChOff();
    public void setChOff(String chOff);

    public int getSpan();
    public void setSpan(int span);

    public String getVAlign();
    public void setVAlign(String vAlign);

    public String getWidth();
    public void setWidth(String width);

}

org/w3c/dom/html2/HTMLTableSectionElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.DOMException;

public interface HTMLTableSectionElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

    public String getCh();
    public void setCh(String ch);

    public String getChOff();
    public void setChOff(String chOff);

    public String getVAlign();
    public void setVAlign(String vAlign);

    public HTMLCollection getRows();

    public HTMLElement insertRow(int index)
                                 throws DOMException;

    public void deleteRow(int index)
                          throws DOMException;

}

org/w3c/dom/html2/HTMLTableRowElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.DOMException;

public interface HTMLTableRowElement extends HTMLElement {
    public int getRowIndex();

    public int getSectionRowIndex();

    public HTMLCollection getCells();

    public String getAlign();
    public void setAlign(String align);

    public String getBgColor();
    public void setBgColor(String bgColor);

    public String getCh();
    public void setCh(String ch);

    public String getChOff();
    public void setChOff(String chOff);

    public String getVAlign();
    public void setVAlign(String vAlign);

    public HTMLElement insertCell(int index)
                                  throws DOMException;

    public void deleteCell(int index)
                           throws DOMException;

}

org/w3c/dom/html2/HTMLTableCellElement.java:

package org.w3c.dom.html2;

public interface HTMLTableCellElement extends HTMLElement {
    public int getCellIndex();

    public String getAbbr();
    public void setAbbr(String abbr);

    public String getAlign();
    public void setAlign(String align);

    public String getAxis();
    public void setAxis(String axis);

    public String getBgColor();
    public void setBgColor(String bgColor);

    public String getCh();
    public void setCh(String ch);

    public String getChOff();
    public void setChOff(String chOff);

    public int getColSpan();
    public void setColSpan(int colSpan);

    public String getHeaders();
    public void setHeaders(String headers);

    public String getHeight();
    public void setHeight(String height);

    public boolean getNoWrap();
    public void setNoWrap(boolean noWrap);

    public int getRowSpan();
    public void setRowSpan(int rowSpan);

    public String getScope();
    public void setScope(String scope);

    public String getVAlign();
    public void setVAlign(String vAlign);

    public String getWidth();
    public void setWidth(String width);

}

org/w3c/dom/html2/HTMLFrameSetElement.java:

package org.w3c.dom.html2;

public interface HTMLFrameSetElement extends HTMLElement {
    public String getCols();
    public void setCols(String cols);

    public String getRows();
    public void setRows(String rows);

}

org/w3c/dom/html2/HTMLFrameElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.Document;

public interface HTMLFrameElement extends HTMLElement {
    public String getFrameBorder();
    public void setFrameBorder(String frameBorder);

    public String getLongDesc();
    public void setLongDesc(String longDesc);

    public String getMarginHeight();
    public void setMarginHeight(String marginHeight);

    public String getMarginWidth();
    public void setMarginWidth(String marginWidth);

    public String getName();
    public void setName(String name);

    public boolean getNoResize();
    public void setNoResize(boolean noResize);

    public String getScrolling();
    public void setScrolling(String scrolling);

    public String getSrc();
    public void setSrc(String src);

    public Document getContentDocument();

}

org/w3c/dom/html2/HTMLIFrameElement.java:

package org.w3c.dom.html2;

import org.w3c.dom.Document;

public interface HTMLIFrameElement extends HTMLElement {
    public String getAlign();
    public void setAlign(String align);

    public String getFrameBorder();
    public void setFrameBorder(String frameBorder);

    public String getHeight();
    public void setHeight(String height);

    public String getLongDesc();
    public void setLongDesc(String longDesc);

    public String getMarginHeight();
    public void setMarginHeight(String marginHeight);

    public String getMarginWidth();
    public void setMarginWidth(String marginWidth);

    public String getName();
    public void setName(String name);

    public String getScrolling();
    public void setScrolling(String scrolling);

    public String getSrc();
    public void setSrc(String src);

    public String getWidth();
    public void setWidth(String width);

    public Document getContentDocument();

}
previous next contents index


ECMAScript Language Binding

previous next contents index

09 January 2003

Appendix D: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 2 Document Object Model HTML definitions.

Note: Exceptions handling is only supported by ECMAScript implementation conformant with the Standard ECMA-262 3rd. Edition ([ECMAScript]).

Objects that implement the HTMLCollection interface:
Properties of objects that implement the HTMLCollection interface:
length
This read-only property is a Number.
Functions of objects that implement the HTMLCollection interface:
item(index)
This function returns an object that implements the Node interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
namedItem(name)
This function returns an object that implements the Node interface.
The name parameter is a String.
Note: This object can also be dereferenced using square bracket notation (e.g. obj["foo"]). Dereferencing using a string index is equivalent to invoking the namedItem function with that index.
Objects that implement the HTMLOptionsCollection interface:
Properties of objects that implement the HTMLOptionsCollection interface:
length
This property is a Number and can raise an object that implements DOMException interface on setting.
Functions of objects that implement the HTMLOptionsCollection interface:
item(index)
This function returns an object that implements the Node interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
namedItem(name)
This function returns an object that implements the Node interface.
The name parameter is a String.
Note: This object can also be dereferenced using square bracket notation (e.g. obj["foo"]). Dereferencing using a string index is equivalent to invoking the namedItem function with that index.
Objects that implement the HTMLDocument interface:
Objects that implement the HTMLDocument interface have all properties and functions of the Document interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLDocument interface:
title
This property is a String.
referrer
This read-only property is a String.
domain
This read-only property is a String.
URL
This read-only property is a String.
body
This property is an object that implements the HTMLElement interface.
images
This read-only property is an object that implements the HTMLCollection interface.
applets
This read-only property is an object that implements the HTMLCollection interface.
links
This read-only property is an object that implements the HTMLCollection interface.
forms
This read-only property is an object that implements the HTMLCollection interface.
anchors
This read-only property is an object that implements the HTMLCollection interface.
cookie
This property is a String and can raise an object that implements DOMException interface on setting.
Functions of objects that implement the HTMLDocument interface:
open()
This function has no return value.
close()
This function has no return value.
write(text)
This function has no return value.
The text parameter is a String.
writeln(text)
This function has no return value.
The text parameter is a String.
getElementsByName(elementName)
This function returns an object that implements the NodeList interface.
The elementName parameter is a String.
Objects that implement the HTMLElement interface:
Objects that implement the HTMLElement interface have all properties and functions of the Element interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLElement interface:
id
This property is a String.
title
This property is a String.
lang
This property is a String.
dir
This property is a String.
className
This property is a String.
Objects that implement the HTMLHtmlElement interface:
Objects that implement the HTMLHtmlElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLHtmlElement interface:
version
This property is a String.
Objects that implement the HTMLHeadElement interface:
Objects that implement the HTMLHeadElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLHeadElement interface:
profile
This property is a String.
Objects that implement the HTMLLinkElement interface:
Objects that implement the HTMLLinkElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLLinkElement interface:
disabled
This property is a Boolean.
charset
This property is a String.
href
This property is a String.
hreflang
This property is a String.
media
This property is a String.
rel
This property is a String.
rev
This property is a String.
target
This property is a String.
type
This property is a String.
Objects that implement the HTMLTitleElement interface:
Objects that implement the HTMLTitleElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTitleElement interface:
text
This property is a String.
Objects that implement the HTMLMetaElement interface:
Objects that implement the HTMLMetaElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLMetaElement interface:
content
This property is a String.
httpEquiv
This property is a String.
name
This property is a String.
scheme
This property is a String.
Objects that implement the HTMLBaseElement interface:
Objects that implement the HTMLBaseElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLBaseElement interface:
href
This property is a String.
target
This property is a String.
Objects that implement the HTMLIsIndexElement interface:
Objects that implement the HTMLIsIndexElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLIsIndexElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
prompt
This property is a String.
Objects that implement the HTMLStyleElement interface:
Objects that implement the HTMLStyleElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLStyleElement interface:
disabled
This property is a Boolean.
media
This property is a String.
type
This property is a String.
Objects that implement the HTMLBodyElement interface:
Objects that implement the HTMLBodyElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLBodyElement interface:
aLink
This property is a String.
background
This property is a String.
bgColor
This property is a String.
link
This property is a String.
text
This property is a String.
vLink
This property is a String.
Objects that implement the HTMLFormElement interface:
Objects that implement the HTMLFormElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLFormElement interface:
elements
This read-only property is an object that implements the HTMLCollection interface.
length
This read-only property is a Number.
name
This property is a String.
acceptCharset
This property is a String.
action
This property is a String.
enctype
This property is a String.
method
This property is a String.
target
This property is a String.
Functions of objects that implement the HTMLFormElement interface:
submit()
This function has no return value.
reset()
This function has no return value.
Objects that implement the HTMLSelectElement interface:
Objects that implement the HTMLSelectElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLSelectElement interface:
type
This read-only property is a String.
selectedIndex
This property is a Number.
value
This property is a String.
length
This property is a Number and can raise an object that implements DOMException interface on setting.
form
This read-only property is an object that implements the HTMLFormElement interface.
options
This read-only property is an object that implements the HTMLOptionsCollection interface.
disabled
This property is a Boolean.
multiple
This property is a Boolean.
name
This property is a String.
size
This property is a Number.
tabIndex
This property is a Number.
Functions of objects that implement the HTMLSelectElement interface:
add(element, before)
This function has no return value.
The element parameter is an object that implements the HTMLElement interface.
The before parameter is an object that implements the HTMLElement interface.
This function can raise an object that implements the DOMException interface.
remove(index)
This function has no return value.
The index parameter is a Number.
blur()
This function has no return value.
focus()
This function has no return value.
Objects that implement the HTMLOptGroupElement interface:
Objects that implement the HTMLOptGroupElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLOptGroupElement interface:
disabled
This property is a Boolean.
label
This property is a String.
Objects that implement the HTMLOptionElement interface:
Objects that implement the HTMLOptionElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLOptionElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
defaultSelected
This property is a Boolean.
text
This read-only property is a String.
index
This read-only property is a Number.
disabled
This property is a Boolean.
label
This property is a String.
selected
This property is a Boolean.
value
This property is a String.
Objects that implement the HTMLInputElement interface:
Objects that implement the HTMLInputElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLInputElement interface:
defaultValue
This property is a String.
defaultChecked
This property is a Boolean.
form
This read-only property is an object that implements the HTMLFormElement interface.
accept
This property is a String.
accessKey
This property is a String.
align
This property is a String.
alt
This property is a String.
checked
This property is a Boolean.
disabled
This property is a Boolean.
maxLength
This property is a Number.
name
This property is a String.
readOnly
This property is a Boolean.
size
This property is a Number.
src
This property is a String.
tabIndex
This property is a Number.
type
This property is a String.
useMap
This property is a String.
value
This property is a String.
Functions of objects that implement the HTMLInputElement interface:
blur()
This function has no return value.
focus()
This function has no return value.
select()
This function has no return value.
click()
This function has no return value.
Objects that implement the HTMLTextAreaElement interface:
Objects that implement the HTMLTextAreaElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTextAreaElement interface:
defaultValue
This property is a String.
form
This read-only property is an object that implements the HTMLFormElement interface.
accessKey
This property is a String.
cols
This property is a Number.
disabled
This property is a Boolean.
name
This property is a String.
readOnly
This property is a Boolean.
rows
This property is a Number.
tabIndex
This property is a Number.
type
This read-only property is a String.
value
This property is a String.
Functions of objects that implement the HTMLTextAreaElement interface:
blur()
This function has no return value.
focus()
This function has no return value.
select()
This function has no return value.
Objects that implement the HTMLButtonElement interface:
Objects that implement the HTMLButtonElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLButtonElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
accessKey
This property is a String.
disabled
This property is a Boolean.
name
This property is a String.
tabIndex
This property is a Number.
type
This read-only property is a String.
value
This property is a String.
Objects that implement the HTMLLabelElement interface:
Objects that implement the HTMLLabelElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLLabelElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
accessKey
This property is a String.
htmlFor
This property is a String.
Objects that implement the HTMLFieldSetElement interface:
Objects that implement the HTMLFieldSetElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLFieldSetElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
Objects that implement the HTMLLegendElement interface:
Objects that implement the HTMLLegendElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLLegendElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
accessKey
This property is a String.
align
This property is a String.
Objects that implement the HTMLUListElement interface:
Objects that implement the HTMLUListElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLUListElement interface:
compact
This property is a Boolean.
type
This property is a String.
Objects that implement the HTMLOListElement interface:
Objects that implement the HTMLOListElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLOListElement interface:
compact
This property is a Boolean.
start
This property is a Number.
type
This property is a String.
Objects that implement the HTMLDListElement interface:
Objects that implement the HTMLDListElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLDListElement interface:
compact
This property is a Boolean.
Objects that implement the HTMLDirectoryElement interface:
Objects that implement the HTMLDirectoryElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLDirectoryElement interface:
compact
This property is a Boolean.
Objects that implement the HTMLMenuElement interface:
Objects that implement the HTMLMenuElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLMenuElement interface:
compact
This property is a Boolean.
Objects that implement the HTMLLIElement interface:
Objects that implement the HTMLLIElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLLIElement interface:
type
This property is a String.
value
This property is a Number.
Objects that implement the HTMLDivElement interface:
Objects that implement the HTMLDivElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLDivElement interface:
align
This property is a String.
Objects that implement the HTMLParagraphElement interface:
Objects that implement the HTMLParagraphElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLParagraphElement interface:
align
This property is a String.
Objects that implement the HTMLHeadingElement interface:
Objects that implement the HTMLHeadingElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLHeadingElement interface:
align
This property is a String.
Objects that implement the HTMLQuoteElement interface:
Objects that implement the HTMLQuoteElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLQuoteElement interface:
cite
This property is a String.
Objects that implement the HTMLPreElement interface:
Objects that implement the HTMLPreElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLPreElement interface:
width
This property is a Number.
Objects that implement the HTMLBRElement interface:
Objects that implement the HTMLBRElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLBRElement interface:
clear
This property is a String.
Objects that implement the HTMLBaseFontElement interface:
Objects that implement the HTMLBaseFontElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLBaseFontElement interface:
color
This property is a String.
face
This property is a String.
size
This property is a Number.
Objects that implement the HTMLFontElement interface:
Objects that implement the HTMLFontElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLFontElement interface:
color
This property is a String.
face
This property is a String.
size
This property is a String.
Objects that implement the HTMLHRElement interface:
Objects that implement the HTMLHRElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLHRElement interface:
align
This property is a String.
noShade
This property is a Boolean.
size
This property is a String.
width
This property is a String.
Objects that implement the HTMLModElement interface:
Objects that implement the HTMLModElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLModElement interface:
cite
This property is a String.
dateTime
This property is a String.
Objects that implement the HTMLAnchorElement interface:
Objects that implement the HTMLAnchorElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLAnchorElement interface:
accessKey
This property is a String.
charset
This property is a String.
coords
This property is a String.
href
This property is a String.
hreflang
This property is a String.
name
This property is a String.
rel
This property is a String.
rev
This property is a String.
shape
This property is a String.
tabIndex
This property is a Number.
target
This property is a String.
type
This property is a String.
Functions of objects that implement the HTMLAnchorElement interface:
blur()
This function has no return value.
focus()
This function has no return value.
Objects that implement the HTMLImageElement interface:
Objects that implement the HTMLImageElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLImageElement interface:
name
This property is a String.
align
This property is a String.
alt
This property is a String.
border
This property is a String.
height
This property is a Number.
hspace
This property is a Number.
isMap
This property is a Boolean.
longDesc
This property is a String.
src
This property is a String.
useMap
This property is a String.
vspace
This property is a Number.
width
This property is a Number.
Objects that implement the HTMLObjectElement interface:
Objects that implement the HTMLObjectElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLObjectElement interface:
form
This read-only property is an object that implements the HTMLFormElement interface.
code
This property is a String.
align
This property is a String.
archive
This property is a String.
border
This property is a String.
codeBase
This property is a String.
codeType
This property is a String.
data
This property is a String.
declare
This property is a Boolean.
height
This property is a String.
hspace
This property is a Number.
name
This property is a String.
standby
This property is a String.
tabIndex
This property is a Number.
type
This property is a String.
useMap
This property is a String.
vspace
This property is a Number.
width
This property is a String.
contentDocument
This read-only property is an object that implements the Document interface.
Objects that implement the HTMLParamElement interface:
Objects that implement the HTMLParamElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLParamElement interface:
name
This property is a String.
type
This property is a String.
value
This property is a String.
valueType
This property is a String.
Objects that implement the HTMLAppletElement interface:
Objects that implement the HTMLAppletElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLAppletElement interface:
align
This property is a String.
alt
This property is a String.
archive
This property is a String.
code
This property is a String.
codeBase
This property is a String.
height
This property is a String.
hspace
This property is a Number.
name
This property is a String.
object
This property is a String.
vspace
This property is a Number.
width
This property is a String.
Objects that implement the HTMLMapElement interface:
Objects that implement the HTMLMapElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLMapElement interface:
areas
This read-only property is an object that implements the HTMLCollection interface.
name
This property is a String.
Objects that implement the HTMLAreaElement interface:
Objects that implement the HTMLAreaElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLAreaElement interface:
accessKey
This property is a String.
alt
This property is a String.
coords
This property is a String.
href
This property is a String.
noHref
This property is a Boolean.
shape
This property is a String.
tabIndex
This property is a Number.
target
This property is a String.
Objects that implement the HTMLScriptElement interface:
Objects that implement the HTMLScriptElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLScriptElement interface:
text
This property is a String.
htmlFor
This property is a String.
event
This property is a String.
charset
This property is a String.
defer
This property is a Boolean.
src
This property is a String.
type
This property is a String.
Objects that implement the HTMLTableElement interface:
Objects that implement the HTMLTableElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableElement interface:
caption
This property is an object that implements the HTMLTableCaptionElement interface and can raise an object that implements DOMException interface on setting.
tHead
This property is an object that implements the HTMLTableSectionElement interface and can raise an object that implements DOMException interface on setting.
tFoot
This property is an object that implements the HTMLTableSectionElement interface and can raise an object that implements DOMException interface on setting.
rows
This read-only property is an object that implements the HTMLCollection interface.
tBodies
This read-only property is an object that implements the HTMLCollection interface.
align
This property is a String.
bgColor
This property is a String.
border
This property is a String.
cellPadding
This property is a String.
cellSpacing
This property is a String.
frame
This property is a String.
rules
This property is a String.
summary
This property is a String.
width
This property is a String.
Functions of objects that implement the HTMLTableElement interface:
createTHead()
This function returns an object that implements the HTMLElement interface.
deleteTHead()
This function has no return value.
createTFoot()
This function returns an object that implements the HTMLElement interface.
deleteTFoot()
This function has no return value.
createCaption()
This function returns an object that implements the HTMLElement interface.
deleteCaption()
This function has no return value.
insertRow(index)
This function returns an object that implements the HTMLElement interface.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
deleteRow(index)
This function has no return value.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
Objects that implement the HTMLTableCaptionElement interface:
Objects that implement the HTMLTableCaptionElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableCaptionElement interface:
align
This property is a String.
Objects that implement the HTMLTableColElement interface:
Objects that implement the HTMLTableColElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableColElement interface:
align
This property is a String.
ch
This property is a String.
chOff
This property is a String.
span
This property is a Number.
vAlign
This property is a String.
width
This property is a String.
Objects that implement the HTMLTableSectionElement interface:
Objects that implement the HTMLTableSectionElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableSectionElement interface:
align
This property is a String.
ch
This property is a String.
chOff
This property is a String.
vAlign
This property is a String.
rows
This read-only property is an object that implements the HTMLCollection interface.
Functions of objects that implement the HTMLTableSectionElement interface:
insertRow(index)
This function returns an object that implements the HTMLElement interface.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
deleteRow(index)
This function has no return value.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
Objects that implement the HTMLTableRowElement interface:
Objects that implement the HTMLTableRowElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableRowElement interface:
rowIndex
This read-only property is a Number.
sectionRowIndex
This read-only property is a Number.
cells
This read-only property is an object that implements the HTMLCollection interface.
align
This property is a String.
bgColor
This property is a String.
ch
This property is a String.
chOff
This property is a String.
vAlign
This property is a String.
Functions of objects that implement the HTMLTableRowElement interface:
insertCell(index)
This function returns an object that implements the HTMLElement interface.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
deleteCell(index)
This function has no return value.
The index parameter is a Number.
This function can raise an object that implements the DOMException interface.
Objects that implement the HTMLTableCellElement interface:
Objects that implement the HTMLTableCellElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLTableCellElement interface:
cellIndex
This read-only property is a Number.
abbr
This property is a String.
align
This property is a String.
axis
This property is a String.
bgColor
This property is a String.
ch
This property is a String.
chOff
This property is a String.
colSpan
This property is a Number.
headers
This property is a String.
height
This property is a String.
noWrap
This property is a Boolean.
rowSpan
This property is a Number.
scope
This property is a String.
vAlign
This property is a String.
width
This property is a String.
Objects that implement the HTMLFrameSetElement interface:
Objects that implement the HTMLFrameSetElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLFrameSetElement interface:
cols
This property is a String.
rows
This property is a String.
Objects that implement the HTMLFrameElement interface:
Objects that implement the HTMLFrameElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLFrameElement interface:
frameBorder
This property is a String.
longDesc
This property is a String.
marginHeight
This property is a String.
marginWidth
This property is a String.
name
This property is a String.
noResize
This property is a Boolean.
scrolling
This property is a String.
src
This property is a String.
contentDocument
This read-only property is an object that implements the Document interface.
Objects that implement the HTMLIFrameElement interface:
Objects that implement the HTMLIFrameElement interface have all properties and functions of the HTMLElement interface as well as the properties and functions defined below.
Properties of objects that implement the HTMLIFrameElement interface:
align
This property is a String.
frameBorder
This property is a String.
height
This property is a String.
longDesc
This property is a String.
marginHeight
This property is a String.
marginWidth
This property is a String.
name
This property is a String.
scrolling
This property is a String.
src
This property is a String.
width
This property is a String.
contentDocument
This read-only property is an object that implements the Document interface.

HTMLAnchorElement objects in String expressions are evaluated as HTMLAnchorElement.href. For example:

     alert(" The absolute URI is " + myAnchorElement);

is equivalent to

     alert(" The absolute URI is " + myAnchorElement.href);
previous next contents index


Acknowledgements

previous next contents index

09 January 2003

Appendix E: Acknowledgements

Many people contributed to this specification, including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andy Heninger (IBM), Arnaud Le Hors (W3C and IBM), Bill Smith (Sun), Bill Shea (Merrill Lynch), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), Glenn Adams (ATSC), James Davidson (Sun), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, Netscape and Chair), Rich Rollman (Microsoft), Rick Gessner (Netscape), Tom Pixley (Netscape), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections.

The W3C tried to produce the most useful and accurate specification as possible but we wouldn't have been able to do so without the help of the DOM Test Suite effort. Special thanks to Curt Arnold, Rick Rivello (NIST), Robert Clary (Netscape) and Dimitris Dimitriadis for the DOM Level 2 HTML Test Suite. The DOM Test Suite is based on the test suite developed by Mary Brady (NIST).

E.1: Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

This document was generated using DOM Level 2. We used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

E.2: DOM Level 1

The authors of the DOM Level 1 specification, members of the DOM Working Group, deserve much credit for their hard work:

Lauren Wood (SoftQuad, Inc., chair), Arnaud Le Hors (W3C, W3C staff contact), Andrew Watson (Object Management Group), Bill Smith (Sun), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Singer (IBM), Don Park (invited), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), Jared Sorensen (Novell), Jonathan Robie (Texcel Research and Software AG), Mike Champion (ArborText and Software AG), Paul Grosso (ArborText), Peter Sharpe (SoftQuad, Inc.), Phil Karlton (Netscape), Ray Whitmer (iMall), Rich Rollman (Microsoft), Rick Gessner (Netscape), Robert Sutor (IBM), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tom Pixley (Netscape), Vidur Apparao (Netscape).

Thanks to Joe English, author of cost for helping so much in allowing us to develop a framework that made the production of this specification possible.

Thanks to Jan Kärrman, author of html2ps for helping so much in creating the Postscript version of the specification.

The editors of the first version of the DOM HTML module were Mike Champion (ArborText), Vidur Apparao (Netscape), Scott Isaacs (Microsoft, January 1998), Chris Wilson (Microsoft, after January 1998), and Ian Jacobs (W3C).

previous next contents index


Glossary

Editors:
Arnaud Le Hors, IBM
Lauren Wood, SoftQuad Software Inc.
Robert S. Sutor, IBM (for DOM Level 1)

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

convenience
A convenience method is an operation on an object that could be accomplished by a program consisting of more basic operations on the object. Convenience methods are usually provided to make the API easier and simpler to use or to allow specific programs to create more optimized implementations for common operations. A similar definition holds for a convenience property.
data model
A data model is a collection of descriptions of data structures and their contained fields, together with the operations or functions that manipulate them.
DOM Level 0
The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".
HTML
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents with generic semantics that are appropriate for representing information from a wide range of applications. [HTML 4.01]
language binding
A programming language binding for an IDL specification is an implementation of the interfaces in the specification for the given language. For example, a Java language binding for the Document Object Model IDL specification would implement the concrete Java classes that provide the functionality exposed by the interfaces.
live
An object is live if any change to the underlying document structure is reflected in the object.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

G.1: Normative references

[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[DOM Level 2 Style Sheets and CSS]
Document Object Model Level 2 Style Sheets and CSS Specification, C. Wilson, P. Le Hégaret, V. Apparao, Editors. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Style Sheets and CSS Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113. The latest version of Document Object Model Level 2 Style Sheets and CSS is available at http://www.w3.org/TR/DOM-Level-2-Style.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, December 1999. This version of the ECMAScript Language is available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM.
[HTML 4.01]
HTML 4.01 Specification, D. Raggett, A. Le Hors, and I. Jacobs, Editors. World Wide Web Consortium, 17 December 1997, revised 24 April 1998, revised 24 December 1999. This version of the HTML 4.01 Recommendation is http://www.w3.org/TR/1999/REC-html401-19991224. The latest version of HTML 4 is available at http://www.w3.org/TR/html4.
[IETF RFC 2396]
Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, Authors. Internet Engineering Task Force, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt.
[IETF RFC 2965]
HTTP State Management Mechanism, D. Kristol and L. Montulli, Editors. Internet Engineering Task Force, October 2000. Available at http://www.ietf.org/rfc/rfc2965.txt.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[XHTML 1.0]
XHTML 1.0: The Extensible HyperText Markup Language, S. Pemberton, et al., Authors. World Wide Web Consortium, 26 January 2000, revised 1 August 2002. This version of the XHTML 1.0 Recommendation is http://www.w3.org/TR/2002/REC-xhtml1-20020801. The latest version of XHTML 1.0 is available at http://www.w3.org/TR/xhtml1.

G.2: Informative references

[DOM Level 1]
DOM Level 1 Specification, V. Apparao, et al., Editors. World Wide Web Consortium, 1 October 1998. This version of the DOM Level 1 Recommendation is http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001. The latest version of DOM Level 1 is available at http://www.w3.org/TR/REC-DOM-Level-1.
[DOM Level 3 Load and Save]
Document Object Model Level 3 Load and Save Specification, J. Stenback, A. Heninger, Editors. World Wide Web Consortium, July 2002. This version of the DOM Level 3 Load and Save Specification is http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725. The latest version of DOM Level 3 Load and Save is available at http://www.w3.org/TR/DOM-Level-3-LS.
[DOM Level 2 Style Sheets and CSS]
Document Object Model Level 2 Style Sheets and CSS Specification, C. Wilson, P. Le Hégaret, V. Apparao, Editors. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Style Sheets and CSS Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113. The latest version of Document Object Model Level 2 Style Sheets and CSS is available at http://www.w3.org/TR/DOM-Level-2-Style.
[DOM Level 2 Traversal]
"Document Object Model Traversal" in Document Object Model Level 2 Traversal and Range Specification, J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood, Editors. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Traversal and Range Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113. The latest version of Document Object Model Level 2 Traversal and Range is available at http://www.w3.org/TR/DOM-Level-2-Traversal-Range.
[IETF RFC 2616]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, Authors. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt.
previous next contents index


Index

abbr | accept | acceptCharset
accessKey 1, 2, 3, 4, 5, 6, 7 | action | add
align 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 | aLink | alt 1, 2, 3, 4
anchors | applets | archive 1, 2
areas | axis
background | bgColor 1, 2, 3, 4 | blur 1, 2, 3, 4
body | border 1, 2, 3
caption | cellIndex | cellPadding
cells | cellSpacing | ch 1, 2, 3, 4
charset 1, 2, 3 | checked | chOff 1, 2, 3, 4
cite 1, 2 | className | clear
click | close | code 1, 2
codeBase 1, 2 | codeType | color 1, 2
cols 1, 2 | colSpan | compact 1, 2, 3, 4, 5
content | contentDocument 1, 2, 3 | convenience 1, 2, 3
cookie | coords 1, 2 | createCaption
createTFoot | createTHead
data | data model 1, 2 | dateTime
declare | defaultChecked | defaultSelected
defaultValue 1, 2 | defer | deleteCaption
deleteCell | deleteRow 1, 2 | deleteTFoot
deleteTHead | dir | disabled 1, 2, 3, 4, 5, 6, 7, 8
DOM Level 0 1, 2, 3, 4 | DOM Level 1 1, 2, 3, 4, 5, 6, 7 | DOM Level 2 Core 1, 2
DOM Level 2 Style Sheets and CSS 1, 2, 3, 4, 5 | DOM Level 2 Traversal 1, 2 | DOM Level 3 Load and Save 1, 2
domain
ECMAScript | elements | enctype
event
face 1, 2 | focus 1, 2, 3, 4 | form 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
forms | frame | frameBorder 1, 2
getElementsByName
headers | height 1, 2, 3, 4, 5 | href 1, 2, 3, 4
hreflang 1, 2 | hspace 1, 2, 3 | HTML 1, 2
HTML 4.01 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 | HTMLAnchorElement | HTMLAppletElement
HTMLAreaElement | HTMLBaseElement | HTMLBaseFontElement
HTMLBodyElement | HTMLBRElement | HTMLButtonElement
HTMLCollection | HTMLDirectoryElement | HTMLDivElement
HTMLDListElement | HTMLDocument | HTMLElement
HTMLFieldSetElement | HTMLFontElement | htmlFor 1, 2
HTMLFormElement | HTMLFrameElement | HTMLFrameSetElement
HTMLHeadElement | HTMLHeadingElement | HTMLHRElement
HTMLHtmlElement | HTMLIFrameElement | HTMLImageElement
HTMLInputElement | HTMLIsIndexElement | HTMLLabelElement
HTMLLegendElement | HTMLLIElement | HTMLLinkElement
HTMLMapElement | HTMLMenuElement | HTMLMetaElement
HTMLModElement | HTMLObjectElement | HTMLOListElement
HTMLOptGroupElement | HTMLOptionElement | HTMLOptionsCollection
HTMLParagraphElement | HTMLParamElement | HTMLPreElement
HTMLQuoteElement | HTMLScriptElement | HTMLSelectElement
HTMLStyleElement | HTMLTableCaptionElement | HTMLTableCellElement
HTMLTableColElement | HTMLTableElement | HTMLTableRowElement
HTMLTableSectionElement | HTMLTextAreaElement | HTMLTitleElement
HTMLUListElement | httpEquiv
id | IETF RFC 2396 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 | IETF RFC 2616 1, 2, 3
IETF RFC 2965 1, 2 | images | index
insertCell | insertRow 1, 2 | isMap
item 1, 2
Java
label 1, 2 | lang | language binding 1, 2
length 1, 2, 3, 4 | link | links
live 1, 2, 3 | longDesc 1, 2, 3
marginHeight 1, 2 | marginWidth 1, 2 | maxLength
media 1, 2 | method | multiple
name 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 | namedItem 1, 2 | noHref
noResize | noShade | noWrap
object | OMG IDL | open
options
profile | prompt
readOnly 1, 2 | referrer | rel 1, 2
remove | reset | rev 1, 2
rowIndex | rows 1, 2, 3, 4 | rowSpan
rules
scheme | scope | scrolling 1, 2
sectionRowIndex | select 1, 2 | selected
selectedIndex | shape 1, 2 | size 1, 2, 3, 4, 5
span | src 1, 2, 3, 4, 5 | standby
start | submit | summary
tabIndex 1, 2, 3, 4, 5, 6, 7 | target 1, 2, 3, 4, 5 | tBodies
text 1, 2, 3, 4 | tFoot | tHead
title 1, 2 | tokenized | type 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13
URL | useMap 1, 2, 3
vAlign 1, 2, 3, 4 | value 1, 2, 3, 4, 5, 6, 7 | valueType
version | vLink | vspace 1, 2, 3
width 1, 2, 3, 4, 5, 6, 7, 8, 9 | write | writeln
XHTML 1.0 1, 2, 3, 4, 5, 6, 7
previous contents


Document Object Model (DOM) Level 3 Core Specification

Version 1.0

W3C Recommendation 07 April 2004

This version:
http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407
Latest version:
http://www.w3.org/TR/DOM-Level-3-Core
Previous version:
http://www.w3.org/TR/2004/PR-DOM-Level-3-Core-20040205/
Editors:
Arnaud Le Hors, IBM
Philippe Le Hégaret, W3C
Lauren Wood, SoftQuad, Inc. (WG Chair emerita, for DOM Level 1 and 2)
Gavin Nicol, Inso EPS (for DOM Level 1)
Jonathan Robie, Texcel Research and Software AG (for DOM Level 1 and 2)
Mike Champion, Arbortext and Software AG (for DOM Level 1 and 2)
Steve Byrne, JavaSoft (for DOM Level 1 until November 19, 1997)

Please refer to the errata for this document, which may include some normative corrections.

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

See also translations of this document.

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

Abstract

This specification defines the Document Object Model Core Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model Core Level 3 builds on the Document Object Model Core Level 2 [DOM Level 2 Core].

This version enhances DOM Level 2 Core by completing the mapping between DOM and the XML Information Set [XML Information Set], including the support for XML Base [XML Base], adding the ability to attach user information to DOM Nodes or to bootstrap a DOM implementation, providing mechanisms to resolve namespace prefixes or to manipulate "ID" attributes, giving to type information, etc.

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 contains the Document Object Model Level 3 Core specification and is a W3C Recommendation. It has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group participants. For more information about DOM, readers can also refer to DOM FAQ and DOM Conformance Test Suites.

It is based on the feedback received during the Proposed Recommendation period. Changes since the Proposed Recommendation version and an implementation report are available. Please refer to the errata for this document, which may include some normative corrections.

Comments on this document should be sent to the public mailing list www-dom@w3.org (public archive).

This is a stable document and has been endorsed by the W3C Membership and the participants of the DOM working group. The English version of this specification is the only normative version. See also translations.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page. This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • What is the Document Object Model?
  • 1. Document Object Model Core
  • Appendix A: Changes
  • Appendix B: Namespaces Algorithms
  • Appendix C: Infoset Mapping
  • Appendix D: Configuration Settings
  • Appendix E: Accessing code point boundaries
  • Appendix F: IDL Definitions
  • Appendix G: Java Language Binding
  • Appendix H: ECMAScript Language Binding
  • Appendix I: Acknowledgements
  • Glossary
  • References
  • Index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • What is the Document Object Model?
    • Introduction
    • What the Document Object Model is
    • What the Document Object Model is not
    • Where the Document Object Model came from
    • Entities and the DOM Core
    • DOM Architecture
    • Conformance
    • DOM Interfaces and DOM Implementations
  • 1 Document Object Model Core
    • 1.1 Overview of the DOM Core Interfaces
      • 1.1.1 The DOM Structure Model
      • 1.1.2 Memory Management
      • 1.1.3 Naming Conventions
      • 1.1.4 Inheritance vs. Flattened Views of the API
    • 1.2 Basic Types
      • 1.2.1 The DOMString Type
      • 1.2.2 The DOMTimeStamp Type
      • 1.2.3 The DOMUserData Type
      • 1.2.4 The DOMObject Type
    • 1.3 General Considerations
      • 1.3.1 String Comparisons in the DOM
      • 1.3.2 DOM URIs
      • 1.3.3 XML Namespaces
      • 1.3.4 Base URIs
      • 1.3.5 Mixed DOM Implementations
      • 1.3.6 DOM Features
      • 1.3.7 Bootstrapping
    • 1.4 Fundamental Interfaces: Core Module
    • 1.5 Extended Interfaces: XML Module
  • Appendix A: Changes
    • A.1 New sections
    • A.2 Changes to DOM Level 2 Core interfaces and exceptions
    • A.3 New DOM features
    • A.4 New types
    • A.5 New interfaces
    • A.6 Objects
  • Appendix B: Namespaces Algorithms
    • B.1 Namespace Normalization
      • B.1.1 Scope of a Binding
      • B.1.2 Conflicting Namespace Declaration
    • B.2 Namespace Prefix Lookup
    • B.3 Default Namespace Lookup
    • B.4 Namespace URI Lookup
  • Appendix C: Infoset Mapping
    • C.1 Document Node Mapping
      • C.1.1 Infoset to Document Node
      • C.1.2 Document Node to Infoset
    • C.2 Element Node Mapping
      • C.2.1 Infoset to Element Node
      • C.2.2 Element Node to Infoset
    • C.3 Attr Node Mapping
      • C.3.1 Infoset to Attr Node
      • C.3.2 Attr Node to Infoset
    • C.4 ProcessingInstruction Node Mapping
      • C.4.1 Infoset to ProcessingInstruction Node
      • C.4.2 ProcessingInstruction Node to Infoset
    • C.5 EntityReference Node Mapping
      • C.5.1 Infoset to EntityReference Node
      • C.5.2 EntityReference Node to Infoset
    • C.6 Text and CDATASection Nodes Mapping
      • C.6.1 Infoset to Text Node
      • C.6.2 Text and CDATASection Nodes to Infoset
    • C.7 Comment Node Mapping
      • C.7.1 Infoset to Comment Node
      • C.7.2 Comment Node to Infoset
    • C.8 DocumentType Node Mapping
      • C.8.1 Infoset to DocumentType Node
      • C.8.2 DocumentType Node to Infoset
    • C.9 Entity Node Mapping
      • C.9.1 Infoset to Entity Node
      • C.9.2 Entity Node to Infoset
    • C.10 Notation Node Mapping
      • C.10.1 Infoset to Notation Node
      • C.10.2 Notation Node to Infoset
  • Appendix D: Configuration Settings
    • D.1 Configuration Scenarios
  • Appendix E: Accessing code point boundaries
    • E.1 Introduction
    • E.2 Methods
  • Appendix F: IDL Definitions
  • Appendix G: Java Language Binding
    • G.1 Java Binding Extension
    • G.2 Other Core interfaces
  • Appendix H: ECMAScript Language Binding
    • H.1 ECMAScript Binding Extension
    • H.2 Other Core interfaces
  • Appendix I: Acknowledgements
    • I.1 Production Systems
  • Glossary
  • References
    • 1 Normative References
    • 2 Informative References
  • Index


W3C Copyright Notices and Licenses

Copyright © 2004 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

This document is published under the W3C® Document Copyright Notice and License. The bindings within this document are published under the W3C® Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.

W3C® Document Copyright Notice and License

Note: This section is a copy of the W3C® Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231.

Copyright © 2004 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231

Public documents on the W3C site are provided by the copyright holders under the following license. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231"
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

W3C® Software Copyright Notice and License

Note: This section is a copy of the W3C® Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231

Copyright © 2004 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231

This work (and included software, documentation such as READMEs, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission to copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C® Short Software Notice should be included (hypertext is preferred, text is permitted) within the body of any redistributed or derivative code.
  3. Notice of any changes or modifications to the files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

W3C® Short Software Notice

Note: This section is a copy of the W3C® Short Software Notice and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-software-short-notice-20021231

Copyright © 2004 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

Copyright © [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This work is distributed under the W3C® Software License [1] in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

[1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231


What is the Document Object Model?

Editors:
Philippe Le Hégaret, W3C
Lauren Wood, SoftQuad Software Inc. (for DOM Level 2)
Jonathan Robie, Texcel (for DOM Level 1)

Introduction

The Document Object Model (DOM) is an application programming interface (API) for valid HTML and well-formed XML documents. It defines the logical structure of documents and the way a document is accessed and manipulated. In the DOM specification, the term "document" is used in the broad sense - increasingly, XML is being used as a way of representing many different kinds of information that may be stored in diverse systems, and much of this would traditionally be seen as data rather than as documents. Nevertheless, XML presents this data as documents, and the DOM may be used to manage this data.

With the Document Object Model, programmers can build documents, navigate their structure, and add, modify, or delete elements and content. Anything found in an HTML or XML document can be accessed, changed, deleted, or added using the Document Object Model, with a few exceptions - in particular, the DOM interfaces for the XML internal and external subsets have not yet been specified.

As a W3C specification, one important objective for the Document Object Model is to provide a standard programming interface that can be used in a wide variety of environments and applications. The DOM is designed to be used with any programming language. In order to provide a precise, language-independent specification of the DOM interfaces, we have chosen to define the specifications in Object Management Group (OMG) IDL [OMG IDL], as defined in the CORBA 2.3.1 specification [CORBA]. In addition to the OMG IDL specification, we provide language bindings for Java [Java] and ECMAScript [ECMAScript] (an industry-standard scripting language based on JavaScript [JavaScript] and JScript [JScript]). Because of language binding restrictions, a mapping has to be applied between the OMG IDL and the programming language in used. For example, while the DOM uses IDL attributes in the definition of interfaces, Java does not allow interfaces to contain attributes:

// example 1: removing the first child of an element using ECMAScript
mySecondTrElement.removeChild(mySecondTrElement.firstChild);

// example 2: removing the first child of an element using Java
mySecondTrElement.removeChild(mySecondTrElement.getFirstChild());

Note: OMG IDL is used only as a language-independent and implementation-neutral way to specify interfaces. Various other IDLs could have been used ([COM], [Java IDL], [MIDL], ...). In general, IDLs are designed for specific computing environments. The Document Object Model can be implemented in any computing environment, and does not require the object binding runtimes generally associated with such IDLs.

What the Document Object Model is

The DOM is a programming API for documents. It is based on an object structure that closely resembles the structure of the documents it models. For instance, consider this table, taken from an XHTML document:

<table>
  <tbody>
    <tr>
      <td>Shady Grove</td>
      <td>Aeolian</td>
    </tr>
    <tr>
      <td>Over the River, Charlie</td>
      <td>Dorian</td>
    </tr>
  </tbody>
</table>

A graphical representation of the DOM of the example table, with whitespaces in element content (often abusively called "ignorable whitespace") removed, is:

graphical representation of the DOM of the example table

Figure: graphical representation of the DOM of the example table [SVG 1.0 version]

An example of DOM manipulation using ECMAScript would be:

// access the tbody element from the table element
var myTbodyElement = myTableElement.firstChild;

// access its second tr element
// The list of children starts at 0 (and not 1).
var mySecondTrElement = myTbodyElement.childNodes[1];

// remove its first td element
mySecondTrElement.removeChild(mySecondTrElement.firstChild);

// change the text content of the remaining td element
mySecondTrElement.firstChild.firstChild.data = "Peter";

In the DOM, documents have a logical structure which is very much like a tree; to be more precise, which is like a "forest" or "grove", which can contain more than one tree. Each document contains zero or one doctype nodes, one document element node, and zero or more comments or processing instructions; the document element serves as the root of the element tree for the document. However, the DOM does not specify that documents must be implemented as a tree or a grove, nor does it specify how the relationships among objects be implemented. The DOM is a logical model that may be implemented in any convenient manner. In this specification, we use the term structure model to describe the tree-like representation of a document. We also use the term "tree" when referring to the arrangement of those information items which can be reached by using "tree-walking" methods; (this does not include attributes). One important property of DOM structure models is structural isomorphism: if any two Document Object Model implementations are used to create a representation of the same document, they will create the same structure model, in accordance with the XML Information Set [XML Information Set].

Note: There may be some variations depending on the parser being used to build the DOM. For instance, the DOM may not contain white spaces in element content if the parser discards them.

The name "Document Object Model" was chosen because it is an "object model" in the traditional object oriented design sense: documents are modeled using objects, and the model encompasses not only the structure of a document, but also the behavior of a document and the objects of which it is composed. In other words, the nodes in the above diagram do not represent a data structure, they represent objects, which have functions and identity. As an object model, the DOM identifies:

  • the interfaces and objects used to represent and manipulate a document
  • the semantics of these interfaces and objects - including both behavior and attributes
  • the relationships and collaborations among these interfaces and objects

The structure of SGML documents has traditionally been represented by an abstract data model, not by an object model. In an abstract data model, the model is centered around the data. In object oriented programming languages, the data itself is encapsulated in objects that hide the data, protecting it from direct external manipulation. The functions associated with these objects determine how the objects may be manipulated, and they are part of the object model.

What the Document Object Model is not

This section is designed to give a more precise understanding of the DOM by distinguishing it from other systems that may seem to be like it.

  • The Document Object Model is not a binary specification. DOM programs written in the same language binding will be source code compatible across platforms, but the DOM does not define any form of binary interoperability.
  • The Document Object Model is not a way of persisting objects to XML or HTML. Instead of specifying how objects may be represented in XML, the DOM specifies how XML and HTML documents are represented as objects, so that they may be used in object oriented programs.
  • The Document Object Model is not a set of data structures; it is an object model that specifies interfaces. Although this document contains diagrams showing parent/child relationships, these are logical relationships defined by the programming interfaces, not representations of any particular internal data structures.
  • The Document Object Model does not define what information in a document is relevant or how information in a document is structured. For XML, this is specified by the XML Information Set [XML Information Set]. The DOM is simply an API to this information set.
  • The Document Object Model, despite its name, is not a competitor to the Component Object Model [COM]. COM, like CORBA, is a language independent way to specify interfaces and objects; the DOM is a set of interfaces and objects designed for managing HTML and XML documents. The DOM may be implemented using language-independent systems like COM or CORBA; it may also be implemented using language-specific bindings like the Java or ECMAScript bindings specified in this document.

Where the Document Object Model came from

The DOM originated as a specification to allow JavaScript scripts and Java programs to be portable among Web browsers. "Dynamic HTML" was the immediate ancestor of the Document Object Model, and it was originally thought of largely in terms of browsers. However, when the DOM Working Group was formed at W3C, it was also joined by vendors in other domains, including HTML or XML editors and document repositories. Several of these vendors had worked with SGML before XML was developed; as a result, the DOM has been influenced by SGML Groves and the HyTime standard. Some of these vendors had also developed their own object models for documents in order to provide an API for SGML/XML editors or document repositories, and these object models have also influenced the DOM.

Entities and the DOM Core

In the fundamental DOM interfaces, there are no objects representing entities. Numeric character references, and references to the pre-defined entities in HTML and XML, are replaced by the single character that makes up the entity's replacement. For example, in:

        <p>This is a dog &amp; a cat</p>

the "&amp;" will be replaced by the character "&", and the text in the P element will form a single continuous sequence of characters. Since numeric character references and pre-defined entities are not recognized as such in CDATA sections, or in the SCRIPT and STYLE elements in HTML, they are not replaced by the single character they appear to refer to. If the example above were enclosed in a CDATA section, the "&amp;" would not be replaced by "&"; neither would the <p> be recognized as a start tag. The representation of general entities, both internal and external, are defined within the extended (XML) interfaces of Document Object Model Core.

Note: When a DOM representation of a document is serialized as XML or HTML text, applications will need to check each character in text data to see if it needs to be escaped using a numeric or pre-defined entity. Failing to do so could result in invalid HTML or XML. Also, implementations should be aware of the fact that serialization into a character encoding ("charset") that does not fully cover ISO 10646 may fail if there are characters in markup or CDATA sections that are not present in the encoding.

DOM Architecture

The DOM specifications provide a set of APIs that forms the DOM API. Each DOM specification defines one or more modules and each module is associated with one feature name. For example, the DOM Core specification (this specification) defines two modules:

  • The Core module, which contains the fundamental interfaces that must be implemented by all DOM conformant implementations, is associated with the feature name "Core";
  • The XML module, which contains the interfaces that must be implemented by all conformant XML 1.0 [XML 1.0] (and higher) DOM implementations, is associated with the feature name "XML".

The following representation contains all DOM modules, represented using their feature names, defined along the DOM specifications:

A view of the DOM Architecture

Figure: A view of the DOM Architecture [SVG 1.0 version]

A DOM implementation can then implement one (i.e. only the Core module) or more modules depending on the host application. A Web user agent is very likely to implement the "MouseEvents" module, while a server-side application will have no use of this module and will probably not implement it.

Conformance

This section explains the different levels of conformance to DOM Level 3. DOM Level 3 consists of 16 modules. It is possible to conform to DOM Level 3, or to a DOM Level 3 module.

An implementation is DOM Level 3 conformant if it supports the Core module defined in this document (see Fundamental Interfaces: Core Module). An implementation conforms to a DOM Level 3 module if it supports all the interfaces for that module and the associated semantics.

Here is the complete list of DOM Level 3.0 modules and the features used by them. Feature names are case-insensitive.

Core module
defines the feature "Core".
XML module
Defines the feature "XML".
Events module
defines the feature "Events" in [DOM Level 3 Events].
User interface Events module
defines the feature "UIEvents" in [DOM Level 3 Events].
Mouse Events module
defines the feature "MouseEvents" in [DOM Level 3 Events].
Text Events module
defines the feature "TextEvents" in [DOM Level 3 Events].
Keyboard Events module
defines the feature "KeyboardEvents" in [DOM Level 3 Events].
Mutation Events module
defines the feature "MutationEvents" in [DOM Level 3 Events].
Mutation name Events module
defines the feature "MutationNameEvents" in [DOM Level 3 Events].
HTML Events module
defines the feature "HTMLEvents" in [DOM Level 3 Events].
Load and Save module
defines the feature "LS" in [DOM Level 3 Load and Save].
Asynchronous load module
defines the feature "LS-Async" in [DOM Level 3 Load and Save].
Validation module
defines the feature "Validation" in [DOM Level 3 Validation].
XPath module
defines the feature "XPath" in [DOM Level 3 XPath].

A DOM implementation must not return true to the DOMImplementation.hasFeature(feature, version) method of the DOMImplementation interface for that feature unless the implementation conforms to that module. The version number for all features used in DOM Level 3.0 is "3.0".

DOM Interfaces and DOM Implementations

The DOM specifies interfaces which may be used to manage XML or HTML documents. It is important to realize that these interfaces are an abstraction - much like "abstract base classes" in C++, they are a means of specifying a way to access and manipulate an application's internal representation of a document. Interfaces do not imply a particular concrete implementation. Each DOM application is free to maintain documents in any convenient representation, as long as the interfaces shown in this specification are supported. Some DOM implementations will be existing programs that use the DOM interfaces to access software written long before the DOM specification existed. Therefore, the DOM is designed to avoid implementation dependencies; in particular,

  1. Attributes defined in the IDL do not imply concrete objects which must have specific data members - in the language bindings, they are translated to a pair of get()/set() functions, not to a data member. Read-only attributes have only a get() function in the language bindings.
  2. DOM applications may provide additional interfaces and objects not found in this specification and still be considered DOM conformant.
  3. Because we specify interfaces and not the actual objects that are to be created, the DOM cannot know what constructors to call for an implementation. In general, DOM users call the createX() methods on the Document class to create document structures, and DOM implementations create their own internal representations of these structures in their implementations of the createX() functions.

The Level 2 interfaces were extended to provide both Level 2 and Level 3 functionality.

DOM implementations in languages other than Java or ECMAScript may choose bindings that are appropriate and natural for their language and run time environment. For example, some systems may need to create a Document3 class which inherits from a Document class and contains the new methods and attributes.

DOM Level 3 does not specify multithreading mechanisms.


Document Object Model Core

07 April 2004

1. Document Object Model Core

Editors:
Arnaud Le Hors, IBM
Philippe Le Hégaret, W3C
Gavin Nicol, Inso EPS (for DOM Level 1)
Lauren Wood, SoftQuad, Inc. (for DOM Level 1)
Mike Champion, Arbortext and Software AG (for DOM Level 1 from November 20, 1997)
Steve Byrne, JavaSoft (for DOM Level 1 until November 19, 1997)

Table of contents

  • 1.1 Overview of the DOM Core Interfaces
    • 1.1.1 The DOM Structure Model
    • 1.1.2 Memory Management
    • 1.1.3 Naming Conventions
    • 1.1.4 Inheritance vs. Flattened Views of the API
  • 1.2 Basic Types
    • 1.2.1 The DOMString Type
      • DOMString
    • 1.2.2 The DOMTimeStamp Type
      • DOMTimeStamp
    • 1.2.3 The DOMUserData Type
      • DOMUserData
    • 1.2.4 The DOMObject Type
      • DOMObject
  • 1.3 General Considerations
    • 1.3.1 String Comparisons in the DOM
    • 1.3.2 DOM URIs
    • 1.3.3 XML Namespaces
    • 1.3.4 Base URIs
    • 1.3.5 Mixed DOM Implementations
    • 1.3.6 DOM Features
    • 1.3.7 Bootstrapping
  • 1.4 Fundamental Interfaces: Core Module
    • DOMException, ExceptionCode, DOMStringList, NameList, DOMImplementationList, DOMImplementationSource, DOMImplementation, DocumentFragment, Document, Node, NodeList, NamedNodeMap, CharacterData, Attr, Element, Text, Comment, TypeInfo, UserDataHandler, DOMError, DOMErrorHandler, DOMLocator, DOMConfiguration
  • 1.5 Extended Interfaces: XML Module
    • CDATASection, DocumentType, Notation, Entity, EntityReference, ProcessingInstruction

This specification defines a set of objects and interfaces for accessing and manipulating document objects. The functionality specified (the Core functionality) is sufficient to allow software developers and Web script authors to access and manipulate parsed HTML [HTML 4.01] and XML [XML 1.0] content inside conforming products. The DOM Core API also allows creation and population of a Document object using only DOM API calls. A solution for loading a Document and saving it persistently is proposed in [DOM Level 3 Load and Save].

1.1 Overview of the DOM Core Interfaces

1.1.1 The DOM Structure Model

The DOM presents documents as a hierarchy of Node objects that also implement other, more specialized interfaces. Some types of nodes may have child nodes of various types, and others are leaf nodes that cannot have anything below them in the document structure. For XML and HTML, the node types, and which node types they may have as children, are as follows:

  • Document -- Element (maximum of one), ProcessingInstruction, Comment, DocumentType (maximum of one)
  • DocumentFragment -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • DocumentType -- no children
  • EntityReference -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Element -- Element, Text, Comment, ProcessingInstruction, CDATASection, EntityReference
  • Attr -- Text, EntityReference
  • ProcessingInstruction -- no children
  • Comment -- no children
  • Text -- no children
  • CDATASection -- no children
  • Entity -- Element, ProcessingInstruction, Comment, Text, CDATASection, EntityReference
  • Notation -- no children

The DOM also specifies a NodeList interface to handle ordered lists of Nodes, such as the children of a Node, or the elements returned by the Element.getElementsByTagNameNS(namespaceURI, localName) method, and also a NamedNodeMap interface to handle unordered sets of nodes referenced by their name attribute, such as the attributes of an Element. NodeList and NamedNodeMap objects in the DOM are live; that is, changes to the underlying document structure are reflected in all relevant NodeList and NamedNodeMap objects. For example, if a DOM user gets a NodeList object containing the children of an Element, then subsequently adds more children to that element (or removes children, or modifies them), those changes are automatically reflected in the NodeList, without further action on the user's part. Likewise, changes to a Node in the tree are reflected in all references to that Node in NodeList and NamedNodeMap objects.

Finally, the interfaces Text, Comment, and CDATASection all inherit from the CharacterData interface.

1.1.2 Memory Management

Most of the APIs defined by this specification are interfaces rather than classes. That means that an implementation need only expose methods with the defined names and specified operation, not implement classes that correspond directly to the interfaces. This allows the DOM APIs to be implemented as a thin veneer on top of legacy applications with their own data structures, or on top of newer applications with different class hierarchies. This also means that ordinary constructors (in the Java or C++ sense) cannot be used to create DOM objects, since the underlying objects to be constructed may have little relationship to the DOM interfaces. The conventional solution to this in object-oriented design is to define factory methods that create instances of objects that implement the various interfaces. Objects implementing some interface "X" are created by a "createX()" method on the Document interface; this is because all DOM objects live in the context of a specific Document.

The Core DOM APIs are designed to be compatible with a wide range of languages, including both general-user scripting languages and the more challenging languages used mostly by professional programmers. Thus, the DOM APIs need to operate across a variety of memory management philosophies, from language bindings that do not expose memory management to the user at all, through those (notably Java) that provide explicit constructors but provide an automatic garbage collection mechanism to automatically reclaim unused memory, to those (especially C/C++) that generally require the programmer to explicitly allocate object memory, track where it is used, and explicitly free it for re-use. To ensure a consistent API across these platforms, the DOM does not address memory management issues at all, but instead leaves these for the implementation. Neither of the explicit language bindings defined by the DOM API (for ECMAScript and Java) require any memory management methods, but DOM bindings for other languages (especially C or C++) may require such support. These extensions will be the responsibility of those adapting the DOM API to a specific language, not the DOM Working Group.

1.1.3 Naming Conventions

While it would be nice to have attribute and method names that are short, informative, internally consistent, and familiar to users of similar APIs, the names also should not clash with the names in legacy APIs supported by DOM implementations. Furthermore, both OMG IDL [OMG IDL] and ECMAScript [ECMAScript] have significant limitations in their ability to disambiguate names from different namespaces that make it difficult to avoid naming conflicts with short, familiar names. So, DOM names tend to be long and descriptive in order to be unique across all environments.

The Working Group has also attempted to be internally consistent in its use of various terms, even though these may not be common distinctions in other APIs. For example, the DOM API uses the method name "remove" when the method changes the structural model, and the method name "delete" when the method gets rid of something inside the structure model. The thing that is deleted is not returned. The thing that is removed may be returned, when it makes sense to return it.

1.1.4 Inheritance vs. Flattened Views of the API

The DOM Core APIs present two somewhat different sets of interfaces to an XML/HTML document: one presenting an "object oriented" approach with a hierarchy of inheritance, and a "simplified" view that allows all manipulation to be done via the Node interface without requiring casts (in Java and other C-like languages) or query interface calls in COM environments. These operations are fairly expensive in Java and COM, and the DOM may be used in performance-critical environments, so we allow significant functionality using just the Node interface. Because many other users will find the inheritance hierarchy easier to understand than the "everything is a Node" approach to the DOM, we also support the full higher-level interfaces for those who prefer a more object-oriented API.

In practice, this means that there is a certain amount of redundancy in the API. The Working Group considers the "inheritance" approach the primary view of the API, and the full set of functionality on Node to be "extra" functionality that users may employ, but that does not eliminate the need for methods on other interfaces that an object-oriented analysis would dictate. (Of course, when the O-O analysis yields an attribute or method that is identical to one on the Node interface, we don't specify a completely redundant one.) Thus, even though there is a generic Node.nodeName attribute on the Node interface, there is still a Element.tagName attribute on the Element interface; these two attributes must contain the same value, but the it is worthwhile to support both, given the different constituencies the DOM API must satisfy.

1.2 Basic Types

To ensure interoperability, this specification specifies the following basic types used in various DOM modules. Even though the DOM uses the basic types in the interfaces, bindings may use different types and normative bindings are only given for Java and ECMAScript in this specification.

1.2.1 The DOMString Type

The DOMString type is used to store [Unicode] characters as a sequence of 16-bit units using UTF-16 as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646].

Characters are fully normalized as defined in appendix B of [XML 1.1] if:

  • the parameter "normalize-characters" was set to true while loading the document or the document was certified as defined in [XML 1.1];
  • the parameter "normalize-characters" was set to true while using the method Document.normalizeDocument(), or while using the method Node.normalize();

Note that, with the exceptions of Document.normalizeDocument() and Node.normalize(), manipulating characters using DOM methods does not guarantee to preserve a fully-normalized text.

Type Definition DOMString

A DOMString is a sequence of 16-bit units.

IDL Definition
valuetype DOMString sequence<unsigned short>;

The UTF-16 encoding was chosen because of its widespread industry practice. Note that for both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS [ISO/IEC 10646]. A single numeric character reference in a source document may therefore in some cases correspond to two 16-bit units in a DOMString (a high surrogate and a low surrogate). For issues related to string comparisons, refer to String Comparisons in the DOM.

For Java and ECMAScript, DOMString is bound to the String type because both languages also use UTF-16 as their encoding.

Note: As of August 2000, the OMG IDL specification ([OMG IDL]) included a wstring type. However, that definition did not meet the interoperability criteria of the DOM API since it relied on negotiation to decide the width and encoding of a character.

1.2.2 The DOMTimeStamp Type

The DOMTimeStamp type is used to store an absolute or relative time.

Type Definition DOMTimeStamp

A DOMTimeStamp represents a number of milliseconds.

IDL Definition
typedef unsigned long long DOMTimeStamp;

For Java, DOMTimeStamp is bound to the long type. For ECMAScript, DOMTimeStamp is bound to the Date type because the range of the integer type is too small.

1.2.3 The DOMUserData Type

The DOMUserData type is used to store application data.

Type Definition DOMUserData

A DOMUserData represents a reference to application data.

IDL Definition
typedef any DOMUserData;

For Java, DOMUserData is bound to the Object type. For ECMAScript, DOMUserData is bound to any type.

1.2.4 The DOMObject Type

The DOMObject type is used to represent an object.

Type Definition DOMObject

A DOMObject represents an object reference.

IDL Definition
typedef Object DOMObject;

For Java and ECMAScript, DOMObject is bound to the Object type.

1.3 General Considerations

1.3.1 String Comparisons in the DOM

The DOM has many interfaces that imply string matching. For XML, string comparisons are case-sensitive and performed with a binary comparison of the 16-bit units of the DOMStrings. However, for case-insensitive markup languages, such as HTML 4.01 or earlier, these comparisons are case-insensitive where appropriate.

Note that HTML processors often perform specific case normalizations (canonicalization) of the markup before the DOM structures are built. This is typically using uppercase for element names and lowercase for attribute names. For this reason, applications should also compare element and attribute names returned by the DOM implementation in a case-insensitive manner.

The character normalization, i.e. transforming into their fully normalized form as as defined in [XML 1.1], is assumed to happen at serialization time. The DOM Level 3 Load and Save module [DOM Level 3 Load and Save] provides a serialization mechanism (see the DOMSerializer interface, section 2.3.1) and uses the DOMConfiguration parameters "normalize-characters" and "check-character-normalization" to assure that text is fully normalized [XML 1.1]. Other serialization mechanisms built on top of the DOM Level 3 Core also have to assure that text is fully normalized.

1.3.2 DOM URIs

The DOM specification relies on DOMString values as resource identifiers, such that the following conditions are met:

  1. An absolute identifier absolutely identifies a resource on the Web;
  2. Simple string equality establishes equality of absolute resource identifiers, and no other equivalence of resource identifiers is considered significant to the DOM specification;
  3. A relative identifier is easily detected and made absolute relative to an absolute identifier;
  4. Retrieval of content of a resource may be accomplished where required.

The term "absolute URI" refers to a complete resource identifier and the term "relative URI" refers to an incomplete resource identifier.

Within the DOM specifications, these identifiers are called URIs, "Uniform Resource Identifiers", but this is meant abstractly. The DOM implementation does not necessarily process its URIs according to the URI specification [IETF RFC 2396]. Generally the particular form of these identifiers must be ignored.

When is not possible to completely ignore the type of a DOM URI, either because a relative identifier must be made absolute or because content must be retrieved, the DOM implementation must at least support identifier types appropriate to the content being processed. [HTML 4.01], [XML 1.0], and associated namespace specification [XML Namespaces] rely on [IETF RFC 2396] to determine permissible characters and resolving relative URIs. Other specifications such as namespaces in XML 1.1 [XML Namespaces 1.1] may rely on alternative resource identifier types that may, for example, include non-ASCII characters, necessitating support for alternative resource identifier types where required by applicable specifications.

1.3.3 XML Namespaces

DOM Level 2 and 3 support XML namespaces [XML Namespaces] by augmenting several interfaces of the DOM Level 1 Core to allow creating and manipulating elements and attributes associated to a namespace. When [XML 1.1] is in use (see Document.xmlVersion), DOM Level 3 also supports [XML Namespaces 1.1].

As far as the DOM is concerned, special attributes used for declaring XML namespaces are still exposed and can be manipulated just like any other attribute. However, nodes are permanently bound to namespace URIs as they get created. Consequently, moving a node within a document, using the DOM, in no case results in a change of its namespace prefix or namespace URI. Similarly, creating a node with a namespace prefix and namespace URI, or changing the namespace prefix of a node, does not result in any addition, removal, or modification of any special attributes for declaring the appropriate XML namespaces. Namespace validation is not enforced; the DOM application is responsible. In particular, since the mapping between prefixes and namespace URIs is not enforced, in general, the resulting document cannot be serialized naively. For example, applications may have to declare every namespace in use when serializing a document.

In general, the DOM implementation (and higher) doesn't perform any URI normalization or canonicalization. The URIs given to the DOM are assumed to be valid (e.g., characters such as white spaces are properly escaped), and no lexical checking is performed. Absolute URI references are treated as strings and compared literally. How relative namespace URI references are treated is undefined. To ensure interoperability only absolute namespace URI references (i.e., URI references beginning with a scheme name and a colon) should be used. Applications should use the value null as the namespaceURI parameter for methods if they wish to have no namespace. In programming languages where empty strings can be differentiated from null, empty strings, when given as a namespace URI, are converted to null. This is true even though the DOM does no lexical checking of URIs.

Note: Element.setAttributeNS(null, ...) puts the attribute in the per-element-type partitions as defined in XML Namespace Partitions in [XML Namespaces].

Note: In the DOM, all namespace declaration attributes are by definition bound to the namespace URI: "http://www.w3.org/2000/xmlns/". These are the attributes whose namespace prefix or qualified name is "xmlns" as introduced in [XML Namespaces 1.1].

In a document with no namespaces, the child list of an EntityReference node is always the same as that of the corresponding Entity. This is not true in a document where an entity contains unbound namespace prefixes. In such a case, the descendants of the corresponding EntityReference nodes may be bound to different namespace URIs, depending on where the entity references are. Also, because, in the DOM, nodes always remain bound to the same namespace URI, moving such EntityReference nodes can lead to documents that cannot be serialized. This is also true when the DOM Level 1 method Document.createEntityReference(name) is used to create entity references that correspond to such entities, since the descendants of the returned EntityReference are unbound. While DOM Level 3 does have support for the resolution of namespace prefixes, use of such entities and entity references should be avoided or used with extreme care.

The "NS" methods, such as Document.createElementNS(namespaceURI, qualifiedName) and Document.createAttributeNS(namespaceURI, qualifiedName), are meant to be used by namespace aware applications. Simple applications that do not use namespaces can use the DOM Level 1 methods, such as Document.createElement(tagName) and Document.createAttribute(name). Elements and attributes created in this way do not have any namespace prefix, namespace URI, or local name.

Note: DOM Level 1 methods are namespace ignorant. Therefore, while it is safe to use these methods when not dealing with namespaces, using them and the new ones at the same time should be avoided. DOM Level 1 methods solely identify attribute nodes by their Node.nodeName. On the contrary, the DOM Level 2 methods related to namespaces, identify attribute nodes by their Node.namespaceURI and Node.localName. Because of this fundamental difference, mixing both sets of methods can lead to unpredictable results. In particular, using Element.setAttributeNS(namespaceURI, qualifiedName, value), an element may have two attributes (or more) that have the same Node.nodeName, but different Node.namespaceURIs. Calling Element.getAttribute(name) with that nodeName could then return any of those attributes. The result depends on the implementation. Similarly, using Element.setAttributeNode(newAttr), one can set two attributes (or more) that have different Node.nodeNames but the same Node.prefix and Node.namespaceURI. In this case Element.getAttributeNodeNS(namespaceURI, localName) will return either attribute, in an implementation dependent manner. The only guarantee in such cases is that all methods that access a named item by its nodeName will access the same item, and all methods which access a node by its URI and local name will access the same node. For instance, Element.setAttribute(name, value) and Element.setAttributeNS(namespaceURI, qualifiedName, value) affect the node that Element.getAttribute(name) and Element.getAttributeNS(namespaceURI, localName), respectively, return.

1.3.4 Base URIs

The DOM Level 3 adds support for the [base URI] property defined in [XML Information Set] by providing a new attribute on the Node interface that exposes this information. However, unlike the Node.namespaceURI attribute, the Node.baseURI attribute is not a static piece of information that every node carries. Instead, it is a value that is dynamically computed according to [XML Base]. This means its value depends on the location of the node in the tree and moving the node from one place to another in the tree may affect its value. Other changes, such as adding or changing an xml:base attribute on the node being queried or one of its ancestors may also affect its value.

One consequence of this it that when external entity references are expanded while building a Document one may need to add, or change, an xml:base attribute to the Element nodes originally contained in the entity being expanded so that the Node.baseURI returns the correct value. In the case of ProcessingInstruction nodes originally contained in the entity being expanded the information is lost. [DOM Level 3 Load and Save] handles elements as described here and generates a warning in the latter case.

1.3.5 Mixed DOM Implementations

As new XML vocabularies are developed, those defining the vocabularies are also beginning to define specialized APIs for manipulating XML instances of those vocabularies. This is usually done by extending the DOM to provide interfaces and methods that perform operations frequently needed by their users. For example, the MathML [MathML 2.0] and SVG [SVG 1.1] specifications have developed 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 XML semantics. Instances of SVG or MathML are often embedded in XML documents conforming to a different schema such as XHTML.

While the Namespaces in XML specification [XML Namespaces] provides a mechanism for integrating these documents at the syntax level, it has become clear that the DOM Level 2 Recommendation [DOM Level 2 Core] 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. DOM Level 3 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.

A DOM implementation supporting DOM Level 3 Core should be able to collaborate with subcomponents implementing specific DOMs to assemble a compound document that can be traversed and manipulated via DOM interfaces as if it were a seamless whole.

The normal typecast operation on an object should support the interfaces expected by legacy code for a given document type. Typecasting techniques may not be adequate for selecting between multiple DOM specializations of an object which were combined at run time, because they may not all be part of the same object as defined by the binding's object model. Conflicts are most obvious with the Document object, since it is shared as owner by the rest of the document. In a homogeneous document, elements rely on the Document for specialized services and construction of specialized nodes. In a heterogeneous document, elements from different modules expect different services and APIs from the same Document object, since there can only be one owner and root of the document hierarchy.

1.3.6 DOM Features

Each DOM module defines one or more features, as listed in the conformance section (Conformance). Features are case-insensitive and are also defined for a specific set of versions. For example, this specification defines the features "Core" and "XML", for the version "3.0". Versions "1.0" and "2.0" can also be used for features defined in the corresponding DOM Levels. To avoid possible conflicts, as a convention, names referring to features defined outside the DOM specification should be made unique. Applications could then request for features to be supported by a DOM implementation using the methods DOMImplementationSource.getDOMImplementation(features) or DOMImplementationSource.getDOMImplementationList(features), check the features supported by a DOM implementation using the method DOMImplementation.hasFeature(feature, version), or by a specific node using Node.isSupported(feature, version). Note that when using the methods that take a feature and a version as parameters, applications can use null or empty string for the version parameter if they don't wish to specify a particular version for the specified feature.

Up to the DOM Level 2 modules, all interfaces, that were an extension of existing ones, were accessible using binding-specific casting mechanisms if the feature associated to the extension was supported. For example, an instance of the EventTarget interface could be obtained from an instance of the Node interface if the feature "Events" was supported by the node.

As discussed Mixed DOM Implementations, DOM Level 3 Core should be able to collaborate with subcomponents implementing specific DOMs. For that effect, the methods DOMImplementation.getFeature(feature, version) and Node.getFeature(feature, version) were introduced. In the case of DOMImplementation.hasFeature(feature, version) and Node.isSupported(feature, version), if a plus sign "+" is prepended to any feature name, implementations are considered in which the specified feature may not be directly castable but would require discovery through DOMImplementation.getFeature(feature, version) and Node.getFeature(feature, version). Without a plus, only features whose interfaces are directly castable are considered.

// example 1, without prepending the "+"
if (myNode.isSupported("Events", "3.0")) {
    EventTarget evt = (EventTarget) myNode;
    // ...
}
// example 2, with the "+"
if (myNode.isSupported("+Events", "3.0")) {
    // (the plus sign "+" is irrelevant for the getFeature method itself
    // and is ignored by this method anyway)
    EventTarget evt = (EventTarget) myNode.getFeature("Events", "3.0");
    // ...
}

1.3.7 Bootstrapping

Because previous versions of the DOM specification only defined a set of interfaces, applications had to rely on some implementation dependent code to start from. However, hard-coding the application to a specific implementation prevents the application from running on other implementations and from using the most-suitable implementation of the environment. At the same time, implementations may also need to load modules or perform other setup to efficiently adapt to different and sometimes mutually-exclusive feature sets.

To solve these problems this specification introduces a DOMImplementationRegistry object with a function that lets an application find implementations, based on the specific features it requires. How this object is found and what it exactly looks like is not defined here, because this cannot be done in a language-independent manner. Instead, each language binding defines its own way of doing this. See Java Language Binding and ECMAScript Language Binding for specifics.

In all cases, though, the DOMImplementationRegistry provides a getDOMImplementation method accepting a features string, which is passed to every known DOMImplementationSource until a suitable DOMImplementation is found and returned. The DOMImplementationRegistry also provides a getDOMImplementationList method accepting a features string, which is passed to every known DOMImplementationSource, and returns a list of suitable DOMImplementations. Those two methods are the same as the ones found on the DOMImplementationSource interface.

Any number of DOMImplementationSource objects can be registered. A source may return one or more DOMImplementation singletons or construct new DOMImplementation objects, depending upon whether the requested features require specialized state in the DOMImplementation object.

1.4 Fundamental Interfaces: Core Module

The interfaces within this section are considered fundamental, and must be fully implemented by all conforming implementations of the DOM, including all HTML DOM implementations [DOM Level 2 HTML], unless otherwise specified.

A DOM application may use the DOMImplementation.hasFeature(feature, version) method with parameter values "Core" and "3.0" (respectively) to determine whether or not this module is supported by the implementation. Any implementation that conforms to DOM Level 3 or a DOM Level 3 module must conform to the Core module. Please refer to additional information about conformance in this specification. The DOM Level 3 Core module is backward compatible with the DOM Level 2 Core [DOM Level 2 Core] module, i.e. a DOM Level 3 Core implementation who returns true for "Core" with the version number "3.0" must also return true for this feature when the version number is "2.0", "" or, null.

Exception DOMException

DOM operations only raise exceptions in "exceptional" circumstances, i.e., when an operation is impossible to perform (either for logical reasons, because data is lost, or because the implementation has become unstable). In general, DOM methods return specific error values in ordinary processing situations, such as out-of-bound errors when using NodeList.

Implementations should raise other exceptions under other circumstances. For example, implementations should raise an implementation-dependent exception if a null argument is passed when null was not expected.

Some languages and object systems do not support the concept of exceptions. For such systems, error conditions may be indicated using native error reporting mechanisms. For some bindings, for example, methods may return error codes similar to those listed in the corresponding method descriptions.

IDL Definition
exception DOMException {
  unsigned short   code;
};
// ExceptionCode
const unsigned short      INDEX_SIZE_ERR                 = 1;
const unsigned short      DOMSTRING_SIZE_ERR             = 2;
const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
const unsigned short      WRONG_DOCUMENT_ERR             = 4;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
const unsigned short      NOT_FOUND_ERR                  = 8;
const unsigned short      NOT_SUPPORTED_ERR              = 9;
const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
// Introduced in DOM Level 2:
const unsigned short      INVALID_STATE_ERR              = 11;
// Introduced in DOM Level 2:
const unsigned short      SYNTAX_ERR                     = 12;
// Introduced in DOM Level 2:
const unsigned short      INVALID_MODIFICATION_ERR       = 13;
// Introduced in DOM Level 2:
const unsigned short      NAMESPACE_ERR                  = 14;
// Introduced in DOM Level 2:
const unsigned short      INVALID_ACCESS_ERR             = 15;
// Introduced in DOM Level 3:
const unsigned short      VALIDATION_ERR                 = 16;
// Introduced in DOM Level 3:
const unsigned short      TYPE_MISMATCH_ERR              = 17;

Definition group ExceptionCode

An integer indicating the type of error generated.

Note: Other numeric codes are reserved for W3C for possible future use.

Defined Constants
DOMSTRING_SIZE_ERR
If the specified range of text does not fit into a DOMString.
HIERARCHY_REQUEST_ERR
If any Node is inserted somewhere it doesn't belong.
INDEX_SIZE_ERR
If index or size is negative, or greater than the allowed value.
INUSE_ATTRIBUTE_ERR
If an attempt is made to add an attribute that is already in use elsewhere.
INVALID_ACCESS_ERR, introduced in DOM Level 2.
If a parameter or an operation is not supported by the underlying object.
INVALID_CHARACTER_ERR
If an invalid or illegal character is specified, such as in an XML name.
INVALID_MODIFICATION_ERR, introduced in DOM Level 2.
If an attempt is made to modify the type of the underlying object.
INVALID_STATE_ERR, introduced in DOM Level 2.
If an attempt is made to use an object that is not, or is no longer, usable.
NAMESPACE_ERR, introduced in DOM Level 2.
If an attempt is made to create or change an object in a way which is incorrect with regard to namespaces.
NOT_FOUND_ERR
If an attempt is made to reference a Node in a context where it does not exist.
NOT_SUPPORTED_ERR
If the implementation does not support the requested type of object or operation.
NO_DATA_ALLOWED_ERR
If data is specified for a Node which does not support data.
NO_MODIFICATION_ALLOWED_ERR
If an attempt is made to modify an object where modifications are not allowed.
SYNTAX_ERR, introduced in DOM Level 2.
If an invalid or illegal string is specified.
TYPE_MISMATCH_ERR, introduced in DOM Level 3.
If the type of an object is incompatible with the expected type of the parameter associated to the object.
VALIDATION_ERR, introduced in DOM Level 3.
If a call to a method such as insertBefore or removeChild would make the Node invalid with respect to "partial validity", this exception would be raised and the operation would not be done. This code is used in [DOM Level 3 Validation]. Refer to this specification for further information.
WRONG_DOCUMENT_ERR
If a Node is used in a different document than the one that created it (that doesn't support it).
Interface DOMStringList (introduced in DOM Level 3)

The DOMStringList interface provides the abstraction of an ordered collection of DOMString values, without defining or constraining how this collection is implemented. The items in the DOMStringList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 3:
interface DOMStringList {
  DOMString          item(in unsigned long index);
  readonly attribute unsigned long   length;
  boolean            contains(in DOMString str);
};

Attributes
length of type unsigned long, readonly
The number of DOMStrings in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
contains
Test if a string is part of this DOMStringList.
Parameters
str of type DOMString
The string to look for.
Return Value

boolean

true if the string has been found, false otherwise.

No Exceptions
item
Returns the indexth item in the collection. If index is greater than or equal to the number of DOMStrings in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

DOMString

The DOMString at the indexth position in the DOMStringList, or null if that is not a valid index.

No Exceptions
Interface NameList (introduced in DOM Level 3)

The NameList interface provides the abstraction of an ordered collection of parallel pairs of name and namespace values (which could be null values), without defining or constraining how this collection is implemented. The items in the NameList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 3:
interface NameList {
  DOMString          getName(in unsigned long index);
  DOMString          getNamespaceURI(in unsigned long index);
  readonly attribute unsigned long   length;
  boolean            contains(in DOMString str);
  boolean            containsNS(in DOMString namespaceURI,
                                in DOMString name);
};

Attributes
length of type unsigned long, readonly
The number of pairs (name and namespaceURI) in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
contains
Test if a name is part of this NameList.
Parameters
str of type DOMString
The name to look for.
Return Value

boolean

true if the name has been found, false otherwise.

No Exceptions
containsNS
Test if the pair namespaceURI/name is part of this NameList.
Parameters
namespaceURI of type DOMString
The namespace URI to look for.
name of type DOMString
The name to look for.
Return Value

boolean

true if the pair namespaceURI/name has been found, false otherwise.

No Exceptions
getName
Returns the indexth name item in the collection.
Parameters
index of type unsigned long
Index into the collection.
Return Value

DOMString

The name at the indexth position in the NameList, or null if there is no name for the specified index or if the index is out of range.

No Exceptions
getNamespaceURI
Returns the indexth namespaceURI item in the collection.
Parameters
index of type unsigned long
Index into the collection.
Return Value

DOMString

The namespace URI at the indexth position in the NameList, or null if there is no name for the specified index or if the index is out of range.

No Exceptions
Interface DOMImplementationList (introduced in DOM Level 3)

The DOMImplementationList interface provides the abstraction of an ordered collection of DOM implementations, without defining or constraining how this collection is implemented. The items in the DOMImplementationList are accessible via an integral index, starting from 0.

IDL Definition
// Introduced in DOM Level 3:
interface DOMImplementationList {
  DOMImplementation  item(in unsigned long index);
  readonly attribute unsigned long   length;
};

Attributes
length of type unsigned long, readonly
The number of DOMImplementations in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. If index is greater than or equal to the number of DOMImplementations in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

DOMImplementation

The DOMImplementation at the indexth position in the DOMImplementationList, or null if that is not a valid index.

No Exceptions
Interface DOMImplementationSource (introduced in DOM Level 3)

This interface permits a DOM implementer to supply one or more implementations, based upon requested features and versions, as specified in DOM Features. Each implemented DOMImplementationSource object is listed in the binding-specific list of available sources so that its DOMImplementation objects are made available.

IDL Definition
// Introduced in DOM Level 3:
interface DOMImplementationSource {
  DOMImplementation  getDOMImplementation(in DOMString features);
  DOMImplementationList getDOMImplementationList(in DOMString features);
};

Methods
getDOMImplementation
A method to request the first DOM implementation that supports the specified features.
Parameters
features of type DOMString
A string that specifies which features and versions are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number.
This method returns the first item of the list returned by getDOMImplementationList.
As an example, the string "XML 3.0 Traversal +Events 2.0" will request a DOM implementation that supports the module "XML" for its 3.0 version, a module that support of the "Traversal" module for any version, and the module "Events" for its 2.0 version. The module "Events" must be accessible using the method Node.getFeature() and DOMImplementation.getFeature().
Return Value

DOMImplementation

The first DOM implementation that support the desired features, or null if this source has none.

No Exceptions
getDOMImplementationList
A method to request a list of DOM implementations that support the specified features and versions, as specified in DOM Features.
Parameters
features of type DOMString
A string that specifies which features and versions are required. This is a space separated list in which each feature is specified by its name optionally followed by a space and a version number. This is something like: "XML 3.0 Traversal +Events 2.0"
Return Value

DOMImplementationList

A list of DOM implementations that support the desired features.

No Exceptions
Interface DOMImplementation

The DOMImplementation interface provides a number of methods for performing operations that are independent of any particular instance of the document object model.

IDL Definition
interface DOMImplementation {
  boolean            hasFeature(in DOMString feature,
                                in DOMString version);
  // Introduced in DOM Level 2:
  DocumentType       createDocumentType(in DOMString qualifiedName,
                                        in DOMString publicId,
                                        in DOMString systemId)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Document           createDocument(in DOMString namespaceURI,
                                    in DOMString qualifiedName,
                                    in DocumentType doctype)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  DOMObject          getFeature(in DOMString feature,
                                in DOMString version);
};

Methods
createDocument introduced in DOM Level 2
Creates a DOM Document object of the specified type with its document element.
Note that based on the DocumentType given to create the document, the implementation may instantiate specialized Document objects that support additional features than the "Core", such as "HTML" [DOM Level 2 HTML]. On the other hand, setting the DocumentType after the document was created makes this very unlikely to happen. Alternatively, specialized Document creation methods, such as createHTMLDocument [DOM Level 2 HTML], can be used to obtain specific types of Document objects.
Parameters
namespaceURI of type DOMString
The namespace URI of the document element to create or null.
qualifiedName of type DOMString
The qualified name of the document element to be created or null.
doctype of type DocumentType
The type of document to be created or null.
When doctype is not null, its Node.ownerDocument attribute is set to the document being created.
Return Value

Document

A new Document object with its document element. If the NamespaceURI, qualifiedName, and doctype are null, the returned Document is empty with no document element.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to [XML 1.0].

NAMESPACE_ERR: Raised if the qualifiedName is malformed, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName is null and the namespaceURI is different from null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace" [XML Namespaces], or if the DOM implementation does not support the "XML" feature but a non-null namespace URI was provided, since namespaces were defined by XML.

WRONG_DOCUMENT_ERR: Raised if doctype has already been used with a different document or was created from a different implementation.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

createDocumentType introduced in DOM Level 2
Creates an empty DocumentType node. Entity declarations and notations are not made available. Entity reference expansions and default attribute additions do not occur..
Parameters
qualifiedName of type DOMString
The qualified name of the document type to be created.
publicId of type DOMString
The external subset public identifier.
systemId of type DOMString
The external subset system identifier.
Return Value

DocumentType

A new DocumentType node with Node.ownerDocument set to null.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to [XML 1.0].

NAMESPACE_ERR: Raised if the qualifiedName is malformed.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

getFeature introduced in DOM Level 3
This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in DOM Features. The specialized object may also be obtained by using binding-specific casting methods but is not necessarily expected to, as discussed in Mixed DOM Implementations. This method also allow the implementation to provide specialized objects which do not support the DOMImplementation interface.
Parameters
feature of type DOMString
The name of the feature requested. Note that any plus sign "+" prepended to the name of the feature will be ignored since it is not significant in the context of this method.
version of type DOMString
This is the version number of the feature to test.
Return Value

DOMObject

Returns an object which implements the specialized APIs of the specified feature and version, if any, or null if there is no object which implements interfaces associated with that feature. If the DOMObject returned by this method implements the DOMImplementation interface, it must delegate to the primary core DOMImplementation and not return results inconsistent with the primary core DOMImplementation such as hasFeature, getFeature, etc.

No Exceptions
hasFeature
Test if the DOM implementation implements a specific feature and version, as specified in DOM Features.
Parameters
feature of type DOMString
The name of the feature to test.
version of type DOMString
This is the version number of the feature to test.
Return Value

boolean

true if the feature is implemented in the specified version, false otherwise.

No Exceptions
Interface DocumentFragment

DocumentFragment is a "lightweight" or "minimal" Document object. It is very common to want to be able to extract a portion of a document's tree or to create a new fragment of a document. Imagine implementing a user command like cut or rearranging a document by moving fragments around. It is desirable to have an object which can hold such fragments and it is quite natural to use a Node for this purpose. While it is true that a Document object could fulfill this role, a Document object can potentially be a heavyweight object, depending on the underlying implementation. What is really needed for this is a very lightweight object. DocumentFragment is such an object.

Furthermore, various operations -- such as inserting nodes as children of another Node -- may take DocumentFragment objects as arguments; this results in all the child nodes of the DocumentFragment being moved to the child list of this node.

The children of a DocumentFragment node are zero or more nodes representing the tops of any sub-trees defining the structure of the document. DocumentFragment nodes do not need to be well-formed XML documents (although they do need to follow the rules imposed upon well-formed XML parsed entities, which can have multiple top nodes). For example, a DocumentFragment might have only one child and that child node could be a Text node. Such a structure model represents neither an HTML document nor a well-formed XML document.

When a DocumentFragment is inserted into a Document (or indeed any other Node that may take children) the children of the DocumentFragment and not the DocumentFragment itself are inserted into the Node. This makes the DocumentFragment very useful when the user wishes to create nodes that are siblings; the DocumentFragment acts as the parent of these nodes so that the user can use the standard methods from the Node interface, such as Node.insertBefore and Node.appendChild.

IDL Definition
interface DocumentFragment : Node {
};

Interface Document

The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

IDL Definition
interface Document : Node {
  // Modified in DOM Level 3:
  readonly attribute DocumentType    doctype;
  readonly attribute DOMImplementation implementation;
  readonly attribute Element         documentElement;
  Element            createElement(in DOMString tagName)
                                        raises(DOMException);
  DocumentFragment   createDocumentFragment();
  Text               createTextNode(in DOMString data);
  Comment            createComment(in DOMString data);
  CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
  ProcessingInstruction createProcessingInstruction(in DOMString target,
                                                    in DOMString data)
                                        raises(DOMException);
  Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
  EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString tagname);
  // Introduced in DOM Level 2:
  Node               importNode(in Node importedNode,
                                in boolean deep)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Element            createElementNS(in DOMString namespaceURI,
                                     in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Attr               createAttributeNS(in DOMString namespaceURI,
                                       in DOMString qualifiedName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                            in DOMString localName);
  // Introduced in DOM Level 2:
  Element            getElementById(in DOMString elementId);
  // Introduced in DOM Level 3:
  readonly attribute DOMString       inputEncoding;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       xmlEncoding;
  // Introduced in DOM Level 3:
           attribute boolean         xmlStandalone;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 3:
           attribute DOMString       xmlVersion;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 3:
           attribute boolean         strictErrorChecking;
  // Introduced in DOM Level 3:
           attribute DOMString       documentURI;
  // Introduced in DOM Level 3:
  Node               adoptNode(in Node source)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  readonly attribute DOMConfiguration domConfig;
  // Introduced in DOM Level 3:
  void               normalizeDocument();
  // Introduced in DOM Level 3:
  Node               renameNode(in Node n,
                                in DOMString namespaceURI,
                                in DOMString qualifiedName)
                                        raises(DOMException);
};

Attributes
doctype of type DocumentType, readonly, modified in DOM Level 3
The Document Type Declaration (see DocumentType) associated with this document. For XML documents without a document type declaration this returns null. For HTML documents, a DocumentType object may be returned, independently of the presence or absence of document type declaration in the HTML document.
This provides direct access to the DocumentType node, child node of this Document. This node can be set at document creation time and later changed through the use of child nodes manipulation methods, such as Node.insertBefore, or Node.replaceChild. Note, however, that while some implementations may instantiate different types of Document objects supporting additional features than the "Core", such as "HTML" [DOM Level 2 HTML], based on the DocumentType specified at creation time, changing it afterwards is very unlikely to result in a change of the features supported.
documentElement of type Element, readonly
This is a convenience attribute that allows direct access to the child node that is the document element of the document.
documentURI of type DOMString, introduced in DOM Level 3
The location of the document or null if undefined or if the Document was created using DOMImplementation.createDocument. No lexical checking is performed when setting this attribute; this could result in a null value returned when using Node.baseURI.
Beware that when the Document supports the feature "HTML" [DOM Level 2 HTML], the href attribute of the HTML BASE element takes precedence over this attribute when computing Node.baseURI.
domConfig of type DOMConfiguration, readonly, introduced in DOM Level 3
The configuration used when Document.normalizeDocument() is invoked.
implementation of type DOMImplementation, readonly
The DOMImplementation object that handles this document. A DOM application may use objects from multiple implementations.
inputEncoding of type DOMString, readonly, introduced in DOM Level 3
An attribute specifying the encoding used for this document at the time of the parsing. This is null when it is not known, such as when the Document was created in memory.
strictErrorChecking of type boolean, introduced in DOM Level 3
An attribute specifying whether error checking is enforced or not. When set to false, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any DOMException on DOM operations or report errors while using Document.normalizeDocument(). In case of error, the behavior is undefined. This attribute is true by default.
xmlEncoding of type DOMString, readonly, introduced in DOM Level 3
An attribute specifying, as part of the XML declaration, the encoding of this document. This is null when unspecified or when it is not known, such as when the Document was created in memory.
xmlStandalone of type boolean, introduced in DOM Level 3
An attribute specifying, as part of the XML declaration, whether this document is standalone. This is false when unspecified.

Note: No verification is done on the value when setting this attribute. Applications should use Document.normalizeDocument() with the "validate" parameter to verify if the value matches the validity constraint for standalone document declaration as defined in [XML 1.0].

Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: Raised if this document does not support the "XML" feature.

xmlVersion of type DOMString, introduced in DOM Level 3
An attribute specifying, as part of the XML declaration, the version number of this document. If there is no declaration and if this document supports the "XML" feature, the value is "1.0". If this document does not support the "XML" feature, the value is always null. Changing this attribute will affect methods that check for invalid characters in XML names. Application should invoke Document.normalizeDocument() in order to check for invalid characters in the Nodes that are already part of this Document.
DOM applications may use the DOMImplementation.hasFeature(feature, version) method with parameter values "XMLVersion" and "1.0" (respectively) to determine if an implementation supports [XML 1.0]. DOM applications may use the same method with parameter values "XMLVersion" and "1.1" (respectively) to determine if an implementation supports [XML 1.1]. In both cases, in order to support XML, an implementation must also support the "XML" feature defined in this specification. Document objects supporting a version of the "XMLVersion" feature must not raise a NOT_SUPPORTED_ERR exception for the same version number when using Document.xmlVersion.
Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: Raised if the version is set to a value that is not supported by this Document or if this document does not support the "XML" feature.

Methods
adoptNode introduced in DOM Level 3
Attempts to adopt a node from another document to this document. If supported, it changes the ownerDocument of the source node, its children, as well as the attached attribute nodes if there are any. If the source node has a parent it is first removed from the child list of its parent. This effectively allows moving a subtree from one document to another (unlike importNode() which create a copy of the source node instead of moving it). When it fails, applications should use Document.importNode() instead. Note that if the adopted node is already part of this document (i.e. the source and target document are the same), this method still has the effect of removing the source node from the child list of its parent, if any. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the adopted Attr. The descendants of the source Attr are recursively adopted.
DOCUMENT_FRAGMENT_NODE
The descendants of the source node are recursively adopted.
DOCUMENT_NODE
Document nodes cannot be adopted.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be adopted.
ELEMENT_NODE
Specified attribute nodes of the source element are adopted. Default attributes are discarded, though if the document being adopted into defines default attributes for this element name, those are assigned. The descendants of the source element are recursively adopted.
ENTITY_NODE
Entity nodes cannot be adopted.
ENTITY_REFERENCE_NODE
Only the EntityReference node itself is adopted, the descendants are discarded, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes cannot be adopted.
PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These nodes can all be adopted. No specifics.

Note: Since it does not create new nodes unlike the Document.importNode() method, this method does not raise an INVALID_CHARACTER_ERR exception, and applications should use the Document.normalizeDocument() method to check if an imported name is not an XML name according to the XML version in use.

Parameters
source of type Node
The node to move into this document.
Return Value

Node

The adopted node, or null if this operation fails, such as when the source node comes from a different implementation.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the source node is of type DOCUMENT, DOCUMENT_TYPE.

NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is readonly.

createAttribute
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttributeNode method.
To create an attribute with a qualified name and namespace URI, use the createAttributeNS method.
Parameters
name of type DOMString
The name of the attribute.
Return Value

Attr

A new Attr object with the nodeName attribute set to name, and localName, prefix, and namespaceURI set to null. The value of the attribute is the empty string.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

createAttributeNS introduced in DOM Level 2
Creates an attribute of the given qualified name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to create.
qualifiedName of type DOMString
The qualified name of the attribute to instantiate.
Return Value

Attr

A new Attr object with the following attributes:

Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Attr.name | qualifiedName
Node.nodeValue | the empty string
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualifiedName is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".

NOT_SUPPORTED_ERR: Always thrown if the current document does not support the "XML" feature, since namespaces were defined by XML.

createCDATASection
Creates a CDATASection node whose value is the specified string.
Parameters
data of type DOMString
The data for the CDATASection contents.
Return Value

CDATASection

The new CDATASection object.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createComment
Creates a Comment node given the specified string.
Parameters
data of type DOMString
The data for the node.
Return Value

Comment

The new Comment object.

No Exceptions
createDocumentFragment
Creates an empty DocumentFragment object.
Return Value

DocumentFragment

A new DocumentFragment.

No Parameters
No Exceptions
createElement
Creates an element of the type specified. Note that the instance returned implements the Element interface, so attributes can be specified directly on the returned object.
In addition, if there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.
To create an element with a qualified name and namespace URI, use the createElementNS method.
Parameters
tagName of type DOMString
The name of the element type to instantiate. For XML, this is case-sensitive, otherwise it depends on the case-sensitivity of the markup language in use. In that case, the name is mapped to the canonical form of that markup by the DOM implementation.
Return Value

Element

A new Element object with the nodeName attribute set to tagName, and localName, prefix, and namespaceURI set to null.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

createElementNS introduced in DOM Level 2
Creates an element of the given qualified name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the element to create.
qualifiedName of type DOMString
The qualified name of the element type to instantiate.
Return Value

Element

A new Element object with the following attributes:

Attribute | Value
Node.nodeName | qualifiedName
Node.namespaceURI | namespaceURI
Node.prefix | prefix, extracted from qualifiedName, or null if there is no prefix
Node.localName | local name, extracted from qualifiedName
Element.tagName | qualifiedName
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualifiedName is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace" [XML Namespaces], or if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".

NOT_SUPPORTED_ERR: Always thrown if the current document does not support the "XML" feature, since namespaces were defined by XML.

createEntityReference
Creates an EntityReference object. In addition, if the referenced entity is known, the child list of the EntityReference node is made the same as that of the corresponding Entity node.

Note: If any descendant of the Entity node has an unbound namespace prefix, the corresponding descendant of the created EntityReference node is also unbound; (its namespaceURI is null). The DOM Level 2 and 3 do not support any mechanism to resolve namespace prefixes in this case.

Parameters
name of type DOMString
The name of the entity to reference.
Unlike Document.createElementNS or Document.createAttributeNS, no namespace well-formed checking is done on the entity name. Applications should invoke Document.normalizeDocument() with the parameter "namespaces" set to true in order to ensure that the entity name is namespace well-formed.
Return Value

EntityReference

The new EntityReference object.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createProcessingInstruction
Creates a ProcessingInstruction node given the specified name and data strings.
Parameters
target of type DOMString
The target part of the processing instruction.
Unlike Document.createElementNS or Document.createAttributeNS, no namespace well-formed checking is done on the target name. Applications should invoke Document.normalizeDocument() with the parameter "namespaces" set to true in order to ensure that the target name is namespace well-formed.
data of type DOMString
The data for the node.
Return Value

ProcessingInstruction

The new ProcessingInstruction object.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified target is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

createTextNode
Creates a Text node given the specified string.
Parameters
data of type DOMString
The data for the node.
Return Value

Text

The new Text object.

No Exceptions
getElementById introduced in DOM Level 2
Returns the Element that has an ID attribute with the given value. If no such element exists, this returns null. If more than one element has an ID attribute with that value, what is returned is undefined.
The DOM implementation is expected to use the attribute Attr.isId to determine if an attribute is of type ID.

Note: Attributes with the name "ID" or "id" are not of type ID unless so defined.

Parameters
elementId of type DOMString
The unique id value for an element.
Return Value

Element

The matching element or null if there is none.

No Exceptions
getElementsByTagName
Returns a NodeList of all the Elements in document order with a given tag name and are contained in the document.
Parameters
tagname of type DOMString
The name of the tag to match on. The special value "*" matches all tags. For XML, the tagname parameter is case-sensitive, otherwise it depends on the case-sensitivity of the markup language in use.
Return Value

NodeList

A new NodeList object containing all the matched Elements.

No Exceptions
getElementsByTagNameNS introduced in DOM Level 2
Returns a NodeList of all the Elements with a given local name and namespace URI in document order.
Parameters
namespaceURI of type DOMString
The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName of type DOMString
The local name of the elements to match on. The special value "*" matches all local names.
Return Value

NodeList

A new NodeList object containing all the matched Elements.

No Exceptions
importNode introduced in DOM Level 2
Imports a node from another document to this document, without altering or removing the source node from the original document; this method creates a new copy of the source node. The returned node has no parent; (parentNode is null).
For all nodes, importing a node creates a node object owned by the importing document, with attribute values identical to the source node's nodeName and nodeType, plus the attributes related to namespaces (prefix, localName, and namespaceURI). As in the cloneNode operation, the source node is not altered. User data associated to the imported node is not carried over. However, if any UserDataHandlers has been specified along with the associated data these handlers will be called with the appropriate parameters before this method returns.
Additional information is copied as appropriate to the nodeType, attempting to mirror the behavior expected if a fragment of XML or HTML source was copied from one document to another, recognizing that the two documents may have different DTDs in the XML case. The following list describes the specifics for each type of node.
ATTRIBUTE_NODE
The ownerElement attribute is set to null and the specified flag is set to true on the generated Attr. The descendants of the source Attr are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
Note that the deep parameter has no effect on Attr nodes; they always carry their children with them when imported.
DOCUMENT_FRAGMENT_NODE
If the deep option was set to true, the descendants of the source DocumentFragment are recursively imported and the resulting nodes reassembled under the imported DocumentFragment to form the corresponding subtree. Otherwise, this simply generates an empty DocumentFragment.
DOCUMENT_NODE
Document nodes cannot be imported.
DOCUMENT_TYPE_NODE
DocumentType nodes cannot be imported.
ELEMENT_NODE
Specified attribute nodes of the source element are imported, and the generated Attr nodes are attached to the generated Element. Default attributes are not copied, though if the document being imported into defines default attributes for this element name, those are assigned. If the importNode deep parameter was set to true, the descendants of the source element are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_NODE
Entity nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.
On import, the publicId, systemId, and notationName attributes are copied. If a deep import is requested, the descendants of the the source Entity are recursively imported and the resulting nodes reassembled to form the corresponding subtree.
ENTITY_REFERENCE_NODE
Only the EntityReference itself is copied, even if a deep import is requested, since the source and destination documents might have defined the entity differently. If the document being imported into provides a definition for this entity name, its value is assigned.
NOTATION_NODE
Notation nodes can be imported, however in the current release of the DOM the DocumentType is readonly. Ability to add these imported nodes to a DocumentType will be considered for addition to a future release of the DOM.
On import, the publicId and systemId attributes are copied.
Note that the deep parameter has no effect on this type of nodes since they cannot have any children.
PROCESSING_INSTRUCTION_NODE
The imported node copies its target and data values from those of the source node.
Note that the deep parameter has no effect on this type of nodes since they cannot have any children.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE
These three types of nodes inheriting from CharacterData copy their data and length attributes from those of the source node.
Note that the deep parameter has no effect on these types of nodes since they cannot have any children.
Parameters
importedNode of type Node
The node to import.
deep of type boolean
If true, recursively import the subtree under the specified node; if false, import only the node itself, as explained above. This has no effect on nodes that cannot have any children, and on Attr, and EntityReference nodes.
Return Value

Node

The imported node that belongs to this Document.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

INVALID_CHARACTER_ERR: Raised if one of the imported names is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute. This may happen when importing an XML 1.1 [XML 1.1] element into an XML 1.0 document, for instance.

normalizeDocument introduced in DOM Level 3
This method acts as if the document was going through a save and load cycle, putting the document in a "normal" form. As a consequence, this method updates the replacement tree of EntityReference nodes and normalizes Text nodes, as defined in the method Node.normalize().
Otherwise, the actual result depends on the features being set on the Document.domConfig object and governing what operations actually take place. Noticeably this method could also make the document namespace well-formed according to the algorithm described in Namespace Normalization, check the character normalization, remove the CDATASection nodes, etc. See DOMConfiguration for details.
// Keep in the document the information defined
// in the XML Information Set (Java example)
DOMConfiguration docConfig = myDocument.getDomConfig();
docConfig.setParameter("infoset", Boolean.TRUE);
myDocument.normalizeDocument();

Mutation events, when supported, are generated to reflect the changes occurring on the document.
If errors occur during the invocation of this method, such as an attempt to update a read-only node or a Node.nodeName contains an invalid character according to the XML version in use, errors or warnings (DOMError.SEVERITY_ERROR or DOMError.SEVERITY_WARNING) will be reported using the DOMErrorHandler object associated with the "error-handler" parameter. Note this method might also report fatal errors (DOMError.SEVERITY_FATAL_ERROR) if an implementation cannot recover from an error.

No Parameters
No Return Value
No Exceptions
renameNode introduced in DOM Level 3
Rename an existing node of type ELEMENT_NODE or ATTRIBUTE_NODE.
When possible this simply changes the name of the given node, otherwise this creates a new node with the specified name and replaces the existing node with the new node as described below.
If simply changing the name of the given node is not possible, the following operations are performed: a new node is created, any registered event listener is registered on the new node, any user data attached to the old node is removed from that node, the old node is removed from its parent if it has one, the children are moved to the new node, if the renamed node is an Element its attributes are moved to the new node, the new node is inserted at the position the old node used to have in its parent's child nodes list if it has one, the user data that was attached to the old node is attached to the new node.
When the node being renamed is an Element only the specified attributes are moved, default attributes originated from the DTD are updated according to the new element name. In addition, the implementation may update default attributes from other schemas. Applications should use Document.normalizeDocument() to guarantee these attributes are up-to-date.
When the node being renamed is an Attr that is attached to an Element, the node is first removed from the Element attributes map. Then, once renamed, either by modifying the existing node or creating a new one as described above, it is put back.
In addition,
  • a user data event NODE_RENAMED is fired,
  • when the implementation supports the feature "MutationNameEvents", each mutation operation involved in this method fires the appropriate event, and in the end the event {http://www.w3.org/2001/xml-events, DOMElementNameChanged} or {http://www.w3.org/2001/xml-events, DOMAttributeNameChanged} is fired.
Parameters
n of type Node
The node to rename.
namespaceURI of type DOMString
The new namespace URI.
qualifiedName of type DOMString
The new qualified name.
Return Value

Node

The renamed node. This is either the specified node or the new node that was created to replace the specified node.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised when the type of the specified node is neither ELEMENT_NODE nor ATTRIBUTE_NODE, or if the implementation does not support the renaming of the document element.

INVALID_CHARACTER_ERR: Raised if the new qualified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

WRONG_DOCUMENT_ERR: Raised when the specified node was created from a different document than this document.

NAMESPACE_ERR: Raised if the qualifiedName is a malformed qualified name, if the qualifiedName has a prefix and the namespaceURI is null, or if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace" [XML Namespaces]. Also raised, when the node being renamed is an attribute, if the qualifiedName, or its prefix, is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/".

Interface Node

The Node interface is the primary datatype for the entire Document Object Model. It represents a single node in the document tree. While all objects implementing the Node interface expose methods for dealing with children, not all objects implementing the Node interface may have children. For example, Text nodes may not have children, and adding children to such nodes results in a DOMException being raised.

The attributes nodeName, nodeValue and attributes are included as a mechanism to get at node information without casting down to the specific derived interface. In cases where there is no obvious mapping of these attributes for a specific nodeType (e.g., nodeValue for an Element or attributes for a Comment), this returns null. Note that the specialized interfaces may contain additional and more convenient mechanisms to get and set the relevant information.

IDL Definition
interface Node {

  // NodeType
  const unsigned short      ELEMENT_NODE                   = 1;
  const unsigned short      ATTRIBUTE_NODE                 = 2;
  const unsigned short      TEXT_NODE                      = 3;
  const unsigned short      CDATA_SECTION_NODE             = 4;
  const unsigned short      ENTITY_REFERENCE_NODE          = 5;
  const unsigned short      ENTITY_NODE                    = 6;
  const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
  const unsigned short      COMMENT_NODE                   = 8;
  const unsigned short      DOCUMENT_NODE                  = 9;
  const unsigned short      DOCUMENT_TYPE_NODE             = 10;
  const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
  const unsigned short      NOTATION_NODE                  = 12;

  readonly attribute DOMString       nodeName;
           attribute DOMString       nodeValue;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned short  nodeType;
  readonly attribute Node            parentNode;
  readonly attribute NodeList        childNodes;
  readonly attribute Node            firstChild;
  readonly attribute Node            lastChild;
  readonly attribute Node            previousSibling;
  readonly attribute Node            nextSibling;
  readonly attribute NamedNodeMap    attributes;
  // Modified in DOM Level 2:
  readonly attribute Document        ownerDocument;
  // Modified in DOM Level 3:
  Node               insertBefore(in Node newChild,
                                  in Node refChild)
                                        raises(DOMException);
  // Modified in DOM Level 3:
  Node               replaceChild(in Node newChild,
                                  in Node oldChild)
                                        raises(DOMException);
  // Modified in DOM Level 3:
  Node               removeChild(in Node oldChild)
                                        raises(DOMException);
  // Modified in DOM Level 3:
  Node               appendChild(in Node newChild)
                                        raises(DOMException);
  boolean            hasChildNodes();
  Node               cloneNode(in boolean deep);
  // Modified in DOM Level 3:
  void               normalize();
  // Introduced in DOM Level 2:
  boolean            isSupported(in DOMString feature,
                                 in DOMString version);
  // Introduced in DOM Level 2:
  readonly attribute DOMString       namespaceURI;
  // Introduced in DOM Level 2:
           attribute DOMString       prefix;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 2:
  readonly attribute DOMString       localName;
  // Introduced in DOM Level 2:
  boolean            hasAttributes();
  // Introduced in DOM Level 3:
  readonly attribute DOMString       baseURI;

  // DocumentPosition
  const unsigned short      DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short      DOCUMENT_POSITION_PRECEDING    = 0x02;
  const unsigned short      DOCUMENT_POSITION_FOLLOWING    = 0x04;
  const unsigned short      DOCUMENT_POSITION_CONTAINS     = 0x08;
  const unsigned short      DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short      DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;

  // Introduced in DOM Level 3:
  unsigned short     compareDocumentPosition(in Node other)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
           attribute DOMString       textContent;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  // Introduced in DOM Level 3:
  boolean            isSameNode(in Node other);
  // Introduced in DOM Level 3:
  DOMString          lookupPrefix(in DOMString namespaceURI);
  // Introduced in DOM Level 3:
  boolean            isDefaultNamespace(in DOMString namespaceURI);
  // Introduced in DOM Level 3:
  DOMString          lookupNamespaceURI(in DOMString prefix);
  // Introduced in DOM Level 3:
  boolean            isEqualNode(in Node arg);
  // Introduced in DOM Level 3:
  DOMObject          getFeature(in DOMString feature,
                                in DOMString version);
  // Introduced in DOM Level 3:
  DOMUserData        setUserData(in DOMString key,
                                 in DOMUserData data,
                                 in UserDataHandler handler);
  // Introduced in DOM Level 3:
  DOMUserData        getUserData(in DOMString key);
};

Definition group NodeType

An integer indicating which type of node this is.

Note: Numeric codes up to 200 are reserved to W3C for possible future use.

Defined Constants
ATTRIBUTE_NODE
The node is an Attr.
CDATA_SECTION_NODE
The node is a CDATASection.
COMMENT_NODE
The node is a Comment.
DOCUMENT_FRAGMENT_NODE
The node is a DocumentFragment.
DOCUMENT_NODE
The node is a Document.
DOCUMENT_TYPE_NODE
The node is a DocumentType.
ELEMENT_NODE
The node is an Element.
ENTITY_NODE
The node is an Entity.
ENTITY_REFERENCE_NODE
The node is an EntityReference.
NOTATION_NODE
The node is a Notation.
PROCESSING_INSTRUCTION_NODE
The node is a ProcessingInstruction.
TEXT_NODE
The node is a Text node.

The values of nodeName, nodeValue, and attributes vary according to the node type as follows:

Interface | nodeName | nodeValue | attributes
Attr | same as Attr.name | same as Attr.value | null
CDATASection | "#cdata-section" | same as CharacterData.data, the content of the CDATA Section | null
Comment | "#comment" | same as CharacterData.data, the content of the comment | null
Document | "#document" | null | null
DocumentFragment | "#document-fragment" | null | null
DocumentType | same as DocumentType.name | null | null
Element | same as Element.tagName | null | NamedNodeMap
Entity | entity name | null | null
EntityReference | name of entity referenced | null | null
Notation | notation name | null | null
ProcessingInstruction | same as ProcessingInstruction.target | same as ProcessingInstruction.data | null
Text | "#text" | same as CharacterData.data, the content of the text node | null
Definition group DocumentPosition

A bitmask indicating the relative document position of a node with respect to another node.

If the two nodes being compared are the same node, then no flags are set on the return.

Otherwise, the order of two nodes is determined by looking for common containers -- containers which contain both. A node directly contains any child nodes. A node also directly contains any other nodes attached to it such as attributes contained in an element or entities and notations contained in a document type. Nodes contained in contained nodes are also contained, but less-directly as the number of intervening containers increases.

If there is no common container node, then the order is based upon order between the root container of each node that is in no container. In this case, the result is disconnected and implementation-specific. This result is stable as long as these outer-most containing nodes remain in memory and are not inserted into some other containing node. This would be the case when the nodes belong to different documents or fragments, and cloning the document or inserting a fragment might change the order.

If one of the nodes being compared contains the other node, then the container precedes the contained node, and reversely the contained node follows the container. For example, when comparing an element against its own attribute or child, the element node precedes its attribute node and its child node, which both follow it.

If neither of the previous cases apply, then there exists a most-direct container common to both nodes being compared. In this case, the order is determined based upon the two determining nodes directly contained in this most-direct common container that either are or contain the corresponding nodes being compared.

If these two determining nodes are both child nodes, then the natural DOM order of these determining nodes within the containing node is returned as the order of the corresponding nodes. This would be the case, for example, when comparing two child elements of the same element.

If one of the two determining nodes is a child node and the other is not, then the corresponding node of the child node follows the corresponding node of the non-child node. This would be the case, for example, when comparing an attribute of an element with a child element of the same element.

If neither of the two determining node is a child node and one determining node has a greater value of nodeType than the other, then the corresponding node precedes the other. This would be the case, for example, when comparing an entity of a document type against a notation of the same document type.

If neither of the two determining node is a child node and nodeType is the same for both determining nodes, then an implementation-dependent order between the determining nodes is returned. This order is stable as long as no nodes of the same nodeType are inserted into or removed from the direct container. This would be the case, for example, when comparing two attributes of the same element, and inserting or removing additional attributes might change the order between existing attributes.

Defined Constants
DOCUMENT_POSITION_CONTAINED_BY
The node is contained by the reference node. A node which is contained is always following, too.
DOCUMENT_POSITION_CONTAINS
The node contains the reference node. A node which contains is always preceding, too.
DOCUMENT_POSITION_DISCONNECTED
The two nodes are disconnected. Order between disconnected nodes is always implementation-specific.
DOCUMENT_POSITION_FOLLOWING
The node follows the reference node.
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
The determination of preceding versus following is implementation-specific.
DOCUMENT_POSITION_PRECEDING
The second node precedes the reference node.
Attributes
attributes of type NamedNodeMap, readonly
A NamedNodeMap containing the attributes of this node (if it is an Element) or null otherwise.
baseURI of type DOMString, readonly, introduced in DOM Level 3
The absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI. This value is computed as described in Base URIs. However, when the Document supports the feature "HTML" [DOM Level 2 HTML], the base URI is computed using first the value of the href attribute of the HTML BASE element if any, and the value of the documentURI attribute from the Document interface otherwise.
childNodes of type NodeList, readonly
A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.
firstChild of type Node, readonly
The first child of this node. If there is no such node, this returns null.
lastChild of type Node, readonly
The last child of this node. If there is no such node, this returns null.
localName of type DOMString, readonly, introduced in DOM Level 2
Returns the local part of the qualified name of this node.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as Document.createElement(), this is always null.
namespaceURI of type DOMString, readonly, introduced in DOM Level 2
The namespace URI of this node, or null if it is unspecified (see XML Namespaces).
This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as Document.createElement(), this is always null.

Note: Per the Namespaces in XML Specification [XML Namespaces] an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace.

nextSibling of type Node, readonly
The node immediately following this node. If there is no such node, this returns null.
nodeName of type DOMString, readonly
The name of this node, depending on its type; see the table above.
nodeType of type unsigned short, readonly
A code representing the type of the underlying object, as defined above.
nodeValue of type DOMString
The value of this node, depending on its type; see the table above. When it is defined to be null, setting it has no effect, including if the node is read-only.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if it is not defined to be null.

Exceptions on retrieval

DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

ownerDocument of type Document, readonly, modified in DOM Level 2
The Document object associated with this node. This is also the Document object used to create new nodes. When this node is a Document or a DocumentType which is not used with any Document yet, this is null.
parentNode of type Node, readonly
The parent of this node. All nodes, except Attr, Document, DocumentFragment, Entity, and Notation may have a parent. However, if a node has just been created and not yet added to the tree, or if it has been removed from the tree, this is null.
prefix of type DOMString, introduced in DOM Level 2
The namespace prefix of this node, or null if it is unspecified. When it is defined to be null, setting it has no effect, including if the node is read-only.
Note that setting this attribute, when permitted, changes the nodeName attribute, which holds the qualified name, as well as the tagName and name attributes of the Element and Attr interfaces, when applicable.
Setting the prefix to null makes it unspecified, setting it to an empty string is implementation dependent.
Note also that changing the prefix of an attribute that is known to have a default value, does not make a new attribute with the default value and the original prefix appear, since the namespaceURI and localName do not change.
For nodes of any type other than ELEMENT_NODE and ATTRIBUTE_NODE and nodes created with a DOM Level 1 method, such as createElement from the Document interface, this is always null.
Exceptions on setting

DOMException

INVALID_CHARACTER_ERR: Raised if the specified prefix contains an illegal character according to the XML version in use specified in the Document.xmlVersion attribute.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NAMESPACE_ERR: Raised if the specified prefix is malformed per the Namespaces in XML specification, if the namespaceURI of this node is null, if the specified prefix is "xml" and the namespaceURI of this node is different from "http://www.w3.org/XML/1998/namespace", if this node is an attribute and the specified prefix is "xmlns" and the namespaceURI of this node is different from "http://www.w3.org/2000/xmlns/", or if this node is an attribute and the qualifiedName of this node is "xmlns" [XML Namespaces].

previousSibling of type Node, readonly
The node immediately preceding this node. If there is no such node, this returns null.
textContent of type DOMString, introduced in DOM Level 3
This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. On setting, any possible children this node may have are removed and, if it the new string is not empty or null, replaced by a single Text node containing the string this attribute is set to.
On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed and the returned string does not contain the white spaces in element content (see the attribute Text.isElementContentWhitespace). Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
The string returned is made of the text content of this node depending on its type, as defined below:
Node type | Content
ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the textContent attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the node has no children.
TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | nodeValue
DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

Exceptions on retrieval

DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

Methods
appendChild modified in DOM Level 3
Adds the node newChild to the end of the list of children of this node. If the newChild is already in the tree, it is first removed.
Parameters
newChild of type Node
The node to add.
If it is a DocumentFragment object, the entire contents of the document fragment are moved into the child list of this node
Return Value

Node

The node added.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to append is one of this node's ancestors or this node itself, or if this node is of type Document and the DOM application attempts to append a second DocumentType or Element node.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the previous parent of the node being inserted is readonly.

NOT_SUPPORTED_ERR: if the newChild node is a child of the Document node, this exception might be raised if the DOM implementation doesn't support the removal of the DocumentType child or Element child.

cloneNode
Returns a duplicate of this node, i.e., serves as a generic copy constructor for nodes. The duplicate node has no parent (parentNode is null) and no user data. User data associated to the imported node is not carried over. However, if any UserDataHandlers has been specified along with the associated data these handlers will be called with the appropriate parameters before this method returns.
Cloning an Element copies all attributes and their values, including those generated by the XML processor to represent defaulted attributes, but this method does not copy any children it contains unless it is a deep clone. This includes text contained in an the Element since the text is contained in a child Text node. Cloning an Attr directly, as opposed to be cloned as part of an Element cloning operation, returns a specified attribute (specified is true). Cloning an Attr always clones its children, since they represent its value, no matter whether this is a deep clone or not. Cloning an EntityReference automatically constructs its subtree if a corresponding Entity is available, no matter whether this is a deep clone or not. Cloning any other type of node simply returns a copy of this node.
Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly. In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.
Parameters
deep of type boolean
If true, recursively clone the subtree under the specified node; if false, clone only the node itself (and its attributes, if it is an Element).
Return Value

Node

The duplicate node.

No Exceptions
compareDocumentPosition introduced in DOM Level 3
Compares the reference node, i.e. the node on which this method is being called, with a node, i.e. the one passed as a parameter, with regard to their position in the document and according to the document order.
Parameters
other of type Node
The node to compare against the reference node.
Return Value

unsigned short

Returns how the node is positioned relatively to the reference node.

Exceptions

DOMException

NOT_SUPPORTED_ERR: when the compared nodes are from different DOM implementations that do not coordinate to return consistent implementation-specific results.

getFeature introduced in DOM Level 3
This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in DOM Features. The specialized object may also be obtained by using binding-specific casting methods but is not necessarily expected to, as discussed in Mixed DOM Implementations. This method also allow the implementation to provide specialized objects which do not support the Node interface.
Parameters
feature of type DOMString
The name of the feature requested. Note that any plus sign "+" prepended to the name of the feature will be ignored since it is not significant in the context of this method.
version of type DOMString
This is the version number of the feature to test.
Return Value

DOMObject

Returns an object which implements the specialized APIs of the specified feature and version, if any, or null if there is no object which implements interfaces associated with that feature. If the DOMObject returned by this method implements the Node interface, it must delegate to the primary core Node and not return results inconsistent with the primary core Node such as attributes, childNodes, etc.

No Exceptions
getUserData introduced in DOM Level 3
Retrieves the object associated to a key on a this node. The object must first have been set to this node by calling setUserData with the same key.
Parameters
key of type DOMString
The key the object is associated to.
Return Value

DOMUserData

Returns the DOMUserData associated to the given key on this node, or null if there was none.

No Exceptions
hasAttributes introduced in DOM Level 2
Returns whether this node (if it is an element) has any attributes.
Return Value

boolean

Returns true if this node has any attributes, false otherwise.

No Parameters
No Exceptions
hasChildNodes
Returns whether this node has any children.
Return Value

boolean

Returns true if this node has any children, false otherwise.

No Parameters
No Exceptions
insertBefore modified in DOM Level 3
Inserts the node newChild before the existing child node refChild. If refChild is null, insert newChild at the end of the list of children.
If newChild is a DocumentFragment object, all of its children are inserted, in the same order, before refChild. If the newChild is already in the tree, it is first removed.

Note: Inserting a node before itself is implementation dependent.

Parameters
newChild of type Node
The node to insert.
refChild of type Node
The reference node, i.e., the node before which the new node must be inserted.
Return Value

Node

The node being inserted.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to insert is one of this node's ancestors or this node itself, or if this node is of type Document and the DOM application attempts to insert a second DocumentType or Element node.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the parent of the node being inserted is readonly.

NOT_FOUND_ERR: Raised if refChild is not a child of this node.

NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the insertion of a DocumentType or Element node.

isDefaultNamespace introduced in DOM Level 3
This method checks if the specified namespaceURI is the default namespace or not.
Parameters
namespaceURI of type DOMString
The namespace URI to look for.
Return Value

boolean

Returns true if the specified namespaceURI is the default namespace, false otherwise.

No Exceptions
isEqualNode introduced in DOM Level 3
Tests whether two nodes are equal.
This method tests for equality of nodes, not sameness (i.e., whether the two nodes are references to the same object) which can be tested with Node.isSameNode(). All nodes that are the same will also be equal, though the reverse may not be true.
Two nodes are equal if and only if the following conditions are satisfied:
  • The two nodes are of the same type.
  • The following string attributes are equal: nodeName, localName, namespaceURI, prefix, nodeValue. This is: they are both null, or they have the same length and are character for character identical.
  • The attributes NamedNodeMaps are equal. This is: they are both null, or they have the same length and for each node that exists in one map there is a node that exists in the other map and is equal, although not necessarily at the same index.
  • The childNodes NodeLists are equal. This is: they are both null, or they have the same length and contain equal nodes at the same index. Note that normalization can affect equality; to avoid this, nodes should be normalized before being compared.

For two DocumentType nodes to be equal, the following conditions must also be satisfied:
  • The following string attributes are equal: publicId, systemId, internalSubset.
  • The entities NamedNodeMaps are equal.
  • The notations NamedNodeMaps are equal.

On the other hand, the following do not affect equality: the ownerDocument, baseURI, and parentNode attributes, the specified attribute for Attr nodes, the schemaTypeInfo attribute for Attr and Element nodes, the Text.isElementContentWhitespace attribute for Text nodes, as well as any user data or event listeners registered on the nodes.

Note: As a general rule, anything not mentioned in the description above is not significant in consideration of equality checking. Note that future versions of this specification may take into account more attributes and implementations conform to this specification are expected to be updated accordingly.

Parameters
arg of type Node
The node to compare equality with.
Return Value

boolean

Returns true if the nodes are equal, false otherwise.

No Exceptions
isSameNode introduced in DOM Level 3
Returns whether this node is the same node as the given one.
This method provides a way to determine whether two Node references returned by the implementation reference the same object. When two Node references are references to the same object, even if through a proxy, the references may be used completely interchangeably, such that all attributes have the same values and calling the same DOM method on either reference always has exactly the same effect.
Parameters
other of type Node
The node to test against.
Return Value

boolean

Returns true if the nodes are the same, false otherwise.

No Exceptions
isSupported introduced in DOM Level 2
Tests whether the DOM implementation implements a specific feature and that feature is supported by this node, as specified in DOM Features.
Parameters
feature of type DOMString
The name of the feature to test.
version of type DOMString
This is the version number of the feature to test.
Return Value

boolean

Returns true if the specified feature is supported on this node, false otherwise.

No Exceptions
lookupNamespaceURI introduced in DOM Level 3
Look up the namespace URI associated to the given prefix, starting from this node.
See Namespace URI Lookup for details on the algorithm used by this method.
Parameters
prefix of type DOMString
The prefix to look for. If this parameter is null, the method will return the default namespace URI if any.
Return Value

DOMString

Returns the associated namespace URI or null if none is found.

No Exceptions
lookupPrefix introduced in DOM Level 3
Look up the prefix associated to the given namespace URI, starting from this node. The default namespace declarations are ignored by this method.
See Namespace Prefix Lookup for details on the algorithm used by this method.
Parameters
namespaceURI of type DOMString
The namespace URI to look for.
Return Value

DOMString

Returns an associated namespace prefix if found or null if none is found. If more than one prefix are associated to the namespace prefix, the returned namespace prefix is implementation dependent.

No Exceptions
normalize modified in DOM Level 3
Puts all Text nodes in the full depth of the sub-tree underneath this Node, including attribute nodes, into a "normal" form where only structure (e.g., elements, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are neither adjacent Text nodes nor empty Text nodes. This can be used to ensure that the DOM view of a document is the same as if it were saved and re-loaded, and is useful when operations (such as XPointer [XPointer] lookups) that depend on a particular document tree structure are to be used. If the parameter "normalize-characters" of the DOMConfiguration object attached to the Node.ownerDocument is true, this method will also fully normalize the characters of the Text nodes.

Note: In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.

No Parameters
No Return Value
No Exceptions
removeChild modified in DOM Level 3
Removes the child node indicated by oldChild from the list of children, and returns it.
Parameters
oldChild of type Node
The node being removed.
Return Value

Node

The node removed.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.

NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the removal of the DocumentType child or the Element child.

replaceChild modified in DOM Level 3
Replaces the child node oldChild with newChild in the list of children, and returns the oldChild node.
If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.

Note: Replacing a node with itself is implementation dependent.

Parameters
newChild of type Node
The new node to put in the child list.
oldChild of type Node
The node being replaced in the list.
Return Value

Node

The node replaced.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the newChild node, or if the node to put in is one of this node's ancestors or this node itself, or if this node is of type Document and the result of the replacement operation would add a second DocumentType or Element on the Document node.

WRONG_DOCUMENT_ERR: Raised if newChild was created from a different document than the one that created this node.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the new node is readonly.

NOT_FOUND_ERR: Raised if oldChild is not a child of this node.

NOT_SUPPORTED_ERR: if this node is of type Document, this exception might be raised if the DOM implementation doesn't support the replacement of the DocumentType child or Element child.

setUserData introduced in DOM Level 3
Associate an object to a key on this node. The object can later be retrieved from this node by calling getUserData with the same key.
Parameters
key of type DOMString
The key to associate the object to.
data of type DOMUserData
The object to associate to the given key, or null to remove any existing association to that key.
handler of type UserDataHandler
The handler to associate to that key, or null.
Return Value

DOMUserData

Returns the DOMUserData previously associated to the given key on this node, or null if there was none.

No Exceptions
Interface NodeList

The NodeList interface provides the abstraction of an ordered collection of nodes, without defining or constraining how this collection is implemented. NodeList objects in the DOM are live.

The items in the NodeList are accessible via an integral index, starting from 0.

IDL Definition
interface NodeList {
  Node               item(in unsigned long index);
  readonly attribute unsigned long   length;
};

Attributes
length of type unsigned long, readonly
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

Node

The node at the indexth position in the NodeList, or null if that is not a valid index.

No Exceptions
Interface NamedNodeMap

Objects implementing the NamedNodeMap interface are used to represent collections of nodes that can be accessed by name. Note that NamedNodeMap does not inherit from NodeList; NamedNodeMaps are not maintained in any particular order. Objects contained in an object implementing NamedNodeMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a NamedNodeMap, and does not imply that the DOM specifies an order to these Nodes.

NamedNodeMap objects in the DOM are live.

IDL Definition
interface NamedNodeMap {
  Node               getNamedItem(in DOMString name);
  Node               setNamedItem(in Node arg)
                                        raises(DOMException);
  Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
  Node               item(in unsigned long index);
  readonly attribute unsigned long   length;
  // Introduced in DOM Level 2:
  Node               getNamedItemNS(in DOMString namespaceURI,
                                    in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Node               removeNamedItemNS(in DOMString namespaceURI,
                                       in DOMString localName)
                                        raises(DOMException);
};

Attributes
length of type unsigned long, readonly
The number of nodes in this map. The range of valid child node indices is 0 to length-1 inclusive.
Methods
getNamedItem
Retrieves a node specified by name.
Parameters
name of type DOMString
The nodeName of a node to retrieve.
Return Value

Node

A Node (of any type) with the specified nodeName, or null if it does not identify any node in this map.

No Exceptions
getNamedItemNS introduced in DOM Level 2
Retrieves a node specified by local name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to retrieve.
localName of type DOMString
The local name of the node to retrieve.
Return Value

Node

A Node (of any type) with the specified local name and namespace URI, or null if they do not identify any node in this map.

Exceptions

DOMException

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

item
Returns the indexth item in the map. If index is greater than or equal to the number of nodes in this map, this returns null.
Parameters
index of type unsigned long
Index into this map.
Return Value

Node

The node at the indexth position in the map, or null if that is not a valid index.

No Exceptions
removeNamedItem
Removes a node specified by name. When this map contains the attributes attached to an element, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Parameters
name of type DOMString
The nodeName of the node to remove.
Return Value

Node

The node removed from this map if a node with such a name exists.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node named name in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

removeNamedItemNS introduced in DOM Level 2
Removes a node specified by local name and namespace URI. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the Node interface. If so, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to remove.
localName of type DOMString
The local name of the node to remove.
Return Value

Node

The node removed from this map if a node with such a local name and namespace URI exists.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node with the specified namespaceURI and localName in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

setNamedItem
Adds a node using its nodeName attribute. If a node with that name is already present in this map, it is replaced by the new one. Replacing a node by itself has no effect.
As the nodeName attribute is used to derive the name which the node must be stored under, multiple nodes of certain types (those that have a "special" string value) cannot be stored as the names would clash. This is seen as preferable to allowing nodes to be aliased.
Parameters
arg of type Node
A node to store in this map. The node will later be accessible using the value of its nodeName attribute.
Return Value

Node

If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this NamedNodeMap. Examples would include trying to insert something other than an Attr node into an Element's map of attributes, or a non-Entity node into the DocumentType's map of Entities.

setNamedItemNS introduced in DOM Level 2
Adds a node using its namespaceURI and localName. If a node with that namespace URI and that local name is already present in this map, it is replaced by the new one. Replacing a node by itself has no effect.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
arg of type Node
A node to store in this map. The node will later be accessible using the value of its namespaceURI and localName attributes.
Return Value

Node

If the new Node replaces an existing node the replaced Node is returned, otherwise null is returned.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different document than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

INUSE_ATTRIBUTE_ERR: Raised if arg is an Attr that is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this NamedNodeMap. Examples would include trying to insert something other than an Attr node into an Element's map of attributes, or a non-Entity node into the DocumentType's map of Entities.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

Interface CharacterData

The CharacterData interface extends Node with a set of attributes and methods for accessing character data in the DOM. For clarity this set is defined here rather than on each object that uses these attributes and methods. No DOM objects correspond directly to CharacterData, though Text and others do inherit the interface from it. All offsets in this interface start from 0.

As explained in the DOMString interface, text strings in the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In the following, the term 16-bit units is used whenever necessary to indicate that indexing on CharacterData is done in 16-bit units.

IDL Definition
interface CharacterData : Node {
           attribute DOMString       data;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

  readonly attribute unsigned long   length;
  DOMString          substringData(in unsigned long offset,
                                   in unsigned long count)
                                        raises(DOMException);
  void               appendData(in DOMString arg)
                                        raises(DOMException);
  void               insertData(in unsigned long offset,
                                in DOMString arg)
                                        raises(DOMException);
  void               deleteData(in unsigned long offset,
                                in unsigned long count)
                                        raises(DOMException);
  void               replaceData(in unsigned long offset,
                                 in unsigned long count,
                                 in DOMString arg)
                                        raises(DOMException);
};

Attributes
data of type DOMString
The character data of the node that implements this interface. The DOM implementation may not put arbitrary limits on the amount of data that may be stored in a CharacterData node. However, implementation limits may mean that the entirety of a node's data may not fit into a single DOMString. In such cases, the user may call substringData to retrieve the data in appropriately sized pieces.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

Exceptions on retrieval

DOMException

DOMSTRING_SIZE_ERR: Raised when it would return more characters than fit in a DOMString variable on the implementation platform.

length of type unsigned long, readonly
The number of 16-bit units that are available through data and the substringData method below. This may have the value zero, i.e., CharacterData nodes may be empty.
Methods
appendData
Append the string to the end of the character data of the node. Upon success, data provides access to the concatenation of data and the DOMString specified.
Parameters
arg of type DOMString
The DOMString to append.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
deleteData
Remove a range of 16-bit units from the node. Upon success, data and length reflect the change.
Parameters
offset of type unsigned long
The offset from which to start removing.
count of type unsigned long
The number of 16-bit units to delete. If the sum of offset and count exceeds length then all 16-bit units from offset to the end of the data are deleted.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
insertData
Insert a string at the specified 16-bit unit offset.
Parameters
offset of type unsigned long
The character offset at which to insert.
arg of type DOMString
The DOMString to insert.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
replaceData
Replace the characters starting at the specified 16-bit unit offset with the specified string.
Parameters
offset of type unsigned long
The offset from which to start replacing.
count of type unsigned long
The number of 16-bit units to replace. If the sum of offset and count exceeds length, then all 16-bit units to the end of the data are replaced; (i.e., the effect is the same as a remove method call with the same range, followed by an append method invocation).
arg of type DOMString
The DOMString with which the range must be replaced.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
substringData
Extracts a range of data from the node.
Parameters
offset of type unsigned long
Start offset of substring to extract.
count of type unsigned long
The number of 16-bit units to extract.
Return Value

DOMString

The specified substring. If the sum of offset and count exceeds the length, then all 16-bit units to the end of the data are returned.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

DOMSTRING_SIZE_ERR: Raised if the specified range of text does not fit into a DOMString.

Interface Attr

The Attr interface represents an attribute in an Element object. Typically the allowable values for the attribute are defined in a schema associated with the document.

Attr objects inherit the Node interface, but since they are not actually child nodes of the element they describe, the DOM does not consider them part of the document tree. Thus, the Node attributes parentNode, previousSibling, and nextSibling have a null value for Attr objects. The DOM takes the view that attributes are properties of elements rather than having a separate identity from the elements they are associated with; this should make it more efficient to implement such features as default attributes associated with all elements of a given type. Furthermore, Attr nodes may not be immediate children of a DocumentFragment. However, they can be associated with Element nodes contained within a DocumentFragment. In short, users and implementors of the DOM need to be aware that Attr nodes have some things in common with other objects inheriting the Node interface, but they also are quite distinct.

The attribute's effective value is determined as follows: if this attribute has been explicitly assigned any value, that value is the attribute's effective value; otherwise, if there is a declaration for this attribute, and that declaration includes a default value, then that default value is the attribute's effective value; otherwise, the attribute does not exist on this element in the structure model until it has been explicitly added. Note that the Node.nodeValue attribute on the Attr instance can also be used to retrieve the string version of the attribute's value(s).

If the attribute was not explicitly given a value in the instance document but has a default value provided by the schema associated with the document, an attribute node will be created with specified set to false. Removing attribute nodes for which a default value is defined in the schema generates a new attribute node with the default value and specified set to false. If validation occurred while invoking Document.normalizeDocument(), attribute nodes with specified equals to false are recomputed according to the default attribute values provided by the schema. If no default value is associate with this attribute in the schema, the attribute node is discarded.

In XML, where the value of an attribute can contain entity references, the child nodes of the Attr node may be either Text or EntityReference nodes (when these are in use; see the description of EntityReference for discussion).

The DOM Core represents all attribute values as simple strings, even if the DTD or schema associated with the document declares them of some specific type such as tokenized.

The way attribute value normalization is performed by the DOM implementation depends on how much the implementation knows about the schema in use. Typically, the value and nodeValue attributes of an Attr node initially returns the normalized value given by the parser. It is also the case after Document.normalizeDocument() is called (assuming the right options have been set). But this may not be the case after mutation, independently of whether the mutation is performed by setting the string value directly or by changing the Attr child nodes. In particular, this is true when character references are involved, given that they are not represented in the DOM and they impact attribute value normalization. On the other hand, if the implementation knows about the schema in use when the attribute value is changed, and it is of a different type than CDATA, it may normalize it again at that time. This is especially true of specialized DOM implementations, such as SVG DOM implementations, which store attribute values in an internal form different from a string.

The following table gives some examples of the relations between the attribute value in the original document (parsed attribute), the value as exposed in the DOM, and the serialization of the value:

Examples Parsed attribute value Initial Attr.value Serialized attribute value
Character reference
"x&#178;=5"

"x²=5"

"x&#178;=5"
Built-in character entity
"y&lt;6"

"y<6"

"y&lt;6"
Literal newline between
"x=5&#10;y=6"

"x=5
y=6"

"x=5&#10;y=6"
Normalized newline between
"x=5
y=6"

"x=5 y=6"

"x=5 y=6"
Entity e with literal newline
<!ENTITY e
'...&#10;...'>
[...]>
"x=5&e;y=6"
 Dependent on Implementation and Load Options Dependent on Implementation and Load/Save Options

IDL Definition
interface Attr : Node {
  readonly attribute DOMString       name;
  readonly attribute boolean         specified;
           attribute DOMString       value;
                                        // raises(DOMException) on setting

  // Introduced in DOM Level 2:
  readonly attribute Element         ownerElement;
  // Introduced in DOM Level 3:
  readonly attribute TypeInfo        schemaTypeInfo;
  // Introduced in DOM Level 3:
  readonly attribute boolean         isId;
};

Attributes
isId of type boolean, readonly, introduced in DOM Level 3
Returns whether this attribute is known to be of type ID (i.e. to contain an identifier for its owner element) or not. When it is and its value is unique, the ownerElement of this attribute can be retrieved using the method Document.getElementById. The implementation could use several ways to determine if an attribute node is known to contain an identifier:
  • If validation occurred using an XML Schema [XML Schema Part 1] while loading the document or while invoking Document.normalizeDocument(), the post-schema-validation infoset contributions (PSVI contributions) values are used to determine if this attribute is a schema-determined ID attribute using the schema-determined ID definition in [XPointer].
  • If validation occurred using a DTD while loading the document or while invoking Document.normalizeDocument(), the infoset [type definition] value is used to determine if this attribute is a DTD-determined ID attribute using the DTD-determined ID definition in [XPointer].
  • from the use of the methods Element.setIdAttribute(), Element.setIdAttributeNS(), or Element.setIdAttributeNode(), i.e. it is an user-determined ID attribute;

    Note: XPointer framework (see section 3.2 in [XPointer]) consider the DOM user-determined ID attribute as being part of the XPointer externally-determined ID definition.

  • using mechanisms that are outside the scope of this specification, it is then an externally-determined ID attribute. This includes using schema languages different from XML schema and DTD.

If validation occurred while invoking Document.normalizeDocument(), all user-determined ID attributes are reset and all attribute nodes ID information are then reevaluated in accordance to the schema used. As a consequence, if the Attr.schemaTypeInfo attribute contains an ID type, isId will always return true.
name of type DOMString, readonly
Returns the name of this attribute. If Node.localName is different from null, this attribute is a qualified name.
ownerElement of type Element, readonly, introduced in DOM Level 2
The Element node this attribute is attached to or null if this attribute is not in use.
schemaTypeInfo of type TypeInfo, readonly, introduced in DOM Level 3
The type information associated with this attribute. While the type information contained in this attribute is guarantee to be correct after loading the document or invoking Document.normalizeDocument(), schemaTypeInfo may not be reliable if the node was moved.
specified of type boolean, readonly
True if this attribute was explicitly given a value in the instance document, false otherwise. If the application changed the value of this attribute node (even if it ends up having the same value as the default value) then it is set to true. The implementation may handle attributes with default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
value of type DOMString
On retrieval, the value of the attribute is returned as a string. Character and general entity references are replaced with their values. See also the method getAttribute on the Element interface.
On setting, this creates a Text node with the unparsed contents of the string, i.e. any characters that an XML processor would recognize as markup are instead treated as literal text. See also the method Element.setAttribute().
Some specialized implementations, such as some [SVG 1.1] implementations, may do normalization automatically, even after mutation; in such case, the value on retrieval may differ from the value on setting.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

Interface Element

The Element interface represents an element in an HTML or XML document. Elements may have attributes associated with them; since the Element interface inherits from Node, the generic Node interface attribute attributes may be used to retrieve the set of all attributes for an element. There are methods on the Element interface to retrieve either an Attr object by name or an attribute value by name. In XML, where an attribute value may contain entity references, an Attr object should be retrieved to examine the possibly fairly complex sub-tree representing the attribute value. On the other hand, in HTML, where all attributes have simple string values, methods to directly access an attribute value can safely be used as a convenience.

Note: In DOM Level 2, the method normalize is inherited from the Node interface where it was moved.

IDL Definition
interface Element : Node {
  readonly attribute DOMString       tagName;
  DOMString          getAttribute(in DOMString name);
  void               setAttribute(in DOMString name,
                                  in DOMString value)
                                        raises(DOMException);
  void               removeAttribute(in DOMString name)
                                        raises(DOMException);
  Attr               getAttributeNode(in DOMString name);
  Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
  Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
  NodeList           getElementsByTagName(in DOMString name);
  // Introduced in DOM Level 2:
  DOMString          getAttributeNS(in DOMString namespaceURI,
                                    in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  void               setAttributeNS(in DOMString namespaceURI,
                                    in DOMString qualifiedName,
                                    in DOMString value)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  void               removeAttributeNS(in DOMString namespaceURI,
                                       in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Attr               getAttributeNodeNS(in DOMString namespaceURI,
                                        in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                            in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 2:
  boolean            hasAttribute(in DOMString name);
  // Introduced in DOM Level 2:
  boolean            hasAttributeNS(in DOMString namespaceURI,
                                    in DOMString localName)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  readonly attribute TypeInfo        schemaTypeInfo;
  // Introduced in DOM Level 3:
  void               setIdAttribute(in DOMString name,
                                    in boolean isId)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  void               setIdAttributeNS(in DOMString namespaceURI,
                                      in DOMString localName,
                                      in boolean isId)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  void               setIdAttributeNode(in Attr idAttr,
                                        in boolean isId)
                                        raises(DOMException);
};

Attributes
schemaTypeInfo of type TypeInfo, readonly, introduced in DOM Level 3
The type information associated with this element.
tagName of type DOMString, readonly
The name of the element. If Node.localName is different from null, this attribute is a qualified name. For example, in:
          <elementExample id="demo">
          ...
          </elementExample> ,
tagName has the value "elementExample". Note that this is case-preserving in XML, as are all of the operations of the DOM. The HTML DOM returns the tagName of an HTML element in the canonical uppercase form, regardless of the case in the source HTML document.
Methods
getAttribute
Retrieves an attribute value by name.
Parameters
name of type DOMString
The name of the attribute to retrieve.
Return Value

DOMString

The Attr value as a string, or the empty string if that attribute does not have a specified or default value.

No Exceptions
getAttributeNS introduced in DOM Level 2
Retrieves an attribute value by local name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value

DOMString

The Attr value as a string, or the empty string if that attribute does not have a specified or default value.

Exceptions

DOMException

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

getAttributeNode
Retrieves an attribute node by name.
To retrieve an attribute node by qualified name and namespace URI, use the getAttributeNodeNS method.
Parameters
name of type DOMString
The name (nodeName) of the attribute to retrieve.
Return Value

Attr

The Attr node with the specified name (nodeName) or null if there is no such attribute.

No Exceptions
getAttributeNodeNS introduced in DOM Level 2
Retrieves an Attr node by local name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to retrieve.
localName of type DOMString
The local name of the attribute to retrieve.
Return Value

Attr

The Attr node with the specified attribute local name and namespace URI or null if there is no such attribute.

Exceptions

DOMException

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

getElementsByTagName
Returns a NodeList of all descendant Elements with a given tag name, in document order.
Parameters
name of type DOMString
The name of the tag to match on. The special value "*" matches all tags.
Return Value

NodeList

A list of matching Element nodes.

No Exceptions
getElementsByTagNameNS introduced in DOM Level 2
Returns a NodeList of all the descendant Elements with a given local name and namespace URI in document order.
Parameters
namespaceURI of type DOMString
The namespace URI of the elements to match on. The special value "*" matches all namespaces.
localName of type DOMString
The local name of the elements to match on. The special value "*" matches all local names.
Return Value

NodeList

A new NodeList object containing all the matched Elements.

Exceptions

DOMException

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

hasAttribute introduced in DOM Level 2
Returns true when an attribute with a given name is specified on this element or has a default value, false otherwise.
Parameters
name of type DOMString
The name of the attribute to look for.
Return Value

boolean

true if an attribute with the given name is specified on this element or has a default value, false otherwise.

No Exceptions
hasAttributeNS introduced in DOM Level 2
Returns true when an attribute with a given local name and namespace URI is specified on this element or has a default value, false otherwise.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to look for.
localName of type DOMString
The local name of the attribute to look for.
Return Value

boolean

true if an attribute with the given local name and namespace URI is specified or has a default value on this element, false otherwise.

Exceptions

DOMException

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

removeAttribute
Removes an attribute by name. If a default value for the removed attribute is defined in the DTD, a new attribute immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
If no attribute with this name is found, this method has no effect.
To remove an attribute by local name and namespace URI, use the removeAttributeNS method.
Parameters
name of type DOMString
The name of the attribute to remove.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
removeAttributeNS introduced in DOM Level 2
Removes an attribute by local name and namespace URI. If a default value for the removed attribute is defined in the DTD, a new attribute immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
If no attribute with this local name and namespace URI is found, this method has no effect.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to remove.
localName of type DOMString
The local name of the attribute to remove.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

No Return Value
removeAttributeNode
Removes the specified attribute node. If a default value for the removed Attr node is defined in the DTD, a new node immediately appears with the default value as well as the corresponding namespace URI, local name, and prefix when applicable. The implementation may handle default values from other schemas similarly but applications should use Document.normalizeDocument() to guarantee this information is up-to-date.
Parameters
oldAttr of type Attr
The Attr node to remove from the attribute list.
Return Value

Attr

The Attr node that was removed.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if oldAttr is not an attribute of the element.

setAttribute
Adds a new attribute. If an attribute with that name is already present in the element, its value is changed to be that of the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNode to assign it as the value of an attribute.
To set an attribute with a qualified name and namespace URI, use the setAttributeNS method.
Parameters
name of type DOMString
The name of the attribute to create or alter.
value of type DOMString
Value to set in string form.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

No Return Value
setAttributeNS introduced in DOM Level 2
Adds a new attribute. If an attribute with the same local name and namespace URI is already present on the element, its prefix is changed to be the prefix part of the qualifiedName, and its value is changed to be the value parameter. This value is a simple string; it is not parsed as it is being set. So any markup (such as syntax to be recognized as an entity reference) is treated as literal text, and needs to be appropriately escaped by the implementation when it is written out. In order to assign an attribute value that contains entity references, the user must create an Attr node plus any Text and EntityReference nodes, build the appropriate subtree, and use setAttributeNodeNS or setAttributeNode to assign it as the value of an attribute.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to create or alter.
qualifiedName of type DOMString
The qualified name of the attribute to create or alter.
value of type DOMString
The value to set in string form.

Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified qualified name is not an XML name according to the XML version in use specified in the Document.xmlVersion attribute.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NAMESPACE_ERR: Raised if the qualifiedName is malformed per the Namespaces in XML specification, if the qualifiedName has a prefix and the namespaceURI is null, if the qualifiedName has a prefix that is "xml" and the namespaceURI is different from "http://www.w3.org/XML/1998/namespace", if the qualifiedName or its prefix is "xmlns" and the namespaceURI is different from "http://www.w3.org/2000/xmlns/", or if the namespaceURI is "http://www.w3.org/2000/xmlns/" and neither the qualifiedName nor its prefix is "xmlns".

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

No Return Value
setAttributeNode
Adds a new attribute node. If an attribute with that name (nodeName) is already present in the element, it is replaced by the new one. Replacing an attribute node by itself has no effect.
To add a new attribute node with a qualified name and namespace URI, use the setAttributeNodeNS method.
Parameters
newAttr of type Attr
The Attr node to add to the attribute list.
Return Value

Attr

If the newAttr attribute replaces an existing attribute, the replaced Attr node is returned, otherwise null is returned.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

setAttributeNodeNS introduced in DOM Level 2
Adds a new attribute. If an attribute with that local name and that namespace URI is already present in the element, it is replaced by the new one. Replacing an attribute node by itself has no effect.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
newAttr of type Attr
The Attr node to add to the attribute list.
Return Value

Attr

If the newAttr attribute replaces an existing attribute with the same local name and namespace URI, the replaced Attr node is returned, otherwise null is returned.

Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if newAttr was created from a different document than the one that created the element.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

INUSE_ATTRIBUTE_ERR: Raised if newAttr is already an attribute of another Element object. The DOM user must explicitly clone Attr nodes to re-use them in other elements.

NOT_SUPPORTED_ERR: May be raised if the implementation does not support the feature "XML" and the language exposed through the Document does not support XML Namespaces (such as [HTML 4.01]).

setIdAttribute introduced in DOM Level 3
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute. This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.
To specify an attribute by local name and namespace URI, use the setIdAttributeNS method.
Parameters
name of type DOMString
The name of the attribute.
isId of type boolean
Whether the attribute is a of type ID.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.

No Return Value
setIdAttributeNS introduced in DOM Level 3
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute. This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute.
localName of type DOMString
The local name of the attribute.
isId of type boolean
Whether the attribute is a of type ID.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.

No Return Value
setIdAttributeNode introduced in DOM Level 3
If the parameter isId is true, this method declares the specified attribute to be a user-determined ID attribute. This affects the value of Attr.isId and the behavior of Document.getElementById, but does not change any schema that may be in use, in particular this does not affect the Attr.schemaTypeInfo of the specified Attr node. Use the value false for the parameter isId to undeclare an attribute for being a user-determined ID attribute.
Parameters
idAttr of type Attr
The attribute node.
isId of type boolean
Whether the attribute is a of type ID.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

NOT_FOUND_ERR: Raised if the specified node is not an attribute of this element.

No Return Value
Interface Text

The Text interface inherits from CharacterData and represents the textual content (termed character data in XML) of an Element or Attr. If there is no markup inside an element's content, the text is contained in a single object implementing the Text interface that is the only child of the element. If there is markup, it is parsed into the information items (elements, comments, etc.) and Text nodes that form the list of children of the element.

When a document is first made available via the DOM, there is only one Text node for each block of text. Users may create adjacent Text nodes that represent the contents of a given element without any intervening markup, but should be aware that there is no way to represent the separations between these nodes in XML or HTML, so they will not (in general) persist between DOM editing sessions. The Node.normalize() method merges any such adjacent Text objects into a single node for each block of text.

No lexical check is done on the content of a Text node and, depending on its position in the document, some characters must be escaped during serialization using character references; e.g. the characters "<&" if the textual content is part of an element or of an attribute, the character sequence "]]>" when part of an element, the quotation mark character " or the apostrophe character ' when part of an attribute.

IDL Definition
interface Text : CharacterData {
  Text               splitText(in unsigned long offset)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  readonly attribute boolean         isElementContentWhitespace;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       wholeText;
  // Introduced in DOM Level 3:
  Text               replaceWholeText(in DOMString content)
                                        raises(DOMException);
};

Attributes
isElementContentWhitespace of type boolean, readonly, introduced in DOM Level 3
Returns whether this text node contains element content whitespace, often abusively called "ignorable whitespace". The text node is determined to contain whitespace in element content during the load of the document or if validation occurs while using Document.normalizeDocument().
wholeText of type DOMString, readonly, introduced in DOM Level 3
Returns all text of Text nodes logically-adjacent text nodes to this node, concatenated in document order.
For instance, in the example below wholeText on the Text node that contains "bar" returns "barfoo", while on the Text node that contains "foo" it returns "barfoo".
barTextNode.wholeText value is "barfoo"

Figure: barTextNode.wholeText value is "barfoo" [SVG 1.0 version]

Methods
replaceWholeText introduced in DOM Level 3
Replaces the text of the current node and all logically-adjacent text nodes with the specified text. All logically-adjacent text nodes are removed including the current node unless it was the recipient of the replacement text.
This method returns the node which received the replacement text. The returned node is:
  • null, when the replacement text is the empty string;
  • the current node, except when the current node is read-only;
  • a new Text node of the same type (Text or CDATASection) as the current node inserted at the location of the replacement.

For instance, in the above example calling replaceWholeText on the Text node that contains "bar" with "yo" in argument results in the following:
barTextNode.replaceWholeText("yo") modifies the textual content of barTextNode with "yo"

Figure: barTextNode.replaceWholeText("yo") modifies the textual content of barTextNode with "yo" [SVG 1.0 version]

Where the nodes to be removed are read-only descendants of an EntityReference, the EntityReference must be removed instead of the read-only nodes. If any EntityReference to be removed has descendants that are not EntityReference, Text, or CDATASection nodes, the replaceWholeText method must fail before performing any modification of the document, raising a DOMException with the code NO_MODIFICATION_ALLOWED_ERR.
For instance, in the example below calling replaceWholeText on the Text node that contains "bar" fails, because the EntityReference node "ent" contains an Element node which cannot be removed.
barTextNode.replaceWholeText("yo") raises a NO_MODIFICATION_ALLOWED_ERR DOMException

Figure: barTextNode.replaceWholeText("yo") raises a NO_MODIFICATION_ALLOWED_ERR DOMException [SVG 1.0 version]

Parameters
content of type DOMString
The content of the replacing Text node.
Return Value

Text

The Text node created with the specified content.

Exceptions

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised if one of the Text nodes being replaced is readonly.

splitText
Breaks this node into two nodes at the specified offset, keeping both in the tree as siblings. After being split, this node will contain all the content up to the offset point. A new node of the same type, which contains all the content at and after the offset point, is returned. If the original node had a parent node, the new node is inserted as the next sibling of the original node. When the offset is equal to the length of this node, the new node has no data.
Parameters
offset of type unsigned long
The 16-bit unit offset at which to split, starting from 0.
Return Value

Text

The new node, of the same type as this node.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.

NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

Interface Comment

This interface inherits from CharacterData and represents the content of a comment, i.e., all the characters between the starting '<!--' and ending '-->'. Note that this is the definition of a comment in XML, and, in practice, HTML, although some HTML tools may implement the full SGML comment structure.

No lexical check is done on the content of a comment and it is therefore possible to have the character sequence "--" (double-hyphen) in the content, which is illegal in a comment per section 2.5 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization.

IDL Definition
interface Comment : CharacterData {
};

Interface TypeInfo (introduced in DOM Level 3)

The TypeInfo interface represents a type referenced from Element or Attr nodes, specified in the schemas associated with the document. The type is a pair of a namespace URI and name properties, and depends on the document's schema.

If the document's schema is an XML DTD [XML 1.0], the values are computed as follows:

  • If this type is referenced from an Attr node, typeNamespace is "http://www.w3.org/TR/REC-xml" and typeName represents the [attribute type] property in the [XML Information Set]. If there is no declaration for the attribute, typeNamespace and typeName are null.
  • If this type is referenced from an Element node, typeNamespace and typeName are null.

If the document's schema is an XML Schema [XML Schema Part 1], the values are computed as follows using the post-schema-validation infoset contributions (also called PSVI contributions):

  • If the [validity] property exists AND is "invalid" or "notKnown": the {target namespace} and {name} properties of the declared type if available, otherwise null.

    Note: At the time of writing, the XML Schema specification does not require exposing the declared type. Thus, DOM implementations might choose not to provide type information if validity is not valid.

  • If the [validity] property exists and is "valid":
    1. If [member type definition] exists:
      1. If {name} is not absent, then expose {name} and {target namespace} properties of the [member type definition] property;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    2. If the [type definition] property exists:
      1. If {name} is not absent, then expose {name} and {target namespace} properties of the [type definition] property;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    3. If the [member type definition anonymous] exists:
      1. If it is false, then expose [member type definition name] and [member type definition namespace] properties;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.
    4. If the [type definition anonymous] exists:
      1. If it is false, then expose [type definition name] and [type definition namespace] properties;
      2. Otherwise, expose the namespace and local name of the corresponding anonymous type name.

Note: Other schema languages are outside the scope of the W3C and therefore should define how to represent their type systems using TypeInfo.

IDL Definition
// Introduced in DOM Level 3:
interface TypeInfo {
  readonly attribute DOMString       typeName;
  readonly attribute DOMString       typeNamespace;

  // DerivationMethods
  const unsigned long       DERIVATION_RESTRICTION         = 0x00000001;
  const unsigned long       DERIVATION_EXTENSION           = 0x00000002;
  const unsigned long       DERIVATION_UNION               = 0x00000004;
  const unsigned long       DERIVATION_LIST                = 0x00000008;

  boolean            isDerivedFrom(in DOMString typeNamespaceArg,
                                   in DOMString typeNameArg,
                                   in unsigned long derivationMethod);
};

Definition group DerivationMethods

These are the available values for the derivationMethod parameter used by the method TypeInfo.isDerivedFrom(). It is a set of possible types of derivation, and the values represent bit positions. If a bit in the derivationMethod parameter is set to 1, the corresponding type of derivation will be taken into account when evaluating the derivation between the reference type definition and the other type definition. When using the isDerivedFrom method, combining all of them in the derivationMethod parameter is equivalent to invoking the method for each of them separately and combining the results with the OR boolean function. This specification only defines the type of derivation for XML Schema.

In addition to the types of derivation listed below, please note that:

  • any type derives from xsd:anyType.
  • any simple type derives from xsd:anySimpleType by restriction.
  • any complex type does not derive from xsd:anySimpleType by restriction.
Defined Constants
DERIVATION_EXTENSION
If the document's schema is an XML Schema [XML Schema Part 1], this constant represents the derivation by extension.
The reference type definition is derived by extension from the other type definition if the other type definition can be reached recursively following the {base type definition} property from the reference type definition, and at least one of the derivation methods involved is an extension.
DERIVATION_LIST
If the document's schema is an XML Schema [XML Schema Part 1], this constant represents the list.
The reference type definition is derived by list from the other type definition if there exists two type definitions T1 and T2 such as the reference type definition is derived from T1 by DERIVATION_RESTRICTION or DERIVATION_EXTENSION, T2 is derived from the other type definition by DERIVATION_RESTRICTION, T1 has {variety} list, and T2 is the {item type definition}. Note that T1 could be the same as the reference type definition, and T2 could be the same as the other type definition.
DERIVATION_RESTRICTION
If the document's schema is an XML Schema [XML Schema Part 1], this constant represents the derivation by restriction if complex types are involved, or a restriction if simple types are involved.
The reference type definition is derived by restriction from the other type definition if the other type definition is the same as the reference type definition, or if the other type definition can be reached recursively following the {base type definition} property from the reference type definition, and all the derivation methods involved are restriction.
DERIVATION_UNION
If the document's schema is an XML Schema [XML Schema Part 1], this constant represents the union if simple types are involved.
The reference type definition is derived by union from the other type definition if there exists two type definitions T1 and T2 such as the reference type definition is derived from T1 by DERIVATION_RESTRICTION or DERIVATION_EXTENSION, T2 is derived from the other type definition by DERIVATION_RESTRICTION, T1 has {variety} union, and one of the {member type definitions} is T2. Note that T1 could be the same as the reference type definition, and T2 could be the same as the other type definition.
Attributes
typeName of type DOMString, readonly
The name of a type declared for the associated element or attribute, or null if unknown.
typeNamespace of type DOMString, readonly
The namespace of the type declared for the associated element or attribute or null if the element does not have declaration or if no namespace information is available.
Methods
isDerivedFrom
This method returns if there is a derivation between the reference type definition, i.e. the TypeInfo on which the method is being called, and the other type definition, i.e. the one passed as parameters.
Parameters
typeNamespaceArg of type DOMString
the namespace of the other type definition.
typeNameArg of type DOMString
the name of the other type definition.
derivationMethod of type unsigned long
the type of derivation and conditions applied between two types, as described in the list of constants provided in this interface.
Return Value

boolean

If the document's schema is a DTD or no schema is associated with the document, this method will always return false.
If the document's schema is an XML Schema, the method will true if the reference type definition is derived from the other type definition according to the derivation parameter. If the value of the parameter is 0 (no bit is set to 1 for the derivationMethod parameter), the method will return true if the other type definition can be reached by recursing any combination of {base type definition}, {item type definition}, or {member type definitions} from the reference type definition.

No Exceptions
Interface UserDataHandler (introduced in DOM Level 3)

When associating an object to a key on a node using Node.setUserData() the application can provide a handler that gets called when the node the object is associated to is being cloned, imported, or renamed. This can be used by the application to implement various behaviors regarding the data it associates to the DOM nodes. This interface defines that handler.

IDL Definition
// Introduced in DOM Level 3:
interface UserDataHandler {

  // OperationType
  const unsigned short      NODE_CLONED                    = 1;
  const unsigned short      NODE_IMPORTED                  = 2;
  const unsigned short      NODE_DELETED                   = 3;
  const unsigned short      NODE_RENAMED                   = 4;
  const unsigned short      NODE_ADOPTED                   = 5;

  void               handle(in unsigned short operation,
                            in DOMString key,
                            in DOMUserData data,
                            in Node src,
                            in Node dst);
};

Definition group OperationType

An integer indicating the type of operation being performed on a node.

Defined Constants
NODE_ADOPTED
The node is adopted, using Document.adoptNode().
NODE_CLONED
The node is cloned, using Node.cloneNode().
NODE_DELETED
The node is deleted.

Note: This may not be supported or may not be reliable in certain environments, such as Java, where the implementation has no real control over when objects are actually deleted.

NODE_IMPORTED
The node is imported, using Document.importNode().
NODE_RENAMED
The node is renamed, using Document.renameNode().
Methods
handle
This method is called whenever the node for which this handler is registered is imported or cloned.
DOM applications must not raise exceptions in a UserDataHandler. The effect of throwing exceptions from the handler is DOM implementation dependent.
Parameters
operation of type unsigned short
Specifies the type of operation that is being performed on the node.
key of type DOMString
Specifies the key for which this handler is being called.
data of type DOMUserData
Specifies the data for which this handler is being called.
src of type Node
Specifies the node being cloned, adopted, imported, or renamed. This is null when the node is being deleted.
dst of type Node
Specifies the node newly created if any, or null.

No Return Value
No Exceptions
Interface DOMError (introduced in DOM Level 3)

DOMError is an interface that describes an error.

IDL Definition
// Introduced in DOM Level 3:
interface DOMError {

  // ErrorSeverity
  const unsigned short      SEVERITY_WARNING               = 1;
  const unsigned short      SEVERITY_ERROR                 = 2;
  const unsigned short      SEVERITY_FATAL_ERROR           = 3;

  readonly attribute unsigned short  severity;
  readonly attribute DOMString       message;
  readonly attribute DOMString       type;
  readonly attribute DOMObject       relatedException;
  readonly attribute DOMObject       relatedData;
  readonly attribute DOMLocator      location;
};

Definition group ErrorSeverity

An integer indicating the severity of the error.

Defined Constants
SEVERITY_ERROR
The severity of the error described by the DOMError is error. A SEVERITY_ERROR may not cause the processing to stop if the error can be recovered, unless DOMErrorHandler.handleError() returns false.
SEVERITY_FATAL_ERROR
The severity of the error described by the DOMError is fatal error. A SEVERITY_FATAL_ERROR will cause the normal processing to stop. The return value of DOMErrorHandler.handleError() is ignored unless the implementation chooses to continue, in which case the behavior becomes undefined.
SEVERITY_WARNING
The severity of the error described by the DOMError is warning. A SEVERITY_WARNING will not cause the processing to stop, unless DOMErrorHandler.handleError() returns false.
Attributes
location of type DOMLocator, readonly
The location of the error.
message of type DOMString, readonly
An implementation specific string describing the error that occurred.
relatedData of type DOMObject, readonly
The related DOMError.type dependent data if any.
relatedException of type DOMObject, readonly
The related platform dependent exception if any.
severity of type unsigned short, readonly
The severity of the error, either SEVERITY_WARNING, SEVERITY_ERROR, or SEVERITY_FATAL_ERROR.
type of type DOMString, readonly
A DOMString indicating which related data is expected in relatedData. Users should refer to the specification of the error in order to find its DOMString type and relatedData definitions if any.

Note: As an example, Document.normalizeDocument() does generate warnings when the "split-cdata-sections" parameter is in use. Therefore, the method generates a SEVERITY_WARNING with type "cdata-sections-splitted" and the first CDATASection node in document order resulting from the split is returned by the relatedData attribute.

Interface DOMErrorHandler (introduced in DOM Level 3)

DOMErrorHandler is a callback interface that the DOM implementation can call when reporting errors that happens while processing XML data, or when doing some other processing (e.g. validating a document). A DOMErrorHandler object can be attached to a Document using the "error-handler" on the DOMConfiguration interface. If more than one error needs to be reported during an operation, the sequence and numbers of the errors passed to the error handler are implementation dependent.

The application that is using the DOM implementation is expected to implement this interface.

IDL Definition
// Introduced in DOM Level 3:
interface DOMErrorHandler {
  boolean            handleError(in DOMError error);
};

Methods
handleError
This method is called on the error handler when an error occurs.
If an exception is thrown from this method, it is considered to be equivalent of returning true.
Parameters
error of type DOMError
The error object that describes the error. This object may be reused by the DOM implementation across multiple calls to the handleError method.
Return Value

boolean

If the handleError method returns false, the DOM implementation should stop the current processing when possible. If the method returns true, the processing may continue depending on DOMError.severity.

No Exceptions
Interface DOMLocator (introduced in DOM Level 3)

DOMLocator is an interface that describes a location (e.g. where an error occurred).

IDL Definition
// Introduced in DOM Level 3:
interface DOMLocator {
  readonly attribute long            lineNumber;
  readonly attribute long            columnNumber;
  readonly attribute long            byteOffset;
  readonly attribute long            utf16Offset;
  readonly attribute Node            relatedNode;
  readonly attribute DOMString       uri;
};

Attributes
byteOffset of type long, readonly
The byte offset into the input source this locator is pointing to or -1 if there is no byte offset available.
columnNumber of type long, readonly
The column number this locator is pointing to, or -1 if there is no column number available.
lineNumber of type long, readonly
The line number this locator is pointing to, or -1 if there is no column number available.
relatedNode of type Node, readonly
The node this locator is pointing to, or null if no node is available.
uri of type DOMString, readonly
The URI this locator is pointing to, or null if no URI is available.
utf16Offset of type long, readonly
The UTF-16, as defined in [Unicode] and Amendment 1 of [ISO/IEC 10646], offset into the input source this locator is pointing to or -1 if there is no UTF-16 offset available.
Interface DOMConfiguration (introduced in DOM Level 3)

The DOMConfiguration interface represents the configuration of a document and maintains a table of recognized parameters. Using the configuration, it is possible to change Document.normalizeDocument() behavior, such as replacing the CDATASection nodes with Text nodes or specifying the type of the schema that must be used when the validation of the Document is requested. DOMConfiguration objects are also used in [DOM Level 3 Load and Save] in the DOMParser and DOMSerializer interfaces.

The parameter names used by the DOMConfiguration object are defined throughout the DOM Level 3 specifications. Names are case-insensitive. To avoid possible conflicts, as a convention, names referring to parameters defined outside the DOM specification should be made unique. Because parameters are exposed as properties in the ECMAScript Language Binding, names are recommended to follow the section "5.16 Identifiers" of [Unicode] with the addition of the character '-' (HYPHEN-MINUS) but it is not enforced by the DOM implementation. DOM Level 3 Core Implementations are required to recognize all parameters defined in this specification. Some parameter values may also be required to be supported by the implementation. Refer to the definition of the parameter to know if a value must be supported or not.

Note: Parameters are similar to features and properties used in SAX2 [SAX].

The following list of parameters defined in the DOM:

"canonical-form"
true
[optional]
Canonicalize the document according to the rules specified in [Canonical XML], such as removing the DocumentType node (if any) from the tree, or removing superfluous namespace declarations from each element. Note that this is limited to what can be represented in the DOM; in particular, there is no way to specify the order of the attributes in the DOM. In addition,
Setting this parameter to true will also set the state of the parameters listed below. Later changes to the state of one of those parameters will revert "canonical-form" back to false.
Parameters set to false: "entities", "normalize-characters", "cdata-sections".
Parameters set to true: "namespaces", "namespace-declarations", "well-formed", "element-content-whitespace".
Other parameters are not changed unless explicitly specified in the description of the parameters.
false
[required] (default)
Do not canonicalize the document.
"cdata-sections"
true
[required] (default)
Keep CDATASection nodes in the document.
false
[required]
Transform CDATASection nodes in the document into Text nodes. The new Text node is then combined with any adjacent Text node.
"check-character-normalization"
true
[optional]
Check if the characters in the document are fully normalized, as defined in appendix B of [XML 1.1]. When a sequence of characters is encountered that fails normalization checking, an error with the DOMError.type equals to "check-character-normalization-failure" is issued.
false
[required] (default)
Do not check if characters are normalized.
"comments"
true
[required] (default)
Keep Comment nodes in the document.
false
[required]
Discard Comment nodes in the document.
"datatype-normalization"
true
[optional]
Expose schema normalized values in the tree, such as XML Schema normalized values in the case of XML Schema. Since this parameter requires to have schema information, the "validate" parameter will also be set to true. Having this parameter activated when "validate" is false has no effect and no schema-normalization will happen.

Note: Since the document contains the result of the XML 1.0 processing, this parameter does not apply to attribute value normalization as defined in section 3.3.3 of [XML 1.0] and is only meant for schema languages other than Document Type Definition (DTD).

false
[required] (default)
Do not perform schema normalization on the tree.
"element-content-whitespace"
true
[required] (default)
Keep all whitespaces in the document.
false
[optional]
Discard all Text nodes that contain whitespaces in element content, as described in [element content whitespace]. The implementation is expected to use the attribute Text.isElementContentWhitespace to determine if a Text node should be discarded or not.
"entities"
true
[required] (default)
Keep EntityReference nodes in the document.
false
[required]
Remove all EntityReference nodes from the document, putting the entity expansions directly in their place. Text nodes are normalized, as defined in Node.normalize. Only unexpanded entity references are kept in the document.

Note: This parameter does not affect Entity nodes.

"error-handler"
[required]
Contains a DOMErrorHandler object. If an error is encountered in the document, the implementation will call back the DOMErrorHandler registered using this parameter. The implementation may provide a default DOMErrorHandler object.
When called, DOMError.relatedData will contain the closest node to where the error occurred. If the implementation is unable to determine the node where the error occurs, DOMError.relatedData will contain the Document node. Mutations to the document from within an error handler will result in implementation dependent behavior.
"infoset"
true
[required]
Keep in the document the information defined in the XML Information Set [XML Information Set].
This forces the following parameters to false: "validate-if-schema", "entities", "datatype-normalization", "cdata-sections".
This forces the following parameters to true: "namespace-declarations", "well-formed", "element-content-whitespace", "comments", "namespaces".
Other parameters are not changed unless explicitly specified in the description of the parameters.
Note that querying this parameter with getParameter returns true only if the individual parameters specified above are appropriately set.
false
Setting infoset to false has no effect.
"namespaces"
true
[required] (default)
Perform the namespace processing as defined in Namespace Normalization.
false
[optional]
Do not perform the namespace processing.
"namespace-declarations"
This parameter has no effect if the parameter "namespaces" is set to false.
true
[required] (default)
Include namespace declaration attributes, specified or defaulted from the schema, in the document. See also the sections "Declaring Namespaces" in [XML Namespaces] and [XML Namespaces 1.1].
false
[required]
Discard all namespace declaration attributes. The namespace prefixes (Node.prefix) are retained even if this parameter is set to false.
"normalize-characters"
true
[optional]
Fully normalized the characters in the document as defined in appendix B of [XML 1.1].
false
[required] (default)
Do not perform character normalization.
"schema-location"
[optional]
Represent a DOMString object containing a list of URIs, separated by whitespaces (characters matching the nonterminal production S defined in section 2.3 [XML 1.0]), that represents the schemas against which validation should occur, i.e. the current schema. The types of schemas referenced in this list must match the type specified with schema-type, otherwise the behavior of an implementation is undefined.
The schemas specified using this property take precedence to the schema information specified in the document itself. For namespace aware schema, if a schema specified using this property and a schema specified in the document instance (i.e. using the schemaLocation attribute) in a schema document (i.e. using schema import mechanisms) share the same targetNamespace, the schema specified by the user using this property will be used. If two schemas specified using this property share the same targetNamespace or have no namespace, the behavior is implementation dependent.
If no location has been provided, this parameter is null.

Note: The "schema-location" parameter is ignored unless the "schema-type" parameter value is set. It is strongly recommended that Document.documentURI will be set so that an implementation can successfully resolve any external entities referenced.

"schema-type"
[optional]
Represent a DOMString object containing an absolute URI and representing the type of the schema language used to validate a document against. Note that no lexical checking is done on the absolute URI.
If this parameter is not set, a default value may be provided by the implementation, based on the schema languages supported and on the schema language used at load time. If no value is provided, this parameter is null.

Note: For XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.

"split-cdata-sections"
true
[required] (default)
Split CDATA sections containing the CDATA section termination marker ']]>'. When a CDATA section is split a warning is issued with a DOMError.type equals to "cdata-sections-splitted" and DOMError.relatedData equals to the first CDATASection node in document order resulting from the split.
false
[required]
Signal an error if a CDATASection contains an unrepresentable character.
"validate"
true
[optional]
Require the validation against a schema (i.e. XML schema, DTD, any other type or representation of schema) of the document as it is being normalized as defined by [XML 1.0]. If validation errors are found, or no schema was found, the error handler is notified. Schema-normalized values will not be exposed according to the schema in used unless the parameter "datatype-normalization" is true.
This parameter will reevaluate:
  • Attribute nodes with Attr.specified equals to false, as specified in the description of the Attr interface;
  • The value of the attribute Text.isElementContentWhitespace for all Text nodes;
  • The value of the attribute Attr.isId for all Attr nodes;
  • The attributes Element.schemaTypeInfo and Attr.schemaTypeInfo.

Note: "validate-if-schema" and "validate" are mutually exclusive, setting one of them to true will set the other one to false. Applications should also consider setting the parameter "well-formed" to true, which is the default for that option, when validating the document.

false
[required] (default)
Do not accomplish schema processing, including the internal subset processing. Default attribute values information are kept. Note that validation might still happen if "validate-if-schema" is true.
"validate-if-schema"
true
[optional]
Enable validation only if a declaration for the document element can be found in a schema (independently of where it is found, i.e. XML schema, DTD, or any other type or representation of schema). If validation is enabled, this parameter has the same behavior as the parameter "validate" set to true.

Note: "validate-if-schema" and "validate" are mutually exclusive, setting one of them to true will set the other one to false.

false
[required] (default)
No schema processing should be performed if the document has a schema, including internal subset processing. Default attribute values information are kept. Note that validation must still happen if "validate" is true.
"well-formed"
true
[required] (default)
Check if all nodes are XML well formed according to the XML version in use in Document.xmlVersion:
  • check if the attribute Node.nodeName contains invalid characters according to its node type and generate a DOMError of type "wf-invalid-character-in-node-name", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the text content inside Attr, Element, Comment, Text, CDATASection nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
  • check if the data inside ProcessingInstruction nodes for invalid characters and generate a DOMError of type "wf-invalid-character", with a DOMError.SEVERITY_ERROR severity, if necessary;
false
[optional]
Do not check for XML well-formedness.

The resolution of the system identifiers associated with entities is done using Document.documentURI. However, when the feature "LS" defined in [DOM Level 3 Load and Save] is supported by the DOM implementation, the parameter "resource-resolver" can also be used on DOMConfiguration objects attached to Document nodes. If this parameter is set, Document.normalizeDocument() will invoke the resource resolver instead of using Document.documentURI.

IDL Definition
// Introduced in DOM Level 3:
interface DOMConfiguration {
  void               setParameter(in DOMString name,
                                  in DOMUserData value)
                                        raises(DOMException);
  DOMUserData        getParameter(in DOMString name)
                                        raises(DOMException);
  boolean            canSetParameter(in DOMString name,
                                     in DOMUserData value);
  readonly attribute DOMStringList   parameterNames;
};

Attributes
parameterNames of type DOMStringList, readonly
The list of the parameters supported by this DOMConfiguration object and for which at least one value can be set by the application. Note that this list can also contain parameter names defined outside this specification.
Methods
canSetParameter
Check if setting a parameter to a specific value is supported.
Parameters
name of type DOMString
The name of the parameter to check.
value of type DOMUserData
An object. if null, the returned value is true.
Return Value

boolean

true if the parameter could be successfully set to the specified value, or false if the parameter is not recognized or the requested value is not supported. This does not change the current value of the parameter itself.

No Exceptions
getParameter
Return the value of a parameter if known.
Parameters
name of type DOMString
The name of the parameter.
Return Value

DOMUserData

The current object associated with the specified parameter or null if no object has been associated or if the parameter is not supported.

Exceptions

DOMException

NOT_FOUND_ERR: Raised when the parameter name is not recognized.

setParameter
Set the value of a parameter.
Parameters
name of type DOMString
The name of the parameter to set.
value of type DOMUserData
The new value or null if the user wishes to unset the parameter. While the type of the value parameter is defined as DOMUserData, the object type must match the type defined by the definition of the parameter. For example, if the parameter is "error-handler", the value must be of type DOMErrorHandler.
Exceptions

DOMException

NOT_FOUND_ERR: Raised when the parameter name is not recognized.

NOT_SUPPORTED_ERR: Raised when the parameter name is recognized but the requested value cannot be set.

TYPE_MISMATCH_ERR: Raised if the value type for this parameter name is incompatible with the expected value type.

No Return Value

1.5 Extended Interfaces: XML Module

The interfaces defined here form part of the DOM Core specification, but objects that expose these interfaces will never be encountered in a DOM implementation that deals only with HTML.

The interfaces found within this section are not mandatory. A DOM application may use the DOMImplementation.hasFeature(feature, version) method with parameter values "XML" and "3.0" (respectively) to determine whether or not this module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined in Fundamental Interfaces: Core Module and the feature "XMLVersion" with version "1.0" defined in Document.xmlVersion. Please refer to additional information about Conformance in this specification. The DOM Level 3 XML module is backward compatible with the DOM Level 2 XML [DOM Level 2 Core] and DOM Level 1 XML [DOM Level 1] modules, i.e. a DOM Level 3 XML implementation who returns true for "XML" with the version number "3.0" must also return true for this feature when the version number is "2.0", "1.0", "" or, null.

Interface CDATASection

CDATA sections are used to escape blocks of text containing characters that would otherwise be regarded as markup. The only delimiter that is recognized in a CDATA section is the "]]>" string that ends the CDATA section. CDATA sections cannot be nested. Their primary purpose is for including material such as XML fragments, without needing to escape all the delimiters.

The CharacterData.data attribute holds the text that is contained by the CDATA section. Note that this may contain characters that need to be escaped outside of CDATA sections and that, depending on the character encoding ("charset") chosen for serialization, it may be impossible to write out some characters as part of a CDATA section.

The CDATASection interface inherits from the CharacterData interface through the Text interface. Adjacent CDATASection nodes are not merged by use of the normalize method of the Node interface.

No lexical check is done on the content of a CDATA section and it is therefore possible to have the character sequence "]]>" in the content, which is illegal in a CDATA section per section 2.7 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization or the cdata section must be splitted before the serialization (see also the parameter "split-cdata-sections" in the DOMConfiguration interface).

Note: Because no markup is recognized within a CDATASection, character numeric references cannot be used as an escape mechanism when serializing. Therefore, action needs to be taken when serializing a CDATASection with a character encoding where some of the contained characters cannot be represented. Failure to do so would not produce well-formed XML.
One potential solution in the serialization process is to end the CDATA section before the character, output the character using a character reference or entity reference, and open a new CDATA section for any further characters in the text node. Note, however, that some code conversion libraries at the time of writing do not return an error or exception when a character is missing from the encoding, making the task of ensuring that data is not corrupted on serialization more difficult.

IDL Definition
interface CDATASection : Text {
};

Interface DocumentType

Each Document has a doctype attribute whose value is either null or a DocumentType object. The DocumentType interface in the DOM Core provides an interface to the list of entities that are defined for the document, and little else because the effect of namespaces and the various XML schema efforts on DTD representation are not clearly understood as of this writing.

DOM Level 3 doesn't support editing DocumentType nodes. DocumentType nodes are read-only.

IDL Definition
interface DocumentType : Node {
  readonly attribute DOMString       name;
  readonly attribute NamedNodeMap    entities;
  readonly attribute NamedNodeMap    notations;
  // Introduced in DOM Level 2:
  readonly attribute DOMString       publicId;
  // Introduced in DOM Level 2:
  readonly attribute DOMString       systemId;
  // Introduced in DOM Level 2:
  readonly attribute DOMString       internalSubset;
};

Attributes
entities of type NamedNodeMap, readonly
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Parameter entities are not contained. Duplicates are discarded. For example in:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY bar "bar2">
  <!ENTITY % baz "baz">
]>
<ex/>
the interface provides access to foo and the first declaration of bar but not the second declaration of bar or baz. Every node in this map also implements the Entity interface.
The DOM Level 2 does not support editing entities, therefore entities cannot be altered in any way.
internalSubset of type DOMString, readonly, introduced in DOM Level 2
The internal subset as a string, or null if there is none. This is does not contain the delimiting square brackets.

Note: The actual content returned depends on how much information is available to the implementation. This may vary depending on various parameters, including the XML processor used to build the document.

name of type DOMString, readonly
The name of DTD; i.e., the name immediately following the DOCTYPE keyword.
notations of type NamedNodeMap, readonly
A NamedNodeMap containing the notations declared in the DTD. Duplicates are discarded. Every node in this map also implements the Notation interface.
The DOM Level 2 does not support editing notations, therefore notations cannot be altered in any way.
publicId of type DOMString, readonly, introduced in DOM Level 2
The public identifier of the external subset.
systemId of type DOMString, readonly, introduced in DOM Level 2
The system identifier of the external subset. This may be an absolute URI or not.
Interface Notation

This interface represents a notation declared in the DTD. A notation either declares, by name, the format of an unparsed entity (see section 4.7 of the XML 1.0 specification [XML 1.0]), or is used for formal declaration of processing instruction targets (see section 2.6 of the XML 1.0 specification [XML 1.0]). The nodeName attribute inherited from Node is set to the declared name of the notation.

The DOM Core does not support editing Notation nodes; they are therefore readonly.

A Notation node does not have any parent.

IDL Definition
interface Notation : Node {
  readonly attribute DOMString       publicId;
  readonly attribute DOMString       systemId;
};

Attributes
publicId of type DOMString, readonly
The public identifier of this notation. If the public identifier was not specified, this is null.
systemId of type DOMString, readonly
The system identifier of this notation. If the system identifier was not specified, this is null. This may be an absolute URI or not.
Interface Entity

This interface represents a known entity, either parsed or unparsed, in an XML document. Note that this models the entity itself not the entity declaration.

The nodeName attribute that is inherited from Node contains the name of the entity.

An XML processor may choose to completely expand entities before the structure model is passed to the DOM; in this case there will be no EntityReference nodes in the document tree.

XML does not mandate that a non-validating XML processor read and process entity declarations made in the external subset or declared in parameter entities. This means that parsed entities declared in the external subset need not be expanded by some classes of applications, and that the replacement text of the entity may not be available. When the replacement text is available, the corresponding Entity node's child list represents the structure of that replacement value. Otherwise, the child list is empty.

DOM Level 3 does not support editing Entity nodes; if a user wants to make changes to the contents of an Entity, every related EntityReference node has to be replaced in the structure model by a clone of the Entity's contents, and then the desired changes must be made to each of those clones instead. Entity nodes and all their descendants are readonly.

An Entity node does not have any parent.

Note: If the entity contains an unbound namespace prefix, the namespaceURI of the corresponding node in the Entity node subtree is null. The same is true for EntityReference nodes that refer to this entity, when they are created using the createEntityReference method of the Document interface.

IDL Definition
interface Entity : Node {
  readonly attribute DOMString       publicId;
  readonly attribute DOMString       systemId;
  readonly attribute DOMString       notationName;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       inputEncoding;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       xmlEncoding;
  // Introduced in DOM Level 3:
  readonly attribute DOMString       xmlVersion;
};

Attributes
inputEncoding of type DOMString, readonly, introduced in DOM Level 3
An attribute specifying the encoding used for this entity at the time of parsing, when it is an external parsed entity. This is null if it an entity from the internal subset or if it is not known.
notationName of type DOMString, readonly
For unparsed entities, the name of the notation for the entity. For parsed entities, this is null.
publicId of type DOMString, readonly
The public identifier associated with the entity if specified, and null otherwise.
systemId of type DOMString, readonly
The system identifier associated with the entity if specified, and null otherwise. This may be an absolute URI or not.
xmlEncoding of type DOMString, readonly, introduced in DOM Level 3
An attribute specifying, as part of the text declaration, the encoding of this entity, when it is an external parsed entity. This is null otherwise.
xmlVersion of type DOMString, readonly, introduced in DOM Level 3
An attribute specifying, as part of the text declaration, the version number of this entity, when it is an external parsed entity. This is null otherwise.
Interface EntityReference

EntityReference nodes may be used to represent an entity reference in the tree. Note that character references and references to predefined entities are considered to be expanded by the HTML or XML processor so that characters are represented by their Unicode equivalent rather than by an entity reference. Moreover, the XML processor may completely expand references to entities while building the Document, instead of providing EntityReference nodes. If it does provide such nodes, then for an EntityReference node that represents a reference to a known entity an Entity exists, and the subtree of the EntityReference node is a copy of the Entity node subtree. However, the latter may not be true when an entity contains an unbound namespace prefix. In such a case, because the namespace prefix resolution depends on where the entity reference is, the descendants of the EntityReference node may be bound to different namespace URIs. When an EntityReference node represents a reference to an unknown entity, the node has no children and its replacement value, when used by Attr.value for example, is empty.

As for Entity nodes, EntityReference nodes and all their descendants are readonly.

Note: EntityReference nodes may cause element content and attribute value normalization problems when, such as in XML 1.0 and XML Schema, the normalization is performed after entity reference are expanded.

IDL Definition
interface EntityReference : Node {
};

Interface ProcessingInstruction

The ProcessingInstruction interface represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document.

No lexical check is done on the content of a processing instruction and it is therefore possible to have the character sequence "?>" in the content, which is illegal a processing instruction per section 2.6 of [XML 1.0]. The presence of this character sequence must generate a fatal error during serialization.

IDL Definition
interface ProcessingInstruction : Node {
  readonly attribute DOMString       target;
           attribute DOMString       data;
                                        // raises(DOMException) on setting

};

Attributes
data of type DOMString
The content of this processing instruction. This is from the first non white space character after the target to the character immediately preceding the ?>.
Exceptions on setting

DOMException

NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

target of type DOMString, readonly
The target of this processing instruction. XML defines this as being the first token following the markup that begins the processing instruction.


Changes

07 April 2004

Appendix A: Changes

Editor:
Philippe Le Hégaret, W3C

Table of contents

  • A.1 New sections
  • A.2 Changes to DOM Level 2 Core interfaces and exceptions
  • A.3 New DOM features
  • A.4 New types
  • A.5 New interfaces
  • A.6 Objects

This section summarizes the changes between [DOM Level 2 Core] and this new version of the Core specification.

A.1 New sections

The following new sections have been added:

  • DOM Architecture: a global overview of the DOM Level 3 modules;
  • DOM URIs: general considerations on the URI handling in DOM Level 3;
  • Base URIs: How the [base URI] property defined in [XML Information Set] has been exposed in DOM Level 3;
  • Mixed DOM Implementations: general considerations on DOM implementation extensions;
  • DOM Features: overview of the DOM features and how they relate to the DOM modules;
  • Bootstrapping: general introduction to the DOM Level 3 bootstrapping mechanisms;
  • Namespaces Algorithms: how namespace URIs and prefixes are resolved in DOM Level 3;
  • Infoset Mapping: relation between DOM Level 3 and [XML Information Set];
  • Configuration Settings: relations between parameters as used in DOMConfiguration;

A.2 Changes to DOM Level 2 Core interfaces and exceptions

Interface Attr
The Attr interface has two new attributes, Attr.schemaTypeInfo, and Attr.isId.
Interface Document
The Document interface has seven new attributes: Document.inputEncoding, Document.xmlEncoding, Document.xmlStandalone, Document.xmlVersion, Document.strictErrorChecking, Document.documentURI, and Document.domConfig. It has three new methods: Document.adoptNode(source), Document.normalizeDocument(), and Document.renameNode(n, namespaceURI, qualifiedName). The attribute Document.doctype has been modified.
Exception DOMException
The DOMException has two new exception codes: VALIDATION_ERR and TYPE_MISMATCH_ERR.
Interface DOMImplementation
The DOMImplementation interface has one new method, DOMImplementation.getFeature(feature, version).
Interface Entity
The Entity interface has three new attributes: Entity.inputEncoding, Entity.xmlEncoding, and Entity.xmlVersion.
Interface Element
The Element interface has one new attribute, Element.schemaTypeInfo, and three new methods: Element.setIdAttribute(name, isId), Element.setIdAttributeNS(namespaceURI, localName, isId), and Element.setIdAttributeNode(idAttr, isId).
Interface Node
The Node interface has two new attributes, Node.baseURI and Node.textContent. It has nine new methods: Node.compareDocumentPosition(other), Node.isSameNode(other), Node.lookupPrefix(namespaceURI), Node.isDefaultNamespace(namespaceURI), Node.lookupNamespaceURI(prefix), Node.isEqualNode(arg), Node.getFeature(feature, version), Node.setUserData(key, data, handler), Node.getUserData(key). It introduced 6 new constants: Node.DOCUMENT_POSITION_DISCONNECTED, Node.DOCUMENT_POSITION_PRECEDING, Node.DOCUMENT_POSITION_FOLLOWING, Node.DOCUMENT_POSITION_CONTAINS, Node.DOCUMENT_POSITION_CONTAINED_BY, and Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC. The methods Node.insertBefore(newChild, refChild), Node.replaceChild(newChild, oldChild) and Node.removeChild(oldChild) have been modified.
Interface Text
The Text interface has two new attributes, Text.wholeText and Text.isElementContentWhitespace, and one new method, Text.replaceWholeText(content).

A.3 New DOM features

"XMLVersion"
The "XMLVersion" DOM feature was introduced to represent if an implementation is able to support [XML 1.0] or [XML 1.1]. See Document.xmlVersion.

A.4 New types

DOMUserData
The DOMUserData type was added to the Core module.
DOMObject
The DOMObject type was added to the Core module.

A.5 New interfaces

DOMStringList
The DOMStringList interface has one attribute, DOMStringList.length, and one method, DOMStringList.item(index).
NameList
The NameList interface has one attribute, NameList.length, and two methods, NameList.getName(index) and NameList.getNamespaceURI(index).
DOMImplementationList
The DOMImplementationList interface has one attribute, DOMImplementationList.length, and one method, DOMImplementationList.item(index).
DOMImplementationSource
The DOMImplementationSource interface has two methods, DOMImplementationSource.getDOMImplementation(features), and DOMImplementationSource.getDOMImplementationList(features).
TypeInfo
The TypeInfo interface has two attributes, TypeInfo.typeName, and TypeInfo.typeNamespace.
UserDataHandler
The UserDataHandler interface has one method, UserDataHandler.handle(operation, key, data, src, dst), and four constants: UserDataHandler.NODE_CLONED, UserDataHandler.NODE_IMPORTED, UserDataHandler.NODE_DELETED, and UserDataHandler.NODE_RENAMED.
DOMError
The DOMError interface has six attributes: DOMError.severity, DOMError.message, DOMError.type, DOMError.relatedException, DOMError.relatedData, and DOMError.location. It has four constants: DOMError.SEVERITY_WARNING, DOMError.SEVERITY_ERROR, and DOMError.SEVERITY_FATAL_ERROR.
DOMErrorHandler
The DOMErrorHandler interface has one method: DOMErrorHandler.handleError(error).
DOMLocator
The DOMLocator interface has seven attributes: DOMLocator.lineNumber, DOMLocator.columnNumber, DOMLocator.byteOffset, DOMLocator.utf16Offset, DOMLocator.relatedNode, DOMLocator.uri, and DOMLocator.lineNumber.
DOMConfiguration
The DOMConfiguration interface has one attribute: DOMConfiguration.parameterNames. It also has three methods: DOMConfiguration.setParameter(name, value), DOMConfiguration.getParameter(name), and DOMConfiguration.canSetParameter(name, value).

A.6 Objects

This specification defines one object, only provided in the bindings:

DOMImplementationRegistry
The DOMImplementationRegistry object has two methods, DOMImplementationRegistry.getDOMImplementation(features), and DOMImplementationRegistry.getDOMImplementationList(features).


Namespaces Algorithms

07 April 2004

Appendix B: Namespaces Algorithms

Editors:
Arnaud Le Hors, IBM
Elena Litani, IBM

Table of contents

  • B.1 Namespace Normalization
    • B.1.1 Scope of a Binding
    • B.1.2 Conflicting Namespace Declaration
  • B.2 Namespace Prefix Lookup
  • B.3 Default Namespace Lookup
  • B.4 Namespace URI Lookup

This appendix contains several namespace algorithms, such as namespace normalization algorithm that fixes namespace information in the Document Object Model to produce a namespace well-formed document. If [XML 1.0] is in use (see Document.xmlVersion) the algorithms conform to [XML Namespaces], otherwise if [XML 1.1] is in use, algorithms conform to [XML Namespaces 1.1].

B.1 Namespace Normalization

Namespace declaration attributes and prefixes are normalized as part of the normalizeDocument method of the Document interface as if the following method described in pseudo code was called on the document element.

void Element.normalizeNamespaces()
{

  // Pick up local namespace declarations
  //
  for ( all DOM Level 2 valid local namespace declaration attributes of Element )
  {
      if (the namespace declaration is invalid)
      {
          // Note: The prefix xmlns is used only to declare namespace bindings and
          // is by definition bound to the namespace name http://www.w3.org/2000/xmlns/.
          // It must not be declared. No other prefix may be bound to this namespace name.

          ==> Report an error.

      }
      else
      {
          ==>  Record the namespace declaration
      }
  }

  // Fixup element's namespace
  //
  if ( Element's namespaceURI != null )
  {
    if ( Element's prefix/namespace pair (or default namespace,
         if no prefix) are within the scope of a binding )
    {
      ==> do nothing, declaration in scope is inherited

      See section "B.1.1: Scope of a binding" for an example

    }
    else
    {
      ==> Create a local namespace declaration attr for this namespace,
          with Element's current prefix (or a default namespace, if
          no prefix). If there's a conflicting local declaration
          already present, change its value to use this namespace.

          See section "B.1.2: Conflicting namespace declaration" for an example

          // NOTE that this may break other nodes within this Element's
          // subtree, if they're already using this prefix.
          // They will be repaired when we reach them.
    }
  }
  else
  {
    // Element has no namespace URI:
    if ( Element's localName is null )
    {
       // DOM Level 1 node
       ==> if in process of validation against a namespace aware schema
           (i.e XML Schema) report a fatal error: the processor can not recover
           in this situation.
           Otherwise, report an error: no namespace fixup will be performed on this node.
    }
    else
    {
      // Element has no pseudo-prefix
      if ( there's a conflicting local default namespace declaration
           already present )
      {
        ==> change its value to use this empty namespace.

      }
      // NOTE that this may break other nodes within this Element's
      // subtree, if they're already using the default namespaces.
      // They will be repaired when we reach them.
    }
  }

  // Examine and polish the attributes
  //
  for ( all non-namespace Attrs of Element )
  {
     if ( Attr[i] has a namespace URI )
     {
        if ( attribute has no prefix (default namespace decl does not apply to attributes)
             OR
             attribute prefix is not declared
             OR
             conflict: attribute has a prefix that conflicts with a binding
                       already active in scope)
        {
           if (namespaceURI matches an in scope declaration of one or more prefixes)
           {
               // pick the most local binding available;
               // if there is more than one pick one arbitrarily

               ==> change attribute's prefix.
           }
           else
           {
               if (the current prefix is not null and it has no in scope declaration)
               {
                   ==> declare this prefix
               }
               else
               {
                   // find a prefix following the pattern "NS" +index (starting at 1)
                   // make sure this prefix is not declared in the current scope.
                   // create a local namespace declaration attribute

                   ==> change attribute's prefix.
               }
           }
        }
     }
     else
     {
        // Attr[i] has no namespace URI

        if ( Attr[i] has no localName )
        {
           // DOM Level 1 node
           ==> if in process of validation against a namespace aware schema
               (i.e XML Schema) report a fatal error: the processor can not recover
                in this situation.
                Otherwise, report an error: no namespace fixup will be performed on this node.
        }
        else
        {
           // attr has no namespace URI and no prefix
           // no action is required, since attrs don't use default
           ==> do nothing
        }
     }
  } // end for-all-Attrs

  // do this recursively
  for ( all child elements of Element )
  {
    childElement.normalizeNamespaces()
  }
} // end Element.normalizeNamespaces

B.1.1 Scope of a Binding

Note: This section is informative.

An element's prefix/namespace URI pair is said to be within the scope of a binding if its namespace prefix is bound to the same namespace URI in the [in-scope namespaces] defined in [XML Information Set].

As an example, the following document is loaded in a DOM tree:

<root>
  <parent xmlns:ns="http://www.example.org/ns1"
          xmlns:bar="http://www.example.org/ns2">
    <ns:child1 xmlns:ns="http://www.example.org/ns2"/>
  </parent>
</root>

In the case of the child1 element, the namespace prefix and namespace URI are within the scope of the appropriate namespace declaration given that the namespace prefix ns of child1 is bound to http://www.example.org/ns2.

Using the method Node.appendChild, a child2 element is added as a sibling of child1 with the same namespace prefix and namespace URI, i.e. "ns" and "http://www.example.org/ns2" respectively. Unlike child1 which contains the appropriate namespace declaration in its attributes, child2's prefix/namespace URI pair is within the scope of the namespace declaration of its parent, and the namespace prefix "ns" is bound to "http://www.example.org/ns1". child2's prefix/namespace URI pair is therefore not within the scope of a binding. In order to put them within a scope of a binding, the namespace normalization algorithm will create a namespace declaration attribute value to bind the namespace prefix "ns" to the namespace URI "http://www.example.org/ns2" and will attach to child2. The XML representation of the document after the completion of the namespace normalization algorithm will be:

<root>
  <parent xmlns:ns="http://www.example.org/ns1"
          xmlns:bar="http://www.example.org/ns2">
    <ns:child1 xmlns:ns="http://www.example.org/ns2"/>
    <ns:child2 xmlns:ns="http://www.example.org/ns2"/>
  </parent>
</root>

To determine if an element is within the scope of a binding, one can invoke Node.lookupNamespaceURI, using its namespace prefix as the parameter, and compare the resulting namespace URI against the desired URI, or one can invoke Node.isDefaultNamespaceURI using its namespace URI if the element has no namespace prefix.

B.1.2 Conflicting Namespace Declaration

Note: This section is informative.

A conflicting namespace declaration could occur on an element if an Element node and a namespace declaration attribute use the same prefix but map them to two different namespace URIs.

As an example, the following document is loaded in a DOM tree:

<root>
  <ns:child1 xmlns:ns="http://www.example.org/ns1">
    <ns:child2/>
  </ns:child1>
</root>

Using the method Node.renameNode, the namespace URI of the element child1 is renamed from "http://www.example.org/ns1" to "http://www.example.org/ns2". The namespace prefix "ns" is now mapped to two different namespace URIs at the element child1 level and thus the namespace declaration is declared conflicting. The namespace normalization algorithm will resolved the namespace prefix conflict by modifying the namespace declaration attribute value from "http://www.example.org/ns1" to "http://www.example.org/ns2". The algorithm will then continue and consider the element child2, will no longer find a namespace declaration mapping the namespace prefix "ns" to "http://www.example.org/ns1" in the element's scope, and will create a new one. The XML representation of the document after the completion of the namespace normalization algorithm will be:

<root>
  <ns:child1 xmlns:ns="http://www.example.org/ns2">
    <ns:child2  xmlns:ns="http://www.example.org/ns1"/>
  </ns:child1>
</root>

B.2 Namespace Prefix Lookup

The following describes in pseudo code the algorithm used in the lookupPrefix method of the Node interface. Before returning found prefix the algorithm needs to make sure that the prefix is not redefined on an element from which the lookup started. This methods ignores DOM Level 1 nodes.

Note: This method ignores all default namespace declarations. To look up default namespace use isDefaultNamespace method.

DOMString lookupPrefix(in DOMString namespaceURI)
{
  if (namespaceURI has no value, i.e. namespaceURI is null or empty string) {
     return null;
  }
  short type = this.getNodeType();
  switch (type) {
        case Node.ELEMENT_NODE:
        {
             return lookupNamespacePrefix(namespaceURI, this);
        }
        case Node.DOCUMENT_NODE:
        {
             return getDocumentElement().lookupNamespacePrefix(namespaceURI);
        }
        case Node.ENTITY_NODE :
        case Node.NOTATION_NODE:
        case Node.DOCUMENT_FRAGMENT_NODE:
        case Node.DOCUMENT_TYPE_NODE:
            return null;  // type is unknown
        case Node.ATTRIBUTE_NODE:
        {
             if ( Attr has an owner Element )
             {
                 return ownerElement.lookupNamespacePrefix(namespaceURI);
             }
             return null;
        }
        default:
        {
           if (Node has an ancestor Element )
           // EntityReferences may have to be skipped to get to it
           {
                    return ancestor.lookupNamespacePrefix(namespaceURI);
           }
            return null;
        }
     }
 }

DOMString lookupNamespacePrefix(DOMString namespaceURI, Element originalElement){
        if ( Element has a namespace and Element's namespace == namespaceURI and
             Element has a prefix and
             originalElement.lookupNamespaceURI(Element's prefix) == namespaceURI)
        {
             return (Element's prefix);
        }
        if ( Element has attributes)
        {
            for ( all DOM Level 2 valid local namespace declaration attributes of Element )
            {
                if (Attr's prefix == "xmlns" and
                   Attr's value == namespaceURI and
                   originalElement.lookupNamespaceURI(Attr's localname) == namespaceURI)
                   {
                      return (Attr's localname);
                   }
            }
        }

        if (Node has an ancestor Element )
           // EntityReferences may have to be skipped to get to it
        {
            return ancestor.lookupNamespacePrefix(namespaceURI, originalElement);
        }
        return null;
    }

B.3 Default Namespace Lookup

The following describes in pseudo code the algorithm used in the isDefaultNamespace method of the Node interface. This methods ignores DOM Level 1 nodes.

boolean isDefaultNamespace(in DOMString namespaceURI)
{
  switch (nodeType) {
  case ELEMENT_NODE:
     if ( Element has no prefix )
     {
          return (Element's namespace == namespaceURI);
     }
     if ( Element has attributes and there is a valid DOM Level 2
          default namespace declaration, i.e. Attr's localName == "xmlns" )
     {
      return (Attr's value == namespaceURI);
     }

     if ( Element has an ancestor Element )
         // EntityReferences may have to be skipped to get to it
     {
          return ancestorElement.isDefaultNamespace(namespaceURI);
     }
     else {
          return unknown (false);
     }
  case DOCUMENT_NODE:
     return documentElement.isDefaultNamespace(namespaceURI);
  case ENTITY_NODE:
  case NOTATION_NODE:
  case DOCUMENT_TYPE_NODE:
  case DOCUMENT_FRAGMENT_NODE:
     return unknown (false);
  case ATTRIBUTE_NODE:
     if ( Attr has an owner Element )
     {
          return ownerElement.isDefaultNamespace(namespaceURI);
     }
     else {
          return unknown (false);
     }
  default:
     if ( Node has an ancestor Element )
         // EntityReferences may have to be skipped to get to it
     {
          return ancestorElement.isDefaultNamespace(namespaceURI);
     }
     else {
          return unknown (false);
     }
  }
}

B.4 Namespace URI Lookup

The following describes in pseudo code the algorithm used in the lookupNamespaceURI method of the Node interface. This methods ignores DOM Level 1 nodes.

DOMString lookupNamespaceURI(in DOMString prefix)
{
  switch (nodeType) {
     case ELEMENT_NODE:
     {
         if ( Element's namespace != null and Element's prefix == prefix )
         {
               // Note: prefix could be "null" in this case we are looking for default namespace
               return (Element's namespace);
         }
         if ( Element has attributes)
         {
            for ( all DOM Level 2 valid local namespace declaration attributes of Element )
            {
                 if (Attr's prefix == "xmlns" and Attr's localName == prefix )
                       // non default namespace
                 {
                        if (Attr's value is not empty)
                        {
                          return (Attr's value);
                        }
                        return unknown (null);
                 }
                 else if (Attr's localname == "xmlns" and prefix == null)
                       // default namespace
                 {
                        if (Attr's value is not empty)
                        {
                          return (Attr's value);
                        }
                        return unknown (null);
                 }
           }
         }
         if ( Element has an ancestor Element )
            // EntityReferences may have to be skipped to get to it
         {
                   return ancestorElement.lookupNamespaceURI(prefix);
         }
         return null;
     }
     case DOCUMENT_NODE:
          return documentElement.lookupNamespaceURI(prefix)

     case ENTITY_NODE:
     case NOTATION_NODE:
     case DOCUMENT_TYPE_NODE:
     case DOCUMENT_FRAGMENT_NODE:
           return unknown (null);

     case ATTRIBUTE_NODE:
         if (Attr has an owner Element)
         {
             return ownerElement.lookupNamespaceURI(prefix);
         }
         else
         {
             return unknown (null);
         }
     default:
         if (Node has an ancestor Element)
          // EntityReferences may have to be skipped to get to it
         {
             return ancestorElement.lookupNamespaceURI(prefix);
         }
         else {
             return unknown (null);
         }
  }
}


Infoset Mapping

07 April 2004

Appendix C: Infoset Mapping

Editor:
Philippe Le Hégaret, W3C

Table of contents

  • C.1 Document Node Mapping
    • C.1.1 Infoset to Document Node
    • C.1.2 Document Node to Infoset
  • C.2 Element Node Mapping
    • C.2.1 Infoset to Element Node
    • C.2.2 Element Node to Infoset
  • C.3 Attr Node Mapping
    • C.3.1 Infoset to Attr Node
    • C.3.2 Attr Node to Infoset
  • C.4 ProcessingInstruction Node Mapping
    • C.4.1 Infoset to ProcessingInstruction Node
    • C.4.2 ProcessingInstruction Node to Infoset
  • C.5 EntityReference Node Mapping
    • C.5.1 Infoset to EntityReference Node
    • C.5.2 EntityReference Node to Infoset
  • C.6 Text and CDATASection Nodes Mapping
    • C.6.1 Infoset to Text Node
    • C.6.2 Text and CDATASection Nodes to Infoset
  • C.7 Comment Node Mapping
    • C.7.1 Infoset to Comment Node
    • C.7.2 Comment Node to Infoset
  • C.8 DocumentType Node Mapping
    • C.8.1 Infoset to DocumentType Node
    • C.8.2 DocumentType Node to Infoset
  • C.9 Entity Node Mapping
    • C.9.1 Infoset to Entity Node
    • C.9.2 Entity Node to Infoset
  • C.10 Notation Node Mapping
    • C.10.1 Infoset to Notation Node
    • C.10.2 Notation Node to Infoset

This appendix contains the mappings between the XML Information Set [XML Information Set] model and the Document Object Model. Starting from a Document node, each information item is mapped to its respective Node, and each Node is mapped to its respective information item. As used in the Infoset specification, the Infoset property names are shown in square brackets, [thus].

Unless specified, the Infoset to DOM node mapping makes no distinction between unknown and no value since both will be exposed as null (or false if the DOM attribute is of type boolean).

C.1 Document Node Mapping

C.1.1 Infoset to Document Node

An document information item maps to a Document node. The attributes of the corresponding Document node are constructed as follows:

Attribute | Value
Node.nodeName | "#document"
Node.nodeValue | null
Node.nodeType | Node.DOCUMENT_NODE
Node.parentNode | null
Node.childNodes | A NodeList containing the information items in the [children] property.
Node.firstChild | The first node contained in Node.childNodes
Node.lastChild | The last node contained in Node.childNodes
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | null
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | same as Document.documentURI
Node.textContent | null
Document.doctype | The document type information item
Document.implementation | The DOMImplementation object used to create this node
Document.documentElement | The [document element] property
Document.inputEncoding | The [character encoding scheme] property
Document.xmlEncoding | null
Document.xmlStandalone | The [standalone] property, or false if the latter has no value.
Document.xmlVersion | The [version] property, or "1.0" if the latter has no value.
Document.strictErrorChecking | true
Document.documentURI | The [base URI] property
Document.domConfig | A DOMConfiguration object whose parameters are set to their default values

The [notations], [unparsed entities] properties are being exposed in the DocumentType node.

Note: The [all declarations processed] property is not exposed through the Document node.

C.1.2 Document Node to Infoset

A Document node maps to an document information item. Document nodes with no namespace URI (Node.namespaceURI equals to null) cannot be represented using the Infoset. The properties of the corresponding document information item are constructed as follows:

Property | Value
[children] | Node.childNodes
[document element] | Document.documentElement
[notations] | Document.doctype.notations
[unparsed entities] | The information items from Document.doctype.entities, whose Node.childNodes is an empty list
[base URI] | Document.documentURI
[character encoding scheme] | Document.inputEncoding
[standalone] | Document.xmlStandalone
[version] | Document.xmlVersion
[all declarations processed] | The value is implementation dependent

C.2 Element Node Mapping

C.2.1 Infoset to Element Node

An element information item maps to a Element node. The attributes of the corresponding Element node are constructed as follows:

Attribute | Value
Node.nodeName | same as Element.tagName
Node.nodeValue | null
Node.nodeType | Node.ELEMENT_NODE
Node.parentNode | The [parent] property
Node.childNodes | A NodeList containing the information items in the [children] property
Node.firstChild | The first node contained in Node.childNodes
Node.lastChild | The last node contained in Node.childNodes
Node.previousSibling | The information item preceding the current one on the [children] property contained in the [parent] property
Node.nextSibling | The information item following the current one on the [children] property contained in the [parent] property
Node.attributes | The information items contained in the [attributes] and [namespace attributes] properties
Node.ownerDocument | The document information item
Node.namespaceURI | The [namespace name] property
Node.prefix | The [prefix] property
Node.localName | The [local name] property
Node.baseURI | The [base URI] property
Node.textContent | Concatenation of the Node.textContent attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the node has no children.
Element.tagName | If the [prefix] property has no value, this contains the [local name] property. Otherwise, this contains the concatenation of the [prefix] property, the colon ':' character, and the [local name] property.
Element.schemaTypeInfo | A TypeInfo object whose TypeInfo.typeNamespace and TypeInfo.typeName are inferred from the schema in use if available.

Note: The [in-scope namespaces] property is not exposed through the Element node.

C.2.2 Element Node to Infoset

An Element node maps to an element information item. Because the Infoset only represents unexpanded entity references, non-empty EntityReference nodes contained in Node.childNodes need to be replaced by their content. DOM applications could use the Document.normalizeDocument() method for that effect with the "entities" parameter set to false. The properties of the corresponding element information item are constructed as follows:

Property | Value
[namespace name] | Node.namespaceURI
[local name] | Node.localName
[prefix] | Node.prefix
[children] | Node.childNodes, whose expanded entity references (EntityReference nodes with children) have been replaced with their content.
[attributes] | The nodes contained in Node.attributes, whose Node.namespaceURI value is different from "http://www.w3.org/2000/xmlns/"
[namespace attributes] | The nodes contained in Node.attributes, whose Node.namespaceURI value is "http://www.w3.org/2000/xmlns/"
[in-scope namespaces] | The namespace information items computed using the [namespace attributes] properties of this node and its ancestors. If the [DOM Level 3 XPath] module is supported, the namespace information items can also be computed from the XPathNamespace nodes.
[base URI] | Node.baseURI
[parent] | Node.parentNode

C.3 Attr Node Mapping

C.3.1 Infoset to Attr Node

An attribute information item map to a Attr node. The attributes of the corresponding Attr node are constructed as follows:

Attribute/Method | Value
Node.nodeName | same as Attr.name
Node.nodeValue | same as Attr.value
Node.nodeType | Node.ATTRIBUTE_NODE
Node.parentNode | null
Node.childNodes | A NodeList containing one Text node whose text content is the same as Attr.value.
Node.firstChild | The Text node contained in Node.childNodes
Node.lastChild | The Text node contained in Node.childNodes
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | The [namespace name] property
Node.prefix | The [prefix] property
Node.localName | The [local name] property
Node.baseURI | null
Node.textContent | the value of Node.textContent of the Text child. same as Node.nodeValue (since this attribute node only contains one Text node)
Attr.name | If the [prefix] property has no value, this contains the [local name] property. Otherwise, this contains the concatenation of the [prefix] property, the colon ':' character, and the [local name] property.
Attr.specified | The [specified] property
Attr.value | The [normalized value] property
Attr.ownerElement | The [owner element] property
Attr.schemaTypeInfo | A TypeInfo object whose TypeInfo.typeNamespace is "http://www.w3.org/TR/REC-xml" and TypeInfo.typeName is the [attribute type] property
Attr.isId | if the [attribute type] property is ID, this method return true

C.3.2 Attr Node to Infoset

An Attr node maps to an attribute information item. Attr nodes with no namespace URI (Node.namespaceURI equals to null) cannot be represented using the Infoset. The properties of the corresponding attribute information item are constructed as follows:

Property | Value
[namespace name] | Node.namespaceURI
[local name] | Node.localName
[prefix] | Node.prefix
[normalized value] | Attr.value
[specified] | Attr.specified
[attribute type] | Using the TypeInfo object referenced from Attr.schemaTypeInfo, the value of TypeInfo.typeName if TypeInfo.typeNamespace is "http://www.w3.org/TR/REC-xml".
[references] | if the computed [attribute type] property is IDREF, IDREFS, ENTITY, ENTITIES, or NOTATION, the value of this property is an ordered list of the element, unparsed entity, or notation information items referred to in the attribute value, in the order that they appear there. The ordered list is computed using Node.ownerDocument.getElementById, Node.ownerDocument.doctype.entities, and Node.ownerDocument.doctype.notations.
[owner element] | Attr.ownerElement

C.4 ProcessingInstruction Node Mapping

C.4.1 Infoset to ProcessingInstruction Node

A processing instruction information item map to a ProcessingInstruction node. The attributes of the corresponding ProcessingInstruction node are constructed as follows:

Attribute | Value
Node.nodeName | same as ProcessingInstruction.target
Node.nodeValue | same as ProcessingInstruction.data
Node.nodeType | Node.PROCESSING_INSTRUCTION_NODE
Node.parentNode | The [parent] property
Node.childNodes | empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | The [base URI] property of the parent element if any. The [base URI] property of the processing instruction information item is not exposed through the ProcessingInstruction node.
Node.textContent | same as Node.nodeValue
ProcessingInstruction.target | The [target] property
ProcessingInstruction.data | The [content] property

C.4.2 ProcessingInstruction Node to Infoset

A ProcessingInstruction node maps to an processing instruction information item. The properties of the corresponding processing instruction information item are constructed as follows:

Property | Value
[target] | ProcessingInstruction.target
[content] | ProcessingInstruction.data
[base URI] | Node.baseURI (which is equivalent to the base URI of its parent element if any)
[notation] | The Notation node named by the target and if available from Node.ownerDocument.doctype.notations
[parent] | Node.parentNode

C.5 EntityReference Node Mapping

C.5.1 Infoset to EntityReference Node

An unexpanded entity reference information item maps to a EntityReference node. The attributes of the corresponding EntityReference node are constructed as follows:

Attribute | Value
Node.nodeName | The [name] property
Node.nodeValue | null
Node.nodeType | Node.ENTITY_REFERENCE_NODE
Node.parentNode | the [parent] property
Node.childNodes | Empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | The [declaration base URI] property
Node.textContent | null (the node has no children)

Note: The [system identifier] and [public identifier] properties are not exposed through the EntityReference node, but through the Entity node reference from this EntityReference node, if any.

C.5.2 EntityReference Node to Infoset

An EntityReference node maps to an unexpanded entity reference information item. EntityReference nodes with children (Node.childNodes contains a non-empty list) cannot be represented using the Infoset. The properties of the corresponding unexpanded entity reference information item are constructed as follows:

Property | Value
[name] | Node.nodeName
[system identifier] | The Entity.systemId value of the Entity node available from Node.ownerDocument.doctype.entities if available
[public identifier] | The Entity.publicId value of the Entity node available from Node.ownerDocument.doctype.entities if available
[declaration base URI] | Node.baseURI
[parent] | Node.parentNode

C.6 Text and CDATASection Nodes Mapping

Since the [XML Information Set] doesn't represent the boundaries of CDATA marked sections, CDATASection nodes cannot occur from an infoset mapping.

C.6.1 Infoset to Text Node

Consecutive character information items map to a Text node. The attributes of the corresponding Text node are constructed as follows:

Attribute/Method | Value
Node.nodeName | "#text"
Node.nodeValue | same as CharacterData.data
Node.nodeType | Node.TEXT_NODE
Node.parentNode | The [parent] property
Node.childNodes | empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | null
Node.textContent | same as Node.nodeValue
CharacterData.data | A DOMString including all [character code] contained in the character information items
CharacterData.length | The number of 16-bit units needed to encode all ISO 10646 character code contained in the character information items using the UTF-16 encoding.
Text.isElementContentWhitespace | The [element content whitespace] property
Text.wholeText | same as CharacterData.data

Note: By construction, the values of the [parent] and [element content whitespace] properties are necessarily the sames for all consecutive character information items.

C.6.2 Text and CDATASection Nodes to Infoset

The text content of a Text or a CDATASection node maps to a sequence of character information items. The number of items is less or equal to CharacterData.length. Text nodes contained in Attr nodes are mapped to the Infoset using the Attr.value attribute. Text nodes contained in Document nodes cannot be represented using the Infoset. The properties of the corresponding character information items are constructed as follows:

Property | Value
[character code] | The ISO 10646 character code produced using one or two 16-bit units from CharacterData.data
[element content whitespace] | Text.isElementContentWhitespace
[parent] | Node.parentNode

C.7 Comment Node Mapping

C.7.1 Infoset to Comment Node

A comment information item maps to a Comment node. The attributes of the corresponding Comment node are constructed as follows:

Attribute | Value
Node.nodeName | "#comment"
Node.nodeValue | same as CharacterData.data
Node.nodeType | Node.COMMENT_NODE
Node.parentNode | The [parent] property
Node.childNodes | empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | null
Node.textContent | same as Node.nodeValue
CharacterData.data | The [content] property encoded using the UTF-16 encoding.
CharacterData.length | The number of 16-bit units needed to encode all ISO character code contained in the [content] property using the UTF-16 encoding.

C.7.2 Comment Node to Infoset

A Comment maps to a comment information item. The properties of the corresponding comment information item are constructed as follows:

Property | Value
[content] | CharacterData.data
[parent] | Node.parentNode

C.8 DocumentType Node Mapping

C.8.1 Infoset to DocumentType Node

A document type declaration information item maps to a DocumentType node. The attributes of the corresponding DocumentType node are constructed as follows:

Attribute | Value
Node.nodeName | same as DocumentType.name
Node.nodeValue | null
Node.nodeType | Node.DOCUMENT_TYPE_NODE
Node.parentNode | The [parent] property
Node.childNodes | empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | null
Node.textContent | null
DocumentType.name | The name of the document element.
DocumentType.entities | The [unparsed entities] property available from the document information item.
DocumentType.notations | The [notations] property available from the document information item.
DocumentType.publicId | The [public identifier] property
DocumentType.systemId | The [system identifier] property
DocumentType.internalSubset | The value is implementation dependent

Note: The [children] property is not exposed through the DocumentType node.

C.8.2 DocumentType Node to Infoset

A DocumentType maps to a document type declaration information item. The properties of the corresponding document type declaration information item are constructed as follows:

Property | Value
[system identifier] | DocumentType.systemId
[public identifier] | DocumentType.publicId
[children] | The value of this property is implementation dependent
[parent] | Node.parentNode

C.9 Entity Node Mapping

C.9.1 Infoset to Entity Node

An unparsed entity information item maps to a Entity node. The attributes of the corresponding Entity node are constructed as follows:

Attribute | Value
Node.nodeName | The [name] property
Node.nodeValue | null
Node.nodeType | Node.ENTITY_NODE
Node.parentNode | null
Node.childNodes | Empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | The [declaration base URI] property
Node.textContent | "" (the node has no children)
Entity.publicId | The [public identifier] property
Entity.systemId | The [system identifier] property
Entity.notationName | The [notation name] property
Entity.inputEncoding | null
Entity.xmlEncoding | null
Entity.xmlVersion | null

Note: The [notation] property is available through the DocumentType node.

C.9.2 Entity Node to Infoset

An Entity node maps to an unparsed entity information item. Entity nodes with children (Node.childNodes contains a non-empty list) cannot be represented using the Infoset. The properties of the corresponding unparsed entity information item are constructed as follows:

Property | Value
[name] | Node.nodeName
[system identifier] | Entity.systemId
[public identifier] | Entity.publicId
[declaration base URI] | Node.baseURI
[notation name] | Entity.notationName
[notation] | The Notation node referenced from DocumentType.notations whose name is the [notation name] property

C.10 Notation Node Mapping

C.10.1 Infoset to Notation Node

A notation information item maps to a Notation node. The attributes of the corresponding Notation node are constructed as follows:

Attribute | Value
Node.nodeName | The [name] property
Node.nodeValue | null
Node.nodeType | Node.NOTATION_NODE
Node.parentNode | null
Node.childNodes | Empty NodeList
Node.firstChild | null
Node.lastChild | null
Node.previousSibling | null
Node.nextSibling | null
Node.attributes | null
Node.ownerDocument | The document information item
Node.namespaceURI | null
Node.prefix | null
Node.localName | null
Node.baseURI | The [declaration base URI] property
Node.textContent | null
Notation.publicId | The [public identifier] property
Notation.systemId | The [system identifier] property

C.10.2 Notation Node to Infoset

A Notation maps to a notation information item. The properties of the corresponding notation information item are constructed as follows:

Property | Value
[name] | Node.nodeName
[system identifier] | Notation.systemId
[public identifier] | Notation.publicId
[parent] | Node.parentNode


Configuration Settings

07 April 2004

Appendix D: Configuration Settings

Editor:
Elena Litani, IBM

D.1 Configuration Scenarios

Using the DOMConfiguration users can change behavior of the DOMParser, DOMSerializer and Document.normalizeDocument(). If a DOM implementation supports XML Schemas and DTD validation, the table below defines behavior of such implementation following various parameter settings on the DOMConfiguration. Errors are effectively reported only if a DOMErrorHandler object is attached to the "error-handler" parameter.

"schema-type" | "validate" | "validate-if-schema" | Instance schemas, i.e. the current schema | Outcome | Other parameters
null | true | false | DTD and XML Schema | Implementation dependent | The outcome of setting the "datatype-normalization", "element-content-whitespace" or "namespaces" parameters to true or false is implementation dependent.
 | false | true
null | true | false | none | Report an error | Setting the "datatype-normalization" to true or false has no effect on the DOM.
 | false | true |  | No error is reported
null | true | false | DTD | Validate against DTD | Setting the "datatype-normalization" to true or false has no effect on the DOM.
 | false | true
null | true | false | XML Schema | Validate against XML Schema | The outcome of setting the "namespaces" to false is implementation dependent (likely to be an error). Setting the "element-content-whitespace" to false does not have any effect on the DOM.
 | false | true
"http://www.w3.org/TR/REC-xml" | true | false | DTD or XML Schema or both | If DTD is found, validate against DTD. Otherwise, report an error. | Setting the "datatype-normalization" to true or false has no effect on the DOM.
 | false | true |  | If DTD is found, validate against DTD.
"http://www.w3.org/2001/XMLSchema" | true | false | DTD or XML Schema or both | If XML Schema is found, validate against the schema. Otherwise, report an error. | Setting the "datatype-normalization" to true exposes XML Schema normalized values in the DOM. The outcome of setting the "namespaces" to false is implementation dependent (likely to be an error).
 | false | true |  | If XML Schema is found, validate against the schema.
"http://www.w3.org/2001/XMLSchema" or "http://www.w3.org/TR/REC-xml" | false | false | DTD or XML Schema or both | If XML Schema is found, it is ignored. DOM implementations may use information available in the DTD to perform entity resolution. | Setting the "datatype-normalization" to true of false has no effect on the DOM.

Note: If an error has to be reported, as specified in the "Outcome" column above, the DOMError.type is "no-schema-available".


Accessing code point boundaries

07 April 2004

Appendix E: Accessing code point boundaries

Mark Davis, IBM
Lauren Wood, SoftQuad Software Inc.

Table of contents

  • E.1 Introduction
  • E.2 Methods
    • StringExtend

E.1 Introduction

This appendix is an informative, not a normative, part of the Level 3 DOM specification.

Characters are represented in Unicode by numbers called code points (also called scalar values). These numbers can range from 0 up to 1,114,111 = 10FFFF16 (although some of these values are illegal). Each code point can be directly encoded with a 32-bit code unit. This encoding is termed UCS-4 (or UTF-32). The DOM specification, however, uses UTF-16, in which the most frequent characters (which have values less than FFFF16) are represented by a single 16-bit code unit, while characters above FFFF16 use a special pair of code units called a surrogate pair. For more information, see [Unicode] or the Unicode Web site.

While indexing by code points as opposed to code units is not common in programs, some specifications such as [XPath 1.0] (and therefore XSLT and [XPointer]) use code point indices. For interfacing with such formats it is recommended that the programming language provide string processing methods for converting code point indices to code unit indices and back. Some languages do not provide these functions natively; for these it is recommended that the native String type that is bound to DOMString be extended to enable this conversion. An example of how such an API might look is supplied below.

Note: Since these methods are supplied as an illustrative example of the type of functionality that is required, the names of the methods, exceptions, and interface may differ from those given here.

E.2 Methods

Interface StringExtend

Extensions to a language's native String class or interface

IDL Definition
interface StringExtend {
  int                findOffset16(in int offset32)
                                        raises(StringIndexOutOfBoundsException);
  int                findOffset32(in int offset16)
                                        raises(StringIndexOutOfBoundsException);
};

Methods
findOffset16
Returns the UTF-16 offset that corresponds to a UTF-32 offset. Used for random access.

Note: You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.

Parameters
offset32 of type int
UTF-32 offset.
Return Value

int

UTF-16 offset

Exceptions

StringIndexOutOfBoundsException

if offset32 is out of bounds.

findOffset32
Returns the UTF-32 offset corresponding to a UTF-16 offset. Used for random access. To find the UTF-32 length of a string, use:
len32 = findOffset32(source, source.length());

Note: If the UTF-16 offset is into the middle of a surrogate pair, then the UTF-32 offset of the end of the pair is returned; that is, the index of the char after the end of the pair. You can always round-trip from a UTF-32 offset to a UTF-16 offset and back. You can round-trip from a UTF-16 offset to a UTF-32 offset and back if and only if the offset16 is not in the middle of a surrogate pair. Unmatched surrogates count as a single UTF-16 value.

Parameters
offset16 of type int
UTF-16 offset
Return Value

int

UTF-32 offset

Exceptions

StringIndexOutOfBoundsException

if offset16 is out of bounds.


IDL Definitions

07 April 2004

Appendix F: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Core definitions.

The IDL files are also available as: http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/idl.zip

dom.idl:

// File: dom.idl

#ifndef _DOM_IDL_
#define _DOM_IDL_

#pragma prefix "w3c.org"
module dom
{

  valuetype DOMString sequence<unsigned short>;

  typedef   unsigned long long DOMTimeStamp;

  typedef   any DOMUserData;

  typedef   Object DOMObject;

  interface DOMImplementation;
  interface DocumentType;
  interface Document;
  interface NodeList;
  interface NamedNodeMap;
  interface UserDataHandler;
  interface Element;
  interface TypeInfo;
  interface DOMLocator;

  exception DOMException {
    unsigned short   code;
  };
  // ExceptionCode
  const unsigned short      INDEX_SIZE_ERR                 = 1;
  const unsigned short      DOMSTRING_SIZE_ERR             = 2;
  const unsigned short      HIERARCHY_REQUEST_ERR          = 3;
  const unsigned short      WRONG_DOCUMENT_ERR             = 4;
  const unsigned short      INVALID_CHARACTER_ERR          = 5;
  const unsigned short      NO_DATA_ALLOWED_ERR            = 6;
  const unsigned short      NO_MODIFICATION_ALLOWED_ERR    = 7;
  const unsigned short      NOT_FOUND_ERR                  = 8;
  const unsigned short      NOT_SUPPORTED_ERR              = 9;
  const unsigned short      INUSE_ATTRIBUTE_ERR            = 10;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_STATE_ERR              = 11;
  // Introduced in DOM Level 2:
  const unsigned short      SYNTAX_ERR                     = 12;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_MODIFICATION_ERR       = 13;
  // Introduced in DOM Level 2:
  const unsigned short      NAMESPACE_ERR                  = 14;
  // Introduced in DOM Level 2:
  const unsigned short      INVALID_ACCESS_ERR             = 15;
  // Introduced in DOM Level 3:
  const unsigned short      VALIDATION_ERR                 = 16;
  // Introduced in DOM Level 3:
  const unsigned short      TYPE_MISMATCH_ERR              = 17;

  // Introduced in DOM Level 3:
  interface DOMStringList {
    DOMString          item(in unsigned long index);
    readonly attribute unsigned long   length;
    boolean            contains(in DOMString str);
  };

  // Introduced in DOM Level 3:
  interface NameList {
    DOMString          getName(in unsigned long index);
    DOMString          getNamespaceURI(in unsigned long index);
    readonly attribute unsigned long   length;
    boolean            contains(in DOMString str);
    boolean            containsNS(in DOMString namespaceURI,
                                  in DOMString name);
  };

  // Introduced in DOM Level 3:
  interface DOMImplementationList {
    DOMImplementation  item(in unsigned long index);
    readonly attribute unsigned long   length;
  };

  // Introduced in DOM Level 3:
  interface DOMImplementationSource {
    DOMImplementation  getDOMImplementation(in DOMString features);
    DOMImplementationList getDOMImplementationList(in DOMString features);
  };

  interface DOMImplementation {
    boolean            hasFeature(in DOMString feature,
                                  in DOMString version);
    // Introduced in DOM Level 2:
    DocumentType       createDocumentType(in DOMString qualifiedName,
                                          in DOMString publicId,
                                          in DOMString systemId)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Document           createDocument(in DOMString namespaceURI,
                                      in DOMString qualifiedName,
                                      in DocumentType doctype)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    DOMObject          getFeature(in DOMString feature,
                                  in DOMString version);
  };

  interface Node {

    // NodeType
    const unsigned short      ELEMENT_NODE                   = 1;
    const unsigned short      ATTRIBUTE_NODE                 = 2;
    const unsigned short      TEXT_NODE                      = 3;
    const unsigned short      CDATA_SECTION_NODE             = 4;
    const unsigned short      ENTITY_REFERENCE_NODE          = 5;
    const unsigned short      ENTITY_NODE                    = 6;
    const unsigned short      PROCESSING_INSTRUCTION_NODE    = 7;
    const unsigned short      COMMENT_NODE                   = 8;
    const unsigned short      DOCUMENT_NODE                  = 9;
    const unsigned short      DOCUMENT_TYPE_NODE             = 10;
    const unsigned short      DOCUMENT_FRAGMENT_NODE         = 11;
    const unsigned short      NOTATION_NODE                  = 12;

    readonly attribute DOMString       nodeName;
             attribute DOMString       nodeValue;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

    readonly attribute unsigned short  nodeType;
    readonly attribute Node            parentNode;
    readonly attribute NodeList        childNodes;
    readonly attribute Node            firstChild;
    readonly attribute Node            lastChild;
    readonly attribute Node            previousSibling;
    readonly attribute Node            nextSibling;
    readonly attribute NamedNodeMap    attributes;
    // Modified in DOM Level 2:
    readonly attribute Document        ownerDocument;
    // Modified in DOM Level 3:
    Node               insertBefore(in Node newChild,
                                    in Node refChild)
                                        raises(DOMException);
    // Modified in DOM Level 3:
    Node               replaceChild(in Node newChild,
                                    in Node oldChild)
                                        raises(DOMException);
    // Modified in DOM Level 3:
    Node               removeChild(in Node oldChild)
                                        raises(DOMException);
    // Modified in DOM Level 3:
    Node               appendChild(in Node newChild)
                                        raises(DOMException);
    boolean            hasChildNodes();
    Node               cloneNode(in boolean deep);
    // Modified in DOM Level 3:
    void               normalize();
    // Introduced in DOM Level 2:
    boolean            isSupported(in DOMString feature,
                                   in DOMString version);
    // Introduced in DOM Level 2:
    readonly attribute DOMString       namespaceURI;
    // Introduced in DOM Level 2:
             attribute DOMString       prefix;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 2:
    readonly attribute DOMString       localName;
    // Introduced in DOM Level 2:
    boolean            hasAttributes();
    // Introduced in DOM Level 3:
    readonly attribute DOMString       baseURI;

    // DocumentPosition
    const unsigned short      DOCUMENT_POSITION_DISCONNECTED = 0x01;
    const unsigned short      DOCUMENT_POSITION_PRECEDING    = 0x02;
    const unsigned short      DOCUMENT_POSITION_FOLLOWING    = 0x04;
    const unsigned short      DOCUMENT_POSITION_CONTAINS     = 0x08;
    const unsigned short      DOCUMENT_POSITION_CONTAINED_BY = 0x10;
    const unsigned short      DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;

    // Introduced in DOM Level 3:
    unsigned short     compareDocumentPosition(in Node other)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
             attribute DOMString       textContent;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

    // Introduced in DOM Level 3:
    boolean            isSameNode(in Node other);
    // Introduced in DOM Level 3:
    DOMString          lookupPrefix(in DOMString namespaceURI);
    // Introduced in DOM Level 3:
    boolean            isDefaultNamespace(in DOMString namespaceURI);
    // Introduced in DOM Level 3:
    DOMString          lookupNamespaceURI(in DOMString prefix);
    // Introduced in DOM Level 3:
    boolean            isEqualNode(in Node arg);
    // Introduced in DOM Level 3:
    DOMObject          getFeature(in DOMString feature,
                                  in DOMString version);
    // Introduced in DOM Level 3:
    DOMUserData        setUserData(in DOMString key,
                                   in DOMUserData data,
                                   in UserDataHandler handler);
    // Introduced in DOM Level 3:
    DOMUserData        getUserData(in DOMString key);
  };

  interface NodeList {
    Node               item(in unsigned long index);
    readonly attribute unsigned long   length;
  };

  interface NamedNodeMap {
    Node               getNamedItem(in DOMString name);
    Node               setNamedItem(in Node arg)
                                        raises(DOMException);
    Node               removeNamedItem(in DOMString name)
                                        raises(DOMException);
    Node               item(in unsigned long index);
    readonly attribute unsigned long   length;
    // Introduced in DOM Level 2:
    Node               getNamedItemNS(in DOMString namespaceURI,
                                      in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Node               setNamedItemNS(in Node arg)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Node               removeNamedItemNS(in DOMString namespaceURI,
                                         in DOMString localName)
                                        raises(DOMException);
  };

  interface CharacterData : Node {
             attribute DOMString       data;
                                        // raises(DOMException) on setting
                                        // raises(DOMException) on retrieval

    readonly attribute unsigned long   length;
    DOMString          substringData(in unsigned long offset,
                                     in unsigned long count)
                                        raises(DOMException);
    void               appendData(in DOMString arg)
                                        raises(DOMException);
    void               insertData(in unsigned long offset,
                                  in DOMString arg)
                                        raises(DOMException);
    void               deleteData(in unsigned long offset,
                                  in unsigned long count)
                                        raises(DOMException);
    void               replaceData(in unsigned long offset,
                                   in unsigned long count,
                                   in DOMString arg)
                                        raises(DOMException);
  };

  interface Attr : Node {
    readonly attribute DOMString       name;
    readonly attribute boolean         specified;
             attribute DOMString       value;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 2:
    readonly attribute Element         ownerElement;
    // Introduced in DOM Level 3:
    readonly attribute TypeInfo        schemaTypeInfo;
    // Introduced in DOM Level 3:
    readonly attribute boolean         isId;
  };

  interface Element : Node {
    readonly attribute DOMString       tagName;
    DOMString          getAttribute(in DOMString name);
    void               setAttribute(in DOMString name,
                                    in DOMString value)
                                        raises(DOMException);
    void               removeAttribute(in DOMString name)
                                        raises(DOMException);
    Attr               getAttributeNode(in DOMString name);
    Attr               setAttributeNode(in Attr newAttr)
                                        raises(DOMException);
    Attr               removeAttributeNode(in Attr oldAttr)
                                        raises(DOMException);
    NodeList           getElementsByTagName(in DOMString name);
    // Introduced in DOM Level 2:
    DOMString          getAttributeNS(in DOMString namespaceURI,
                                      in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    void               setAttributeNS(in DOMString namespaceURI,
                                      in DOMString qualifiedName,
                                      in DOMString value)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    void               removeAttributeNS(in DOMString namespaceURI,
                                         in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Attr               getAttributeNodeNS(in DOMString namespaceURI,
                                          in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Attr               setAttributeNodeNS(in Attr newAttr)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                              in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    boolean            hasAttribute(in DOMString name);
    // Introduced in DOM Level 2:
    boolean            hasAttributeNS(in DOMString namespaceURI,
                                      in DOMString localName)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    readonly attribute TypeInfo        schemaTypeInfo;
    // Introduced in DOM Level 3:
    void               setIdAttribute(in DOMString name,
                                      in boolean isId)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    void               setIdAttributeNS(in DOMString namespaceURI,
                                        in DOMString localName,
                                        in boolean isId)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    void               setIdAttributeNode(in Attr idAttr,
                                          in boolean isId)
                                        raises(DOMException);
  };

  interface Text : CharacterData {
    Text               splitText(in unsigned long offset)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    readonly attribute boolean         isElementContentWhitespace;
    // Introduced in DOM Level 3:
    readonly attribute DOMString       wholeText;
    // Introduced in DOM Level 3:
    Text               replaceWholeText(in DOMString content)
                                        raises(DOMException);
  };

  interface Comment : CharacterData {
  };

  // Introduced in DOM Level 3:
  interface TypeInfo {
    readonly attribute DOMString       typeName;
    readonly attribute DOMString       typeNamespace;

    // DerivationMethods
    const unsigned long       DERIVATION_RESTRICTION         = 0x00000001;
    const unsigned long       DERIVATION_EXTENSION           = 0x00000002;
    const unsigned long       DERIVATION_UNION               = 0x00000004;
    const unsigned long       DERIVATION_LIST                = 0x00000008;

    boolean            isDerivedFrom(in DOMString typeNamespaceArg,
                                     in DOMString typeNameArg,
                                     in unsigned long derivationMethod);
  };

  // Introduced in DOM Level 3:
  interface UserDataHandler {

    // OperationType
    const unsigned short      NODE_CLONED                    = 1;
    const unsigned short      NODE_IMPORTED                  = 2;
    const unsigned short      NODE_DELETED                   = 3;
    const unsigned short      NODE_RENAMED                   = 4;
    const unsigned short      NODE_ADOPTED                   = 5;

    void               handle(in unsigned short operation,
                              in DOMString key,
                              in DOMUserData data,
                              in Node src,
                              in Node dst);
  };

  // Introduced in DOM Level 3:
  interface DOMError {

    // ErrorSeverity
    const unsigned short      SEVERITY_WARNING               = 1;
    const unsigned short      SEVERITY_ERROR                 = 2;
    const unsigned short      SEVERITY_FATAL_ERROR           = 3;

    readonly attribute unsigned short  severity;
    readonly attribute DOMString       message;
    readonly attribute DOMString       type;
    readonly attribute DOMObject       relatedException;
    readonly attribute DOMObject       relatedData;
    readonly attribute DOMLocator      location;
  };

  // Introduced in DOM Level 3:
  interface DOMErrorHandler {
    boolean            handleError(in DOMError error);
  };

  // Introduced in DOM Level 3:
  interface DOMLocator {
    readonly attribute long            lineNumber;
    readonly attribute long            columnNumber;
    readonly attribute long            byteOffset;
    readonly attribute long            utf16Offset;
    readonly attribute Node            relatedNode;
    readonly attribute DOMString       uri;
  };

  // Introduced in DOM Level 3:
  interface DOMConfiguration {
    void               setParameter(in DOMString name,
                                    in DOMUserData value)
                                        raises(DOMException);
    DOMUserData        getParameter(in DOMString name)
                                        raises(DOMException);
    boolean            canSetParameter(in DOMString name,
                                       in DOMUserData value);
    readonly attribute DOMStringList   parameterNames;
  };

  interface CDATASection : Text {
  };

  interface DocumentType : Node {
    readonly attribute DOMString       name;
    readonly attribute NamedNodeMap    entities;
    readonly attribute NamedNodeMap    notations;
    // Introduced in DOM Level 2:
    readonly attribute DOMString       publicId;
    // Introduced in DOM Level 2:
    readonly attribute DOMString       systemId;
    // Introduced in DOM Level 2:
    readonly attribute DOMString       internalSubset;
  };

  interface Notation : Node {
    readonly attribute DOMString       publicId;
    readonly attribute DOMString       systemId;
  };

  interface Entity : Node {
    readonly attribute DOMString       publicId;
    readonly attribute DOMString       systemId;
    readonly attribute DOMString       notationName;
    // Introduced in DOM Level 3:
    readonly attribute DOMString       inputEncoding;
    // Introduced in DOM Level 3:
    readonly attribute DOMString       xmlEncoding;
    // Introduced in DOM Level 3:
    readonly attribute DOMString       xmlVersion;
  };

  interface EntityReference : Node {
  };

  interface ProcessingInstruction : Node {
    readonly attribute DOMString       target;
             attribute DOMString       data;
                                        // raises(DOMException) on setting

  };

  interface DocumentFragment : Node {
  };

  interface Document : Node {
    // Modified in DOM Level 3:
    readonly attribute DocumentType    doctype;
    readonly attribute DOMImplementation implementation;
    readonly attribute Element         documentElement;
    Element            createElement(in DOMString tagName)
                                        raises(DOMException);
    DocumentFragment   createDocumentFragment();
    Text               createTextNode(in DOMString data);
    Comment            createComment(in DOMString data);
    CDATASection       createCDATASection(in DOMString data)
                                        raises(DOMException);
    ProcessingInstruction createProcessingInstruction(in DOMString target,
                                                      in DOMString data)
                                        raises(DOMException);
    Attr               createAttribute(in DOMString name)
                                        raises(DOMException);
    EntityReference    createEntityReference(in DOMString name)
                                        raises(DOMException);
    NodeList           getElementsByTagName(in DOMString tagname);
    // Introduced in DOM Level 2:
    Node               importNode(in Node importedNode,
                                  in boolean deep)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Element            createElementNS(in DOMString namespaceURI,
                                       in DOMString qualifiedName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    Attr               createAttributeNS(in DOMString namespaceURI,
                                         in DOMString qualifiedName)
                                        raises(DOMException);
    // Introduced in DOM Level 2:
    NodeList           getElementsByTagNameNS(in DOMString namespaceURI,
                                              in DOMString localName);
    // Introduced in DOM Level 2:
    Element            getElementById(in DOMString elementId);
    // Introduced in DOM Level 3:
    readonly attribute DOMString       inputEncoding;
    // Introduced in DOM Level 3:
    readonly attribute DOMString       xmlEncoding;
    // Introduced in DOM Level 3:
             attribute boolean         xmlStandalone;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 3:
             attribute DOMString       xmlVersion;
                                        // raises(DOMException) on setting

    // Introduced in DOM Level 3:
             attribute boolean         strictErrorChecking;
    // Introduced in DOM Level 3:
             attribute DOMString       documentURI;
    // Introduced in DOM Level 3:
    Node               adoptNode(in Node source)
                                        raises(DOMException);
    // Introduced in DOM Level 3:
    readonly attribute DOMConfiguration domConfig;
    // Introduced in DOM Level 3:
    void               normalizeDocument();
    // Introduced in DOM Level 3:
    Node               renameNode(in Node n,
                                  in DOMString namespaceURI,
                                  in DOMString qualifiedName)
                                        raises(DOMException);
  };
};

#endif // _DOM_IDL_


Java Language Binding

07 April 2004

Appendix G: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Core.

The Java files are also available as http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/java-binding.zip

G.1 Java Binding Extension

Note: This section is informative.

This section defines the DOMImplementationRegistry object, discussed in Bootstrapping, for Java.

The DOMImplementationRegistry is first initialized by the application or the implementation, depending on the context, through the Java system property "org.w3c.dom.DOMImplementationSourceList". The value of this property is a space separated list of names of available classes implementing the DOMImplementationSource interface.

org/w3c/dom/bootstrap/DOMImplementationRegistry.java:

package org.w3c.dom.bootstrap;

import java.util.StringTokenizer;
import java.util.Vector;
import org.w3c.dom.DOMImplementationSource;
import org.w3c.dom.DOMImplementationList;
import org.w3c.dom.DOMImplementation;
import java.io.InputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.security.AccessController;
import java.security.PrivilegedAction;

/**
 * A factory that enables applications to obtain instances of
 * <code>DOMImplementation</code>.
 *
 * <p>
 * Example:
 * </p>
 *
 * <pre class='example'>
 *  // get an instance of the DOMImplementation registry
 *  DOMImplementationRegistry registry =
 *       DOMImplementationRegistry.newInstance();
 *  // get a DOM implementation the Level 3 XML module
 *  DOMImplementation domImpl =
 *       registry.getDOMImplementation("XML 3.0");
 * </pre>
 *
 * <p>
 * This provides an application with an implementation-independent starting
 * point. DOM implementations may modify this class to meet new security
 * standards or to provide *additional* fallbacks for the list of
 * DOMImplementationSources.
 * </p>
 *
 * @see DOMImplementation
 * @see DOMImplementationSource
 * @since DOM Level 3
 */
public final class DOMImplementationRegistry {
    /**
     * The system property to specify the
     * DOMImplementationSource class names.
     */
    public static final String PROPERTY =
    "org.w3c.dom.DOMImplementationSourceList";

    /**
     * Default columns per line.
     */
    private static final int DEFAULT_LINE_LENGTH = 80;

    /**
     * The list of DOMImplementationSources.
     */
    private Vector sources;

    /**
     * Private constructor.
     * @param srcs Vector List of DOMImplementationSources
     */
    private DOMImplementationRegistry(final Vector srcs) {
    sources = srcs;
    }

    /**
     * Obtain a new instance of a <code>DOMImplementationRegistry</code>.
     *

     * The <code>DOMImplementationRegistry</code> is initialized by the
     * application or the implementation, depending on the context, by
     * first checking the value of the Java system property
     * <code>org.w3c.dom.DOMImplementationSourceList</code> and
     * the the service provider whose contents are at
     * "<code>META_INF/services/org.w3c.dom.DOMImplementationSourceList</code>"
     * The value of this property is a white-space separated list of
     * names of availables classes implementing the
     * <code>DOMImplementationSource</code> interface. Each class listed
     * in the class name list is instantiated and any exceptions
     * encountered are thrown to the application.
     *
     * @return an initialized instance of DOMImplementationRegistry
     * @throws ClassNotFoundException
     *     If any specified class can not be found
     * @throws InstantiationException
     *     If any specified class is an interface or abstract class
     * @throws IllegalAccessException
     *     If the default constructor of a specified class is not accessible
     * @throws ClassCastException
     *     If any specified class does not implement
     * <code>DOMImplementationSource</code>
     */
    public static DOMImplementationRegistry newInstance()
    throws
    ClassNotFoundException,
    InstantiationException,
    IllegalAccessException,
    ClassCastException {
    Vector sources = new Vector();

    ClassLoader classLoader = getClassLoader();
    // fetch system property:
    String p = getSystemProperty(PROPERTY);

    //
    // if property is not specified then use contents of
        // META_INF/org.w3c.dom.DOMImplementationSourceList from classpath
    if (p == null) {
        p = getServiceValue(classLoader);
    }
        if (p == null) {
        //
        // DOM Implementations can modify here to add *additional* fallback
        // mechanisms to access a list of default DOMImplementationSources.

    }
    if (p != null) {
        StringTokenizer st = new StringTokenizer(p);
        while (st.hasMoreTokens()) {
        String sourceName = st.nextToken();
        // Use context class loader, falling back to Class.forName
        // if and only if this fails...
        Class sourceClass = null;
        if (classLoader != null) {
            sourceClass = classLoader.loadClass(sourceName);
        } else {
            sourceClass = Class.forName(sourceName);
        }
        DOMImplementationSource source =
            (DOMImplementationSource) sourceClass.newInstance();
        sources.addElement(source);
        }
    }
    return new DOMImplementationRegistry(sources);
    }

    /**
     * Return the first implementation that has the desired
     * features, or <code>null</code> if none is found.
     *
     * @param features
     *            A string that specifies which features are required. This is
     *            a space separated list in which each feature is specified by
     *            its name optionally followed by a space and a version number.
     *            This is something like: "XML 1.0 Traversal +Events 2.0"
     * @return An implementation that has the desired features,
     *         or <code>null</code> if none found.
     */
    public DOMImplementation getDOMImplementation(final String features) {
    int size = sources.size();
    String name = null;
    for (int i = 0; i < size; i++) {
        DOMImplementationSource source =
        (DOMImplementationSource) sources.elementAt(i);
        DOMImplementation impl = source.getDOMImplementation(features);
        if (impl != null) {
        return impl;
        }
    }
    return null;
    }

    /**
     * Return a list of implementations that support the
     * desired features.
     *
     * @param features
     *            A string that specifies which features are required. This is
     *            a space separated list in which each feature is specified by
     *            its name optionally followed by a space and a version number.
     *            This is something like: "XML 1.0 Traversal +Events 2.0"
     * @return A list of DOMImplementations that support the desired features.
     */
    public DOMImplementationList getDOMImplementationList(final String features) {
    final Vector implementations = new Vector();
    int size = sources.size();
    for (int i = 0; i < size; i++) {
        DOMImplementationSource source =
        (DOMImplementationSource) sources.elementAt(i);
        DOMImplementationList impls =
        source.getDOMImplementationList(features);
        for (int j = 0; j < impls.getLength(); j++) {
        DOMImplementation impl = impls.item(j);
        implementations.addElement(impl);
        }
    }
    return new DOMImplementationList() {
        public DOMImplementation item(final int index) {
            if (index >= 0 && index < implementations.size()) {
            try {
                return (DOMImplementation)
                implementations.elementAt(index);
            } catch (ArrayIndexOutOfBoundsException e) {
                return null;
            }
            }
            return null;
        }

        public int getLength() {
            return implementations.size();
        }
        };
    }

    /**
     * Register an implementation.
     *
     * @param s The source to be registered, may not be <code>null</code>
     */
    public void addSource(final DOMImplementationSource s) {
    if (s == null) {
        throw new NullPointerException();
    }
    if (!sources.contains(s)) {
        sources.addElement(s);
    }
    }

    /**
     *
     * Gets a class loader.
     *
     * @return A class loader, possibly <code>null</code>
     */
    private static ClassLoader getClassLoader() {
    try {
        ClassLoader contextClassLoader = getContextClassLoader();

        if (contextClassLoader != null) {
        return contextClassLoader;
        }
    } catch (Exception e) {
        // Assume that the DOM application is in a JRE 1.1, use the
        // current ClassLoader
        return DOMImplementationRegistry.class.getClassLoader();
    }
    return DOMImplementationRegistry.class.getClassLoader();
    }

    /**
     * This method attempts to return the first line of the resource
     * META_INF/services/org.w3c.dom.DOMImplementationSourceList
     * from the provided ClassLoader.
     *
     * @param classLoader classLoader, may not be <code>null</code>.
     * @return first line of resource, or <code>null</code>
     */
    private static String getServiceValue(final ClassLoader classLoader) {
    String serviceId = "META-INF/services/" + PROPERTY;
    // try to find services in CLASSPATH
    try {
        InputStream is = getResourceAsStream(classLoader, serviceId);

        if (is != null) {
        BufferedReader rd;
        try {
            rd =
            new BufferedReader(new InputStreamReader(is, "UTF-8"),
                       DEFAULT_LINE_LENGTH);
        } catch (java.io.UnsupportedEncodingException e) {
            rd =
            new BufferedReader(new InputStreamReader(is),
                       DEFAULT_LINE_LENGTH);
        }
        String serviceValue = rd.readLine();
        rd.close();
        if (serviceValue != null && serviceValue.length() > 0) {
            return serviceValue;
        }
        }
    } catch (Exception ex) {
        return null;
    }
    return null;
    }

    /**
     * A simple JRE (Java Runtime Environment) 1.1 test
     *
     * @return <code>true</code> if JRE 1.1
     */
    private static boolean isJRE11() {
    try {
        Class c = Class.forName("java.security.AccessController");
        // java.security.AccessController existed since 1.2 so, if no
        // exception was thrown, the DOM application is running in a JRE
        // 1.2 or higher
        return false;
    } catch (Exception ex) {
        // ignore
    }
    return true;
    }

    /**
     * This method returns the ContextClassLoader or <code>null</code> if
     * running in a JRE 1.1
     *
     * @return The Context Classloader
     */
    private static ClassLoader getContextClassLoader() {
    return isJRE11()
        ? null
        : (ClassLoader)
           AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
            ClassLoader classLoader = null;
            try {
                classLoader =
                Thread.currentThread().getContextClassLoader();
            } catch (SecurityException ex) {
            }
            return classLoader;
            }
        });
    }

    /**
     * This method returns the system property indicated by the specified name
     * after checking access control privileges. For a JRE 1.1, this check is
     * not done.
     *
     * @param name the name of the system property
     * @return the system property
     */
    private static String getSystemProperty(final String name) {
    return isJRE11()
        ? (String) System.getProperty(name)
        : (String) AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
            return System.getProperty(name);
            }
        });
    }

    /**
     * This method returns an Inputstream for the reading resource
     * META_INF/services/org.w3c.dom.DOMImplementationSourceList after checking
     * access control privileges. For a JRE 1.1, this check is not done.
     *
     * @param classLoader classLoader
     * @param name the resource
     * @return an Inputstream for the resource specified
     */
    private static InputStream getResourceAsStream(final ClassLoader classLoader,
                           final String name) {
    if (isJRE11()) {
        InputStream ris;
        if (classLoader == null) {
        ris = ClassLoader.getSystemResourceAsStream(name);
        } else {
        ris = classLoader.getResourceAsStream(name);
        }
        return ris;
    } else {
        return (InputStream)
        AccessController.doPrivileged(new PrivilegedAction() {
            public Object run() {
                InputStream ris;
                if (classLoader == null) {
                ris =
                    ClassLoader.getSystemResourceAsStream(name);
                } else {
                ris = classLoader.getResourceAsStream(name);
                }
                return ris;
            }
            });
    }
    }
}

G.2 Other Core interfaces

org/w3c/dom/DOMException.java:

package org.w3c.dom;

public class DOMException extends RuntimeException {
    public DOMException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // ExceptionCode
    public static final short INDEX_SIZE_ERR            = 1;
    public static final short DOMSTRING_SIZE_ERR        = 2;
    public static final short HIERARCHY_REQUEST_ERR     = 3;
    public static final short WRONG_DOCUMENT_ERR        = 4;
    public static final short INVALID_CHARACTER_ERR     = 5;
    public static final short NO_DATA_ALLOWED_ERR       = 6;
    public static final short NO_MODIFICATION_ALLOWED_ERR = 7;
    public static final short NOT_FOUND_ERR             = 8;
    public static final short NOT_SUPPORTED_ERR         = 9;
    public static final short INUSE_ATTRIBUTE_ERR       = 10;
    public static final short INVALID_STATE_ERR         = 11;
    public static final short SYNTAX_ERR                = 12;
    public static final short INVALID_MODIFICATION_ERR  = 13;
    public static final short NAMESPACE_ERR             = 14;
    public static final short INVALID_ACCESS_ERR        = 15;
    public static final short VALIDATION_ERR            = 16;
    public static final short TYPE_MISMATCH_ERR         = 17;

}

org/w3c/dom/DOMStringList.java:

package org.w3c.dom;

public interface DOMStringList {
    public String item(int index);

    public int getLength();

    public boolean contains(String str);

}

org/w3c/dom/NameList.java:

package org.w3c.dom;

public interface NameList {
    public String getName(int index);

    public String getNamespaceURI(int index);

    public int getLength();

    public boolean contains(String str);

    public boolean containsNS(String namespaceURI,
                              String name);

}

org/w3c/dom/DOMImplementationList.java:

package org.w3c.dom;

public interface DOMImplementationList {
    public DOMImplementation item(int index);

    public int getLength();

}

org/w3c/dom/DOMImplementationSource.java:

package org.w3c.dom;

public interface DOMImplementationSource {
    public DOMImplementation getDOMImplementation(String features);

    public DOMImplementationList getDOMImplementationList(String features);

}

org/w3c/dom/DOMImplementation.java:

package org.w3c.dom;

public interface DOMImplementation {
    public boolean hasFeature(String feature,
                              String version);

    public DocumentType createDocumentType(String qualifiedName,
                                           String publicId,
                                           String systemId)
                                           throws DOMException;

    public Document createDocument(String namespaceURI,
                                   String qualifiedName,
                                   DocumentType doctype)
                                   throws DOMException;

    public Object getFeature(String feature,
                             String version);

}

org/w3c/dom/DocumentFragment.java:

package org.w3c.dom;

public interface DocumentFragment extends Node {
}

org/w3c/dom/Document.java:

package org.w3c.dom;

public interface Document extends Node {
    public DocumentType getDoctype();

    public DOMImplementation getImplementation();

    public Element getDocumentElement();

    public Element createElement(String tagName)
                                 throws DOMException;

    public DocumentFragment createDocumentFragment();

    public Text createTextNode(String data);

    public Comment createComment(String data);

    public CDATASection createCDATASection(String data)
                                           throws DOMException;

    public ProcessingInstruction createProcessingInstruction(String target,
                                                             String data)
                                                             throws DOMException;

    public Attr createAttribute(String name)
                                throws DOMException;

    public EntityReference createEntityReference(String name)
                                                 throws DOMException;

    public NodeList getElementsByTagName(String tagname);

    public Node importNode(Node importedNode,
                           boolean deep)
                           throws DOMException;

    public Element createElementNS(String namespaceURI,
                                   String qualifiedName)
                                   throws DOMException;

    public Attr createAttributeNS(String namespaceURI,
                                  String qualifiedName)
                                  throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI,
                                           String localName);

    public Element getElementById(String elementId);

    public String getInputEncoding();

    public String getXmlEncoding();

    public boolean getXmlStandalone();
    public void setXmlStandalone(boolean xmlStandalone)
                                  throws DOMException;

    public String getXmlVersion();
    public void setXmlVersion(String xmlVersion)
                                  throws DOMException;

    public boolean getStrictErrorChecking();
    public void setStrictErrorChecking(boolean strictErrorChecking);

    public String getDocumentURI();
    public void setDocumentURI(String documentURI);

    public Node adoptNode(Node source)
                          throws DOMException;

    public DOMConfiguration getDomConfig();

    public void normalizeDocument();

    public Node renameNode(Node n,
                           String namespaceURI,
                           String qualifiedName)
                           throws DOMException;

}

org/w3c/dom/Node.java:

package org.w3c.dom;

public interface Node {
    // NodeType
    public static final short ELEMENT_NODE              = 1;
    public static final short ATTRIBUTE_NODE            = 2;
    public static final short TEXT_NODE                 = 3;
    public static final short CDATA_SECTION_NODE        = 4;
    public static final short ENTITY_REFERENCE_NODE     = 5;
    public static final short ENTITY_NODE               = 6;
    public static final short PROCESSING_INSTRUCTION_NODE = 7;
    public static final short COMMENT_NODE              = 8;
    public static final short DOCUMENT_NODE             = 9;
    public static final short DOCUMENT_TYPE_NODE        = 10;
    public static final short DOCUMENT_FRAGMENT_NODE    = 11;
    public static final short NOTATION_NODE             = 12;

    public String getNodeName();

    public String getNodeValue()
                           throws DOMException;
    public void setNodeValue(String nodeValue)
                           throws DOMException;

    public short getNodeType();

    public Node getParentNode();

    public NodeList getChildNodes();

    public Node getFirstChild();

    public Node getLastChild();

    public Node getPreviousSibling();

    public Node getNextSibling();

    public NamedNodeMap getAttributes();

    public Document getOwnerDocument();

    public Node insertBefore(Node newChild,
                             Node refChild)
                             throws DOMException;

    public Node replaceChild(Node newChild,
                             Node oldChild)
                             throws DOMException;

    public Node removeChild(Node oldChild)
                            throws DOMException;

    public Node appendChild(Node newChild)
                            throws DOMException;

    public boolean hasChildNodes();

    public Node cloneNode(boolean deep);

    public void normalize();

    public boolean isSupported(String feature,
                               String version);

    public String getNamespaceURI();

    public String getPrefix();
    public void setPrefix(String prefix)
                               throws DOMException;

    public String getLocalName();

    public boolean hasAttributes();

    public String getBaseURI();

    // DocumentPosition
    public static final short DOCUMENT_POSITION_DISCONNECTED = 0x01;
    public static final short DOCUMENT_POSITION_PRECEDING = 0x02;
    public static final short DOCUMENT_POSITION_FOLLOWING = 0x04;
    public static final short DOCUMENT_POSITION_CONTAINS = 0x08;
    public static final short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
    public static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;

    public short compareDocumentPosition(Node other)
                                         throws DOMException;

    public String getTextContent()
                                         throws DOMException;
    public void setTextContent(String textContent)
                                         throws DOMException;

    public boolean isSameNode(Node other);

    public String lookupPrefix(String namespaceURI);

    public boolean isDefaultNamespace(String namespaceURI);

    public String lookupNamespaceURI(String prefix);

    public boolean isEqualNode(Node arg);

    public Object getFeature(String feature,
                             String version);

    public Object setUserData(String key,
                              Object data,
                              UserDataHandler handler);

    public Object getUserData(String key);

}

org/w3c/dom/NodeList.java:

package org.w3c.dom;

public interface NodeList {
    public Node item(int index);

    public int getLength();

}

org/w3c/dom/NamedNodeMap.java:

package org.w3c.dom;

public interface NamedNodeMap {
    public Node getNamedItem(String name);

    public Node setNamedItem(Node arg)
                             throws DOMException;

    public Node removeNamedItem(String name)
                                throws DOMException;

    public Node item(int index);

    public int getLength();

    public Node getNamedItemNS(String namespaceURI,
                               String localName)
                               throws DOMException;

    public Node setNamedItemNS(Node arg)
                               throws DOMException;

    public Node removeNamedItemNS(String namespaceURI,
                                  String localName)
                                  throws DOMException;

}

org/w3c/dom/CharacterData.java:

package org.w3c.dom;

public interface CharacterData extends Node {
    public String getData()
                                  throws DOMException;
    public void setData(String data)
                                  throws DOMException;

    public int getLength();

    public String substringData(int offset,
                                int count)
                                throws DOMException;

    public void appendData(String arg)
                           throws DOMException;

    public void insertData(int offset,
                           String arg)
                           throws DOMException;

    public void deleteData(int offset,
                           int count)
                           throws DOMException;

    public void replaceData(int offset,
                            int count,
                            String arg)
                            throws DOMException;

}

org/w3c/dom/Attr.java:

package org.w3c.dom;

public interface Attr extends Node {
    public String getName();

    public boolean getSpecified();

    public String getValue();
    public void setValue(String value)
                            throws DOMException;

    public Element getOwnerElement();

    public TypeInfo getSchemaTypeInfo();

    public boolean isId();

}

org/w3c/dom/Element.java:

package org.w3c.dom;

public interface Element extends Node {
    public String getTagName();

    public String getAttribute(String name);

    public void setAttribute(String name,
                             String value)
                             throws DOMException;

    public void removeAttribute(String name)
                                throws DOMException;

    public Attr getAttributeNode(String name);

    public Attr setAttributeNode(Attr newAttr)
                                 throws DOMException;

    public Attr removeAttributeNode(Attr oldAttr)
                                    throws DOMException;

    public NodeList getElementsByTagName(String name);

    public String getAttributeNS(String namespaceURI,
                                 String localName)
                                 throws DOMException;

    public void setAttributeNS(String namespaceURI,
                               String qualifiedName,
                               String value)
                               throws DOMException;

    public void removeAttributeNS(String namespaceURI,
                                  String localName)
                                  throws DOMException;

    public Attr getAttributeNodeNS(String namespaceURI,
                                   String localName)
                                   throws DOMException;

    public Attr setAttributeNodeNS(Attr newAttr)
                                   throws DOMException;

    public NodeList getElementsByTagNameNS(String namespaceURI,
                                           String localName)
                                           throws DOMException;

    public boolean hasAttribute(String name);

    public boolean hasAttributeNS(String namespaceURI,
                                  String localName)
                                  throws DOMException;

    public TypeInfo getSchemaTypeInfo();

    public void setIdAttribute(String name,
                               boolean isId)
                               throws DOMException;

    public void setIdAttributeNS(String namespaceURI,
                                 String localName,
                                 boolean isId)
                                 throws DOMException;

    public void setIdAttributeNode(Attr idAttr,
                                   boolean isId)
                                   throws DOMException;

}

org/w3c/dom/Text.java:

package org.w3c.dom;

public interface Text extends CharacterData {
    public Text splitText(int offset)
                          throws DOMException;

    public boolean isElementContentWhitespace();

    public String getWholeText();

    public Text replaceWholeText(String content)
                                 throws DOMException;

}

org/w3c/dom/Comment.java:

package org.w3c.dom;

public interface Comment extends CharacterData {
}

org/w3c/dom/TypeInfo.java:

package org.w3c.dom;

public interface TypeInfo {
    public String getTypeName();

    public String getTypeNamespace();

    // DerivationMethods
    public static final int DERIVATION_RESTRICTION    = 0x00000001;
    public static final int DERIVATION_EXTENSION      = 0x00000002;
    public static final int DERIVATION_UNION          = 0x00000004;
    public static final int DERIVATION_LIST           = 0x00000008;

    public boolean isDerivedFrom(String typeNamespaceArg,
                                 String typeNameArg,
                                 int derivationMethod);

}

org/w3c/dom/UserDataHandler.java:

package org.w3c.dom;

public interface UserDataHandler {
    // OperationType
    public static final short NODE_CLONED               = 1;
    public static final short NODE_IMPORTED             = 2;
    public static final short NODE_DELETED              = 3;
    public static final short NODE_RENAMED              = 4;
    public static final short NODE_ADOPTED              = 5;

    public void handle(short operation,
                       String key,
                       Object data,
                       Node src,
                       Node dst);

}

org/w3c/dom/DOMError.java:

package org.w3c.dom;

public interface DOMError {
    // ErrorSeverity
    public static final short SEVERITY_WARNING          = 1;
    public static final short SEVERITY_ERROR            = 2;
    public static final short SEVERITY_FATAL_ERROR      = 3;

    public short getSeverity();

    public String getMessage();

    public String getType();

    public Object getRelatedException();

    public Object getRelatedData();

    public DOMLocator getLocation();

}

org/w3c/dom/DOMErrorHandler.java:

package org.w3c.dom;

public interface DOMErrorHandler {
    public boolean handleError(DOMError error);

}

org/w3c/dom/DOMLocator.java:

package org.w3c.dom;

public interface DOMLocator {
    public int getLineNumber();

    public int getColumnNumber();

    public int getByteOffset();

    public int getUtf16Offset();

    public Node getRelatedNode();

    public String getUri();

}

org/w3c/dom/DOMConfiguration.java:

package org.w3c.dom;

public interface DOMConfiguration {
    public void setParameter(String name,
                             Object value)
                             throws DOMException;

    public Object getParameter(String name)
                               throws DOMException;

    public boolean canSetParameter(String name,
                                   Object value);

    public DOMStringList getParameterNames();

}

org/w3c/dom/CDATASection.java:

package org.w3c.dom;

public interface CDATASection extends Text {
}

org/w3c/dom/DocumentType.java:

package org.w3c.dom;

public interface DocumentType extends Node {
    public String getName();

    public NamedNodeMap getEntities();

    public NamedNodeMap getNotations();

    public String getPublicId();

    public String getSystemId();

    public String getInternalSubset();

}

org/w3c/dom/Notation.java:

package org.w3c.dom;

public interface Notation extends Node {
    public String getPublicId();

    public String getSystemId();

}

org/w3c/dom/Entity.java:

package org.w3c.dom;

public interface Entity extends Node {
    public String getPublicId();

    public String getSystemId();

    public String getNotationName();

    public String getInputEncoding();

    public String getXmlEncoding();

    public String getXmlVersion();

}

org/w3c/dom/EntityReference.java:

package org.w3c.dom;

public interface EntityReference extends Node {
}

org/w3c/dom/ProcessingInstruction.java:

package org.w3c.dom;

public interface ProcessingInstruction extends Node {
    public String getTarget();

    public String getData();
    public void setData(String data)
                                   throws DOMException;

}


ECMAScript Language Binding

07 April 2004

Appendix H: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Core definitions.

H.1 ECMAScript Binding Extension

This section defines the DOMImplementationRegistry object, discussed in Bootstrapping, for ECMAScript.

Objects that implements the DOMImplementationRegistry interface
DOMImplementationRegistry is a global variable which has the following functions:
getDOMImplementation(features)
This method returns the first registered object that implements the DOMImplementation interface and has the desired features, or null if none is found.
The features parameter is a String. See also DOMImplementationSource.getDOMImplementation().
getDOMImplementationList(features)
This method returns a DOMImplementationList list of registered object that implements the DOMImplementation interface and has the desired features.
The features parameter is a String. See also DOMImplementationSource.getDOMImplementationList().

H.2 Other Core interfaces

Properties of the DOMException Constructor function:
DOMException.INDEX_SIZE_ERR
The value of the constant DOMException.INDEX_SIZE_ERR is 1.
DOMException.DOMSTRING_SIZE_ERR
The value of the constant DOMException.DOMSTRING_SIZE_ERR is 2.
DOMException.HIERARCHY_REQUEST_ERR
The value of the constant DOMException.HIERARCHY_REQUEST_ERR is 3.
DOMException.WRONG_DOCUMENT_ERR
The value of the constant DOMException.WRONG_DOCUMENT_ERR is 4.
DOMException.INVALID_CHARACTER_ERR
The value of the constant DOMException.INVALID_CHARACTER_ERR is 5.
DOMException.NO_DATA_ALLOWED_ERR
The value of the constant DOMException.NO_DATA_ALLOWED_ERR is 6.
DOMException.NO_MODIFICATION_ALLOWED_ERR
The value of the constant DOMException.NO_MODIFICATION_ALLOWED_ERR is 7.
DOMException.NOT_FOUND_ERR
The value of the constant DOMException.NOT_FOUND_ERR is 8.
DOMException.NOT_SUPPORTED_ERR
The value of the constant DOMException.NOT_SUPPORTED_ERR is 9.
DOMException.INUSE_ATTRIBUTE_ERR
The value of the constant DOMException.INUSE_ATTRIBUTE_ERR is 10.
DOMException.INVALID_STATE_ERR
The value of the constant DOMException.INVALID_STATE_ERR is 11.
DOMException.SYNTAX_ERR
The value of the constant DOMException.SYNTAX_ERR is 12.
DOMException.INVALID_MODIFICATION_ERR
The value of the constant DOMException.INVALID_MODIFICATION_ERR is 13.
DOMException.NAMESPACE_ERR
The value of the constant DOMException.NAMESPACE_ERR is 14.
DOMException.INVALID_ACCESS_ERR
The value of the constant DOMException.INVALID_ACCESS_ERR is 15.
DOMException.VALIDATION_ERR
The value of the constant DOMException.VALIDATION_ERR is 16.
DOMException.TYPE_MISMATCH_ERR
The value of the constant DOMException.TYPE_MISMATCH_ERR is 17.
Objects that implement the DOMException interface:
Properties of objects that implement the DOMException interface:
code
This property is a Number.
Objects that implement the DOMStringList interface:
Properties of objects that implement the DOMStringList interface:
length
This read-only property is a Number.
Functions of objects that implement the DOMStringList interface:
item(index)
This function returns a String.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
contains(str)
This function returns a Boolean.
The str parameter is a String.
Objects that implement the NameList interface:
Properties of objects that implement the NameList interface:
length
This read-only property is a Number.
Functions of objects that implement the NameList interface:
getName(index)
This function returns a String.
The index parameter is a Number.
getNamespaceURI(index)
This function returns a String.
The index parameter is a Number.
contains(str)
This function returns a Boolean.
The str parameter is a String.
containsNS(namespaceURI, name)
This function returns a Boolean.
The namespaceURI parameter is a String.
The name parameter is a String.
Objects that implement the DOMImplementationList interface:
Properties of objects that implement the DOMImplementationList interface:
length
This read-only property is a Number.
Functions of objects that implement the DOMImplementationList interface:
item(index)
This function returns an object that implements the DOMImplementation interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
Objects that implement the DOMImplementationSource interface:
Functions of objects that implement the DOMImplementationSource interface:
getDOMImplementation(features)
This function returns an object that implements the DOMImplementation interface.
The features parameter is a String.
getDOMImplementationList(features)
This function returns an object that implements the DOMImplementationList interface.
The features parameter is a String.
Objects that implement the DOMImplementation interface:
Functions of objects that implement the DOMImplementation interface:
hasFeature(feature, version)
This function returns a Boolean.
The feature parameter is a String.
The version parameter is a String.
createDocumentType(qualifiedName, publicId, systemId)
This function returns an object that implements the DocumentType interface.
The qualifiedName parameter is a String.
The publicId parameter is a String.
The systemId parameter is a String.
This function can raise an object that implements the DOMException interface.
createDocument(namespaceURI, qualifiedName, doctype)
This function returns an object that implements the Document interface.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
The doctype parameter is an object that implements the DocumentType interface.
This function can raise an object that implements the DOMException interface.
getFeature(feature, version)
This function returns an object that implements the Object interface.
The feature parameter is a String.
The version parameter is a String.
Objects that implement the DocumentFragment interface:
Objects that implement the DocumentFragment interface have all properties and functions of the Node interface.
Objects that implement the Document interface:
Objects that implement the Document interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the Document interface:
doctype
This read-only property is an object that implements the DocumentType interface.
implementation
This read-only property is an object that implements the DOMImplementation interface.
documentElement
This read-only property is an object that implements the Element interface.
inputEncoding
This read-only property is a String.
xmlEncoding
This read-only property is a String.
xmlStandalone
This property is a Boolean and can raise an object that implements the DOMException interface on setting.
xmlVersion
This property is a String and can raise an object that implements the DOMException interface on setting.
strictErrorChecking
This property is a Boolean.
documentURI
This property is a String.
domConfig
This read-only property is an object that implements the DOMConfiguration interface.
Functions of objects that implement the Document interface:
createElement(tagName)
This function returns an object that implements the Element interface.
The tagName parameter is a String.
This function can raise an object that implements the DOMException interface.
createDocumentFragment()
This function returns an object that implements the DocumentFragment interface.
createTextNode(data)
This function returns an object that implements the Text interface.
The data parameter is a String.
createComment(data)
This function returns an object that implements the Comment interface.
The data parameter is a String.
createCDATASection(data)
This function returns an object that implements the CDATASection interface.
The data parameter is a String.
This function can raise an object that implements the DOMException interface.
createProcessingInstruction(target, data)
This function returns an object that implements the ProcessingInstruction interface.
The target parameter is a String.
The data parameter is a String.
This function can raise an object that implements the DOMException interface.
createAttribute(name)
This function returns an object that implements the Attr interface.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
createEntityReference(name)
This function returns an object that implements the EntityReference interface.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
getElementsByTagName(tagname)
This function returns an object that implements the NodeList interface.
The tagname parameter is a String.
importNode(importedNode, deep)
This function returns an object that implements the Node interface.
The importedNode parameter is an object that implements the Node interface.
The deep parameter is a Boolean.
This function can raise an object that implements the DOMException interface.
createElementNS(namespaceURI, qualifiedName)
This function returns an object that implements the Element interface.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
This function can raise an object that implements the DOMException interface.
createAttributeNS(namespaceURI, qualifiedName)
This function returns an object that implements the Attr interface.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
This function can raise an object that implements the DOMException interface.
getElementsByTagNameNS(namespaceURI, localName)
This function returns an object that implements the NodeList interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
getElementById(elementId)
This function returns an object that implements the Element interface.
The elementId parameter is a String.
adoptNode(source)
This function returns an object that implements the Node interface.
The source parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
normalizeDocument()
This function has no return value.
renameNode(n, namespaceURI, qualifiedName)
This function returns an object that implements the Node interface.
The n parameter is an object that implements the Node interface.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
This function can raise an object that implements the DOMException interface.
Properties of the Node Constructor function:
Node.ELEMENT_NODE
The value of the constant Node.ELEMENT_NODE is 1.
Node.ATTRIBUTE_NODE
The value of the constant Node.ATTRIBUTE_NODE is 2.
Node.TEXT_NODE
The value of the constant Node.TEXT_NODE is 3.
Node.CDATA_SECTION_NODE
The value of the constant Node.CDATA_SECTION_NODE is 4.
Node.ENTITY_REFERENCE_NODE
The value of the constant Node.ENTITY_REFERENCE_NODE is 5.
Node.ENTITY_NODE
The value of the constant Node.ENTITY_NODE is 6.
Node.PROCESSING_INSTRUCTION_NODE
The value of the constant Node.PROCESSING_INSTRUCTION_NODE is 7.
Node.COMMENT_NODE
The value of the constant Node.COMMENT_NODE is 8.
Node.DOCUMENT_NODE
The value of the constant Node.DOCUMENT_NODE is 9.
Node.DOCUMENT_TYPE_NODE
The value of the constant Node.DOCUMENT_TYPE_NODE is 10.
Node.DOCUMENT_FRAGMENT_NODE
The value of the constant Node.DOCUMENT_FRAGMENT_NODE is 11.
Node.NOTATION_NODE
The value of the constant Node.NOTATION_NODE is 12.
Node.DOCUMENT_POSITION_DISCONNECTED
The value of the constant Node.DOCUMENT_POSITION_DISCONNECTED is 0x01.
Node.DOCUMENT_POSITION_PRECEDING
The value of the constant Node.DOCUMENT_POSITION_PRECEDING is 0x02.
Node.DOCUMENT_POSITION_FOLLOWING
The value of the constant Node.DOCUMENT_POSITION_FOLLOWING is 0x04.
Node.DOCUMENT_POSITION_CONTAINS
The value of the constant Node.DOCUMENT_POSITION_CONTAINS is 0x08.
Node.DOCUMENT_POSITION_CONTAINED_BY
The value of the constant Node.DOCUMENT_POSITION_CONTAINED_BY is 0x10.
Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC
The value of the constant Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC is 0x20.
Objects that implement the Node interface:
Properties of objects that implement the Node interface:
nodeName
This read-only property is a String.
nodeValue
This property is a String, can raise an object that implements the DOMException interface on setting and can raise an object that implements the DOMException interface on retrieval.
nodeType
This read-only property is a Number.
parentNode
This read-only property is an object that implements the Node interface.
childNodes
This read-only property is an object that implements the NodeList interface.
firstChild
This read-only property is an object that implements the Node interface.
lastChild
This read-only property is an object that implements the Node interface.
previousSibling
This read-only property is an object that implements the Node interface.
nextSibling
This read-only property is an object that implements the Node interface.
attributes
This read-only property is an object that implements the NamedNodeMap interface.
ownerDocument
This read-only property is an object that implements the Document interface.
namespaceURI
This read-only property is a String.
prefix
This property is a String and can raise an object that implements the DOMException interface on setting.
localName
This read-only property is a String.
baseURI
This read-only property is a String.
textContent
This property is a String, can raise an object that implements the DOMException interface on setting and can raise an object that implements the DOMException interface on retrieval.
Functions of objects that implement the Node interface:
insertBefore(newChild, refChild)
This function returns an object that implements the Node interface.
The newChild parameter is an object that implements the Node interface.
The refChild parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
replaceChild(newChild, oldChild)
This function returns an object that implements the Node interface.
The newChild parameter is an object that implements the Node interface.
The oldChild parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
removeChild(oldChild)
This function returns an object that implements the Node interface.
The oldChild parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
appendChild(newChild)
This function returns an object that implements the Node interface.
The newChild parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
hasChildNodes()
This function returns a Boolean.
cloneNode(deep)
This function returns an object that implements the Node interface.
The deep parameter is a Boolean.
normalize()
This function has no return value.
isSupported(feature, version)
This function returns a Boolean.
The feature parameter is a String.
The version parameter is a String.
hasAttributes()
This function returns a Boolean.
compareDocumentPosition(other)
This function returns a Number.
The other parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
isSameNode(other)
This function returns a Boolean.
The other parameter is an object that implements the Node interface.
lookupPrefix(namespaceURI)
This function returns a String.
The namespaceURI parameter is a String.
isDefaultNamespace(namespaceURI)
This function returns a Boolean.
The namespaceURI parameter is a String.
lookupNamespaceURI(prefix)
This function returns a String.
The prefix parameter is a String.
isEqualNode(arg)
This function returns a Boolean.
The arg parameter is an object that implements the Node interface.
getFeature(feature, version)
This function returns an object that implements the Object interface.
The feature parameter is a String.
The version parameter is a String.
setUserData(key, data, handler)
This function returns an object that implements the any type interface.
The key parameter is a String.
The data parameter is an object that implements the any type interface.
The handler parameter is an object that implements the UserDataHandler interface.
getUserData(key)
This function returns an object that implements the any type interface.
The key parameter is a String.
Objects that implement the NodeList interface:
Properties of objects that implement the NodeList interface:
length
This read-only property is a Number.
Functions of objects that implement the NodeList interface:
item(index)
This function returns an object that implements the Node interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
Objects that implement the NamedNodeMap interface:
Properties of objects that implement the NamedNodeMap interface:
length
This read-only property is a Number.
Functions of objects that implement the NamedNodeMap interface:
getNamedItem(name)
This function returns an object that implements the Node interface.
The name parameter is a String.
setNamedItem(arg)
This function returns an object that implements the Node interface.
The arg parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
removeNamedItem(name)
This function returns an object that implements the Node interface.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
item(index)
This function returns an object that implements the Node interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
getNamedItemNS(namespaceURI, localName)
This function returns an object that implements the Node interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
setNamedItemNS(arg)
This function returns an object that implements the Node interface.
The arg parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface.
removeNamedItemNS(namespaceURI, localName)
This function returns an object that implements the Node interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
Objects that implement the CharacterData interface:
Objects that implement the CharacterData interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the CharacterData interface:
data
This property is a String, can raise an object that implements the DOMException interface on setting and can raise an object that implements the DOMException interface on retrieval.
length
This read-only property is a Number.
Functions of objects that implement the CharacterData interface:
substringData(offset, count)
This function returns a String.
The offset parameter is a Number.
The count parameter is a Number.
This function can raise an object that implements the DOMException interface.
appendData(arg)
This function has no return value.
The arg parameter is a String.
This function can raise an object that implements the DOMException interface.
insertData(offset, arg)
This function has no return value.
The offset parameter is a Number.
The arg parameter is a String.
This function can raise an object that implements the DOMException interface.
deleteData(offset, count)
This function has no return value.
The offset parameter is a Number.
The count parameter is a Number.
This function can raise an object that implements the DOMException interface.
replaceData(offset, count, arg)
This function has no return value.
The offset parameter is a Number.
The count parameter is a Number.
The arg parameter is a String.
This function can raise an object that implements the DOMException interface.
Objects that implement the Attr interface:
Objects that implement the Attr interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the Attr interface:
name
This read-only property is a String.
specified
This read-only property is a Boolean.
value
This property is a String and can raise an object that implements the DOMException interface on setting.
ownerElement
This read-only property is an object that implements the Element interface.
schemaTypeInfo
This read-only property is an object that implements the TypeInfo interface.
isId
This read-only property is a Boolean.
Objects that implement the Element interface:
Objects that implement the Element interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the Element interface:
tagName
This read-only property is a String.
schemaTypeInfo
This read-only property is an object that implements the TypeInfo interface.
Functions of objects that implement the Element interface:
getAttribute(name)
This function returns a String.
The name parameter is a String.
setAttribute(name, value)
This function has no return value.
The name parameter is a String.
The value parameter is a String.
This function can raise an object that implements the DOMException interface.
removeAttribute(name)
This function has no return value.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
getAttributeNode(name)
This function returns an object that implements the Attr interface.
The name parameter is a String.
setAttributeNode(newAttr)
This function returns an object that implements the Attr interface.
The newAttr parameter is an object that implements the Attr interface.
This function can raise an object that implements the DOMException interface.
removeAttributeNode(oldAttr)
This function returns an object that implements the Attr interface.
The oldAttr parameter is an object that implements the Attr interface.
This function can raise an object that implements the DOMException interface.
getElementsByTagName(name)
This function returns an object that implements the NodeList interface.
The name parameter is a String.
getAttributeNS(namespaceURI, localName)
This function returns a String.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
setAttributeNS(namespaceURI, qualifiedName, value)
This function has no return value.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
The value parameter is a String.
This function can raise an object that implements the DOMException interface.
removeAttributeNS(namespaceURI, localName)
This function has no return value.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
getAttributeNodeNS(namespaceURI, localName)
This function returns an object that implements the Attr interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
setAttributeNodeNS(newAttr)
This function returns an object that implements the Attr interface.
The newAttr parameter is an object that implements the Attr interface.
This function can raise an object that implements the DOMException interface.
getElementsByTagNameNS(namespaceURI, localName)
This function returns an object that implements the NodeList interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
hasAttribute(name)
This function returns a Boolean.
The name parameter is a String.
hasAttributeNS(namespaceURI, localName)
This function returns a Boolean.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
setIdAttribute(name, isId)
This function has no return value.
The name parameter is a String.
The isId parameter is a Boolean.
This function can raise an object that implements the DOMException interface.
setIdAttributeNS(namespaceURI, localName, isId)
This function has no return value.
The namespaceURI parameter is a String.
The localName parameter is a String.
The isId parameter is a Boolean.
This function can raise an object that implements the DOMException interface.
setIdAttributeNode(idAttr, isId)
This function has no return value.
The idAttr parameter is an object that implements the Attr interface.
The isId parameter is a Boolean.
This function can raise an object that implements the DOMException interface.
Objects that implement the Text interface:
Objects that implement the Text interface have all properties and functions of the CharacterData interface as well as the properties and functions defined below.
Properties of objects that implement the Text interface:
isElementContentWhitespace
This read-only property is a Boolean.
wholeText
This read-only property is a String.
Functions of objects that implement the Text interface:
splitText(offset)
This function returns an object that implements the Text interface.
The offset parameter is a Number.
This function can raise an object that implements the DOMException interface.
replaceWholeText(content)
This function returns an object that implements the Text interface.
The content parameter is a String.
This function can raise an object that implements the DOMException interface.
Objects that implement the Comment interface:
Objects that implement the Comment interface have all properties and functions of the CharacterData interface.
Properties of the TypeInfo Constructor function:
TypeInfo.DERIVATION_RESTRICTION
The value of the constant TypeInfo.DERIVATION_RESTRICTION is 0x00000001.
TypeInfo.DERIVATION_EXTENSION
The value of the constant TypeInfo.DERIVATION_EXTENSION is 0x00000002.
TypeInfo.DERIVATION_UNION
The value of the constant TypeInfo.DERIVATION_UNION is 0x00000004.
TypeInfo.DERIVATION_LIST
The value of the constant TypeInfo.DERIVATION_LIST is 0x00000008.
Objects that implement the TypeInfo interface:
Properties of objects that implement the TypeInfo interface:
typeName
This read-only property is a String.
typeNamespace
This read-only property is a String.
Functions of objects that implement the TypeInfo interface:
isDerivedFrom(typeNamespaceArg, typeNameArg, derivationMethod)
This function returns a Boolean.
The typeNamespaceArg parameter is a String.
The typeNameArg parameter is a String.
The derivationMethod parameter is a Number.
Properties of the UserDataHandler Constructor function:
UserDataHandler.NODE_CLONED
The value of the constant UserDataHandler.NODE_CLONED is 1.
UserDataHandler.NODE_IMPORTED
The value of the constant UserDataHandler.NODE_IMPORTED is 2.
UserDataHandler.NODE_DELETED
The value of the constant UserDataHandler.NODE_DELETED is 3.
UserDataHandler.NODE_RENAMED
The value of the constant UserDataHandler.NODE_RENAMED is 4.
UserDataHandler.NODE_ADOPTED
The value of the constant UserDataHandler.NODE_ADOPTED is 5.
UserDataHandler function:
This function has no return value. The first parameter is a Number. The second parameter is a String. The third parameter is an object that implements the any type interface. The fourth parameter is an object that implements the Node interface. The fifth parameter is an object that implements the Node interface.
Properties of the DOMError Constructor function:
DOMError.SEVERITY_WARNING
The value of the constant DOMError.SEVERITY_WARNING is 1.
DOMError.SEVERITY_ERROR
The value of the constant DOMError.SEVERITY_ERROR is 2.
DOMError.SEVERITY_FATAL_ERROR
The value of the constant DOMError.SEVERITY_FATAL_ERROR is 3.
Objects that implement the DOMError interface:
Properties of objects that implement the DOMError interface:
severity
This read-only property is a Number.
message
This read-only property is a String.
type
This read-only property is a String.
relatedException
This read-only property is an object that implements the Object interface.
relatedData
This read-only property is an object that implements the Object interface.
location
This read-only property is an object that implements the DOMLocator interface.
DOMErrorHandler function:
This function returns a Boolean. The parameter is an object that implements the DOMError interface.
Objects that implement the DOMLocator interface:
Properties of objects that implement the DOMLocator interface:
lineNumber
This read-only property is a Number.
columnNumber
This read-only property is a Number.
byteOffset
This read-only property is a Number.
utf16Offset
This read-only property is a Number.
relatedNode
This read-only property is an object that implements the Node interface.
uri
This read-only property is a String.
Objects that implement the DOMConfiguration interface:
Properties of objects that implement the DOMConfiguration interface:
parameterNames
This read-only property is an object that implements the DOMStringList interface.
Functions of objects that implement the DOMConfiguration interface:
setParameter(name, value)
This function has no return value.
The name parameter is a String.
The value parameter is an object that implements the any type interface.
This function can raise an object that implements the DOMException interface.
getParameter(name)
This function returns an object that implements the any type interface.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
canSetParameter(name, value)
This function returns a Boolean.
The name parameter is a String.
The value parameter is an object that implements the any type interface.
Objects that implement the CDATASection interface:
Objects that implement the CDATASection interface have all properties and functions of the Text interface.
Objects that implement the DocumentType interface:
Objects that implement the DocumentType interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the DocumentType interface:
name
This read-only property is a String.
entities
This read-only property is an object that implements the NamedNodeMap interface.
notations
This read-only property is an object that implements the NamedNodeMap interface.
publicId
This read-only property is a String.
systemId
This read-only property is a String.
internalSubset
This read-only property is a String.
Objects that implement the Notation interface:
Objects that implement the Notation interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the Notation interface:
publicId
This read-only property is a String.
systemId
This read-only property is a String.
Objects that implement the Entity interface:
Objects that implement the Entity interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the Entity interface:
publicId
This read-only property is a String.
systemId
This read-only property is a String.
notationName
This read-only property is a String.
inputEncoding
This read-only property is a String.
xmlEncoding
This read-only property is a String.
xmlVersion
This read-only property is a String.
Objects that implement the EntityReference interface:
Objects that implement the EntityReference interface have all properties and functions of the Node interface.
Objects that implement the ProcessingInstruction interface:
Objects that implement the ProcessingInstruction interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the ProcessingInstruction interface:
target
This read-only property is a String.
data
This property is a String and can raise an object that implements the DOMException interface on setting.

Note: In addition of having DOMConfiguration parameters exposed to the application using the setParameter and getParameter, those parameters are also exposed as ECMAScript properties on the DOMConfiguration object. The name of the parameter is converted into a property name using a camel-case convention: the character '-' (HYPHEN-MINUS) is removed and the following character is being replaced by its uppercase equivalent.


Acknowledgements

07 April 2004

Appendix I: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

Many thanks to Andrew Clover, Petteri Stenius, Curt Arnold, Glenn A. Adams, Christopher Aillon, Scott Nichol, François Yergeau, Anjana Manian, Susan Lesch, and Jeffery B. Rancier for their review and comments of this document.

Special thanks to the DOM Conformance Test Suites contributors: Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape), with a special mention to Curt Arnold.

I.1 Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

16-bit unit
The base unit of a DOMString. This indicates that indexing on a DOMString occurs in units of 16 bits. This must not be misunderstood to mean that a DOMString can store arbitrary 16-bit units. A DOMString is a character string encoded in UTF-16; this means that the restrictions of UTF-16 as well as the other relevant restrictions on character strings must be maintained. A single character, for example in the form of a numeric character reference, may correspond to one or two 16-bit units.
ancestor
An ancestor node of any node A is any node above A in a tree model, where "above" means "toward the root."
API
An API is an Application Programming Interface, a set of functions or methods used to access some functionality.
anonymous type name
An anonymous type name is an implementation-defined, globally unique qualified name provided by the processor for every anonymous type declared in a schema.
child
A child is an immediate descendant node of a node.
client application
A [client] application is any software that uses the Document Object Model programming interfaces provided by the hosting implementation to accomplish useful work. Some examples of client applications are scripts within an HTML or XML document.
COM
COM is Microsoft's Component Object Model [COM], a technology for building applications from binary software components.
convenience
A convenience method is an operation on an object that could be accomplished by a program consisting of more basic operations on the object. Convenience methods are usually provided to make the API easier and simpler to use or to allow specific programs to create more optimized implementations for common operations. A similar definition holds for a convenience property.
data model
A data model is a collection of descriptions of data structures and their contained fields, together with the operations or functions that manipulate them.
descendant
A descendant node of any node A is any node below A in a tree model, where "below" means "away from the root."
document element
There is only one document element in a Document. This element node is a child of the Document node. See Well-Formed XML Documents in XML [XML 1.0].
document order
There is an ordering, document order, defined on all the nodes in the document corresponding to the order in which the first character of the XML representation of each node occurs in the XML representation of the document after expansion of general entities. Thus, the document element node will be the first node. Element nodes occur before their children. Thus, document order orders element nodes in order of the occurrence of their start-tag in the XML (after expansion of entities). The attribute nodes of an element occur after the element and before its children. The relative order of attribute nodes is implementation-dependent.
ECMAScript
The programming language defined by the ECMA-262 standard [ECMAScript]. As stated in the standard, the originating technology for ECMAScript was JavaScript [JavaScript]. Note that in the ECMAScript binding, the word "property" is used in the same sense as the IDL term "attribute."
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. See Logical Structures in XML [XML 1.0].
information item
An information item is an abstract representation of some component of an XML document. See the [XML Information Set] for details.
logically-adjacent text nodes
Logically-adjacent text nodes are Text or CDATASection nodes that can be visited sequentially in document order or in reversed document order without entering, exiting, or passing over Element, Comment, or ProcessingInstruction nodes.
hosting implementation
A [hosting] implementation is a software module that provides an implementation of the DOM interfaces so that a client application can use them. Some examples of hosting implementations are browsers, editors and document repositories.
HTML
The HyperText Markup Language (HTML) is a simple markup language used to create hypertext documents that are portable from one platform to another. HTML documents are SGML documents with generic semantics that are appropriate for representing information from a wide range of applications. [HTML 4.01]
inheritance
In object-oriented programming, the ability to create new classes (or interfaces) that contain all the methods and properties of another class (or interface), plus additional methods and properties. If class (or interface) D inherits from class (or interface) B, then D is said to be derived from B. B is said to be a base class (or interface) for D. Some programming languages allow for multiple inheritance, that is, inheritance from more than one class or interface.
interface
An interface is a declaration of a set of methods with no information given about their implementation. In object systems that support interfaces and inheritance, interfaces can usually inherit from one another.
language binding
A programming language binding for an IDL specification is an implementation of the interfaces in the specification for the given language. For example, a Java language binding for the Document Object Model IDL specification would implement the concrete Java classes that provide the functionality exposed by the interfaces.
local name
A local name is the local part of a qualified name. This is called the local part in Namespaces in XML [XML Namespaces].
method
A method is an operation or function that is associated with an object and is allowed to manipulate the object's data.
model
A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else.
namespace prefix
A namespace prefix is a string that associates an element or attribute name with a namespace URI in XML. See namespace prefix in Namespaces in XML [XML Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in Namespaces in XML [XML Namespaces]. See also sections 1.3.2 "DOM URIs" and 1.3.3 "XML Namespaces" regarding URIs and namespace URIs handling and comparison in the DOM APIs.
namespace well-formed
A node is a namespace well-formed XML node if it is a well-formed node, and follows the productions and namespace constraints. If [XML 1.0] is used, the constraints are defined in [XML Namespaces]. If [XML 1.1] is used, the constraints are defined in [XML Namespaces 1.1].
object model
An object model is a collection of descriptions of classes or interfaces, together with their member data, member functions, and class-static operations.
parent
A parent is an immediate ancestor node of a node.
partially valid
A node in a DOM tree is partially valid if it is well formed (this part is for comments and processing instructions) and its immediate children are those expected by the content model. The node may be missing trailing required children yet still be considered partially valid.
qualified name
A qualified name is the name of an element or attribute defined as the concatenation of a local name (as defined in this specification), optionally preceded by a namespace prefix and colon character. See Qualified Names in Namespaces in XML [XML Namespaces].
read only node
A read only node is a node that is immutable. This means its list of children, its content, and its attributes, when it is an element, cannot be changed in any way. However, a read only node can possibly be moved, when it is not itself contained in a read only node.
root node
The root node is a node that is not a child of any other node. All other nodes are children or other descendants of the root node.
schema
A schema defines a set of structural and value constraints applicable to XML documents. Schemas can be expressed in schema languages, such as DTD, XML Schema, etc.
sibling
Two nodes are siblings if they have the same parent node.
string comparison
When string matching is required, it is to occur as though the comparison was between 2 sequences of code points from [Unicode].
token
An information item such as an XML Name which has been tokenized.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
well-formed
A node is a well-formed XML node if its serialized form, without doing any transformation during its serialization, matches its respective production in [XML 1.0] or [XML 1.1] (depending on the XML version in use) with all well-formedness constraints related to that production, and if the entities which are referenced within the node are also well-formed. If namespaces for XML are in use, the node must also be namespace well-formed.
XML
Extensible Markup Language (XML) is an extremely simple dialect of SGML which is completely described in this document. The goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. [XML 1.0]


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

K.1 Normative References

[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[ISO/IEC 10646]
ISO/IEC 10646-2000 (E). Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane, as, from time to time, amended, replaced by a new edition or expanded by the addition of new parts. [Geneva]: International Organization for Standardization, 2000. See also International Organization for Standardization, available at http://www.iso.ch, for the latest version.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[Unicode]
The Unicode Standard, Version 4, ISBN 0-321-18578-1, as updated from time to time by the publication of new versions. The Unicode Consortium, 2000. See also Versions of the Unicode Standard, available at http://www.unicode.org/unicode/standard/versions, for latest version and additional information on versions of the standard and of the Unicode Character Database.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Third Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, and F. Yergeau, Editors. World Wide Web Consortium, 4 February 2004, revised 10 February 1998 and 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2004/REC-xml-20040204. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML 1.1]
XML 1.1, T. Bray, and al., Editors. World Wide Web Consortium, 4 February 2004. This version of the XML 1.1 Recommendation is http://www.w3.org/TR/2004/REC-xml11-20040204. The latest version of XML 1.1 is available at http://www.w3.org/TR/xml11.
[XML Base]
XML Base, J. Marsh, Editor. World Wide Web Consortium, June 2001. This version of the XML Base Recommendation is http://www.w3.org/TR/2001/REC-xmlbase-20010627. The latest version of XML Base is available at http://www.w3.org/TR/xmlbase.
[XML Information Set]
XML Information Set (Second Edition), J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 4 February 2004, revised 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version of XML Information Set is available at http://www.w3.org/TR/xml-infoset.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the Namespaces in XML Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[XML Namespaces 1.1]
Namespaces in XML 1.1, T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors. World Wide Web Consortium, 4 February 2004. This version of the Namespaces in XML 1.1 Recommendation is http://www.w3.org/TR/2004/REC-xml-names11-20040204. The latest version of Namespaces in XML 1.1 is available at http://www.w3.org/TR/xml-names11/.
[XML Schema Part 1]
XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Part 1 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-1-20010502. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1.
[XPointer]
XPointer Framework, P. Grosso, E. Maler, J. Marsh, and N. Walsh., Editors. World Wide Web Consortium, 25 March 2003. This version of the XPointer Framework Recommendation is http://www.w3.org/TR/2003/REC-xptr-framework-20030325/. The latest version of XPointer Framework is available at http://www.w3.org/TR/xptr-framework/.

K.2 Informative References

[Canonical XML]
Canonical XML Version 1.0, J. Boyer, Editor. World Wide Web Consortium, 15 March 2001. This version of the Canonical XML Recommendation is http://www.w3.org/TR/2001/REC-xml-c14n-20010315. The latest version of Canonical XML is available at http://www.w3.org/TR/xml-c14n.
[COM]
The Microsoft Component Object Model, Microsoft Corporation. Available at http://www.microsoft.com/com.
[CORBA]
The Common Object Request Broker: Architecture and Specification, version 2. Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[DOM Level 1]
DOM Level 1 Specification, V. Apparao, et al., Editors. World Wide Web Consortium, 1 October 1998. This version of the DOM Level 1 Recommendation is http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001. The latest version of DOM Level 1 is available at http://www.w3.org/TR/REC-DOM-Level-1.
[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[DOM Level 3 Events]
Document Object Model Level 3 Events Specification, P. Le Hégaret, T. Pixley, Editors. World Wide Web Consortium, November 2003. This version of the Document Object Model Level 3 Events specification is http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107. The latest version of Document Object Model Level 3 Events is available at http://www.w3.org/TR/DOM-Level-3-Events.
[DOM Level 3 Load and Save]
Document Object Model Level 3 Load and Save Specification, J. Stenback, A. Heninger, Editors. World Wide Web Consortium, 7 April 2004. This version of the DOM Level 3 Load and Save Recommendation is http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407. The latest version of DOM Level 3 Load and Save is available at http://www.w3.org/TR/DOM-Level-3-LS.
[DOM Level 2 HTML]
Document Object Model Level 2 HTML Specification, J. Stenback, et al., Editors. World Wide Web Consortium, 9 January 2003. This version of the Document Object Model Level 2 HTML Recommendation is http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109. The latest version of Document Object Model Level 2 HTML is available at http://www.w3.org/TR/DOM-Level-2-HTML.
[DOM Level 3 Validation]
Document Object Model Level 3 Validation Specification, B. Chang, J. Kesselman, R. Rahman, Editors. World Wide Web Consortium, 27 January 2003. This version of the DOM Level 3 Validation Recommendation is http://www.w3.org/TR/2004/REC-DOM-Level-3-Val-20040127/. The latest version of DOM Level 3 Validation is available at http://www.w3.org/TR/DOM-Level-3-Val.
[DOM Level 3 XPath]
Document Object Model Level 3 XPath Specification, R. Whitmer, Editor. World Wide Web Consortium, March 2003. This version of the Document Object Model Level 3 XPath specification is http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226. The latest version of Document Object Model Level 3 XPath is available at http://www.w3.org/TR/DOM-Level-3-XPath.
[HTML 4.01]
HTML 4.01 Specification, D. Raggett, A. Le Hors, and I. Jacobs, Editors. World Wide Web Consortium, 17 December 1997, revised 24 April 1998, revised 24 December 1999. This version of the HTML 4.01 Recommendation is http://www.w3.org/TR/1999/REC-html401-19991224. The latest version of HTML 4 is available at http://www.w3.org/TR/html4.
[Java IDL]
Java IDL. Sun Microsystems. Available at http://java.sun.com/products/jdk/idl/
[JavaScript]
JavaScript Resources. Netscape Communications Corporation. Available at http://devedge.netscape.com/central/javascript/
[JScript]
JScript Resources. Microsoft. Available at http://msdn.microsoft.com/library/en-us/script56/html/js56jslrfjscriptlanguagereference.asp
[MathML 2.0]
Mathematical Markup Language (MathML) Version 2.0 (Second Edition), D. Carlisle, P. Ion, R. Miner, N. Poppelier, Editors. World Wide Web Consortium, 21 October 2001, revised 21 February 2001. This version of the Math 2.0 Recommendation is http://www.w3.org/TR/2003/REC-MathML2-20031021. The latest version of MathML 2.0 is available at http://www.w3.org/TR/MathML2.
[MIDL]
MIDL Language Reference. Microsoft. Available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/midl/midl/midl_language_reference.asp.
[IETF RFC 2396]
Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, Authors. Internet Engineering Task Force, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt.
[SAX]
Simple API for XML, D. Megginson and D. Brownell, Maintainers. Available at http://www.saxproject.org/.
[SVG 1.1]
Scalable Vector Graphics (SVG) 1.1 Specification, J. Ferraiolo, 藤沢 淳 (FUJISAWA Jun), and D. Jackson, Editors. World Wide Web Consortium, 14 January 2003. This version of the SVG 1.1 Recommendation is http://www.w3.org/TR/2003/REC-SVG11-20030114/. The latest version of SVG 1.1 is available at http://www.w3.org/TR/SVG.
[XPath 1.0]
XML Path Language (XPath) Version 1.0, J. Clark and S. DeRose, Editors. World Wide Web Consortium, 16 November 1999. This version of the XPath 1.0 Recommendation is http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version of XPath 1.0 is available at http://www.w3.org/TR/xpath.


Index

"canonical-form" 1, 2 | "cdata-sections" 1, 2 | "check-character-normalization" 1, 2
"comments" 1, 2 | "datatype-normalization" 1, 2 | "element-content-whitespace" 1, 2
"entities" 1, 2 | "error-handler" 1, 2, 3, 4 | "infoset"
"namespace-declarations" 1, 2 | "namespaces" 1, 2, 3, 4 | "normalize-characters" 1, 2, 3, 4, 5
"schema-location" | "schema-type" 1, 2 | "split-cdata-sections" 1, 2
"validate" 1, 2, 3 | "validate-if-schema" 1, 2 | "well-formed" 1, 2
16-bit unit 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
adoptNode | ancestor 1, 2, 3, 4 | anonymous type name 1, 2
API 1, 2, 3, 4, 5, 6, 7 | appendChild | appendData
Attr | ATTRIBUTE_NODE | attributes
baseURI | byteOffset
Canonical XML 1, 2 | canSetParameter | CDATA_SECTION_NODE
CDATASection | CharacterData | child 1, 2, 3
childNodes | client application 1, 2 | cloneNode
columnNumber | COM 1, 2, 3, 4, 5 | Comment
COMMENT_NODE | compareDocumentPosition | contains 1, 2
containsNS | convenience 1, 2, 3 | CORBA 1, 2
createAttribute | createAttributeNS | createCDATASection
createComment | createDocument | createDocumentFragment
createDocumentType | createElement | createElementNS
createEntityReference | createProcessingInstruction | createTextNode
data 1, 2 | data model 1, 2 | deleteData
DERIVATION_EXTENSION | DERIVATION_LIST | DERIVATION_RESTRICTION
DERIVATION_UNION | descendant 1, 2, 3, 4, 5, 6, 7 | doctype
Document | document element 1, 2, 3 | document order 1, 2, 3, 4, 5, 6
DOCUMENT_FRAGMENT_NODE | DOCUMENT_NODE | DOCUMENT_POSITION_CONTAINED_BY
DOCUMENT_POSITION_CONTAINS | DOCUMENT_POSITION_DISCONNECTED | DOCUMENT_POSITION_FOLLOWING
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC | DOCUMENT_POSITION_PRECEDING | DOCUMENT_TYPE_NODE
documentElement | DocumentFragment | DocumentType
documentURI | DOM Level 1 1, 2 | DOM Level 2 Core 1, 2, 3, 4
DOM Level 2 HTML 1, 2, 3, 4, 5, 6 | DOM Level 3 Events 1, 2 | DOM Level 3 Load and Save 1, 2, 3, 4, 5, 6
DOM Level 3 Validation 1, 2, 3 | DOM Level 3 XPath 1, 2 | domConfig
DOMConfiguration | DOMError | DOMErrorHandler
DOMException | DOMImplementation | DOMImplementationList
DOMImplementationSource | DOMLocator | DOMObject
DOMString | DOMSTRING_SIZE_ERR | DOMStringList
DOMTimeStamp | DOMUserData
ECMAScript 1, 2, 3, 4, 5 | Element 1, 2, 3, 4, 5, 6 | ELEMENT_NODE
entities | Entity | ENTITY_NODE
ENTITY_REFERENCE_NODE | EntityReference | extension
firstChild
getAttribute | getAttributeNode | getAttributeNodeNS
getAttributeNS | getDOMImplementation | getDOMImplementationList
getElementById | getElementsByTagName 1, 2 | getElementsByTagNameNS 1, 2
getFeature 1, 2 | getName | getNamedItem
getNamedItemNS | getNamespaceURI | getParameter
getUserData
handle | handleError | hasAttribute
hasAttributeNS | hasAttributes | hasChildNodes
hasFeature | HIERARCHY_REQUEST_ERR | hosting implementation 1, 2
HTML 1, 2 | HTML 4.01 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16
IETF RFC 2396 1, 2 | implementation | importNode
INDEX_SIZE_ERR | information item 1, 2 | inheritance 1, 2
inputEncoding 1, 2 | insertBefore | insertData
interface 1, 2 | internalSubset | INUSE_ATTRIBUTE_ERR
INVALID_ACCESS_ERR | INVALID_CHARACTER_ERR | INVALID_MODIFICATION_ERR
INVALID_STATE_ERR | isDefaultNamespace | isDerivedFrom
isElementContentWhitespace | isEqualNode | isId
ISO/IEC 10646 1, 2, 3 | isSameNode | isSupported
item 1, 2, 3, 4
Java 1, 2 | Java IDL 1, 2 | JavaScript 1, 2, 3
JScript 1, 2
language binding 1, 2 | lastChild | length 1, 2, 3, 4, 5, 6
lineNumber | list | live 1, 2, 3
local name 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 | localName | location
logically-adjacent text nodes 1, 2, 3 | lookupNamespaceURI | lookupPrefix
MathML 2.0 1, 2 | message | method 1, 2
MIDL 1, 2 | model 1, 2
name 1, 2 | NamedNodeMap | NameList
namespace prefix 1, 2, 3, 4, 5, 6 | namespace URI 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22 | namespace well-formed 1, 2
NAMESPACE_ERR | namespaceURI | nextSibling
NO_DATA_ALLOWED_ERR | NO_MODIFICATION_ALLOWED_ERR | Node
NODE_ADOPTED | NODE_CLONED | NODE_DELETED
NODE_IMPORTED | NODE_RENAMED | NodeList
nodeName | nodeType | nodeValue
normalize | normalizeDocument | NOT_FOUND_ERR
NOT_SUPPORTED_ERR | Notation | NOTATION_NODE
notationName | notations
object model 1, 2, 3 | OMG IDL 1, 2, 3, 4 | ownerDocument
ownerElement
parameterNames | parent 1, 2 | parentNode
partially valid 1, 2 | prefix | previousSibling
PROCESSING_INSTRUCTION_NODE | ProcessingInstruction | publicId 1, 2, 3
qualified name 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
read only node 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | relatedData | relatedException
relatedNode | removeAttribute | removeAttributeNode
removeAttributeNS | removeChild | removeNamedItem
removeNamedItemNS | renameNode | replaceChild
replaceData | replaceWholeText | restriction
root node 1, 2
SAX 1, 2 | schema 1, 2, 3 | schemaTypeInfo 1, 2
setAttribute | setAttributeNode | setAttributeNodeNS
setAttributeNS | setIdAttribute | setIdAttributeNode
setIdAttributeNS | setNamedItem | setNamedItemNS
setParameter | setUserData | severity
SEVERITY_ERROR | SEVERITY_FATAL_ERROR | SEVERITY_WARNING
sibling 1, 2, 3 | specified | splitText
strictErrorChecking | string comparison 1, 2, 3 | substringData
SVG 1.1 1, 2, 3 | SYNTAX_ERR | systemId 1, 2, 3
tagName | target | Text
TEXT_NODE | textContent | token 1, 2
tokenized 1, 2 | type | TYPE_MISMATCH_ERR
TypeInfo | typeName | typeNamespace
Unicode 1, 2, 3, 4, 5 | union | uri
UserDataHandler | utf16Offset
VALIDATION_ERR | value
well-formed 1, 2, 3 | wholeText | WRONG_DOCUMENT_ERR
XML 1, 2 | XML 1.0 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19 | XML 1.1 1, 2, 3, 4, 5, 6, 7, 8, 9
XML Base 1, 2 | XML Information Set 1, 2, 3, 4, 5, 6, 7 | XML Namespaces 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25
XML Namespaces 1.1 1, 2, 3, 4, 5 | XML Schema Part 1 1, 2, 3, 4, 5, 6, 7, 8 | xmlEncoding 1, 2
xmlStandalone | xmlVersion 1, 2 | XPath 1.0
XPointer 1, 2, 3


Document Object Model (DOM) Level 3 Load and Save Specification

Version 1.0

W3C Recommendation 07 April 2004

This version:
http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407
Latest version:
http://www.w3.org/TR/DOM-Level-3-LS
Previous version:
http://www.w3.org/TR/2004/PR-DOM-Level-3-LS-20040205/
Editors:
Johnny Stenback, Netscape
Andy Heninger, IBM (until March 2001)

Please refer to the errata for this document, which may include some normative corrections.

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

See also translations of this document.

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

Abstract

This specification defines the Document Object Model Load and Save Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically load the content of an XML document into a DOM document and serialize a DOM document into an XML document; DOM documents being defined in [DOM Level 2 Core] or newer, and XML documents being defined in [XML 1.0] or newer. It also allows filtering of content at load time and at serialization time.

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 contains the Document Object Model Level 3 Load and Save specification and is a W3C Recommendation. It has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group participants. For more information about DOM, readers can also refer to DOM FAQ and DOM Conformance Test Suites.

It is based on the feedback received during the Proposed Recommendation period. Changes since the Proposed Recommendation version and an implementation report are available. Please refer to the errata for this document, which may include some normative corrections.

Comments on this document should be sent to the public mailing list www-dom@w3.org (public archive).

This is a stable document and has been endorsed by the W3C Membership and the participants of the DOM working group. The English version of this specification is the only normative version. See also translations.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page. This document has been produced under the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) with respect to this specification should disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • 1. Document Object Model Load and Save
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • Glossary
  • References
  • Index


Document Object Model Load and Save

07 April 2004

1. Document Object Model Load and Save

Editors:
Johnny Stenback, Netscape
Andy Heninger, IBM (until March 2001)

Table of contents

  • 1.1 Overview of the Interfaces
  • 1.2 Basic Types
    • 1.2.1 The LSInputStream Type
      • LSInputStream
    • 1.2.2 The LSOutputStream Type
      • LSOutputStream
    • 1.2.3 The LSReader Type
      • LSReader
    • 1.2.4 The LSWriter Type
      • LSWriter
  • 1.3 Fundamental Interfaces
    • LSException, LSExceptionCode, DOMImplementationLS, LSParser, LSInput, LSResourceResolver, LSParserFilter, LSProgressEvent, LSLoadEvent, LSSerializer, LSOutput, LSSerializerFilter

This section defines a set of interfaces for loading and saving document objects as defined in [DOM Level 2 Core] or newer. The functionality specified in this section (the Load and Save functionality) is sufficient to allow software developers and Web script authors to load and save XML content inside conforming products. The DOM Load and Save API also allows filtering of XML content using only DOM API calls; access and manipulation of the Document is defined in [DOM Level 2 Core] or newer.

The proposal for loading is influenced by the Java APIs for XML Processing [JAXP] and by SAX2 [SAX].

1.1 Overview of the Interfaces

The interfaces involved with the loading and saving of XML documents are:

  • DOMImplementationLS -- An extended DOMImplementation interface that provides the factory methods for creating the objects required for loading and saving.
  • LSParser -- An interface for parsing data into DOM documents.
  • LSInput -- Encapsulates information about the data to be loaded.
  • LSResourceResolver -- Provides a way for applications to redirect references to external resources when parsing.
  • LSParserFilter -- Provides the ability to examine and optionally remove nodes as they are being processed while parsing.
  • LSSerializer -- An interface for serializing DOM documents or nodes.
  • LSOutput -- Encapsulates information about the destination for the data to be output.
  • LSSerializerFilter -- Provides the ability to examine and filter DOM nodes as they are being processed for the serialization.

1.2 Basic Types

To ensure interoperability, this specification specifies the following basic types used in various DOM modules. Even though the DOM uses the basic types in the interfaces, bindings may use different types and normative bindings are only given for Java and ECMAScript in this specification.

1.2.1 The LSInputStream Type

This type is used to represent a sequence of input bytes.

Type Definition LSInputStream

A LSInputStream represents a reference to a byte stream source of an XML input.

IDL Definition
typedef Object LSInputStream;

Note: For Java, LSInputStream is bound to the java.io.InputStream type. For ECMAScript, LSInputStream is bound to Object.

1.2.2 The LSOutputStream Type

This type is used to represent a sequence of output bytes.

Type Definition LSOutputStream

A LSOutputStream represents a byte stream destination for the XML output.

IDL Definition
typedef Object LSOutputStream;

Note: For Java, LSOutputStream is bound to the java.io.OutputStream type. For ECMAScript, LSOutputStream is bound to Object.

1.2.3 The LSReader Type

This type is used to represent a sequence of input characters in 16-bit units. The encoding used for the characters is UTF-16, as defined in [Unicode] and in [ISO/IEC 10646]).

Type Definition LSReader

A LSReader represents a character stream for the XML input.

IDL Definition
typedef Object LSReader;

Note: For Java, LSReader is bound to the java.io.Reader type. For ECMAScript, LSReader is not bound, and therefore has no recommended meaning in ECMAScript.

1.2.4 The LSWriter Type

This type is used to represent a sequence of output characters in 16-bit units. The encoding used for the characters is UTF-16, as defined in [Unicode] and in [ISO/IEC 10646]).

Type Definition LSWriter

A LSWriter represents a character stream for the XML output.

IDL Definition
typedef Object LSWriter;

Note: For Java, LSWriter is bound to the java.io.Writer type. For ECMAScript, LSWriter is not bound, and therefore has no recommended meaning in ECMAScript.

1.3 Fundamental Interfaces

The interfaces within this section are considered fundamental, and must be fully implemented by all conforming implementations of the DOM Load and Save module.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "LS" (or "LS-Async") and "3.0" (respectively) to determine whether or not these interfaces are supported by the implementation. In order to fully support them, an implementation must also support the "Core" feature defined in [DOM Level 2 Core].

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "LS-Async" and "3.0" (respectively) to determine whether or not the asynchronous mode is supported by the implementation. In order to fully support the asynchronous mode, an implementation must also support the "LS" feature defined in this section.

For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core].

Exception LSException

Parser or write operations may throw an LSException if the processing is stopped. The processing can be stopped due to a DOMError with a severity of DOMError.SEVERITY_FATAL_ERROR or a non recovered DOMError.SEVERITY_ERROR, or if DOMErrorHandler.handleError() returned false.

Note: As suggested in the definition of the constants in the DOMError interface, a DOM implementation may choose to continue after a fatal error, but the resulting DOM tree is then implementation dependent.

IDL Definition
exception LSException {
  unsigned short   code;
};
// LSExceptionCode
const unsigned short      PARSE_ERR                      = 81;
const unsigned short      SERIALIZE_ERR                  = 82;

Definition group LSExceptionCode

An integer indicating the type of error generated.

Defined Constants
PARSE_ERR
If an attempt was made to load a document, or an XML Fragment, using LSParser and the processing has been stopped.
SERIALIZE_ERR
If an attempt was made to serialize a Node using LSSerializer and the processing has been stopped.
Interface DOMImplementationLS

DOMImplementationLS contains the factory methods for creating Load and Save objects.

The expectation is that an instance of the DOMImplementationLS interface can be obtained by using binding-specific casting methods on an instance of the DOMImplementation interface or, if the Document supports the feature "Core" version "3.0" defined in [DOM Level 3 Core], by using the method DOMImplementation.getFeature with parameter values "LS" (or "LS-Async") and "3.0" (respectively).

IDL Definition
interface DOMImplementationLS {

  // DOMImplementationLSMode
  const unsigned short      MODE_SYNCHRONOUS               = 1;
  const unsigned short      MODE_ASYNCHRONOUS              = 2;

  LSParser           createLSParser(in unsigned short mode,
                                    in DOMString schemaType)
                                        raises(DOMException);
  LSSerializer       createLSSerializer();
  LSInput            createLSInput();
  LSOutput           createLSOutput();
};

Definition group DOMImplementationLSMode

Integer parser mode constants.

Defined Constants
MODE_ASYNCHRONOUS
Create an asynchronous LSParser.
MODE_SYNCHRONOUS
Create a synchronous LSParser.
Methods
createLSInput
Create a new empty input source object where LSInput.characterStream, LSInput.byteStream, LSInput.stringData LSInput.systemId, LSInput.publicId, LSInput.baseURI, and LSInput.encoding are null, and LSInput.certifiedText is false.
Return Value

LSInput

The newly created input object.

No Parameters
No Exceptions
createLSOutput
Create a new empty output destination object where LSOutput.characterStream, LSOutput.byteStream, LSOutput.systemId, LSOutput.encoding are null.
Return Value

LSOutput

The newly created output object.

No Parameters
No Exceptions
createLSParser
Create a new LSParser. The newly constructed parser may then be configured by means of its DOMConfiguration object, and used to parse documents by means of its parse method.
Parameters
mode of type unsigned short
The mode argument is either MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS, if mode is MODE_SYNCHRONOUS then the LSParser that is created will operate in synchronous mode, if it's MODE_ASYNCHRONOUS then the LSParser that is created will operate in asynchronous mode.
schemaType of type DOMString
An absolute URI representing the type of the schema language used during the load of a Document using the newly created LSParser. Note that no lexical checking is done on the absolute URI. In order to create a LSParser for any kind of schema types (i.e. the LSParser will be free to use any schema found), use the value null.

Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.

Return Value

LSParser

The newly created LSParser object. This LSParser is either synchronous or asynchronous depending on the value of the mode argument.

Note: By default, the newly created LSParser does not contain a DOMErrorHandler, i.e. the value of the "error-handler" configuration parameter is null. However, implementations may provide a default error handler at creation time. In that case, the initial value of the "error-handler" configuration parameter on the new LSParser object contains a reference to the default error handler.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the requested mode or schema type is not supported.

createLSSerializer
Create a new LSSerializer object.
Return Value

LSSerializer

The newly created LSSerializer object.

Note: By default, the newly created LSSerializer has no DOMErrorHandler, i.e. the value of the "error-handler" configuration parameter is null. However, implementations may provide a default error handler at creation time. In that case, the initial value of the "error-handler" configuration parameter on the new LSSerializer object contains a reference to the default error handler.

No Parameters
No Exceptions
Interface LSParser

An interface to an object that is able to build, or augment, a DOM tree from various input sources.

LSParser provides an API for parsing XML and building the corresponding DOM document structure. A LSParser instance can be obtained by invoking the DOMImplementationLS.createLSParser() method.

As specified in [DOM Level 3 Core], when a document is first made available via the LSParser:

  • there will never be two adjacent nodes of type NODE_TEXT, and there will never be empty text nodes.
  • it is expected that the value and nodeValue attributes of an Attr node initially return the XML 1.0 normalized value. However, if the parameters "validate-if-schema" and "datatype-normalization" are set to true, depending on the attribute normalization used, the attribute values may differ from the ones obtained by the XML 1.0 attribute normalization. If the parameters "datatype-normalization" is set to false, the XML 1.0 attribute normalization is guaranteed to occur, and if the attributes list does not contain namespace declarations, the attributes attribute on Element node represents the property [attributes] defined in [XML Information Set].

Asynchronous LSParser objects are expected to also implement the events::EventTarget interface so that event listeners can be registered on asynchronous LSParser objects.

Events supported by asynchronous LSParser objects are:

load
The LSParser finishes to load the document. See also the definition of the LSLoadEvent interface.
progress
The LSParser signals progress as data is parsed.
This specification does not attempt to define exactly when progress events should be dispatched. That is intentionally left as implementation-dependent. Here is one example of how an application might dispatch progress events: Once the parser starts receiving data, a progress event is dispatched to indicate that the parsing starts. From there on, a progress event is dispatched for every 4096 bytes of data that is received and processed. This is only one example, though, and implementations can choose to dispatch progress events at any time while parsing, or not dispatch them at all.
See also the definition of the LSProgressEvent interface.

Note: All events defined in this specification use the namespace URI "http://www.w3.org/2002/DOMLS".

While parsing an input source, errors are reported to the application through the error handler (LSParser.domConfig's "error-handler" parameter). This specification does in no way try to define all possible errors that can occur while parsing XML, or any other markup, but some common error cases are defined. The types (DOMError.type) of errors and warnings defined by this specification are:

"check-character-normalization-failure" [error]
Raised if the parameter "check-character-normalization" is set to true and a string is encountered that fails normalization checking.
"doctype-not-allowed" [fatal]
Raised if the configuration parameter "disallow-doctype" is set to true and a doctype is encountered.
"no-input-specified" [fatal]
Raised when loading a document and no input is specified in the LSInput object.
"pi-base-uri-not-preserved" [warning]
Raised if a processing instruction is encountered in a location where the base URI of the processing instruction can not be preserved.
One example of a case where this warning will be raised is if the configuration parameter "entities" is set to false and the following XML file is parsed:
<!DOCTYPE root [
<!ENTITY e SYSTEM 'subdir/myentity.ent'
]>

<root>
&e;
</root>

And subdir/myentity.ent contains:
<one>
  <two/>
</one>
<?pi 3.14159?>
<more/>
"unbound-prefix-in-entity" [warning]
An implementation dependent warning that may be raised if the configuration parameter "namespaces" is set to true and an unbound namespace prefix is encountered in an entity's replacement text. Raising this warning is not enforced since some existing parsers may not recognize unbound namespace prefixes in the replacement text of entities.
"unknown-character-denormalization" [fatal]
Raised if the configuration parameter "ignore-unknown-character-denormalizations" is set to false and a character is encountered for which the processor cannot determine the normalization properties.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.
"unsupported-media-type" [fatal]
Raised if the configuration parameter "supported-media-types-only" is set to true and an unsupported media type is encountered.

In addition to raising the defined errors and warnings, implementations are expected to raise implementation specific errors and warnings for any other error and warning cases such as IO errors (file not found, permission denied,...), XML well-formedness errors, and so on.

IDL Definition
interface LSParser {
  readonly attribute DOMConfiguration domConfig;
           attribute LSParserFilter  filter;
  readonly attribute boolean         async;
  readonly attribute boolean         busy;
  Document           parse(in LSInput input)
                                        raises(DOMException,
                                               LSException);
  Document           parseURI(in DOMString uri)
                                        raises(DOMException,
                                               LSException);

  // ACTION_TYPES
  const unsigned short      ACTION_APPEND_AS_CHILDREN      = 1;
  const unsigned short      ACTION_REPLACE_CHILDREN        = 2;
  const unsigned short      ACTION_INSERT_BEFORE           = 3;
  const unsigned short      ACTION_INSERT_AFTER            = 4;
  const unsigned short      ACTION_REPLACE                 = 5;

  Node               parseWithContext(in LSInput input,
                                      in Node contextArg,
                                      in unsigned short action)
                                        raises(DOMException,
                                               LSException);
  void               abort();
};

Definition group ACTION_TYPES

A set of possible actions for the parseWithContext method.

Defined Constants
ACTION_APPEND_AS_CHILDREN
Append the result of the parse operation as children of the context node. For this action to work, the context node must be an Element or a DocumentFragment.
ACTION_INSERT_AFTER
Insert the result of the parse operation as the immediately following sibling of the context node. For this action to work the context node's parent must be an Element or a DocumentFragment.
ACTION_INSERT_BEFORE
Insert the result of the parse operation as the immediately preceding sibling of the context node. For this action to work the context node's parent must be an Element or a DocumentFragment.
ACTION_REPLACE
Replace the context node with the result of the parse operation. For this action to work, the context node must have a parent, and the parent must be an Element or a DocumentFragment.
ACTION_REPLACE_CHILDREN
Replace all the children of the context node with the result of the parse operation. For this action to work, the context node must be an Element, a Document, or a DocumentFragment.
Attributes
async of type boolean, readonly
true if the LSParser is asynchronous, false if it is synchronous.
busy of type boolean, readonly
true if the LSParser is currently busy loading a document, otherwise false.
domConfig of type DOMConfiguration, readonly
The DOMConfiguration object used when parsing an input source. This DOMConfiguration is specific to the parse operation. No parameter values from this DOMConfiguration object are passed automatically to the DOMConfiguration object on the Document that is created, or used, by the parse operation. The DOM application is responsible for passing any needed parameter values from this DOMConfiguration object to the DOMConfiguration object referenced by the Document object.
In addition to the parameters recognized in on the DOMConfiguration interface defined in [DOM Level 3 Core], the DOMConfiguration objects for LSParser add or modify the following parameters:
"charset-overrides-xml-encoding"
true
[optional] (default)
If a higher level protocol such as HTTP [IETF RFC 2616] provides an indication of the character encoding of the input stream being processed, that will override any encoding specified in the XML declaration or the Text declaration (see also section 4.3.3, "Character Encoding in Entities", in [XML 1.0]). Explicitly setting an encoding in the LSInput overrides any encoding from the protocol.
false
[required]
The parser ignores any character set encoding information from higher-level protocols.
"disallow-doctype"
true
[optional]
Throw a fatal "doctype-not-allowed" error if a doctype node is found while parsing the document. This is useful when dealing with things like SOAP envelopes where doctype nodes are not allowed.
false
[required] (default)
Allow doctype nodes in the document.
"ignore-unknown-character-denormalizations"
true
[required] (default)
If, while verifying full normalization when [XML 1.1] is supported, a processor encounters characters for which it cannot determine the normalization properties, then the processor will ignore any possible denormalizations caused by these characters.
This parameter is ignored for [XML 1.0].
false
[optional]
Report an fatal "unknown-character-denormalization" error if a character is encountered for which the processor cannot determine the normalization properties.
"infoset"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core], this parameter will default to true for LSParser.
"namespaces"
true
[required] (default)
Perform the namespace processing as defined in [XML Namespaces] and [XML Namespaces 1.1].
false
[optional]
Do not perform the namespace processing.
"resource-resolver"
[required]
A reference to a LSResourceResolver object, or null. If the value of this parameter is not null when an external resource (such as an external XML entity or an XML schema location) is encountered, the implementation will request that the LSResourceResolver referenced in this parameter resolves the resource.
"supported-media-types-only"
true
[optional]
Check that the media type of the parsed resource is a supported media type. If an unsupported media type is encountered, a fatal error of type "unsupported-media-type" will be raised. The media types defined in [IETF RFC 3023] must always be accepted.
false
[required] (default)
Accept any media type.
"validate"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even if this parameter is set to false.
"validate-if-schema"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core], the processing of the internal subset is always accomplished, even if this parameter is set to false.
"well-formed"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [DOM Level 3 Core], this parameter cannot be set to false.
filter of type LSParserFilter
When a filter is provided, the implementation will call out to the filter as it is constructing the DOM tree structure. The filter can choose to remove elements from the document being constructed, or to terminate the parsing early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, if "validate" is set to true, the validation is done before invoking the filter.
Methods
abort
Abort the loading of the document that is currently being loaded by the LSParser. If the LSParser is currently not busy, a call to this method does nothing.
No Parameters
No Return Value
No Exceptions
parse
Parse an XML document from a resource identified by a LSInput.
Parameters
input of type LSInput
The LSInput from which the source of the document is to be read.
Return Value

Document

If the LSParser is a synchronous LSParser, the newly created and populated Document is returned. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if the LSParser's LSParser.busy attribute is true.

LSException

PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

parseURI
Parse an XML document from a location identified by a URI reference [IETF RFC 2396]. If the URI contains a fragment identifier (see section 4.1 in [IETF RFC 2396]), the behavior is not defined by this specification, future versions of this specification may define the behavior.
Parameters
uri of type DOMString
The location of the XML document to be read.
Return Value

Document

If the LSParser is a synchronous LSParser, the newly created and populated Document is returned, or null if an error occured. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.

Exceptions

DOMException

INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.

LSException

PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

parseWithContext
Parse an XML fragment from a resource identified by a LSInput and insert the content into an existing document at the position specified with the context and action arguments. When parsing the input stream, the context node (or its parent, depending on where the result will be inserted) is used for resolving unbound namespace prefixes. The context node's ownerDocument node (or the node itself if the node of type DOCUMENT_NODE) is used to resolve default attributes and entity references.
As the new data is inserted into the document, at least one mutation event is fired per new immediate child or sibling of the context node.
If the context node is a Document node and the action is ACTION_REPLACE_CHILDREN, then the document that is passed as the context node will be changed such that its xmlEncoding, documentURI, xmlVersion, inputEncoding, xmlStandalone, and all other such attributes are set to what they would be set to if the input source was parsed using LSParser.parse().
This method is always synchronous, even if the LSParser is asynchronous (LSParser.async is true).
If an error occurs while parsing, the caller is notified through the ErrorHandler instance associated with the "error-handler" parameter of the DOMConfiguration.
When calling parseWithContext, the values of the following configuration parameters will be ignored and their default values will always be used instead: "validate", "validate-if-schema", and "element-content-whitespace". Other parameters will be treated normally, and the parser is expected to call the LSParserFilter just as if a whole document was parsed.
Parameters
input of type LSInput
The LSInput from which the source document is to be read. The source document must be an XML fragment, i.e. anything except a complete XML document (except in the case where the context node of type DOCUMENT_NODE, and the action is ACTION_REPLACE_CHILDREN), a DOCTYPE (internal subset), entity declaration(s), notation declaration(s), or XML or text declaration(s).
contextArg of type Node
The node that is used as the context for the data that is being parsed. This node must be a Document node, a DocumentFragment node, or a node of a type that is allowed as a child of an Element node, e.g. it cannot be an Attribute node.
action of type unsigned short
This parameter describes which action should be taken between the new set of nodes being inserted and the existing children of the context node. The set of possible actions is defined in ACTION_TYPES above.
Return Value

Node

Return the node that is the result of the parse operation. If the result is more than one top-level node, the first one is returned.

Exceptions

DOMException

HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be inserted before, after, or as a child of the context node (see also Node.insertBefore or Node.replaceChild in [DOM Level 3 Core]).

NOT_SUPPORTED_ERR: Raised if the LSParser doesn't support this method, or if the context node is of type Document and the DOM implementation doesn't support the replacement of the DocumentType child or Element child.

NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a read only node and the content is being appended to its child list, or if the parent node of the context node is read only node and the content is being inserted in its child list.

INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.

LSException

PARSE_ERR: Raised if the LSParser was unable to load the XML fragment. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

Interface LSInput

This interface represents an input source for data.

This interface allows an application to encapsulate information about an input source in a single object, which may include a public identifier, a system identifier, a byte stream (possibly with a specified encoding), a base URI, and/or a character stream.

The exact definitions of a byte stream and a character stream are binding dependent.

The application is expected to provide objects that implement this interface whenever such objects are needed. The application can either provide its own objects that implement this interface, or it can use the generic factory method DOMImplementationLS.createLSInput() to create objects that implement this interface.

The LSParser will use the LSInput object to determine how to read data. The LSParser will look at the different inputs specified in the LSInput in the following order to know which one to read from, the first one that is not null and not an empty string will be used:

  1. LSInput.characterStream
  2. LSInput.byteStream
  3. LSInput.stringData
  4. LSInput.systemId
  5. LSInput.publicId

If all inputs are null, the LSParser will report a DOMError with its DOMError.type set to "no-input-specified" and its DOMError.severity set to DOMError.SEVERITY_FATAL_ERROR.

LSInput objects belong to the application. The DOM implementation will never modify them (though it may make copies and modify the copies, if necessary).

IDL Definition
interface LSInput {
  // Depending on the language binding in use,
  // this attribute may not be available.
           attribute LSReader        characterStream;
           attribute LSInputStream   byteStream;
           attribute DOMString       stringData;
           attribute DOMString       systemId;
           attribute DOMString       publicId;
           attribute DOMString       baseURI;
           attribute DOMString       encoding;
           attribute boolean         certifiedText;
};

Attributes
baseURI of type DOMString
The base URI to be used (see section 5.1.4 in [IETF RFC 2396]) for resolving a relative systemId to an absolute URI.
If, when used, the base URI is itself a relative URI, an empty string, or null, the behavior is implementation dependent.
byteStream of type LSInputStream
An attribute of a language and binding dependent type that represents a stream of bytes.
If the application knows the character encoding of the byte stream, it should set the encoding attribute. Setting the encoding in this way will override any encoding specified in an XML declaration in the data.
certifiedText of type boolean
If set to true, assume that the input is certified (see section 2.13 in [XML 1.1]) when parsing [XML 1.1].
characterStream of type LSReader
Depending on the language binding in use, this attribute may not be available.
An attribute of a language and binding dependent type that represents a stream of 16-bit units. The application must encode the stream using UTF-16 (defined in [Unicode] and in [ISO/IEC 10646]). It is not a requirement to have an XML declaration when using character streams. If an XML declaration is present, the value of the encoding attribute will be ignored.
encoding of type DOMString
The character encoding, if known. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities").
This attribute has no effect when the application provides a character stream or string data. For other sources of input, an encoding specified by means of this attribute will override any encoding specified in the XML declaration or the Text declaration, or an encoding obtained from a higher level protocol, such as HTTP [IETF RFC 2616].
publicId of type DOMString
The public identifier for this input source. This may be mapped to an input source using an implementation dependent mechanism (such as catalogues or other mappings). The public identifier, if specified, may also be reported as part of the location information when errors are reported.
stringData of type DOMString
String data to parse. If provided, this will always be treated as a sequence of 16-bit units (UTF-16 encoded characters). It is not a requirement to have an XML declaration when using stringData. If an XML declaration is present, the value of the encoding attribute will be ignored.
systemId of type DOMString
The system identifier, a URI reference [IETF RFC 2396], for this input source. The system identifier is optional if there is a byte stream, a character stream, or string data. It is still useful to provide one, since the application will use it to resolve any relative URIs and can include it in error messages and warnings. (The LSParser will only attempt to fetch the resource identified by the URI reference if there is no other input available in the input source.)
If the application knows the character encoding of the object pointed to by the system identifier, it can set the encoding using the encoding attribute.
If the specified system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the DOM implementation will attempt to resolve the relative URI with the baseURI as the base, if that fails, the behavior is implementation dependent.
Interface LSResourceResolver

LSResourceResolver provides a way for applications to redirect references to external resources.

Applications needing to implement custom handling for external resources can implement this interface and register their implementation by setting the "resource-resolver" parameter of DOMConfiguration objects attached to LSParser and LSSerializer. It can also be register on DOMConfiguration objects attached to Document if the "LS" feature is supported.

The LSParser will then allow the application to intercept any external entities, including the external DTD subset and external parameter entities, before including them. The top-level document entity is never passed to the resolveResource method.

Many DOM applications will not need to implement this interface, but it will be especially useful for applications that build XML documents from databases or other specialized input sources, or for applications that use URNs.

Note: LSResourceResolver is based on the SAX2 [SAX] EntityResolver interface.

IDL Definition
interface LSResourceResolver {
  LSInput            resolveResource(in DOMString type,
                                     in DOMString namespaceURI,
                                     in DOMString publicId,
                                     in DOMString systemId,
                                     in DOMString baseURI);
};

Methods
resolveResource
Allow the application to resolve external resources.
The LSParser will call this method before opening any external resource, including the external DTD subset, external entities referenced within the DTD, and external entities referenced within the document element (however, the top-level document entity is not passed to this method). The application may then request that the LSParser resolve the external resource itself, that it use an alternative URI, or that it use an entirely different input source.
Application writers can use this method to redirect external system identifiers to secure and/or local URI, to look up public identifiers in a catalogue, or to read an entity from a database or other input source (including, for example, a dialog box).
Parameters
type of type DOMString
The type of the resource being resolved. For XML [XML 1.0] resources (i.e. entities), applications must use the value "http://www.w3.org/TR/REC-xml". For XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". Other types of resources are outside the scope of this specification and therefore should recommend an absolute URI in order to use this method.
namespaceURI of type DOMString
The namespace of the resource being resolved, e.g. the target namespace of the XML Schema [XML Schema Part 1] when resolving XML Schema resources.
publicId of type DOMString
The public identifier of the external entity being referenced, or null if no public identifier was supplied or if the resource is not an entity.
systemId of type DOMString
The system identifier, a URI reference [IETF RFC 2396], of the external resource being referenced, or null if no system identifier was supplied.
baseURI of type DOMString
The absolute base URI of the resource being parsed, or null if there is no base URI.
Return Value

LSInput

A LSInput object describing the new input source, or null to request that the parser open a regular URI connection to the resource.

No Exceptions
Interface LSParserFilter

LSParserFilters provide applications the ability to examine nodes as they are being constructed while parsing. As each node is examined, it may be modified or removed, or the entire parse may be terminated early.

At the time any of the filter methods are called by the parser, the owner Document and DOMImplementation objects exist and are accessible. The document element is never passed to the LSParserFilter methods, i.e. it is not possible to filter out the document element. Document, DocumentType, Notation, Entity, and Attr nodes are never passed to the acceptNode method on the filter. The child nodes of an EntityReference node are passed to the filter if the parameter "entities" is set to false. Note that, as described by the parameter "entities", unexpanded entity reference nodes are never discarded and are always passed to the filter.

All validity checking while parsing a document occurs on the source document as it appears on the input stream, not on the DOM document as it is built in memory. With filters, the document in memory may be a subset of the document on the stream, and its validity may have been affected by the filtering.

All default attributes must be present on elements when the elements are passed to the filter methods. All other default content must be passed to the filter methods.

DOM applications must not raise exceptions in a filter. The effect of throwing exceptions from a filter is DOM implementation dependent.

IDL Definition
interface LSParserFilter {

  // Constants returned by startElement and acceptNode
  const short               FILTER_ACCEPT                  = 1;
  const short               FILTER_REJECT                  = 2;
  const short               FILTER_SKIP                    = 3;
  const short               FILTER_INTERRUPT               = 4;

  unsigned short     startElement(in Element elementArg);
  unsigned short     acceptNode(in Node nodeArg);
  readonly attribute unsigned long   whatToShow;
};

Definition group Constants returned by startElement and acceptNode

Constants returned by startElement and acceptNode.

Defined Constants
FILTER_ACCEPT
Accept the node.
FILTER_INTERRUPT
Interrupt the normal processing of the document.
FILTER_REJECT
Reject the node and its children.
FILTER_SKIP
Skip this single node. The children of this node will still be considered.
Attributes
whatToShow of type unsigned long, readonly
Tells the LSParser what types of nodes to show to the method LSParserFilter.acceptNode. If a node is not shown to the filter using this attribute, it is automatically included in the DOM document being built. See NodeFilter for definition of the constants. The constants SHOW_ATTRIBUTE, SHOW_DOCUMENT, SHOW_DOCUMENT_TYPE, SHOW_NOTATION, SHOW_ENTITY, and SHOW_DOCUMENT_FRAGMENT are meaningless here. Those nodes will never be passed to LSParserFilter.acceptNode.
The constants used here are defined in [DOM Level 2 Traversal and Range].
Methods
acceptNode
This method will be called by the parser at the completion of the parsing of each node. The node and all of its descendants will exist and be complete. The parent node will also exist, although it may be incomplete, i.e. it may have additional children that have not yet been parsed. Attribute nodes are never passed to this function.
From within this method, the new node may be freely modified - children may be added or removed, text nodes modified, etc. The state of the rest of the document outside this node is not defined, and the affect of any attempt to navigate to, or to modify any other part of the document is undefined.
For validating parsers, the checks are made on the original document, before any modification by the filter. No validity checks are made on any document modifications made by the filter.
If this new node is rejected, the parser might reuse the new node and any of its descendants.
Parameters
nodeArg of type Node
The newly constructed element. At the time this method is called, the element is complete - it has all of its children (and their children, recursively) and attributes, and is attached as a child to its parent.
Return Value

unsigned short
  • FILTER_ACCEPT if this Node should be included in the DOM document being built.
  • FILTER_REJECT if the Node and all of its children should be rejected.
  • FILTER_SKIP if the Node should be skipped and the Node should be replaced by all the children of the Node.
  • FILTER_INTERRUPT if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the resulting DOM tree is XML well-formed. The Node is accepted and will be the last completely parsed node.
No Exceptions
startElement
The parser will call this method after each Element start tag has been scanned, but before the remainder of the Element is processed. The intent is to allow the element, including any children, to be efficiently skipped. Note that only element nodes are passed to the startElement function.
The element node passed to startElement for filtering will include all of the Element's attributes, but none of the children nodes. The Element may not yet be in place in the document being constructed (it may not have a parent node.)
A startElement filter function may access or change the attributes for the Element. Changing Namespace declarations will have no effect on namespace resolution by the parser.
For efficiency, the Element node passed to the filter may not be the same one as is actually placed in the tree if the node is accepted. And the actual node (node object identity) may be reused during the process of reading in and filtering a document.
Parameters
elementArg of type Element
The newly encountered element. At the time this method is called, the element is incomplete - it will have its attributes, but no children.
Return Value

unsigned short
  • FILTER_ACCEPT if the Element should be included in the DOM document being built.
  • FILTER_REJECT if the Element and all of its children should be rejected.
  • FILTER_SKIP if the Element should be skipped. All of its children are inserted in place of the skipped Element node.
  • FILTER_INTERRUPT if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the resulting DOM tree is XML well-formed. The Element is rejected.

Returning any other values will result in unspecified behavior.
No Exceptions
Interface LSProgressEvent

This interface represents a progress event object that notifies the application about progress as a document is parsed. It extends the Event interface defined in [DOM Level 3 Events].

The units used for the attributes position and totalSize are not specified and can be implementation and input dependent.

IDL Definition
interface LSProgressEvent : events::Event {
  readonly attribute LSInput         input;
  readonly attribute unsigned long   position;
  readonly attribute unsigned long   totalSize;
};

Attributes
input of type LSInput, readonly
The input source that is being parsed.
position of type unsigned long, readonly
The current position in the input source, including all external entities and other resources that have been read.
totalSize of type unsigned long, readonly
The total size of the document including all external resources, this number might change as a document is being parsed if references to more external resources are seen. A value of 0 is returned if the total size cannot be determined or estimated.
Interface LSLoadEvent

This interface represents a load event object that signals the completion of a document load.

IDL Definition
interface LSLoadEvent : events::Event {
  readonly attribute Document        newDocument;
  readonly attribute LSInput         input;
};

Attributes
input of type LSInput, readonly
The input source that was parsed.
newDocument of type Document, readonly
The document that finished loading.
Interface LSSerializer

A LSSerializer provides an API for serializing (writing) a DOM document out into XML. The XML data is written to a string or an output stream. Any changes or fixups made during the serialization affect only the serialized data. The Document object and its children are never altered by the serialization operation.

During serialization of XML data, namespace fixup is done as defined in [DOM Level 3 Core], Appendix B. [DOM Level 2 Core] allows empty strings as a real namespace URI. If the namespaceURI of a Node is empty string, the serialization will treat them as null, ignoring the prefix if any.

LSSerializer accepts any node type for serialization. For nodes of type Document or Entity, well-formed XML will be created when possible (well-formedness is guaranteed if the document or entity comes from a parse operation and is unchanged since it was created). The serialized output for these node types is either as a XML document or an External XML Entity, respectively, and is acceptable input for an XML parser. For all other types of nodes the serialized form is implementation dependent.

Within a Document, DocumentFragment, or Entity being serialized, Nodes are processed as follows

  • Document nodes are written, including the XML declaration (unless the parameter "xml-declaration" is set to false) and a DTD subset, if one exists in the DOM. Writing a Document node serializes the entire document.
  • Entity nodes, when written directly by LSSerializer.write, outputs the entity expansion but no namespace fixup is done. The resulting output will be valid as an external entity.
  • If the parameter "entities" is set to true, EntityReference nodes are serialized as an entity reference of the form "&entityName;" in the output. Child nodes (the expansion) of the entity reference are ignored. If the parameter "entities" is set to false, only the children of the entity reference are serialized. EntityReference nodes with no children (no corresponding Entity node or the corresponding Entity nodes have no children) are always serialized.
  • CDATAsections containing content characters that cannot be represented in the specified output encoding are handled according to the "split-cdata-sections" parameter.
    If the parameter is set to true, CDATAsections are split, and the unrepresentable characters are serialized as numeric character references in ordinary content. The exact position and number of splits is not specified.
    If the parameter is set to false, unrepresentable characters in a CDATAsection are reported as "wf-invalid-character" errors if the parameter "well-formed" is set to true. The error is not recoverable - there is no mechanism for supplying alternative characters and continuing with the serialization.
  • DocumentFragment nodes are serialized by serializing the children of the document fragment in the order they appear in the document fragment.
  • All other node types (Element, Text, etc.) are serialized to their corresponding XML source form.

Note: The serialization of a Node does not always generate a well-formed XML document, i.e. a LSParser might throw fatal errors when parsing the resulting serialization.

Within the character data of a document (outside of markup), any characters that cannot be represented directly are replaced with character references. Occurrences of '<' and '&' are replaced by the predefined entities &lt; and &amp;. The other predefined entities (&gt;, &apos;, and &quot;) might not be used, except where needed (e.g. using &gt; in cases such as ']]>'). Any characters that cannot be represented directly in the output character encoding are serialized as numeric character references (and since character encoding standards commonly use hexadecimal representations of characters, using the hexadecimal representation when serializing character references is encouraged).

To allow attribute values to contain both single and double quotes, the apostrophe or single-quote character (') may be represented as "&apos;", and the double-quote character (") as "&quot;". New line characters and other characters that cannot be represented directly in attribute values in the output character encoding are serialized as a numeric character reference.

Within markup, but outside of attributes, any occurrence of a character that cannot be represented in the output character encoding is reported as a DOMError fatal error. An example would be serializing the element <LaCañada/> with encoding="us-ascii". This will result with a generation of a DOMError "wf-invalid-character-in-node-name" (as proposed in "well-formed").

When requested by setting the parameter "normalize-characters" on LSSerializer to true, character normalization is performed according to the definition of fully normalized characters included in appendix E of [XML 1.1] on all data to be serialized, both markup and character data. The character normalization process affects only the data as it is being written; it does not alter the DOM's view of the document after serialization has completed.

Implementations are required to support the encodings "UTF-8", "UTF-16", "UTF-16BE", and "UTF-16LE" to guarantee that data is serializable in all encodings that are required to be supported by all XML parsers. When the encoding is UTF-8, whether or not a byte order mark is serialized, or if the output is big-endian or little-endian, is implementation dependent. When the encoding is UTF-16, whether or not the output is big-endian or little-endian is implementation dependent, but a Byte Order Mark must be generated for non-character outputs, such as LSOutput.byteStream or LSOutput.systemId. If the Byte Order Mark is not generated, a "byte-order-mark-needed" warning is reported. When the encoding is UTF-16LE or UTF-16BE, the output is big-endian (UTF-16BE) or little-endian (UTF-16LE) and the Byte Order Mark is not be generated. In all cases, the encoding declaration, if generated, will correspond to the encoding used during the serialization (e.g. encoding="UTF-16" will appear if UTF-16 was requested).

Namespaces are fixed up during serialization, the serialization process will verify that namespace declarations, namespace prefixes and the namespace URI associated with elements and attributes are consistent. If inconsistencies are found, the serialized form of the document will be altered to remove them. The method used for doing the namespace fixup while serializing a document is the algorithm defined in Appendix B.1, "Namespace normalization", of [DOM Level 3 Core].

While serializing a document, the parameter "discard-default-content" controls whether or not non-specified data is serialized.

While serializing, errors and warnings are reported to the application through the error handler (LSSerializer.domConfig's "error-handler" parameter). This specification does in no way try to define all possible errors and warnings that can occur while serializing a DOM node, but some common error and warning cases are defined. The types (DOMError.type) of errors and warnings defined by this specification are:

"no-output-specified" [fatal]
Raised when writing to a LSOutput if no output is specified in the LSOutput.
"unbound-prefix-in-entity-reference" [fatal]
Raised if the configuration parameter "namespaces" is set to true and an entity whose replacement text contains unbound namespace prefixes is referenced in a location where there are no bindings for the namespace prefixes.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.

In addition to raising the defined errors and warnings, implementations are expected to raise implementation specific errors and warnings for any other error and warning cases such as IO errors (file not found, permission denied,...) and so on.

IDL Definition
interface LSSerializer {
  readonly attribute DOMConfiguration domConfig;
           attribute DOMString       newLine;
           attribute LSSerializerFilter filter;
  boolean            write(in Node nodeArg,
                           in LSOutput destination)
                                        raises(LSException);
  boolean            writeToURI(in Node nodeArg,
                                in DOMString uri)
                                        raises(LSException);
  DOMString          writeToString(in Node nodeArg)
                                        raises(DOMException,
                                               LSException);
};

Attributes
domConfig of type DOMConfiguration, readonly
The DOMConfiguration object used by the LSSerializer when serializing a DOM node.
In addition to the parameters recognized by the DOMConfiguration interface defined in [DOM Level 3 Core], the DOMConfiguration objects for LSSerializer adds, or modifies, the following parameters:
"canonical-form"
true
[optional]
Writes the document according to the rules specified in [Canonical XML]. In addition to the behavior described in "canonical-form" [DOM Level 3 Core], setting this parameter to true will set the parameters "format-pretty-print", "discard-default-content", and "xml-declaration", to false. Setting one of those parameters to true will set this parameter to false. Serializing an XML 1.1 document when "canonical-form" is true will generate a fatal error.
false
[required] (default)
Do not canonicalize the output.
"discard-default-content"
true
[required] (default)
Use the Attr.specified attribute to decide what attributes should be discarded. Note that some implementations might use whatever information available to the implementation (i.e. XML schema, DTD, the Attr.specified attribute, and so on) to determine what attributes and content to discard if this parameter is set to true.
false
[required]
Keep all attributes and all content.
"format-pretty-print"
true
[optional]
Formatting the output by adding whitespace to produce a pretty-printed, indented, human-readable form. The exact form of the transformations is not specified by this specification. Pretty-printing changes the content of the document and may affect the validity of the document, validating implementations should preserve validity.
false
[required] (default)
Don't pretty-print the result.
"ignore-unknown-character-denormalizations"
true
[required] (default)
If, while verifying full normalization when [XML 1.1] is supported, a character is encountered for which the normalization properties cannot be determined, then raise a "unknown-character-denormalization" warning (instead of raising an error, if this parameter is not set) and ignore any possible denormalizations caused by these characters.
false
[optional]
Report a fatal error if a character is encountered for which the processor cannot determine the normalization properties.
"normalize-characters"
This parameter is equivalent to the one defined by DOMConfiguration in [DOM Level 3 Core]. Unlike in the Core, the default value for this parameter is true. While DOM implementations are not required to support fully normalizing the characters in the document according to appendix E of [XML 1.1], this parameter must be activated by default if supported.
"xml-declaration"
true
[required] (default)
If a Document, Element, or Entity node is serialized, the XML declaration, or text declaration, should be included. The version (Document.xmlVersion if the document is a Level 3 document and the version is non-null, otherwise use the value "1.0"), and the output encoding (see LSSerializer.write for details on how to find the output encoding) are specified in the serialized XML declaration.
false
[required]
Do not serialize the XML and text declarations. Report a "xml-declaration-needed" warning if this will cause problems (i.e. the serialized data is of an XML version other than [XML 1.0], or an encoding would be needed to be able to re-parse the serialized data).
filter of type LSSerializerFilter
When the application provides a filter, the serializer will call out to the filter before serializing each Node. The filter implementation can choose to remove the node from the stream or to terminate the serialization early.
The filter is invoked after the operations requested by the DOMConfiguration parameters have been applied. For example, CDATA sections won't be passed to the filter if "cdata-sections" is set to false.
newLine of type DOMString
The end-of-line sequence of characters to be used in the XML being written out. Any string is supported, but XML treats only a certain set of characters sequence as end-of-line (See section 2.11, "End-of-Line Handling" in [XML 1.0], if the serialized content is XML 1.0 or section 2.11, "End-of-Line Handling" in [XML 1.1], if the serialized content is XML 1.1). Using other character sequences than the recommended ones can result in a document that is either not serializable or not well-formed).
On retrieval, the default value of this attribute is the implementation specific default end-of-line sequence. DOM implementations should choose the default to match the usual convention for text files in the environment being used. Implementations must choose a default sequence that matches one of those allowed by XML 1.0 or XML 1.1, depending on the serialized content. Setting this attribute to null will reset its value to the default value.

Methods
write
Serialize the specified node as described above in the general description of the LSSerializer interface. The output is written to the supplied LSOutput.
When writing to a LSOutput, the encoding is found by looking at the encoding information that is reachable through the LSOutput and the item to be written (or its owner document) in this order:
  1. LSOutput.encoding,
  2. Document.inputEncoding,
  3. Document.xmlEncoding.

If no encoding is reachable through the above properties, a default encoding of "UTF-8" will be used. If the specified encoding is not supported an "unsupported-encoding" fatal error is raised.
If no output is specified in the LSOutput, a "no-output-specified" fatal error is raised.
The implementation is responsible of associating the appropriate media type with the serialized data.
When writing to a HTTP URI, a HTTP PUT is performed. When writing to other types of URIs, the mechanism for writing the data to the URI is implementation dependent.
Parameters
nodeArg of type Node
The node to serialize.
destination of type LSOutput
The destination for the serialized DOM.
Return Value

boolean

Returns true if node was successfully serialized. Return false in case the normal processing stopped but the implementation kept serializing the document; the result of the serialization being implementation dependent then.

Exceptions

LSException

SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

writeToString
Serialize the specified node as described above in the general description of the LSSerializer interface. The output is written to a DOMString that is returned to the caller. The encoding used is the encoding of the DOMString type, i.e. UTF-16. Note that no Byte Order Mark is generated in a DOMString object.
Parameters
nodeArg of type Node
The node to serialize.
Return Value

DOMString

Returns the serialized data.

Exceptions

DOMException

DOMSTRING_SIZE_ERR: Raised if the resulting string is too long to fit in a DOMString.

LSException

SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

writeToURI
A convenience method that acts as if LSSerializer.write was called with a LSOutput with no encoding specified and LSOutput.systemId set to the uri argument.
Parameters
nodeArg of type Node
The node to serialize.
uri of type DOMString
The URI to write to.
Return Value

boolean

Returns true if node was successfully serialized. Return false in case the normal processing stopped but the implementation kept serializing the document; the result of the serialization being implementation dependent then.

Exceptions

LSException

SERIALIZE_ERR: Raised if the LSSerializer was unable to serialize the node. DOM applications should attach a DOMErrorHandler using the parameter "error-handler" if they wish to get details on the error.

Interface LSOutput

This interface represents an output destination for data.

This interface allows an application to encapsulate information about an output destination in a single object, which may include a URI, a byte stream (possibly with a specified encoding), a base URI, and/or a character stream.

The exact definitions of a byte stream and a character stream are binding dependent.

The application is expected to provide objects that implement this interface whenever such objects are needed. The application can either provide its own objects that implement this interface, or it can use the generic factory method DOMImplementationLS.createLSOutput() to create objects that implement this interface.

The LSSerializer will use the LSOutput object to determine where to serialize the output to. The LSSerializer will look at the different outputs specified in the LSOutput in the following order to know which one to output to, the first one that is not null and not an empty string will be used:

  1. LSOutput.characterStream
  2. LSOutput.byteStream
  3. LSOutput.systemId

LSOutput objects belong to the application. The DOM implementation will never modify them (though it may make copies and modify the copies, if necessary).

IDL Definition
interface LSOutput {
  // Depending on the language binding in use,
  // this attribute may not be available.
           attribute LSWriter        characterStream;
           attribute LSOutputStream  byteStream;
           attribute DOMString       systemId;
           attribute DOMString       encoding;
};

Attributes
byteStream of type LSOutputStream
An attribute of a language and binding dependent type that represents a writable stream of bytes.
characterStream of type LSWriter
Depending on the language binding in use, this attribute may not be available.
An attribute of a language and binding dependent type that represents a writable stream to which 16-bit units can be output.
encoding of type DOMString
The character encoding to use for the output. The encoding must be a string acceptable for an XML encoding declaration ([XML 1.0] section 4.3.3 "Character Encoding in Entities"), it is recommended that character encodings registered (as charsets) with the Internet Assigned Numbers Authority [IANA-CHARSETS] should be referred to using their registered names.
systemId of type DOMString
The system identifier, a URI reference [IETF RFC 2396], for this output destination.
If the system ID is a relative URI reference (see section 5 in [IETF RFC 2396]), the behavior is implementation dependent.
Interface LSSerializerFilter

LSSerializerFilters provide applications the ability to examine nodes as they are being serialized and decide what nodes should be serialized or not. The LSSerializerFilter interface is based on the NodeFilter interface defined in [DOM Level 2 Traversal and Range].

Document, DocumentType, DocumentFragment, Notation, Entity, and children of Attr nodes are not passed to the filter. The child nodes of an EntityReference node are only passed to the filter if the EntityReference node is skipped by the method LSParserFilter.acceptNode().

When serializing an Element, the element is passed to the filter before any of its attributes are passed to the filter. Namespace declaration attributes, and default attributes (except in the case when "discard-default-content" is set to false), are never passed to the filter.

The result of any attempt to modify a node passed to a LSSerializerFilter is implementation dependent.

DOM applications must not raise exceptions in a filter. The effect of throwing exceptions from a filter is DOM implementation dependent.

For efficiency, a node passed to the filter may not be the same as the one that is actually in the tree. And the actual node (node object identity) may be reused during the process of filtering and serializing a document.

IDL Definition
interface LSSerializerFilter : traversal::NodeFilter {
  readonly attribute unsigned long   whatToShow;
};

Attributes
whatToShow of type unsigned long, readonly
Tells the LSSerializer what types of nodes to show to the filter. If a node is not shown to the filter using this attribute, it is automatically serialized. See NodeFilter for definition of the constants. The constants SHOW_DOCUMENT, SHOW_DOCUMENT_TYPE, SHOW_DOCUMENT_FRAGMENT, SHOW_NOTATION, and SHOW_ENTITY are meaningless here, such nodes will never be passed to a LSSerializerFilter.
Unlike [DOM Level 2 Traversal and Range], the SHOW_ATTRIBUTE constant indicates that the Attr nodes are shown and passed to the filter.
The constants used here are defined in [DOM Level 2 Traversal and Range].


IDL Definitions

07 April 2004

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Abstract Schemas and Load and Save definitions.

The IDL files are also available as: http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/idl.zip

ls.idl:

// File: ls.idl

#ifndef _LS_IDL_
#define _LS_IDL_

#include "dom.idl"
#include "events.idl"
#include "traversal.idl"

#pragma prefix "dom.w3c.org"
module ls
{

  typedef   Object LSInputStream;

  typedef   Object LSOutputStream;

  typedef   Object LSReader;

  typedef   Object LSWriter;

  typedef dom::DOMString DOMString;
  typedef dom::DOMConfiguration DOMConfiguration;
  typedef dom::Node Node;
  typedef dom::Document Document;
  typedef dom::Element Element;

  interface LSParser;
  interface LSSerializer;
  interface LSInput;
  interface LSOutput;
  interface LSParserFilter;
  interface LSSerializerFilter;

  exception LSException {
    unsigned short   code;
  };
  // LSExceptionCode
  const unsigned short      PARSE_ERR                      = 81;
  const unsigned short      SERIALIZE_ERR                  = 82;

  interface DOMImplementationLS {

    // DOMImplementationLSMode
    const unsigned short      MODE_SYNCHRONOUS               = 1;
    const unsigned short      MODE_ASYNCHRONOUS              = 2;

    LSParser           createLSParser(in unsigned short mode,
                                      in DOMString schemaType)
                                        raises(dom::DOMException);
    LSSerializer       createLSSerializer();
    LSInput            createLSInput();
    LSOutput           createLSOutput();
  };

  interface LSParser {
    readonly attribute DOMConfiguration domConfig;
             attribute LSParserFilter  filter;
    readonly attribute boolean         async;
    readonly attribute boolean         busy;
    Document           parse(in LSInput input)
                                        raises(dom::DOMException,
                                               LSException);
    Document           parseURI(in DOMString uri)
                                        raises(dom::DOMException,
                                               LSException);

    // ACTION_TYPES
    const unsigned short      ACTION_APPEND_AS_CHILDREN      = 1;
    const unsigned short      ACTION_REPLACE_CHILDREN        = 2;
    const unsigned short      ACTION_INSERT_BEFORE           = 3;
    const unsigned short      ACTION_INSERT_AFTER            = 4;
    const unsigned short      ACTION_REPLACE                 = 5;

    Node               parseWithContext(in LSInput input,
                                        in Node contextArg,
                                        in unsigned short action)
                                        raises(dom::DOMException,
                                               LSException);
    void               abort();
  };

  interface LSInput {
    // Depending on the language binding in use,
    // this attribute may not be available.
             attribute LSReader        characterStream;
             attribute LSInputStream   byteStream;
             attribute DOMString       stringData;
             attribute DOMString       systemId;
             attribute DOMString       publicId;
             attribute DOMString       baseURI;
             attribute DOMString       encoding;
             attribute boolean         certifiedText;
  };

  interface LSResourceResolver {
    LSInput            resolveResource(in DOMString type,
                                       in DOMString namespaceURI,
                                       in DOMString publicId,
                                       in DOMString systemId,
                                       in DOMString baseURI);
  };

  interface LSParserFilter {

    // Constants returned by startElement and acceptNode
    const short               FILTER_ACCEPT                  = 1;
    const short               FILTER_REJECT                  = 2;
    const short               FILTER_SKIP                    = 3;
    const short               FILTER_INTERRUPT               = 4;

    unsigned short     startElement(in Element elementArg);
    unsigned short     acceptNode(in Node nodeArg);
    readonly attribute unsigned long   whatToShow;
  };

  interface LSSerializer {
    readonly attribute DOMConfiguration domConfig;
             attribute DOMString       newLine;
             attribute LSSerializerFilter filter;
    boolean            write(in Node nodeArg,
                             in LSOutput destination)
                                        raises(LSException);
    boolean            writeToURI(in Node nodeArg,
                                  in DOMString uri)
                                        raises(LSException);
    DOMString          writeToString(in Node nodeArg)
                                        raises(dom::DOMException,
                                               LSException);
  };

  interface LSOutput {
    // Depending on the language binding in use,
    // this attribute may not be available.
             attribute LSWriter        characterStream;
             attribute LSOutputStream  byteStream;
             attribute DOMString       systemId;
             attribute DOMString       encoding;
  };

  interface LSProgressEvent : events::Event {
    readonly attribute LSInput         input;
    readonly attribute unsigned long   position;
    readonly attribute unsigned long   totalSize;
  };

  interface LSLoadEvent : events::Event {
    readonly attribute Document        newDocument;
    readonly attribute LSInput         input;
  };

  interface LSSerializerFilter : traversal::NodeFilter {
    readonly attribute unsigned long   whatToShow;
  };
};

#endif // _LS_IDL_


Java Language Binding

07 April 2004

Appendix B: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Load and Save.

The Java files are also available as http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/java-binding.zip

org/w3c/dom/ls/LSException.java:

package org.w3c.dom.ls;

public class LSException extends RuntimeException {
    public LSException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // LSExceptionCode
    public static final short PARSE_ERR                 = 81;
    public static final short SERIALIZE_ERR             = 82;

}

org/w3c/dom/ls/DOMImplementationLS.java:

package org.w3c.dom.ls;

import org.w3c.dom.DOMException;

public interface DOMImplementationLS {
    // DOMImplementationLSMode
    public static final short MODE_SYNCHRONOUS          = 1;
    public static final short MODE_ASYNCHRONOUS         = 2;

    public LSParser createLSParser(short mode,
                                   String schemaType)
                                   throws DOMException;

    public LSSerializer createLSSerializer();

    public LSInput createLSInput();

    public LSOutput createLSOutput();

}

org/w3c/dom/ls/LSParser.java:

package org.w3c.dom.ls;

import org.w3c.dom.Document;
import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface LSParser {
    public DOMConfiguration getDomConfig();

    public LSParserFilter getFilter();
    public void setFilter(LSParserFilter filter);

    public boolean getAsync();

    public boolean getBusy();

    public Document parse(LSInput input)
                          throws DOMException, LSException;

    public Document parseURI(String uri)
                             throws DOMException, LSException;

    // ACTION_TYPES
    public static final short ACTION_APPEND_AS_CHILDREN = 1;
    public static final short ACTION_REPLACE_CHILDREN   = 2;
    public static final short ACTION_INSERT_BEFORE      = 3;
    public static final short ACTION_INSERT_AFTER       = 4;
    public static final short ACTION_REPLACE            = 5;

    public Node parseWithContext(LSInput input,
                                 Node contextArg,
                                 short action)
                                 throws DOMException, LSException;

    public void abort();

}

org/w3c/dom/ls/LSInput.java:

package org.w3c.dom.ls;

public interface LSInput {
    public java.io.Reader getCharacterStream();
    public void setCharacterStream(java.io.Reader characterStream);

    public java.io.InputStream getByteStream();
    public void setByteStream(java.io.InputStream byteStream);

    public String getStringData();
    public void setStringData(String stringData);

    public String getSystemId();
    public void setSystemId(String systemId);

    public String getPublicId();
    public void setPublicId(String publicId);

    public String getBaseURI();
    public void setBaseURI(String baseURI);

    public String getEncoding();
    public void setEncoding(String encoding);

    public boolean getCertifiedText();
    public void setCertifiedText(boolean certifiedText);

}

org/w3c/dom/ls/LSResourceResolver.java:

package org.w3c.dom.ls;

public interface LSResourceResolver {
    public LSInput resolveResource(String type,
                                   String namespaceURI,
                                   String publicId,
                                   String systemId,
                                   String baseURI);

}

org/w3c/dom/ls/LSParserFilter.java:

package org.w3c.dom.ls;

import org.w3c.dom.Node;
import org.w3c.dom.Element;

public interface LSParserFilter {
    // Constants returned by startElement and acceptNode
    public static final short FILTER_ACCEPT             = 1;
    public static final short FILTER_REJECT             = 2;
    public static final short FILTER_SKIP               = 3;
    public static final short FILTER_INTERRUPT          = 4;

    public short startElement(Element elementArg);

    public short acceptNode(Node nodeArg);

    public int getWhatToShow();

}

org/w3c/dom/ls/LSProgressEvent.java:

package org.w3c.dom.ls;

import org.w3c.dom.events.Event;

public interface LSProgressEvent extends Event {
    public LSInput getInput();

    public int getPosition();

    public int getTotalSize();

}

org/w3c/dom/ls/LSLoadEvent.java:

package org.w3c.dom.ls;

import org.w3c.dom.Document;
import org.w3c.dom.events.Event;

public interface LSLoadEvent extends Event {
    public Document getNewDocument();

    public LSInput getInput();

}

org/w3c/dom/ls/LSSerializer.java:

package org.w3c.dom.ls;

import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface LSSerializer {
    public DOMConfiguration getDomConfig();

    public String getNewLine();
    public void setNewLine(String newLine);

    public LSSerializerFilter getFilter();
    public void setFilter(LSSerializerFilter filter);

    public boolean write(Node nodeArg,
                         LSOutput destination)
                         throws LSException;

    public boolean writeToURI(Node nodeArg,
                              String uri)
                              throws LSException;

    public String writeToString(Node nodeArg)
                                throws DOMException, LSException;

}

org/w3c/dom/ls/LSOutput.java:

package org.w3c.dom.ls;

public interface LSOutput {
    public java.io.Writer getCharacterStream();
    public void setCharacterStream(java.io.Writer characterStream);

    public java.io.OutputStream getByteStream();
    public void setByteStream(java.io.OutputStream byteStream);

    public String getSystemId();
    public void setSystemId(String systemId);

    public String getEncoding();
    public void setEncoding(String encoding);

}

org/w3c/dom/ls/LSSerializerFilter.java:

package org.w3c.dom.ls;

import org.w3c.dom.traversal.NodeFilter;

public interface LSSerializerFilter extends NodeFilter {
    public int getWhatToShow();

}


ECMAScript Language Binding

07 April 2004

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Load and Save definitions.

Properties of the LSException Constructor function:
LSException.PARSE_ERR
The value of the constant LSException.PARSE_ERR is 81.
LSException.SERIALIZE_ERR
The value of the constant LSException.SERIALIZE_ERR is 82.
Objects that implement the LSException interface:
Properties of objects that implement the LSException interface:
code
This property is a Number.
Properties of the DOMImplementationLS Constructor function:
DOMImplementationLS.MODE_SYNCHRONOUS
The value of the constant DOMImplementationLS.MODE_SYNCHRONOUS is 1.
DOMImplementationLS.MODE_ASYNCHRONOUS
The value of the constant DOMImplementationLS.MODE_ASYNCHRONOUS is 2.
Objects that implement the DOMImplementationLS interface:
Functions of objects that implement the DOMImplementationLS interface:
createLSParser(mode, schemaType)
This function returns an object that implements the LSParser interface.
The mode parameter is a Number.
The schemaType parameter is a String.
This function can raise an object that implements the DOMException interface.
createLSSerializer()
This function returns an object that implements the LSSerializer interface.
createLSInput()
This function returns an object that implements the LSInput interface.
createLSOutput()
This function returns an object that implements the LSOutput interface.
Properties of the LSParser Constructor function:
LSParser.ACTION_APPEND_AS_CHILDREN
The value of the constant LSParser.ACTION_APPEND_AS_CHILDREN is 1.
LSParser.ACTION_REPLACE_CHILDREN
The value of the constant LSParser.ACTION_REPLACE_CHILDREN is 2.
LSParser.ACTION_INSERT_BEFORE
The value of the constant LSParser.ACTION_INSERT_BEFORE is 3.
LSParser.ACTION_INSERT_AFTER
The value of the constant LSParser.ACTION_INSERT_AFTER is 4.
LSParser.ACTION_REPLACE
The value of the constant LSParser.ACTION_REPLACE is 5.
Objects that implement the LSParser interface:
Properties of objects that implement the LSParser interface:
domConfig
This read-only property is an object that implements the DOMConfiguration interface.
filter
This property is an object that implements the LSParserFilter interface.
async
This read-only property is a Boolean.
busy
This read-only property is a Boolean.
Functions of objects that implement the LSParser interface:
parse(input)
This function returns an object that implements the Document interface.
The input parameter is an object that implements the LSInput interface.
This function can raise an object that implements the DOMException interface or the LSException interface.
parseURI(uri)
This function returns an object that implements the Document interface.
The uri parameter is a String.
This function can raise an object that implements the DOMException interface or the LSException interface.
parseWithContext(input, contextArg, action)
This function returns an object that implements the Node interface.
The input parameter is an object that implements the LSInput interface.
The contextArg parameter is an object that implements the Node interface.
The action parameter is a Number.
This function can raise an object that implements the DOMException interface or the LSException interface.
abort()
This function has no return value.
Objects that implement the LSInput interface:
Properties of objects that implement the LSInput interface:
byteStream
This property is an object that implements the Object interface.
stringData
This property is a String.
systemId
This property is a String.
publicId
This property is a String.
baseURI
This property is a String.
encoding
This property is a String.
certifiedText
This property is a Boolean.
LSResourceResolver function:
This function returns an object that implements the LSInput interface. The first parameter is a String. The second parameter is a String. The third parameter is a String. The fourth parameter is a String. The fifth parameter is a String.
Properties of the LSParserFilter Constructor function:
LSParserFilter.FILTER_ACCEPT
The value of the constant LSParserFilter.FILTER_ACCEPT is 1.
LSParserFilter.FILTER_REJECT
The value of the constant LSParserFilter.FILTER_REJECT is 2.
LSParserFilter.FILTER_SKIP
The value of the constant LSParserFilter.FILTER_SKIP is 3.
LSParserFilter.FILTER_INTERRUPT
The value of the constant LSParserFilter.FILTER_INTERRUPT is 4.
Objects that implement the LSParserFilter interface:
Properties of objects that implement the LSParserFilter interface:
whatToShow
This read-only property is a Number.
Functions of objects that implement the LSParserFilter interface:
startElement(elementArg)
This function returns a Number.
The elementArg parameter is an object that implements the Element interface.
acceptNode(nodeArg)
This function returns a Number.
The nodeArg parameter is an object that implements the Node interface.
Objects that implement the LSProgressEvent interface:
Objects that implement the LSProgressEvent interface have all properties and functions of the Event interface as well as the properties and functions defined below.
Properties of objects that implement the LSProgressEvent interface:
input
This read-only property is an object that implements the LSInput interface.
position
This read-only property is a Number.
totalSize
This read-only property is a Number.
Objects that implement the LSLoadEvent interface:
Objects that implement the LSLoadEvent interface have all properties and functions of the Event interface as well as the properties and functions defined below.
Properties of objects that implement the LSLoadEvent interface:
newDocument
This read-only property is an object that implements the Document interface.
input
This read-only property is an object that implements the LSInput interface.
Objects that implement the LSSerializer interface:
Properties of objects that implement the LSSerializer interface:
domConfig
This read-only property is an object that implements the DOMConfiguration interface.
newLine
This property is a String.
filter
This property is an object that implements the LSSerializerFilter interface.
Functions of objects that implement the LSSerializer interface:
write(nodeArg, destination)
This function returns a Boolean.
The nodeArg parameter is an object that implements the Node interface.
The destination parameter is an object that implements the LSOutput interface.
This function can raise an object that implements the LSException interface.
writeToURI(nodeArg, uri)
This function returns a Boolean.
The nodeArg parameter is an object that implements the Node interface.
The uri parameter is a String.
This function can raise an object that implements the LSException interface.
writeToString(nodeArg)
This function returns a String.
The nodeArg parameter is an object that implements the Node interface.
This function can raise an object that implements the DOMException interface or the LSException interface.
Objects that implement the LSOutput interface:
Properties of objects that implement the LSOutput interface:
byteStream
This property is an object that implements the Object interface.
systemId
This property is a String.
encoding
This property is a String.
Objects that implement the LSSerializerFilter interface:
Objects that implement the LSSerializerFilter interface have all properties and functions of the NodeFilter interface as well as the properties and functions defined below.
Properties of objects that implement the LSSerializerFilter interface:
whatToShow
This read-only property is a Number.


Acknowledgements

07 April 2004

Appendix D: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

Many thanks to Elliotte Rusty Harold, Andrew Clover, Anjana Manian, Christian Parpart, Mikko Honkala, and François Yergeau for their review and comments of this document.

Special thanks to the DOM Conformance Test Suites contributors: Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape), with a special mention to Curt Arnold.

D.1 Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

16-bit unit
The base unit of a DOMString. This indicates that indexing on a DOMString occurs in units of 16 bits. This must not be misunderstood to mean that a DOMString can store arbitrary 16-bit units. A DOMString is a character string encoded in UTF-16; this means that the restrictions of UTF-16 as well as the other relevant restrictions on character strings must be maintained. A single character, for example in the form of a numeric character reference, may correspond to one or two 16-bit units.
API
An API is an Application Programming Interface, a set of functions or methods used to access some functionality.
namespace well-formed
A node is a namespace well-formed XML node if it is a well-formed node, and follows the productions and namespace constraints. If [XML 1.0] is used, the constraints are defined in [XML Namespaces]. If [XML 1.1] is used, the constraints are defined in [XML Namespaces 1.1].
read only node
A read only node is a node that is immutable. This means its list of children, its content, and its attributes, when it is an element, cannot be changed in any way. However, a read only node can possibly be moved, when it is not itself contained in a read only node.
schema
A schema defines a set of structural and value constraints applicable to XML documents. Schemas can be expressed in schema languages, such as DTD, XML Schema, etc.
well-formed
A node is a well-formed XML node if its serialized form, without doing any transformation during its serialization, matches its respective production in [XML 1.0] or [XML 1.1] (depending on the XML version in use) with all well-formedness constraints related to that production, and if the entities which are referenced within the node are also well-formed. If namespaces for XML are in use, the node must also be namespace well-formed.


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

F.1 Normative References

[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 7 April 2004. This version of the Document Object Model Level 3 Core Recommendation is http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407. The latest version of DOM Level 3 Core is available at http://www.w3.org/TR/DOM-Level-3-Core.
[DOM Level 2 Traversal and Range]
Document Object Model Level 2 Traversal and Range Specification, J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood, Editors. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Traversal and Range Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113. The latest version of Document Object Model Level 2 Traversal and Range is available at http://www.w3.org/TR/DOM-Level-2-Traversal-Range.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[IANA-CHARSETS]
Official Names for Character Sets, K. Simonsen, et al., Editors. Internet Assigned Numbers Authority. Available at ftp://ftp.isi.edu/in-notes/iana/assignments/character-sets.
[ISO/IEC 10646]
ISO/IEC 10646-2000 (E). Information technology - Universal Multiple-Octet Coded Character Set (UCS) - Part 1: Architecture and Basic Multilingual Plane, as, from time to time, amended, replaced by a new edition or expanded by the addition of new parts. [Geneva]: International Organization for Standardization, 2000. See also International Organization for Standardization, available at http://www.iso.ch, for the latest version.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[IETF RFC 2396]
Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, Authors. Internet Engineering Task Force, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt.
[IETF RFC 3023]
XML Media Types, M. Murata, S. St.Laurent, and D. Kohn, Editors. Internet Engineering Task Force, January 2001. Available at http://www.ietf.org/rfc/rfc3023.txt.
[SAX]
Simple API for XML, D. Megginson and D. Brownell, Maintainers. Available at http://www.saxproject.org/.
[Unicode]
The Unicode Standard, Version 4, ISBN 0-321-18578-1, as updated from time to time by the publication of new versions. The Unicode Consortium, 2000. See also Versions of the Unicode Standard, available at http://www.unicode.org/unicode/standard/versions, for latest version and additional information on versions of the standard and of the Unicode Character Database.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Third Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, and F. Yergeau, Editors. World Wide Web Consortium, 4 February 2004, revised 10 February 1998 and 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2004/REC-xml-20040204. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML 1.1]
XML 1.1, T. Bray, and al., Editors. World Wide Web Consortium, 4 February 2004. This version of the XML 1.1 Recommendation is http://www.w3.org/TR/2004/REC-xml11-20040204. The latest version of XML 1.1 is available at http://www.w3.org/TR/xml11.
[XML Information Set]
XML Information Set (Second Edition), J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 4 February 2004, revised 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version of XML Information Set is available at http://www.w3.org/TR/xml-infoset.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the Namespaces in XML Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[XML Namespaces 1.1]
Namespaces in XML 1.1, T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors. World Wide Web Consortium, 4 February 2004. This version of the Namespaces in XML 1.1 Recommendation is http://www.w3.org/TR/2004/REC-xml-names11-20040204. The latest version of Namespaces in XML 1.1 is available at http://www.w3.org/TR/xml-names11/.

F.2 Informative References

[Canonical XML]
Canonical XML Version 1.0, J. Boyer, Editor. World Wide Web Consortium, 15 March 2001. This version of the Canonical XML Recommendation is http://www.w3.org/TR/2001/REC-xml-c14n-20010315. The latest version of Canonical XML is available at http://www.w3.org/TR/xml-c14n.
[DOM Level 3 Events]
Document Object Model Level 3 Events Specification, P. Le Hégaret, T. Pixley, Editors. World Wide Web Consortium, November 2003. This version of the Document Object Model Level 3 Events specification is http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107. The latest version of Document Object Model Level 3 Events is available at http://www.w3.org/TR/DOM-Level-3-Events.
[JAXP]
Java API for XML Processing (JAXP). Sun Microsystems. Available at http://java.sun.com/xml/jaxp/.
[IETF RFC 2616]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, et al., Authors. Internet Engineering Task Force, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt.
[XML Schema Part 1]
XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Part 1 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-1-20010502. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1.


Index

"ignore-unknown-character-denormalizations"
"canonical-form" | "charset-overrides-xml-encoding" | "disallow-doctype" 1, 2
"discard-default-content" 1, 2, 3, 4 | "format-pretty-print" 1, 2 | "ignore-unknown-character-denormalizations" 1, 2
"infoset" | "namespaces" | "normalize-characters"
"resource-resolver" | "supported-media-types-only" 1, 2 | "validate"
"validate-if-schema" | "well-formed" | "xml-declaration" 1, 2, 3
16-bit unit 1, 2, 3, 4, 5, 6
[attributes]
abort | acceptNode | ACTION_APPEND_AS_CHILDREN
ACTION_INSERT_AFTER | ACTION_INSERT_BEFORE | ACTION_REPLACE
ACTION_REPLACE_CHILDREN | API 1, 2 | async
baseURI | busy | byteStream 1, 2
Canonical XML 1, 2 | certifiedText | characterStream 1, 2
createLSInput | createLSOutput | createLSParser
createLSSerializer
DOM Level 2 Core 1, 2, 3, 4 | DOM Level 2 Traversal and Range 1, 2, 3, 4 | DOM Level 3 Core 1, 2, 3, 4, 5, 6, 7, 8
DOM Level 3 Events 1, 2 | domConfig 1, 2 | DOMImplementationLS
ECMAScript | encoding 1, 2
filter 1, 2 | FILTER_ACCEPT | FILTER_INTERRUPT
FILTER_REJECT | FILTER_SKIP
IANA-CHARSETS 1, 2 | IETF RFC 2396 1, 2, 3, 4, 5, 6 | IETF RFC 2616 1, 2, 3
IETF RFC 3023 1, 2 | input 1, 2 | ISO/IEC 10646 1, 2, 3, 4
Java | JAXP 1, 2
load | LSException | LSInput
LSInputStream | LSLoadEvent | LSOutput
LSOutputStream | LSParser | LSParserFilter
LSProgressEvent | LSReader | LSResourceResolver
LSSerializer | LSSerializerFilter | LSWriter
MODE_ASYNCHRONOUS | MODE_SYNCHRONOUS
namespace well-formed | newDocument | newLine
OMG IDL
parse | PARSE_ERR | parseURI
parseWithContext | position | progress
publicId
read only node 1, 2 | resolveResource
SAX 1, 2, 3 | schema 1, 2 | SERIALIZE_ERR
startElement | stringData | systemId 1, 2
totalSize
Unicode 1, 2, 3, 4
well-formed 1, 2, 3, 4 | whatToShow 1, 2 | write
writeToString | writeToURI
XML 1.0 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 | XML 1.1 1, 2, 3, 4, 5, 6, 7, 8 | XML Information Set 1, 2
XML Namespaces 1, 2, 3 | XML Namespaces 1.1 1, 2, 3 | XML Schema Part 1 1, 2, 3


Document Object Model (DOM) Level 3 Validation Specification

Version 1.0

W3C Recommendation 27 January 2004

This version:
http://www.w3.org/TR/2004/REC-DOM-Level-3-Val-20040127
Latest version:
http://www.w3.org/TR/DOM-Level-3-Val
Previous version:
http://www.w3.org/TR/2003/PR-DOM-Level-3-Val-20031215
Editors:
Ben Chang, Oracle
Joe Kesselman, IBM (until September 2001)
Rezaur Rahman, Intel Corporation (until July 2001)

Please refer to the errata for this document, which may include some normative corrections.

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

See also translations of this document.

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

Abstract

This specification defines the Document Object Model Validation Level 3, a platform- and language-neutral interface. This module provides the guidance to programs and scripts to dynamically update the content and the structure of documents while ensuring that the document remains valid, or to ensure that the document becomes valid.

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 the Recommendation of "DOM Level 3 Validation". No changes were done to this specification since the Proposed Recommendation version.

Comments on this document should be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

An implementation report, along with the test suite, is also available.

This is a stable document and has been endorsed by the W3C Membership and the participants of the DOM working group. The English version of this specification is the only normative version. Information about translations of this document is available at http://www.w3.org/2004/01/DOM-Level-3-translations.

The list of known errors in this document is available at http://www.w3.org/2004/01/DOM-Level-3-errata.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group participants.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • 1. Validation
  • Appendix A: Validation Outcomes
  • Appendix B: IDL Definitions
  • Appendix C: Java Language Binding
  • Appendix D: ECMAScript Language Binding
  • Appendix E: Acknowledgements
  • Glossary
  • References
  • Index


Validation

27 January 2004

1. Validation

Editors:
Ben Chang, Oracle
Joe Kesselman, IBM (until September 2001)
Rezaur Rahman, Intel Corporation (until July 2001)

Table of contents

  • 1.1 Overview
  • 1.2 Exceptions
    • ExceptionVAL, ExceptionVALCode
  • 1.3 Document Editing Interfaces
    • DocumentEditVAL, NodeEditVAL, ElementEditVAL, CharacterDataEditVAL

1.1 Overview

This chapter describes the optional DOM Level 3 Validation feature. This module provides Application Programming Interfaces (APIs) to guide construction and editing of XML documents. Examples of such guided editing are queries like those that combine questions like "what does the schema allow me to insert/delete here" and "if I insert/delete here, will the document still be valid."

To aid users in the editing and creation of XML documents, other queries may expose different levels of details, e.g., all the possible children, those which would be valid given what precedes this point, lists of defined symbols of a given kind. Some of these queries would prompt checks and warn users if they're about to conflict with or overwrite such data.

Finally, users would like to validate an edited or newly constructed document before serializing it or passing it to other users. They may edit, come up with an invalid document, then edit again to result in a valid document. During this process, these APIs can allow the user to check the validity of the document or subtree on demand. If necessary, these APIs can also require that the document or subtree remain valid during this editing process via the DocumentEditVal.continuousValidityChecking flag.

A DOM application can use the hasFeature(feature, version) method of the DOMImplementation interface to determine with parameter values "Validation" and "3.0", respectively, whether or not these interfaces are supported by the implementation. This implementation is dependent on [DOM Level 2 Core] and the [DOM Level 3 Core] DOMConfiguration interface.

This chapter focuses on the editing aspects used in the XML document editing world and usage of such information. The appendix describes in detail all the possible outcomes of the validation operations on the different node types.

1.2 Exceptions

This section describes the "VAL-DOC-EDIT" exceptions.

Exception ExceptionVAL

Some Validation operations may throw an ExceptionVAL as described in their descriptions.

IDL Definition
exception ExceptionVAL {
  unsigned short   code;
};
// ExceptionVALCode
const unsigned short      NO_SCHEMA_AVAILABLE_ERR        = 71;

Definition group ExceptionVALCode

An integer indicating the type of error generated.

Defined Constants
NO_SCHEMA_AVAILABLE_ERR
This error occurs when the operation cannot complete due to an unavailable schema.

1.3 Document Editing Interfaces

This section contains "Document Editing" methods as described in the DocumentEditVAL, NodeEditVAL, ElementEditVAL, and CharacterDataEditVAL interfaces. References to new [DOM Level 3 Core] interfaces such as DOMStringList and NameList also exist. With the latter interface, if the schema is a DTD, the element information item names are simply local names; if the schema is a W3C XML schema, the names are qualified names, which may contain namespace prefixes.

Interface DocumentEditVAL

This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement the Document interface.

IDL Definition
interface DocumentEditVAL : NodeEditVAL {
           attribute boolean         continuousValidityChecking;
                                        // raises(DOMException,
                                        //        ExceptionVAL,
                                        //        DOMException) on setting

  readonly attribute DOMConfiguration domConfig;
  NameList           getDefinedElements(in DOMString namespaceURI);
  unsigned short     validateDocument();
};

Attributes
continuousValidityChecking of type boolean
An attribute specifying whether the validity of the document is continuously enforced. When the attribute is set to true, the implementation may raise certain exceptions, depending on the situation (see the following). This attribute is false by default.
Exceptions on setting

DOMException

NOT_SUPPORTED_ERR: Raised if the implementation does not support setting this attribute to true.

ExceptionVAL

NO_SCHEMA_AVAILABLE_ERR: Raised if this attribute is set to true and a schema is unavailable.

DOMException

VALIDATION_ERR: Raised if an operation makes this document not compliant with the VAL_INCOMPLETE validity type or the document is invalid, and this attribute is set to true.

domConfig of type DOMConfiguration, readonly
This allows the setting of the error handler, as described in the [DOM Level 3 Core] DOMConfiguration interface. An object implementing this DocumentEditVAL interface and the [DOM Level 3 Core] Document interface, which also has a domConfig attribute, needs to only implement this attribute once.
Methods
getDefinedElements
Returns list of all element information item names of global declaration, belonging to the specified namespace.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace. For DTDs, this is null.
Return Value

NameList

List of all element information item names belonging to the specified namespace or null if no schema is available.

No Exceptions
validateDocument
Validates the document against the schema, e.g., a DTD or an W3C XML schema or another. Any attempt to modify any part of the document while validating results in implementation-dependent behavior. In addition, the validation operation itself cannot modify the document, e.g., for default attributes. This method makes use of the error handler, as described in the [DOM Level 3 Core] DOMConfiguration interface, with all errors being SEVERITY_ERROR as defined in the DOMError interface.
Return Value

unsigned short

A validation state constant.

No Parameters
No Exceptions
Interface NodeEditVAL

This interface is similar to the [DOM Level 3 Core] Node interface, with methods for guided document editing.

IDL Definition
interface NodeEditVAL {

  // validationType
  const unsigned short      VAL_WF                         = 1;
  const unsigned short      VAL_NS_WF                      = 2;
  const unsigned short      VAL_INCOMPLETE                 = 3;
  const unsigned short      VAL_SCHEMA                     = 4;

  // validationState
  const unsigned short      VAL_TRUE                       = 5;
  const unsigned short      VAL_FALSE                      = 6;
  const unsigned short      VAL_UNKNOWN                    = 7;

  readonly attribute DOMString       defaultValue;
  readonly attribute DOMStringList   enumeratedValues;
  unsigned short     canInsertBefore(in Node newChild,
                                     in Node refChild);
  unsigned short     canRemoveChild(in Node oldChild);
  unsigned short     canReplaceChild(in Node newChild,
                                     in Node oldChild);
  unsigned short     canAppendChild(in Node newChild);
  unsigned short     nodeValidity(in unsigned short valType);
};

Definition group validationType

An integer indicating the validation type. Other specifications can define stricter validation types/constants by extending the NodeEditVAL interface.

Defined Constants
VAL_INCOMPLETE
Check if the node's immediate children are those expected by the content model. This node's trailing required children could be missing. It includes VAL_NS_WF.
VAL_NS_WF
Check if the node is namespace well-formed.
VAL_SCHEMA
Check if the node's entire subtree are those expected by the content model. It includes VAL_NS_WF.
VAL_WF
Check if the node is well-formed.
Definition group validationState

An integer indicating the validation state, or whether the operation can or cannot be done.

Defined Constants
VAL_FALSE
False if the node is invalid with regards to the operation, or if the operation cannot be done.
VAL_TRUE
True if the node is valid with regards to the operation, or if the operation can be done.
VAL_UNKNOWN
The validity of the node is unknown.
Attributes
defaultValue of type DOMString, readonly
The default value specified in an attribute or an element declaration or null if unspecified. If the schema is a W3C XML schema, this is the canonical lexical representation of the default value.
enumeratedValues of type DOMStringList, readonly
A DOMStringList, as described in [DOM Level 3 Core], of distinct values for an attribute or an element declaration or null if unspecified. If the schema is a W3C XML schema, this is a list of strings which are lexical representations corresponding to the values in the [value] property of the enumeration component for the type of the attribute or element. It is recommended that the canonical lexical representations of the values be used.
Methods
canAppendChild
Determines whether the Node.appendChild operation would make this document not compliant with the VAL_INCOMPLETE validity type.
Parameters
newChild of type Node
Node to be appended.
Return Value

unsigned short

A validation state constant.

No Exceptions
canInsertBefore
Determines whether the Node.insertBefore operation would make this document not compliant with the VAL_INCOMPLETE validity type.
Parameters
newChild of type Node
Node to be inserted.
refChild of type Node
Reference Node.
Return Value

unsigned short

A validation state constant.

No Exceptions
canRemoveChild
Determines whether the Node.removeChild operation would make this document not compliant with the VAL_INCOMPLETE validity type.
Parameters
oldChild of type Node
Node to be removed.
Return Value

unsigned short

A validation state constant.

No Exceptions
canReplaceChild
Determines whether the Node.replaceChild operation would make this document not compliant with the VAL_INCOMPLETE validity type.
Parameters
newChild of type Node
New Node.
oldChild of type Node
Node to be replaced.
Return Value

unsigned short

A validation state constant.

No Exceptions
nodeValidity
Determines if the node is valid relative to the validation type specified in valType. This operation doesn't normalize before checking if it is valid. To do so, one would need to explicitly call a normalize method. The difference between this method and the DocumentEditVAL.validateDocument method is that the latter method only checks to determine whether the entire document is valid.
Parameters
valType of type unsigned short
Flag to indicate the validation type checking to be done.
Return Value

unsigned short

A validation state constant.

No Exceptions
Interface ElementEditVAL

This interface extends the NodeEditVAL interface with additional methods for guided document editing. An object implementing this interface must also implement the Element interface.

This interface also has attributes that are a NameList of elements or attributes which can appear in the specified context. Some schema languages, i.e., W3C XML schema, define wildcards which provide for validation of attribute and element information items dependent on their namespace names but independent of their local names.

To expose wildcards, the NameList returns the values that represent the namespace constraint:

  • {namespaceURI, name} is {null, ##any} if any;
  • {namespaceURI, name} is {namespace_a, ##other} if not and a namespace name (namespace_a);
  • {namespaceURI, name} is {null, ##other} if not and absent;
  • Pairs of {namespaceURI, name} with values {a_namespaceURI | null, null} if a set whose members are either namespace names or absent.

IDL Definition
interface ElementEditVAL : NodeEditVAL {

  // ContentTypeVAL
  const unsigned short      VAL_EMPTY_CONTENTTYPE          = 1;
  const unsigned short      VAL_ANY_CONTENTTYPE            = 2;
  const unsigned short      VAL_MIXED_CONTENTTYPE          = 3;
  const unsigned short      VAL_ELEMENTS_CONTENTTYPE       = 4;
  const unsigned short      VAL_SIMPLE_CONTENTTYPE         = 5;

  readonly attribute NameList        allowedChildren;
  readonly attribute NameList        allowedFirstChildren;
  readonly attribute NameList        allowedParents;
  readonly attribute NameList        allowedNextSiblings;
  readonly attribute NameList        allowedPreviousSiblings;
  readonly attribute NameList        allowedAttributes;
  readonly attribute NameList        requiredAttributes;
  readonly attribute unsigned short  contentType;
  unsigned short     canSetTextContent(in DOMString possibleTextContent);
  unsigned short     canSetAttribute(in DOMString attrname,
                                     in DOMString attrval);
  unsigned short     canSetAttributeNode(in Attr attrNode);
  unsigned short     canSetAttributeNS(in DOMString namespaceURI,
                                       in DOMString qualifiedName,
                                       in DOMString value);
  unsigned short     canRemoveAttribute(in DOMString attrname);
  unsigned short     canRemoveAttributeNS(in DOMString namespaceURI,
                                          in DOMString localName);
  unsigned short     canRemoveAttributeNode(in Node attrNode);
  unsigned short     isElementDefined(in DOMString name);
  unsigned short     isElementDefinedNS(in DOMString namespaceURI,
                                        in DOMString name);
};

Definition group ContentTypeVAL

An integer indicating the content type of an element.

Defined Constants
VAL_ANY_CONTENTTYPE
The content model contains unordered child information item(s), i.e., element, processing instruction, unexpanded entity reference, character, and comment information items as defined in the XML Information Set. If the schema is a DTD, this corresponds to the ANY content model.
VAL_ELEMENTS_CONTENTTYPE
The content model contains a sequence of element information items optionally separated by whitespace. If the schema is a DTD, this is the element content content model; and if the schema is a W3C XML schema, this is the element-only content type.
VAL_EMPTY_CONTENTTYPE
The content model does not allow any content. If the schema is a W3C XML schema, this corresponds to the empty content type; and if the schema is a DTD, this corresponds to the EMPTY content model.
VAL_MIXED_CONTENTTYPE
The content model contains a sequence of ordered element information items optionally interspersed with character data. If the schema is a W3C XML schema, this corresponds to the mixed content type.
VAL_SIMPLE_CONTENTTYPE
The content model contains character information items. If the schema is a W3C XML schema, then the element has a content type of VAL_SIMPLE_CONTENTTYPE if the type of the element is a simple type definition, or the type of the element is a complexType whose {content type} is a simple type definition.
Attributes
allowedAttributes of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all possible attribute information items or wildcards that can appear as attributes of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedChildren of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all possible element information items or wildcards that can appear as children of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedFirstChildren of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all possible element information items or wildcards that can appear as a first child of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedNextSiblings of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all element information items or wildcards that can be inserted as a next sibling of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedParents of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all possible element information items that can appear as a parent this element, or null if this element has no context or schema.
allowedPreviousSiblings of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of all element information items or wildcards that can be inserted as a previous sibling of this element, or null if this element has no context or schema.
contentType of type unsigned short, readonly
The content type of an element as defined above.
requiredAttributes of type NameList, readonly
A NameList, as described in [DOM Level 3 Core], of required attribute information items that must appear on this element, or null if this element has no context or schema.
Methods
canRemoveAttribute
Verifies if an attribute by the given name can be removed.
Parameters
attrname of type DOMString
Name of attribute.
Return Value

unsigned short

A validation state constant.

No Exceptions
canRemoveAttributeNS
Verifies if an attribute by the given local name and namespace can be removed.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to remove.
localName of type DOMString
Local name of the attribute to be removed.
Return Value

unsigned short

A validation state constant.

No Exceptions
canRemoveAttributeNode
Determines if an attribute node can be removed.
Parameters
attrNode of type Node
The Attr node to remove from the attribute list.
Return Value

unsigned short

A validation state constant.

No Exceptions
canSetAttribute
Determines if the value for specified attribute can be set.
Parameters
attrname of type DOMString
Name of attribute.
attrval of type DOMString
Value to be assigned to the attribute.
Return Value

unsigned short

A validation state constant.

No Exceptions
canSetAttributeNS
Determines if the attribute with given namespace and qualified name can be created if not already present in the attribute list of the element. If the attribute with the same qualified name and namespaceURI is already present in the element's attribute list, it tests whether the value of the attribute and its prefix can be set to the new value.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace.
qualifiedName of type DOMString
Qualified name of attribute.
value of type DOMString
Value to be assigned to the attribute.
Return Value

unsigned short

A validation state constant.

No Exceptions
canSetAttributeNode
Determines if an attribute node can be added.
Parameters
attrNode of type Attr
Node in which the attribute can possibly be set.
Return Value

unsigned short

A validation state constant.

No Exceptions
canSetTextContent
Determines if the text content of this node and its descendants can be set to the string passed in.
Parameters
possibleTextContent of type DOMString
Possible text content string.
Return Value

unsigned short

A validation state constant.

No Exceptions
isElementDefined
Determines if name is defined in the schema. This only applies to global declarations. This method is for non-namespace aware schemas.
Parameters
name of type DOMString
Name of element.
Return Value

unsigned short

A validation state constant.

No Exceptions
isElementDefinedNS
Determines if name in this namespace is defined in the current context. Thus not only does this apply to global declarations. but depending on the content, this may also apply to local definitions. This method is for namespace aware schemas.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace.
name of type DOMString
Name of element.
Return Value

unsigned short

A validation state constant.

No Exceptions
Interface CharacterDataEditVAL

This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement CharacterData interface. When validating CharacterData nodes, the NodeEditVAL.nodeValidity operation must find the nearest parent node in order to do this; if no parent node is found, VAL_UNKNOWN is returned. In addition, when VAL_INCOMPLETE is passed in as an argument to the NodeEditVAL.nodeValidity operation to operate on such nodes, the operation considers all the text and not just some of it.

IDL Definition
interface CharacterDataEditVAL : NodeEditVAL {
  unsigned short     isWhitespaceOnly();
  unsigned short     canSetData(in DOMString arg);
  unsigned short     canAppendData(in DOMString arg);
  unsigned short     canReplaceData(in unsigned long offset,
                                    in unsigned long count,
                                    in DOMString arg)
                                        raises(DOMException);
  unsigned short     canInsertData(in unsigned long offset,
                                   in DOMString arg)
                                        raises(DOMException);
  unsigned short     canDeleteData(in unsigned long offset,
                                   in unsigned long count)
                                        raises(DOMException);
};

Methods
canAppendData
Determines if character data can be appended.
Parameters
arg of type DOMString
Data to be appended.
Return Value

unsigned short

A validation state constant.

No Exceptions
canDeleteData
Determines if character data can be deleted.
Parameters
offset of type unsigned long
Offset.
count of type unsigned long
Number of 16-bit units to delete.
Return Value

unsigned short

A validation state constant.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

canInsertData
Determines if character data can be inserted.
Parameters
offset of type unsigned long
Offset.
arg of type DOMString
Argument to be set.
Return Value

unsigned short

A validation state constant.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.

canReplaceData
Determines if character data can be replaced.
Parameters
offset of type unsigned long
Offset.
count of type unsigned long
Replacement.
arg of type DOMString
Argument to be set.
Return Value

unsigned short

A validation state constant.

Exceptions

DOMException

INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

canSetData
Determines if character data can be set.
Parameters
arg of type DOMString
Argument to be set.
Return Value

unsigned short

A validation state constant.

No Exceptions
isWhitespaceOnly
Determines if character data is only whitespace.
Return Value

unsigned short

A validation state constant.

No Parameters
No Exceptions


Validation Outcomes

27 January 2004

Appendix A: Validation Outcomes

Editor:
Ben Chang, Oracle

Table of contents

  • A.1 The nodeValidity and validateDocument methods
  • A.2 Other validation operations

A.1 The nodeValidity and validateDocument methods

The following table describes all possible validation outcomes of the NodeEditVAL.nodeValidity(valType) method.

Validation Type | Validity outcome
 | VAL_TRUE | VAL_FALSE | VAL_UNKNOWN
VAL_WF | The node is well-formed. | The node is not well-formed. | Not applicable.
VAL_NS_WF | The node is well-formed. Processor must take into account all the in-scope namespace declarations. | The node is not namespace well-formed. Processor must take into account all the in-scope namespace declarations. | Not applicable.
VAL_NS_WF | The node is well-formed. Processor must take into account all namespace declarations in scope. | The node is not namespace well-formed. Processor must take into account all the in-scope namespace declarations. | Not applicable.
VAL_SCHEMA | The node is valid: it complies with all the constraints expressed in the schema. | The node fails to comply to all the constraints expressed in the schema. | If the schema is an XML Schema, PSVI [validity] property value is unknown.
VAL_INCOMPLETE | The node is valid: it complies with the VAL_INCOMPLETE definition. | The node is invalid with regard to the VAL_INCOMPLETE definition. | If the schema is an XML Schema, PSVI [validity] property value is unknown.

The following table describes the outcome of the DocumentEditVAL.validateDocument() and NodeEditVAL.nodeValidity(valType) methods, with the latter called on the DocumentEditVAL node with validationType NodeEditVAL.VAL_SCHEMA.

Methods | Validity outcome
 | VAL_TRUE | VAL_FALSE | VAL_UNKNOWN
validateDocument and nodeValidity, called on the Document node with validationType VAL_SCHEMA. | If the schema is a DTD, then the document valid constraint is satisfied. If the schema is an XML Schema, then the document validity is the same as the validity of the validation root, i.e., documentElement: PSVI [validity] valid. | Fails to satisfy the constraints defined. | If the schema is an XML Schema, then schema is not found or the declaration for the validation root is not found: PSVI [validity] unknown.

The following table describes outcomes for the NodeEditVAL.nodeValidity(valType) method called with the validationType NodeEditVAL.VAL_SCHEMA:

Node types | Validity outcome
 | VAL_TRUE | VAL_FALSE | VAL_UNKNOWN
Element | If the schema is a DTD, then element and attribute validity constraints, including attribute validity constraint defined below are satisfied. If the schema is an XML Schema, then PSVI [validity] valid. | Fails to satisfy the constraints defined. | If the schema is an XML Schema, then PSVI [validity] unknown.
Attr | If the schema is a DTD, then all validity constraints defined in section 3.3.1, "Attribute Type", required and fixed attribute are satisfied. If the schema is an XML Schema, then PSVI [validity] valid. | Fails to satisfy the constraints defined. | If the schema is an XML Schema, then PSVI [validity] unknown.
Text | The node is well-formed. | The node is not well-formed. | If no parent node is found.
CDATASection | The node is well-formed. | The node is not well-formed. | If no parent node is found.
ProcessingInstruction | The node is well-formed. | The node is not well-formed. | If no parent node is found.
Comment | The node is well-formed. | The node is not well-formed. | If no parent node is found.
EntityReference | Entity is declared. | Entity is not declared. | Not applicable.
Entity | Implementation-specific. | Implementation-specific. | Implementation-specific.
Notation | Implementation-specific. | Implementation-specific. | Implementation-specific.
DocumentType | Implementation-specific. | Implementation-specific. | Implementation-specific.
DocumentFragment | Not applicable. | Not applicable. | Not applicable.

A.2 Other validation operations

The table below describes validation outcomes from can* validation operations, such as NodeEditVAL.canRemoveChild(), or ElementEditVAL.canSetAttributeNS, CharacterDataEditVAL.canAppendData(). All these operations attempt to validate with validityType NodeEditVAL.VAL_INCOMPLETE.

VAL_TRUE | VAL_FALSE | VAL_UNKNOWN
If the associated operation is performed, then the node would be valid with regards to the VAL_INCOMPLETE definition or if there is no schema found. | If the associated operation is performed, then the node would be invalid with regards to the VAL_INCOMPLETE definition. | Not applicable.

Note: If the document includes more than one type of schema, e.g., DTD and XML Schema, and the DOMConfiguration "schema-type" parameter is not specified, the validation outcome for NodeEditVAL.VAL_INCOMPLETE and NodeEditVAL.VAL_SCHEMA is implementation-specific.


IDL Definitions

27 January 2004

Appendix B: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Validation definitions.

The IDL files are also available as: http://www.w3.org/TR/2004/REC-DOM-Level-3-Val-20040127/idl.zip

validation.idl:

// File: validation.idl

#ifndef _VALIDATION_IDL_
#define _VALIDATION_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module validation
{

  typedef dom::DOMString DOMString;
  typedef dom::DOMStringList DOMStringList;
  typedef dom::Node Node;
  typedef dom::NameList NameList;
  typedef dom::Attr Attr;
  typedef dom::DOMConfiguration DOMConfiguration;

  exception ExceptionVAL {
    unsigned short   code;
  };
  // ExceptionVALCode
  const unsigned short      NO_SCHEMA_AVAILABLE_ERR        = 71;

  interface NodeEditVAL {

    // validationType
    const unsigned short      VAL_WF                         = 1;
    const unsigned short      VAL_NS_WF                      = 2;
    const unsigned short      VAL_INCOMPLETE                 = 3;
    const unsigned short      VAL_SCHEMA                     = 4;

    // validationState
    const unsigned short      VAL_TRUE                       = 5;
    const unsigned short      VAL_FALSE                      = 6;
    const unsigned short      VAL_UNKNOWN                    = 7;

    readonly attribute DOMString       defaultValue;
    readonly attribute DOMStringList   enumeratedValues;
    unsigned short     canInsertBefore(in Node newChild,
                                       in Node refChild);
    unsigned short     canRemoveChild(in Node oldChild);
    unsigned short     canReplaceChild(in Node newChild,
                                       in Node oldChild);
    unsigned short     canAppendChild(in Node newChild);
    unsigned short     nodeValidity(in unsigned short valType);
  };

  interface ElementEditVAL : NodeEditVAL {

    // ContentTypeVAL
    const unsigned short      VAL_EMPTY_CONTENTTYPE          = 1;
    const unsigned short      VAL_ANY_CONTENTTYPE            = 2;
    const unsigned short      VAL_MIXED_CONTENTTYPE          = 3;
    const unsigned short      VAL_ELEMENTS_CONTENTTYPE       = 4;
    const unsigned short      VAL_SIMPLE_CONTENTTYPE         = 5;

    readonly attribute NameList        allowedChildren;
    readonly attribute NameList        allowedFirstChildren;
    readonly attribute NameList        allowedParents;
    readonly attribute NameList        allowedNextSiblings;
    readonly attribute NameList        allowedPreviousSiblings;
    readonly attribute NameList        allowedAttributes;
    readonly attribute NameList        requiredAttributes;
    readonly attribute unsigned short  contentType;
    unsigned short     canSetTextContent(in DOMString possibleTextContent);
    unsigned short     canSetAttribute(in DOMString attrname,
                                       in DOMString attrval);
    unsigned short     canSetAttributeNode(in Attr attrNode);
    unsigned short     canSetAttributeNS(in DOMString namespaceURI,
                                         in DOMString qualifiedName,
                                         in DOMString value);
    unsigned short     canRemoveAttribute(in DOMString attrname);
    unsigned short     canRemoveAttributeNS(in DOMString namespaceURI,
                                            in DOMString localName);
    unsigned short     canRemoveAttributeNode(in Node attrNode);
    unsigned short     isElementDefined(in DOMString name);
    unsigned short     isElementDefinedNS(in DOMString namespaceURI,
                                          in DOMString name);
  };

  interface CharacterDataEditVAL : NodeEditVAL {
    unsigned short     isWhitespaceOnly();
    unsigned short     canSetData(in DOMString arg);
    unsigned short     canAppendData(in DOMString arg);
    unsigned short     canReplaceData(in unsigned long offset,
                                      in unsigned long count,
                                      in DOMString arg)
                                        raises(dom::DOMException);
    unsigned short     canInsertData(in unsigned long offset,
                                     in DOMString arg)
                                        raises(dom::DOMException);
    unsigned short     canDeleteData(in unsigned long offset,
                                     in unsigned long count)
                                        raises(dom::DOMException);
  };

  interface DocumentEditVAL : NodeEditVAL {
             attribute boolean         continuousValidityChecking;
                                        // raises(dom::DOMException,
                                        //        ExceptionVAL,
                                        //        dom::DOMException) on setting

    readonly attribute DOMConfiguration domConfig;
    NameList           getDefinedElements(in DOMString namespaceURI);
    unsigned short     validateDocument();
  };
};

#endif // _VALIDATION_IDL_


Java Language Binding

27 January 2004

Appendix C: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Validation.

The Java files are also available as http://www.w3.org/TR/2004/REC-DOM-Level-3-Val-20040127/java-binding.zip

org/w3c/dom/validation/ExceptionVAL.java:

package org.w3c.dom.validation;

public class ExceptionVAL extends RuntimeException {
    public ExceptionVAL(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // ExceptionVALCode
    public static final short NO_SCHEMA_AVAILABLE_ERR   = 71;

}

org/w3c/dom/validation/DocumentEditVAL.java:

package org.w3c.dom.validation;

import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.DOMException;
import org.w3c.dom.NameList;

public interface DocumentEditVAL extends NodeEditVAL {
    public boolean getContinuousValidityChecking();
    public void setContinuousValidityChecking(boolean continuousValidityChecking)
 throws DOMException, ExceptionVAL, DOMException;

    public DOMConfiguration getDomConfig();

    public NameList getDefinedElements(String namespaceURI);

    public short validateDocument();

}

org/w3c/dom/validation/NodeEditVAL.java:

package org.w3c.dom.validation;

import org.w3c.dom.Node;
import org.w3c.dom.DOMStringList;

public interface NodeEditVAL {
    // validationType
    public static final short VAL_WF                    = 1;
    public static final short VAL_NS_WF                 = 2;
    public static final short VAL_INCOMPLETE            = 3;
    public static final short VAL_SCHEMA                = 4;

    // validationState
    public static final short VAL_TRUE                  = 5;
    public static final short VAL_FALSE                 = 6;
    public static final short VAL_UNKNOWN               = 7;

    public String getDefaultValue();

    public DOMStringList getEnumeratedValues();

    public short canInsertBefore(Node newChild,
                                 Node refChild);

    public short canRemoveChild(Node oldChild);

    public short canReplaceChild(Node newChild,
                                 Node oldChild);

    public short canAppendChild(Node newChild);

    public short nodeValidity(short valType);

}

org/w3c/dom/validation/ElementEditVAL.java:

package org.w3c.dom.validation;

import org.w3c.dom.Node;
import org.w3c.dom.Attr;
import org.w3c.dom.NameList;

public interface ElementEditVAL extends NodeEditVAL {
    // ContentTypeVAL
    public static final short VAL_EMPTY_CONTENTTYPE     = 1;
    public static final short VAL_ANY_CONTENTTYPE       = 2;
    public static final short VAL_MIXED_CONTENTTYPE     = 3;
    public static final short VAL_ELEMENTS_CONTENTTYPE  = 4;
    public static final short VAL_SIMPLE_CONTENTTYPE    = 5;

    public NameList getAllowedChildren();

    public NameList getAllowedFirstChildren();

    public NameList getAllowedParents();

    public NameList getAllowedNextSiblings();

    public NameList getAllowedPreviousSiblings();

    public NameList getAllowedAttributes();

    public NameList getRequiredAttributes();

    public short getContentType();

    public short canSetTextContent(String possibleTextContent);

    public short canSetAttribute(String attrname,
                                 String attrval);

    public short canSetAttributeNode(Attr attrNode);

    public short canSetAttributeNS(String namespaceURI,
                                   String qualifiedName,
                                   String value);

    public short canRemoveAttribute(String attrname);

    public short canRemoveAttributeNS(String namespaceURI,
                                      String localName);

    public short canRemoveAttributeNode(Node attrNode);

    public short isElementDefined(String name);

    public short isElementDefinedNS(String namespaceURI,
                                    String name);

}

org/w3c/dom/validation/CharacterDataEditVAL.java:

package org.w3c.dom.validation;

import org.w3c.dom.DOMException;

public interface CharacterDataEditVAL extends NodeEditVAL {
    public short isWhitespaceOnly();

    public short canSetData(String arg);

    public short canAppendData(String arg);

    public short canReplaceData(int offset,
                                int count,
                                String arg)
                                throws DOMException;

    public short canInsertData(int offset,
                               String arg)
                               throws DOMException;

    public short canDeleteData(int offset,
                               int count)
                               throws DOMException;

}


ECMAScript Language Binding

27 January 2004

Appendix D: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Validation definitions.

Properties of the ExceptionVAL Constructor function:
ExceptionVAL.NO_SCHEMA_AVAILABLE_ERR
The value of the constant ExceptionVAL.NO_SCHEMA_AVAILABLE_ERR is 71.
Objects that implement the ExceptionVAL interface:
Properties of objects that implement the ExceptionVAL interface:
code
This property is a Number.
Objects that implement the DocumentEditVAL interface:
Objects that implement the DocumentEditVAL interface have all properties and functions of the NodeEditVAL interface as well as the properties and functions defined below.
Properties of objects that implement the DocumentEditVAL interface:
continuousValidityChecking
This property is a Boolean and can raise an object that implements the DOMException interface or the ExceptionVAL interface or the DOMException interface on setting.
domConfig
This read-only property is an object that implements the DOMConfiguration interface.
Functions of objects that implement the DocumentEditVAL interface:
getDefinedElements(namespaceURI)
This function returns an object that implements the NameList interface.
The namespaceURI parameter is a String.
validateDocument()
This function returns a Number.
Properties of the NodeEditVAL Constructor function:
NodeEditVAL.VAL_WF
The value of the constant NodeEditVAL.VAL_WF is 1.
NodeEditVAL.VAL_NS_WF
The value of the constant NodeEditVAL.VAL_NS_WF is 2.
NodeEditVAL.VAL_INCOMPLETE
The value of the constant NodeEditVAL.VAL_INCOMPLETE is 3.
NodeEditVAL.VAL_SCHEMA
The value of the constant NodeEditVAL.VAL_SCHEMA is 4.
NodeEditVAL.VAL_TRUE
The value of the constant NodeEditVAL.VAL_TRUE is 5.
NodeEditVAL.VAL_FALSE
The value of the constant NodeEditVAL.VAL_FALSE is 6.
NodeEditVAL.VAL_UNKNOWN
The value of the constant NodeEditVAL.VAL_UNKNOWN is 7.
Objects that implement the NodeEditVAL interface:
Properties of objects that implement the NodeEditVAL interface:
defaultValue
This read-only property is a String.
enumeratedValues
This read-only property is an object that implements the DOMStringList interface.
Functions of objects that implement the NodeEditVAL interface:
canInsertBefore(newChild, refChild)
This function returns a Number.
The newChild parameter is an object that implements the Node interface.
The refChild parameter is an object that implements the Node interface.
canRemoveChild(oldChild)
This function returns a Number.
The oldChild parameter is an object that implements the Node interface.
canReplaceChild(newChild, oldChild)
This function returns a Number.
The newChild parameter is an object that implements the Node interface.
The oldChild parameter is an object that implements the Node interface.
canAppendChild(newChild)
This function returns a Number.
The newChild parameter is an object that implements the Node interface.
nodeValidity(valType)
This function returns a Number.
The valType parameter is a Number.
Properties of the ElementEditVAL Constructor function:
ElementEditVAL.VAL_EMPTY_CONTENTTYPE
The value of the constant ElementEditVAL.VAL_EMPTY_CONTENTTYPE is 1.
ElementEditVAL.VAL_ANY_CONTENTTYPE
The value of the constant ElementEditVAL.VAL_ANY_CONTENTTYPE is 2.
ElementEditVAL.VAL_MIXED_CONTENTTYPE
The value of the constant ElementEditVAL.VAL_MIXED_CONTENTTYPE is 3.
ElementEditVAL.VAL_ELEMENTS_CONTENTTYPE
The value of the constant ElementEditVAL.VAL_ELEMENTS_CONTENTTYPE is 4.
ElementEditVAL.VAL_SIMPLE_CONTENTTYPE
The value of the constant ElementEditVAL.VAL_SIMPLE_CONTENTTYPE is 5.
Objects that implement the ElementEditVAL interface:
Objects that implement the ElementEditVAL interface have all properties and functions of the NodeEditVAL interface as well as the properties and functions defined below.
Properties of objects that implement the ElementEditVAL interface:
allowedChildren
This read-only property is an object that implements the NameList interface.
allowedFirstChildren
This read-only property is an object that implements the NameList interface.
allowedParents
This read-only property is an object that implements the NameList interface.
allowedNextSiblings
This read-only property is an object that implements the NameList interface.
allowedPreviousSiblings
This read-only property is an object that implements the NameList interface.
allowedAttributes
This read-only property is an object that implements the NameList interface.
requiredAttributes
This read-only property is an object that implements the NameList interface.
contentType
This read-only property is a Number.
Functions of objects that implement the ElementEditVAL interface:
canSetTextContent(possibleTextContent)
This function returns a Number.
The possibleTextContent parameter is a String.
canSetAttribute(attrname, attrval)
This function returns a Number.
The attrname parameter is a String.
The attrval parameter is a String.
canSetAttributeNode(attrNode)
This function returns a Number.
The attrNode parameter is an object that implements the Attr interface.
canSetAttributeNS(namespaceURI, qualifiedName, value)
This function returns a Number.
The namespaceURI parameter is a String.
The qualifiedName parameter is a String.
The value parameter is a String.
canRemoveAttribute(attrname)
This function returns a Number.
The attrname parameter is a String.
canRemoveAttributeNS(namespaceURI, localName)
This function returns a Number.
The namespaceURI parameter is a String.
The localName parameter is a String.
canRemoveAttributeNode(attrNode)
This function returns a Number.
The attrNode parameter is an object that implements the Node interface.
isElementDefined(name)
This function returns a Number.
The name parameter is a String.
isElementDefinedNS(namespaceURI, name)
This function returns a Number.
The namespaceURI parameter is a String.
The name parameter is a String.
Objects that implement the CharacterDataEditVAL interface:
Objects that implement the CharacterDataEditVAL interface have all properties and functions of the NodeEditVAL interface as well as the properties and functions defined below.
Functions of objects that implement the CharacterDataEditVAL interface:
isWhitespaceOnly()
This function returns a Number.
canSetData(arg)
This function returns a Number.
The arg parameter is a String.
canAppendData(arg)
This function returns a Number.
The arg parameter is a String.
canReplaceData(offset, count, arg)
This function returns a Number.
The offset parameter is a Number.
The count parameter is a Number.
The arg parameter is a String.
This function can raise an object that implements the DOMException interface.
canInsertData(offset, arg)
This function returns a Number.
The offset parameter is a Number.
The arg parameter is a String.
This function can raise an object that implements the DOMException interface.
canDeleteData(offset, count)
This function returns a Number.
The offset parameter is a Number.
The count parameter is a Number.
This function can raise an object that implements the DOMException interface.


Acknowledgements

27 January 2004

Appendix E: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Clover, Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

Special thanks to the DOM Conformance Test Suites contributors: Curt Arnold, Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape).

E.1 Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

global declaration
A global declaration is a schema declaration, usually for an element or an attribute, that is available for use in content models throughout the schema, i.e. a declaration that is not bound to a particular context.
namespace well-formed
A node is a namespace well-formed XML node if it is a well-formed node, and follows the productions and namespace constraints. If [XML 1.0] is used, the constraints are defined in [XML Namespaces]. If [XML 1.1] is used, the constraints are defined in [XML Namespaces 1.1].
schema
A schema defines a set of structural and value constraints applicable to XML documents. Schemas can be expressed in schema languages, such as DTD, XML Schema, etc.
well-formed
A node is a well-formed XML node if its serialized form, without doing any transformation during its serialization, matches its respective production in [XML 1.0] or [XML 1.1] (depending on the XML version in use) with all well-formedness constraints related to that production, and if the entities which are referenced within the node are also well-formed. If namespaces for XML are in use, the node must also be namespace well-formed.


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

The references listed in this section are normatives.

[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, January 2004. This version of the Document Object Model Level 3 Core Specification is http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107. The latest version of DOM Level 3 Core is available at http://www.w3.org/TR/DOM-Level-3-Core.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML 1.1]
XML 1.1, T. Bray, and al., Editors. World Wide Web Consortium, November 2003. This version of the XML 1.1 Specification is http://www.w3.org/TR/2003/PR-xml11-20031105. The latest version of XML 1.1 is available at http://www.w3.org/TR/xml11.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[XML Namespaces 1.1]
Namespaces in XML 1.1, T. Bray, D. Hollander, A. Layman, and R. Tobin, Editors. World Wide Web Consortium, November 2003. This version of the XML Information Set Specification is http://www.w3.org/TR/2003/PR-xml-names11-20031105/. The latest version of Namespaces in XML is available at http://www.w3.org/TR/xml-names11/.


Index

allowedAttributes | allowedChildren | allowedFirstChildren
allowedNextSiblings | allowedParents | allowedPreviousSiblings
canAppendChild | canAppendData | canDeleteData
canInsertBefore | canInsertData | canRemoveAttribute
canRemoveAttributeNode | canRemoveAttributeNS | canRemoveChild
canReplaceChild | canReplaceData | canSetAttribute
canSetAttributeNode | canSetAttributeNS | canSetData
canSetTextContent | CharacterDataEditVAL | contentType
continuousValidityChecking
defaultValue | DocumentEditVAL | DOM Level 2 Core 1, 2
DOM Level 3 Core 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14 | domConfig
ECMAScript | ElementEditVAL | enumeratedValues
ExceptionVAL
getDefinedElements | global declaration 1, 2, 3, 4
isElementDefined | isElementDefinedNS | isWhitespaceOnly
Java
namespace well-formed 1, 2 | NO_SCHEMA_AVAILABLE_ERR | NodeEditVAL
nodeValidity
OMG IDL
requiredAttributes
schema 1, 2
VAL_ANY_CONTENTTYPE | VAL_ELEMENTS_CONTENTTYPE | VAL_EMPTY_CONTENTTYPE
VAL_FALSE | VAL_INCOMPLETE | VAL_MIXED_CONTENTTYPE
VAL_NS_WF | VAL_SCHEMA | VAL_SIMPLE_CONTENTTYPE
VAL_TRUE | VAL_UNKNOWN | VAL_WF
validateDocument
well-formed 1, 2
XML 1.0 1, 2, 3 | XML 1.1 1, 2, 3 | XML Namespaces 1, 2
XML Namespaces 1.1 1, 2


Document Object Model (DOM) Level 3 XPath Specification

Version 1.0

W3C Working Group Note 26 February 2004

This version:
http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226
Latest version:
http://www.w3.org/TR/DOM-Level-3-XPath
Previous version:
http://www.w3.org/TR/2003/CR-DOM-Level-3-XPath-20030331
Editor:
Ray Whitmer, Netscape/AOL, then Invited Expert

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

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

Abstract

This specification defines the Document Object Model Level 3 XPath. It provides simple functionalities to access a DOM tree using [XPath 1.0].

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 Working Group Note of "DOM Level 3 XPath" and is based on the feedback received during the Last Call period. The W3C DOM Working Group participants do not expect to provide two interoperable implementations of this module, using the same binding. Implementation feedbacks are however welcome and have to be sent to the public mailing list www-dom@w3.org (public archive). Other W3C Working Groups may continue the work and provide implementations of this document.

Individuals or organizations are also invited to send a message to the public mailing list if they intend to produce an implementation of this module.

Publication as a Working Group Note 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.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.

An implementation report is also available.

Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • 1. Document Object Model XPath
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • Glossary
  • References
  • Index


Document Object Model XPath

26 February 2004

1. Document Object Model XPath

Editor:
Ray Whitmer, Netscape/AOL

Table of contents

  • 1.1 Introduction
  • 1.2 Mapping DOM to XPath
    • 1.2.1 Element Nodes
    • 1.2.2 Attribute Nodes
    • 1.2.3 Namespace Nodes
    • 1.2.4 Text Nodes
    • 1.2.5 Entity Reference Nodes
    • 1.2.6 Comment Nodes
    • 1.2.7 Processing Instruction Nodes
    • 1.2.8 Document order
  • 1.3 Conformance
  • 1.4 Interfaces
    • XPathException, XPathExceptionCode, XPathEvaluator, XPathExpression, XPathNSResolver, XPathResult, XPathNamespace

1.1 Introduction

XPath 1.0 [XPath 1.0] is becoming an important part of a variety of many specifications including XForms, XPointer, XSL, XML Query, and so on. It is also a clear advantage for user applications which use DOM to be able to use XPath expressions to locate nodes automatically and declaratively.

This specification was created to map between the Document Object Model's representation of the W3C Information Set and XPath's model to permit XPath functions to be supplied and results returned within the framework of DOM APIs in a standard, interoperable way, allowing also for liveness of data, which is not addressed by the XPath specification but is present in results coming from the DOM hierarchy.

1.2 Mapping DOM to XPath

This section presents a mapping between the Document Object Model [DOM Level 2 Core] and the XPath 1.0 [XPath 1.0] model for the purposes of implementing the APIs.

1.2.1 Element Nodes

The DOM model uses Element nodes to represent Element Information Items. These nodes of a document are directly used to represent the elements of an XPath result.

1.2.2 Attribute Nodes

The DOM model uses Attr nodes to represent Attribute Information Items of attribute and namespace attribute properties of Element Information Item. These nodes have no parent, but have an ownerElement which can be used as XPath defines an attribute's parent.

XPath 1.0 does not make available the namespace attributes of an element. The DOM implementation of XPath 1.0 using these defined interfaces never directly returns Attr nodes of namespace attributes, but returned Element nodes still contain them.

1.2.3 Namespace Nodes

The XPath model expects namespace nodes for each in-scope namespace to be attached to each element. DOM only maintains the namespace attributes instead of replicating in-scope namespaces on each Element where they are in-scope. The DOM implementation of XPath produces a new node of type XPATH_NAMESPACE_NODE, defined in the XPathNamespace interface, to properly preserve identity and ordering in a way that is compatible with XPath. This node type is only visible using the XPath evaluation methods.

The set of in-scope namespaces of an element is the default xml namespace combined with the contributions of namespace attributes of the current and all ancestor elements. In addition to explicit namespace attributes, any element has an implicit declaration of its own prefix, if any, or if no prefix then of the default namespace, which is enforced during namespace serialization, fixup, and lookup, which must be added to the set of in-scope namespaces when generating namespace nodes for an element. This causes the set of namespace nodes to be consistent with serialization, fixup, and lookup of namespaces in DOM Level 3.

1.2.4 Text Nodes

The XPath model relies on the XML Information Set [XML Information Set] ands represents Character Information Items in a single logical text node where DOM may have multiple fragmented Text nodes due to cdata sections, entity references, etc. Instead of returning multiple nodes where XPath sees a single logical text node, only the first non-empty DOM Text or CDATASection node of any logical XPath text will be returned in the node set. Applications using XPath in an environment with fragmented text nodes must manually gather the text of a single logical text node possibly from multiple nodes beginning with the first Text node or CDATASection node returned by the implementation.

Note: In an attempt to better implement the XML Information Set, DOM Level 3 Core [DOM Level 3 Core] adds the attribute wholeText on the Text interface for retrieving the whole text for logically-adjacent Text nodes and the method replaceWholeText for replacing those nodes.

1.2.5 Entity Reference Nodes

The DOM model may represent Unexpanded Entity Reference Information Items or may provide the position and URI of expanded entity hierarchies by using EntityReference nodes. XPath 1.0 does not preserve corresponding information.

Where the node represents an unexpanded entity reference, it is skipped as dictated by the XPath specifications for all infoset items besides those specifically processed.

Where there is a hierarchy underneath the node, these nodes are processed as though they were siblings of the entity reference, as is consistent with the rest of the DOM specification.

EntityReference nodes found within a DOM hierarchy are never returned as a node of the result, but returned nodes may contain or be contained within an EntityReference node. Text may be split partially inside and partially outside of an EntityReference node, but this is solved by handling Text nodes as described in the previous section.

1.2.6 Comment Nodes

The DOM model uses Comment nodes to represent Comment Information Items. These nodes of a document are directly used to represent the comments of an XPath result.

1.2.7 Processing Instruction Nodes

The DOM model uses ProcessingInstruction nodes to represent Processing Instruction Information Items. These nodes of a document are directly used to represent the processing instructions of an XPath result.

1.2.8 Document order

The document order of nodes in the DOM Core has been defined to be compatible with the XPath document order. The XPath DOM extends the document order of the DOM Core to include the XPathNamespace nodes. Element nodes occur before their children. The attribute nodes and namespace nodes of an element occur before the children of the element. The namespace nodes are defined to occur before the attribute nodes. The relative order of namespace nodes is implementation-dependent. The relative order of attribute nodes is implementation-dependent. The compareTreePosition method on the Node interface defined in the DOM Core must compare the XPathNamespace nodes using this extended document order if the XPath DOM module is supported.

Note: It is possible that in future versions of XPath, the order of namespace nodes or other aspects of document order may change incompatibly.

1.3 Conformance

This section explains conformance to DOM Level 3 XPath Module.

A DOM implementation must not return true to hasFeature("xpath", "3.0") unless the implementation conforms to that module. As documented in [DOM Level 3 Core], if a null or empty string is passed in for the second parameter, then conformance is still required to some version of the DOM XPath Module or false must be returned.

A conformant implementation is DOM Level 3 XPath must support all the interfaces as specified in that specification. In addition to implementing the interfaces in the DOM XPath Module, a conforming implementation must correctly implement each part of the XPath 1.0 specification when evaluating expressions including Location Paths, Expressions, the Core Function Library, and the mapping between DOM and the XPath 1.0 data model described in the DOM Level 3 XPath Module. The XPath id()function must return the corresponding element, if any, returned by the DOM method Document.getElementById.

After meeting the requirements for conformance, a conforming implementation may implement additional functions and variables. Applications which evaluate expressions using these extensions will not necessarily be portable to other implementations of the DOM Level 3 XPath Module.

1.4 Interfaces

An implementation is DOM Level 3 XPath conformant if it supports the Core module defined in [DOM Level 2 Core] and the module defined in this specification. An implementation conforms to a DOM module if it supports all the interfaces for that module and the associated semantics.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "XPath" and "3.0" (respectively) to determine whether or not the XPath module is supported by the implementation. In order to fully support this module, an implementation must also support the "Core" feature defined in the DOM Level 2 Core specification [DOM Level 2 Core].

A DOM implementation must not return true to the hasFeature(feature, version) method of the DOMImplementation interface for that feature unless the implementation conforms to that module. The version number for the feature used in this document is "3.0".

Exception XPathException

A new exception has been created for exceptions specific to these XPath interfaces.

IDL Definition
exception XPathException {
  unsigned short   code;
};
// XPathExceptionCode
const unsigned short      INVALID_EXPRESSION_ERR         = 51;
const unsigned short      TYPE_ERR                       = 52;

Definition group XPathExceptionCode
Defined Constants
INVALID_EXPRESSION_ERR
If the expression has a syntax error or otherwise is not a legal expression according to the rules of the specific XPathEvaluator or contains specialized extension functions or variables not supported by this implementation.
TYPE_ERR
If the expression cannot be converted to return the specified type.
Interface XPathEvaluator

The evaluation of XPath expressions is provided by XPathEvaluator. In a DOM implementation which supports the XPath 3.0 feature, as described above, the XPathEvaluator interface will be implemented on the same object which implements the Document interface permitting it to be obtained by the usual binding-specific method such as casting or by using the DOM Level 3 getInterface method. In this case the implementation obtained from the Document supports the XPath DOM module and is compatible with the XPath 1.0 specification.

Evaluation of expressions with specialized extension functions or variables may not work in all implementations and is, therefore, not portable. XPathEvaluator implementations may be available from other sources that could provide specific support for specialized extension functions or variables as would be defined by other specifications.

IDL Definition
interface XPathEvaluator {
  XPathExpression    createExpression(in DOMString expression,
                                      in XPathNSResolver resolver)
                                        raises(XPathException,
                                               DOMException);
  XPathNSResolver    createNSResolver(in Node nodeResolver);
  DOMObject          evaluate(in DOMString expression,
                              in Node contextNode,
                              in XPathNSResolver resolver,
                              in unsigned short type,
                              in DOMObject result)
                                        raises(XPathException,
                                               DOMException);
};

Methods
createExpression
Creates a parsed XPath expression with resolved namespaces. This is useful when an expression will be reused in an application since it makes it possible to compile the expression string into a more efficient internal form and preresolve all namespace prefixes which occur within the expression.
Parameters
expression of type DOMString
The XPath expression string to be parsed.
resolver of type XPathNSResolver
The resolver permits translation of all prefixes, including the xml namespace prefix, within the XPath expression into appropriate namespace URIs. If this is specified as null, any namespace prefix within the expression will result in DOMException being thrown with the code NAMESPACE_ERR.
Return Value

XPathExpression

The compiled form of the XPath expression.

Exceptions

XPathException

INVALID_EXPRESSION_ERR: Raised if the expression is not legal according to the rules of the XPathEvaluator.

DOMException

NAMESPACE_ERR: Raised if the expression contains namespace prefixes which cannot be resolved by the specified XPathNSResolver.

createNSResolver
Adapts any DOM node to resolve namespaces so that an XPath expression can be easily evaluated relative to the context of the node where it appeared within the document. This adapter works like the DOM Level 3 method lookupNamespaceURI on nodes in resolving the namespaceURI from a given prefix using the current information available in the node's hierarchy at the time lookupNamespaceURI is called. also correctly resolving the implicit xml prefix.
Parameters
nodeResolver of type Node
The node to be used as a context for namespace resolution.
Return Value

XPathNSResolver

XPathNSResolver which resolves namespaces with respect to the definitions in scope for a specified node.

No Exceptions
evaluate
Evaluates an XPath expression string and returns a result of the specified type if possible.
Parameters
expression of type DOMString
The XPath expression string to be parsed and evaluated.
contextNode of type Node
The context is context node for the evaluation of this XPath expression. If the XPathEvaluator was obtained by casting the Document then this must be owned by the same document and must be a Document, Element, Attribute, Text, CDATASection, Comment, ProcessingInstruction, or XPathNamespace node. If the context node is a Text or a CDATASection, then the context is interpreted as the whole logical text node as seen by XPath, unless the node is empty in which case it may not serve as the XPath context.
resolver of type XPathNSResolver
The resolver permits translation of all prefixes, including the xml namespace prefix, within the XPath expression into appropriate namespace URIs. If this is specified as null, any namespace prefix within the expression will result in DOMException being thrown with the code NAMESPACE_ERR.
type of type unsigned short
If a specific type is specified, then the result will be returned as the corresponding type.
For XPath 1.0 results, this must be one of the codes of the XPathResult interface.
result of type DOMObject
The result specifies a specific result object which may be reused and returned by this method. If this is specified as nullor the implementation does not reuse the specified result, a new result object will be constructed and returned.
For XPath 1.0 results, this object will be of type XPathResult.
Return Value

DOMObject

The result of the evaluation of the XPath expression.
For XPath 1.0 results, this object will be of type XPathResult.

Exceptions

XPathException

INVALID_EXPRESSION_ERR: Raised if the expression is not legal according to the rules of the XPathEvaluatori

TYPE_ERR: Raised if the result cannot be converted to return the specified type.

DOMException

NAMESPACE_ERR: Raised if the expression contains namespace prefixes which cannot be resolved by the specified XPathNSResolver.

WRONG_DOCUMENT_ERR: The Node is from a document that is not supported by this XPathEvaluator.

NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath context node or the request type is not permitted by this XPathEvaluator.

Interface XPathExpression

The XPathExpression interface represents a parsed and resolved XPath expression.

IDL Definition
interface XPathExpression {
  DOMObject          evaluate(in Node contextNode,
                              in unsigned short type,
                              in DOMObject result)
                                        raises(XPathException,
                                               DOMException);
};

Methods
evaluate
Evaluates this XPath expression and returns a result.
Parameters
contextNode of type Node
The context is context node for the evaluation of this XPath expression.
If the XPathEvaluator was obtained by casting the Document then this must be owned by the same document and must be a Document, Element, Attribute, Text, CDATASection, Comment, ProcessingInstruction, or XPathNamespace node.
If the context node is a Text or a CDATASection, then the context is interpreted as the whole logical text node as seen by XPath, unless the node is empty in which case it may not serve as the XPath context.
type of type unsigned short
If a specific type is specified, then the result will be coerced to return the specified type relying on XPath conversions and fail if the desired coercion is not possible. This must be one of the type codes of XPathResult.
result of type DOMObject
The result specifies a specific result object which may be reused and returned by this method. If this is specified as nullor the implementation does not reuse the specified result, a new result object will be constructed and returned.
For XPath 1.0 results, this object will be of type XPathResult.
Return Value

DOMObject

The result of the evaluation of the XPath expression.
For XPath 1.0 results, this object will be of type XPathResult.

Exceptions

XPathException

TYPE_ERR: Raised if the result cannot be converted to return the specified type.

DOMException

WRONG_DOCUMENT_ERR: The Node is from a document that is not supported by the XPathEvaluator that created this XPathExpression.

NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath context node or the request type is not permitted by this XPathExpression.

Interface XPathNSResolver

The XPathNSResolver interface permit prefix strings in the expression to be properly bound to namespaceURI strings. XPathEvaluator can construct an implementation of XPathNSResolver from a node, or the interface may be implemented by any application.

IDL Definition
interface XPathNSResolver {
  DOMString          lookupNamespaceURI(in DOMString prefix);
};

Methods
lookupNamespaceURI
Look up the namespace URI associated to the given namespace prefix. The XPath evaluator must never call this with a null or empty argument, because the result of doing this is undefined.
Parameters
prefix of type DOMString
The prefix to look for.
Return Value

DOMString

Returns the associated namespace URI or null if none is found.

No Exceptions
Interface XPathResult

The XPathResult interface represents the result of the evaluation of an XPath 1.0 expression within the context of a particular node. Since evaluation of an XPath expression can result in various result types, this object makes it possible to discover and manipulate the type and value of the result.

IDL Definition
interface XPathResult {

  // XPathResultType
  const unsigned short      ANY_TYPE                       = 0;
  const unsigned short      NUMBER_TYPE                    = 1;
  const unsigned short      STRING_TYPE                    = 2;
  const unsigned short      BOOLEAN_TYPE                   = 3;
  const unsigned short      UNORDERED_NODE_ITERATOR_TYPE   = 4;
  const unsigned short      ORDERED_NODE_ITERATOR_TYPE     = 5;
  const unsigned short      UNORDERED_NODE_SNAPSHOT_TYPE   = 6;
  const unsigned short      ORDERED_NODE_SNAPSHOT_TYPE     = 7;
  const unsigned short      ANY_UNORDERED_NODE_TYPE        = 8;
  const unsigned short      FIRST_ORDERED_NODE_TYPE        = 9;

  readonly attribute unsigned short  resultType;
  readonly attribute double          numberValue;
                                        // raises(XPathException) on retrieval

  readonly attribute DOMString       stringValue;
                                        // raises(XPathException) on retrieval

  readonly attribute boolean         booleanValue;
                                        // raises(XPathException) on retrieval

  readonly attribute Node            singleNodeValue;
                                        // raises(XPathException) on retrieval

  readonly attribute boolean         invalidIteratorState;
  readonly attribute unsigned long   snapshotLength;
                                        // raises(XPathException) on retrieval

  Node               iterateNext()
                                        raises(XPathException,
                                               DOMException);
  Node               snapshotItem(in unsigned long index)
                                        raises(XPathException);
};

Definition group XPathResultType

An integer indicating what type of result this is.

If a specific type is specified, then the result will be returned as the corresponding type, using XPath type conversions where required and possible.

Defined Constants
ANY_TYPE
This code does not represent a specific type. An evaluation of an XPath expression will never produce this type. If this type is requested, then the evaluation returns whatever type naturally results from evaluation of the expression.
If the natural result is a node set when ANY_TYPE was requested, then UNORDERED_NODE_ITERATOR_TYPE is always the resulting type. Any other representation of a node set must be explicitly requested.
ANY_UNORDERED_NODE_TYPE
The result is a node set as defined by [XPath 1.0] and will be accessed as a single node, which may be nullif the node set is empty. Document modification does not invalidate the node, but may mean that the result node no longer corresponds to the current document. This is a convenience that permits optimization since the implementation can stop once any node in the resulting set has been found.
If there is more than one node in the actual result, the single node returned might not be the first in document order.
BOOLEAN_TYPE
The result is a boolean as defined by [XPath 1.0]. Document modification does not invalidate the boolean, but may mean that reevaluation would not yield the same boolean.
FIRST_ORDERED_NODE_TYPE
The result is a node set as defined by [XPath 1.0] and will be accessed as a single node, which may be null if the node set is empty. Document modification does not invalidate the node, but may mean that the result node no longer corresponds to the current document. This is a convenience that permits optimization since the implementation can stop once the first node in document order of the resulting set has been found.
If there are more than one node in the actual result, the single node returned will be the first in document order.
NUMBER_TYPE
The result is a number as defined by [XPath 1.0]. Document modification does not invalidate the number, but may mean that reevaluation would not yield the same number.
ORDERED_NODE_ITERATOR_TYPE
The result is a node set as defined by [XPath 1.0] that will be accessed iteratively, which will produce document-ordered nodes. Document modification invalidates the iteration.
ORDERED_NODE_SNAPSHOT_TYPE
The result is a node set as defined by [XPath 1.0] that will be accessed as a snapshot list of nodes that will be in original document order. Document modification does not invalidate the snapshot but may mean that reevaluation would not yield the same snapshot and nodes in the snapshot may have been altered, moved, or removed from the document.
STRING_TYPE
The result is a string as defined by [XPath 1.0]. Document modification does not invalidate the string, but may mean that the string no longer corresponds to the current document.
UNORDERED_NODE_ITERATOR_TYPE
The result is a node set as defined by [XPath 1.0] that will be accessed iteratively, which may not produce nodes in a particular order. Document modification invalidates the iteration.
This is the default type returned if the result is a node set and ANY_TYPE is requested.
UNORDERED_NODE_SNAPSHOT_TYPE
The result is a node set as defined by [XPath 1.0] that will be accessed as a snapshot list of nodes that may not be in a particular order. Document modification does not invalidate the snapshot but may mean that reevaluation would not yield the same snapshot and nodes in the snapshot may have been altered, moved, or removed from the document.
Attributes
booleanValue of type boolean, readonly
The value of this boolean result.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not BOOLEAN_TYPE.

invalidIteratorState of type boolean, readonly
Signifies that the iterator has become invalid. True if resultType is UNORDERED_NODE_ITERATOR_TYPE or ORDERED_NODE_ITERATOR_TYPE and the document has been modified since this result was returned.
numberValue of type double, readonly
The value of this number result. If the native double type of the DOM binding does not directly support the exact IEEE 754 result of the XPath expression, then it is up to the definition of the binding to specify how the XPath number is converted to the native binding number.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not NUMBER_TYPE.

resultType of type unsigned short, readonly
A code representing the type of this result, as defined by the type constants.
singleNodeValue of type Node, readonly
The value of this single node result, which may be null.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not ANY_UNORDERED_NODE_TYPE or FIRST_ORDERED_NODE_TYPE.

snapshotLength of type unsigned long, readonly
The number of nodes in the result snapshot. Valid values for snapshotItem indices are 0 to snapshotLength-1 inclusive.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_SNAPSHOT_TYPE.

stringValue of type DOMString, readonly
The value of this string result.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not STRING_TYPE.

Methods
iterateNext
Iterates and returns the next node from the node set or nullif there are no more nodes.
Return Value

Node

Returns the next node.

Exceptions

XPathException

TYPE_ERR: raised if resultType is not UNORDERED_NODE_ITERATOR_TYPE or ORDERED_NODE_ITERATOR_TYPE.

DOMException

INVALID_STATE_ERR: The document has been mutated since the result was returned.

No Parameters
snapshotItem
Returns the indexth item in the snapshot collection. If index is greater than or equal to the number of nodes in the list, this method returns null. Unlike the iterator result, the snapshot does not become invalid, but may not correspond to the current document if it is mutated.
Parameters
index of type unsigned long
Index into the snapshot collection.
Return Value

Node

The node at the indexth position in the NodeList, or null if that is not a valid index.

Exceptions

XPathException

TYPE_ERR: raised if resultType is not UNORDERED_NODE_SNAPSHOT_TYPE or ORDERED_NODE_SNAPSHOT_TYPE.

Interface XPathNamespace

The XPathNamespace interface is returned by XPathResult interfaces to represent the XPath namespace node type that DOM lacks. There is no public constructor for this node type. Attempts to place it into a hierarchy or a NamedNodeMap result in a DOMException with the code HIERARCHY_REQUEST_ERR. This node is read only, so methods or setting of attributes that would mutate the node result in a DOMException with the code NO_MODIFICATION_ALLOWED_ERR.

The core specification describes attributes of the Node interface that are different for different node types but does not describe XPATH_NAMESPACE_NODE, so here is a description of those attributes for this node type. All attributes of Node not described in this section have a null or false value.

ownerDocument matches the ownerDocument of the ownerElement even if the element is later adopted.

nodeName is always the string "#namespace".

prefix is the prefix of the namespace represented by the node.

localName is the same as prefix.

nodeType is equal to XPATH_NAMESPACE_NODE.

namespaceURI is the namespace URI of the namespace represented by the node.

nodeValue is the same as namespaceURI.

adoptNode, cloneNode, and importNode fail on this node type by raising a DOMException with the code NOT_SUPPORTED_ERR.

Note: In future versions of the XPath specification, the definition of a namespace node may be changed incomatibly, in which case incompatible changes to field values may be required to implement versions beyond XPath 1.0.

IDL Definition
interface XPathNamespace : Node {

  // XPathNodeType
  const unsigned short      XPATH_NAMESPACE_NODE           = 13;

  readonly attribute Element         ownerElement;
};

Definition group XPathNodeType

An integer indicating which type of node this is.

Note: There is currently only one type of node which is specific to XPath. The numbers in this list must not collide with the values assigned to core node types.

Defined Constants
XPATH_NAMESPACE_NODE
The node is a Namespace.
Attributes
ownerElement of type Element, readonly
The Element on which the namespace was in scope when it was requested. This does not change on a returned namespace node even if the document changes such that the namespace goes out of scope on that element and this node is no longer found there by XPath.


IDL Definitions

26 February 2004

Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model XPath definitions.

The IDL files are also available as: http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226/idl.zip

xpath.idl:

// File: xpath.idl

#ifndef _XPATH_IDL_
#define _XPATH_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module xpath
{

  typedef dom::DOMString DOMString;
  typedef dom::Node Node;
  typedef dom::DOMObject DOMObject;
  typedef dom::Element Element;

  interface XPathNSResolver;
  interface XPathExpression;

  exception XPathException {
    unsigned short   code;
  };
  // XPathExceptionCode
  const unsigned short      INVALID_EXPRESSION_ERR         = 51;
  const unsigned short      TYPE_ERR                       = 52;

  interface XPathEvaluator {
    XPathExpression    createExpression(in DOMString expression,
                                        in XPathNSResolver resolver)
                                        raises(XPathException,
                                               dom::DOMException);
    XPathNSResolver    createNSResolver(in Node nodeResolver);
    DOMObject          evaluate(in DOMString expression,
                                in Node contextNode,
                                in XPathNSResolver resolver,
                                in unsigned short type,
                                in DOMObject result)
                                        raises(XPathException,
                                               dom::DOMException);
  };

  interface XPathExpression {
    DOMObject          evaluate(in Node contextNode,
                                in unsigned short type,
                                in DOMObject result)
                                        raises(XPathException,
                                               dom::DOMException);
  };

  interface XPathNSResolver {
    DOMString          lookupNamespaceURI(in DOMString prefix);
  };

  interface XPathResult {

    // XPathResultType
    const unsigned short      ANY_TYPE                       = 0;
    const unsigned short      NUMBER_TYPE                    = 1;
    const unsigned short      STRING_TYPE                    = 2;
    const unsigned short      BOOLEAN_TYPE                   = 3;
    const unsigned short      UNORDERED_NODE_ITERATOR_TYPE   = 4;
    const unsigned short      ORDERED_NODE_ITERATOR_TYPE     = 5;
    const unsigned short      UNORDERED_NODE_SNAPSHOT_TYPE   = 6;
    const unsigned short      ORDERED_NODE_SNAPSHOT_TYPE     = 7;
    const unsigned short      ANY_UNORDERED_NODE_TYPE        = 8;
    const unsigned short      FIRST_ORDERED_NODE_TYPE        = 9;

    readonly attribute unsigned short  resultType;
    readonly attribute double          numberValue;
                                        // raises(XPathException) on retrieval

    readonly attribute DOMString       stringValue;
                                        // raises(XPathException) on retrieval

    readonly attribute boolean         booleanValue;
                                        // raises(XPathException) on retrieval

    readonly attribute Node            singleNodeValue;
                                        // raises(XPathException) on retrieval

    readonly attribute boolean         invalidIteratorState;
    readonly attribute unsigned long   snapshotLength;
                                        // raises(XPathException) on retrieval

    Node               iterateNext()
                                        raises(XPathException,
                                               dom::DOMException);
    Node               snapshotItem(in unsigned long index)
                                        raises(XPathException);
  };

  interface XPathNamespace : Node {

    // XPathNodeType
    const unsigned short      XPATH_NAMESPACE_NODE           = 13;

    readonly attribute Element         ownerElement;
  };
};

#endif // _XPATH_IDL_


Java Language Binding

26 February 2004

Appendix B: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model XPath.

The Java files are also available as http://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226/java-binding.zip

B.1 Other XPath interfaces

org/w3c/dom/xpath/XPathException.java:

package org.w3c.dom.xpath;

public class XPathException extends RuntimeException {
    public XPathException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // XPathExceptionCode
    public static final short INVALID_EXPRESSION_ERR    = 51;
    public static final short TYPE_ERR                  = 52;

}

org/w3c/dom/xpath/XPathEvaluator.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface XPathEvaluator {
    public XPathExpression createExpression(String expression,
                                            XPathNSResolver resolver)
                                            throws XPathException, DOMException;

    public XPathNSResolver createNSResolver(Node nodeResolver);

    public Object evaluate(String expression,
                           Node contextNode,
                           XPathNSResolver resolver,
                           short type,
                           Object result)
                           throws XPathException, DOMException;

}

org/w3c/dom/xpath/XPathExpression.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface XPathExpression {
    public Object evaluate(Node contextNode,
                           short type,
                           Object result)
                           throws XPathException, DOMException;

}

org/w3c/dom/xpath/XPathNSResolver.java:

package org.w3c.dom.xpath;

public interface XPathNSResolver {
    public String lookupNamespaceURI(String prefix);

}

org/w3c/dom/xpath/XPathResult.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface XPathResult {
    // XPathResultType
    public static final short ANY_TYPE                  = 0;
    public static final short NUMBER_TYPE               = 1;
    public static final short STRING_TYPE               = 2;
    public static final short BOOLEAN_TYPE              = 3;
    public static final short UNORDERED_NODE_ITERATOR_TYPE = 4;
    public static final short ORDERED_NODE_ITERATOR_TYPE = 5;
    public static final short UNORDERED_NODE_SNAPSHOT_TYPE = 6;
    public static final short ORDERED_NODE_SNAPSHOT_TYPE = 7;
    public static final short ANY_UNORDERED_NODE_TYPE   = 8;
    public static final short FIRST_ORDERED_NODE_TYPE   = 9;

    public short getResultType();

    public double getNumberValue()
                                     throws XPathException;

    public String getStringValue()
                                     throws XPathException;

    public boolean getBooleanValue()
                                     throws XPathException;

    public Node getSingleNodeValue()
                                     throws XPathException;

    public boolean getInvalidIteratorState();

    public int getSnapshotLength()
                                     throws XPathException;

    public Node iterateNext()
                            throws XPathException, DOMException;

    public Node snapshotItem(int index)
                             throws XPathException;

}

org/w3c/dom/xpath/XPathNamespace.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Element;
import org.w3c.dom.Node;

public interface XPathNamespace extends Node {
    // XPathNodeType
    public static final short XPATH_NAMESPACE_NODE      = 13;

    public Element getOwnerElement();

}


ECMAScript Language Binding

26 February 2004

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model XPath definitions.

Properties of the XPathException Constructor function:
XPathException.INVALID_EXPRESSION_ERR
The value of the constant XPathException.INVALID_EXPRESSION_ERR is 51.
XPathException.TYPE_ERR
The value of the constant XPathException.TYPE_ERR is 52.
Objects that implement the XPathException interface:
Properties of objects that implement the XPathException interface:
code
This property is a Number.
Objects that implement the XPathEvaluator interface:
Functions of objects that implement the XPathEvaluator interface:
createExpression(expression, resolver)
This function returns an object that implements the XPathExpression interface.
The expression parameter is a String.
The resolver parameter is an object that implements the XPathNSResolver interface.
This function can raise an object that implements the XPathException interface or the DOMException interface.
createNSResolver(nodeResolver)
This function returns an object that implements the XPathNSResolver interface.
The nodeResolver parameter is an object that implements the Node interface.
evaluate(expression, contextNode, resolver, type, result)
This function returns an object that implements the Object interface.
The expression parameter is a String.
The contextNode parameter is an object that implements the Node interface.
The resolver parameter is an object that implements the XPathNSResolver interface.
The type parameter is a Number.
The result parameter is an object that implements the Object interface.
This function can raise an object that implements the XPathException interface or the DOMException interface.
Objects that implement the XPathExpression interface:
Functions of objects that implement the XPathExpression interface:
evaluate(contextNode, type, result)
This function returns an object that implements the Object interface.
The contextNode parameter is an object that implements the Node interface.
The type parameter is a Number.
The result parameter is an object that implements the Object interface.
This function can raise an object that implements the XPathException interface or the DOMException interface.
Objects that implement the XPathNSResolver interface:
Functions of objects that implement the XPathNSResolver interface:
lookupNamespaceURI(prefix)
This function returns a String.
The prefix parameter is a String.
Properties of the XPathResult Constructor function:
XPathResult.ANY_TYPE
The value of the constant XPathResult.ANY_TYPE is 0.
XPathResult.NUMBER_TYPE
The value of the constant XPathResult.NUMBER_TYPE is 1.
XPathResult.STRING_TYPE
The value of the constant XPathResult.STRING_TYPE is 2.
XPathResult.BOOLEAN_TYPE
The value of the constant XPathResult.BOOLEAN_TYPE is 3.
XPathResult.UNORDERED_NODE_ITERATOR_TYPE
The value of the constant XPathResult.UNORDERED_NODE_ITERATOR_TYPE is 4.
XPathResult.ORDERED_NODE_ITERATOR_TYPE
The value of the constant XPathResult.ORDERED_NODE_ITERATOR_TYPE is 5.
XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE
The value of the constant XPathResult.UNORDERED_NODE_SNAPSHOT_TYPE is 6.
XPathResult.ORDERED_NODE_SNAPSHOT_TYPE
The value of the constant XPathResult.ORDERED_NODE_SNAPSHOT_TYPE is 7.
XPathResult.ANY_UNORDERED_NODE_TYPE
The value of the constant XPathResult.ANY_UNORDERED_NODE_TYPE is 8.
XPathResult.FIRST_ORDERED_NODE_TYPE
The value of the constant XPathResult.FIRST_ORDERED_NODE_TYPE is 9.
Objects that implement the XPathResult interface:
Properties of objects that implement the XPathResult interface:
resultType
This read-only property is a Number.
numberValue
This read-only property is a Number and can raise an object that implements the XPathException interface on retrieval.
stringValue
This read-only property is a String and can raise an object that implements the XPathException interface on retrieval.
booleanValue
This read-only property is a Boolean and can raise an object that implements the XPathException interface on retrieval.
singleNodeValue
This read-only property is an object that implements the Node interface and can raise an object that implements the XPathException interface on retrieval.
invalidIteratorState
This read-only property is a Boolean.
snapshotLength
This read-only property is a Number and can raise an object that implements the XPathException interface on retrieval.
Functions of objects that implement the XPathResult interface:
iterateNext()
This function returns an object that implements the Node interface.
This function can raise an object that implements the XPathException interface or the DOMException interface.
snapshotItem(index)
This function returns an object that implements the Node interface.
The index parameter is a Number.
This function can raise an object that implements the XPathException interface.
Properties of the XPathNamespace Constructor function:
XPathNamespace.XPATH_NAMESPACE_NODE
The value of the constant XPathNamespace.XPATH_NAMESPACE_NODE is 13.
Objects that implement the XPathNamespace interface:
Objects that implement the XPathNamespace interface have all properties and functions of the Node interface as well as the properties and functions defined below.
Properties of objects that implement the XPathNamespace interface:
ownerElement
This read-only property is an object that implements the Element interface.

Note: The parameter resolver of the method XPathEvaluator.evaluate is specified as an object that implements the XPathNSResolver interface. ECMAScript users can also pass to this method a function which returns a String and takes a String parameter instead of the resolver parameter.


Acknowledgements

26 February 2004

Appendix D: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Clover, Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

Special thanks to the DOM Conformance Test Suites contributors: Curt Arnold, Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape).

D.1 Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

API
An API is an Application Programming Interface, a set of functions or methods used to access some functionality.
document element
There is only one document element in a Document. This element node is a child of the Document node. See Well-Formed XML Documents in XML [XML 1.0].
document order
There is an ordering, document order, defined on all the nodes in the document corresponding to the order in which the first character of the XML representation of each node occurs in the XML representation of the document after expansion of general entities. Thus, the document element node will be the first node. Element nodes occur before their children. Thus, document order orders element nodes in order of the occurrence of their start-tag in the XML (after expansion of entities). The attribute nodes of an element occur after the element and before its children. The relative order of attribute nodes is implementation-dependent.
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. See Logical Structures in XML [XML 1.0].
logically-adjacent text nodes
Logically-adjacent text nodes are Text or CDATASection nodes that can be visited sequentially in document order or in reversed document order without entering, exiting, or passing over Element, Comment, or ProcessingInstruction nodes.
live
An object is live if any change to the underlying document structure is reflected in the object.
model
A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else.
namespace prefix
A namespace prefix is a string that associates an element or attribute name with a namespace URI in XML. See namespace prefix in Namespaces in XML [XML Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in Namespaces in XML [XML Namespaces]. See also sections 1.3.2 "DOM URIs" and 1.3.3 "XML Namespaces" regarding URIs and namespace URIs handling and comparison in the DOM APIs.
read only node
A read only node is a node that is immutable. This means its list of children, its content, and its attributes, when it is an element, cannot be changed in any way. However, a read only node can possibly be moved, when it is not itself contained in a read only node.


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

F.1 Normative references

[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[XML Information Set]
XML Information Set (Second Edition), J. Cowan and R. Tobin, Editors. World Wide Web Consortium, 4 February 2004, revised 24 October 2001. This version of the XML Information Set Recommendation is http://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version of XML Information Set is available at http://www.w3.org/TR/xml-infoset.
[XPath 1.0]
XML Path Language (XPath) Version 1.0, J. Clark and S. DeRose, Editors. World Wide Web Consortium, 16 November 1999. This version of the XPath 1.0 Recommendation is http://www.w3.org/TR/1999/REC-xpath-19991116. The latest version of XPath 1.0 is available at http://www.w3.org/TR/xpath.

F.2 Informative references

[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, February 2004. This version of the Document Object Model Level 3 Core specification is http://www.w3.org/TR/2004/PR-DOM-Level-3-Core-20040205. The latest version of DOM Level 3 Core is available at http://www.w3.org/TR/DOM-Level-3-Core.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Third Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, E. Maler, and F. Yergeau, Editors. World Wide Web Consortium, 4 February 2004, revised 10 February 1998 and 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2004/REC-xml-20040204. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the Namespaces in XML Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.


Index

ANY_TYPE ANY_UNORDERED_NODE_TYPE API 1, 2
BOOLEAN_TYPE booleanValue
createExpression createNSResolver
document element document order 1, 2 DOM Level 2 Core 1, 2, 3
DOM Level 3 Core 1, 2, 3
ECMAScript element 1, 2, 3 evaluate 1, 2
FIRST_ORDERED_NODE_TYPE
INVALID_EXPRESSION_ERR invalidIteratorState iterateNext
Java
live 1, 2 logically-adjacent text nodes 1, 2 lookupNamespaceURI
model 1, 2
namespace prefix 1, 2, 3, 4 namespace URI 1, 2, 3, 4 NUMBER_TYPE
numberValue
OMG IDL ORDERED_NODE_ITERATOR_TYPE ORDERED_NODE_SNAPSHOT_TYPE
ownerElement
read only node 1, 2 resultType
singleNodeValue snapshotItem snapshotLength
STRING_TYPE stringValue
TYPE_ERR
UNORDERED_NODE_ITERATOR_TYPE UNORDERED_NODE_SNAPSHOT_TYPE
XML 1.0 1, 2, 3 XML Information Set 1, 2 XML Namespaces 1, 2, 3
XPath 1.0 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 XPATH_NAMESPACE_NODE XPathEvaluator


Document Object Model (DOM) Level 3 Views and Formatting Specification

Version 1.0

W3C Working Group Note 26 February 2004

This version:
http://www.w3.org/TR/2004/NOTE-DOM-Level-3-Views-20040226
Latest version:
http://www.w3.org/TR/DOM-Level-3-Views
Previous version:
http://www.w3.org/TR/2000/WD-DOM-Level-3-Views-20001115
Editor:
Ray Whitmer, Netscape/AOL, then Invited Expert

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

Abstract

This specification defines the Document Object Model Views and Formatting Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model Views and Formatting Level 3 builds on the Document Object Model Views Level 2.

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 specification is a very early version of the Views and Formatting API. This document is part of the DOM Level 3 specifications and W3C is not committed to do more experience and experimentation on this document.

Publication as a Working Group Note 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.

Comments and experiences on this document are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.

Patent disclosures relevant to this specification may be found on the DOM Working Group's patent disclosure page.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • 1. Document Object Model Views and Formatting
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • References
  • Index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • 1 Document Object Model Views and Formatting
    • 1.1 Overview
      • 1.1.1 Issues
      • 1.1.2 Segments
      • 1.1.3 View
      • 1.1.4 Generic and Medium-Specific APIs
    • 1.2 Formal Interface Definition for a Generic View
    • 1.3 Formal Interface Definition for a Visual View
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • References
  • Index


1 Document Object Model Views and Formatting

26 February 2004

1. Document Object Model Views and Formatting

Editor:
Ray Whitmer, Netscape Communications Corp

Table of contents

  • 1.1 Overview
    • 1.1.1 Issues
    • 1.1.2 Segments
    • 1.1.3 View
    • 1.1.4 Generic and Medium-Specific APIs
  • 1.2 Formal Interface Definition for a Generic View
    • View, Segment, Match, MatchString, MatchInteger, MatchBoolean, MatchContent, MatchSet, Item, StringItem, IntegerItem, BooleanItem, ContentItem
  • 1.3 Formal Interface Definition for a Visual View
    • VisualView, VisualResource, VisualFont, VisualSegment, VisualCharacter, VisualCharacterRun, VisualFrame, VisualImage, VisualFormButton, VisualFormField

1.1 Overview

This chapter describes the optional DOM Level 3 Views and Formatting feature. A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether this feature is supported or not. The feature string for generic interfaces is "ViewsAndFormatting". The feature string for visual properties and interfaces is "VisualViewsAndFormatting". The additional feature strings will be used to identify support specific to other media,

DOM implementations frequently create views of the document content available through DOM APIs. Such views present content in different ways using various processing, styling, and presentation systems. While a strong separation is typically maintained between content and the view, DOM applications may need to correlate characteristics such as position within a visual view with specific content presented within the view in order to augment and interact with the presentation.

This API allows a DOM application access to a view's computed layout and presentation. This feature functions independently from any specific styling system that may have been applied. An implementation of this API must be able to maintain a correspondence between specific content and its presentation within the view, however the presentation was computed. Presentation state such as selection or scrolling may be manipulatable though this interface, but state which is computed or supplied from the content must be manipulated through the content.

Two versions of the API have been supplied, which are redundant in their functionality. The DOM WG has not decided which of the two is better, or if both are needed. The generic API, described first, is more robust because the specifics are contained in identifying strings passed to general mechanisms. The medium-specific APIs, described last, directly expose the attributes of the medium on the interface, which provides a flatter, simpler model for the user, but one which is less able to adapt to new or extended media types or different uses.

1.1.1 Issues

Issue VF-Issue-1:
There are not enough examples in this document.
Issue VF-Issue-2:
We need to comprehensively look at typical presentations and decide the initial segments, properties, orders, and lookup criteria we want to support, at least in the visual case. We also need to see if we think that Visual needs to be further subclassed. We are clearly lacking things, but how many segment types and properties do we need to reasonably meet requirements for level 3?
Issue VF-Issue-3:
How should we represent types such as colors, fonts, and so on. How much time we can spend defining reporting value types or supporting arbitrary display value types. CSS style properties have done significant work in these areas, but it is not clear that their work is applicable for this view model, due to differences between stylistic intent and computed results.
Issue VF-Issue-4:
What types of events should we support: keyboard, mouse, selection, repaint, layout, properties, etc. Is it reasonable to support these at the view level, without exposing the lower layers of the presentation? Can we wait for a future version of the spec? We need compelling use cases for the first release.
Issue VF-Issue-5:
Is it reasonable to expose computed content? Should this be done by creating appropriate DocumentFragments? How does this figure into the ordering of the segments, since segments which present computed content instead of other content have less natural order. We need compelling use cases for the first release.
Issue VF-Issue-6:
What about case insensitivity when comparing string values? Should it be an option, the rule, or automatic?

1.1.2 Segments

A Segment is a distinct part of a view. Each Segment is privately owned and maintained by the containing view, which may destroy or reconstruct it at any time. Each Segment has a type related to the presentation medium and the function of that part of the presentation. Additional properties specific to the segment type contain information about that part of the view and identify the corresponding content, if any. Segments may also contain embedded segments where appropriate to the structure of the presentation.

A Segment is not expected to have any particular structure beyond its properties, any contained segments, and dependency on the content it presents. Containment of one segment within another does not change the fact that properties such as offsets are relative to the entire view so that they may be matched, applied, and compared from anywhere within the view.

The actual segments or parts of the view are not directly available to the DOM application, but this API provides generic Segment objects which can more-generally find and return items of the actual parts of the view.

1.1.3 View

A View is the root of a presentation, owned and maintained by a Document. A view formats the contents of a document into a particular type of presentation. A view may contain general properties of the view, resource segments, and segments representing the content of a document, prepared for presentation.

A Segment object specifies the actual criteria of segments to match, and captures items of each matched segment.

1.1.4 Generic and Medium-Specific APIs

The generic API provides access to variety of view and segment types by way of a medium-specific table of strings used to identify properties of medium-specific segment types:

// Find all selected runs of characters in the view at least half an inch from the edges.

View v = (View)((DocumentView)document).getDefaultView();
Segment q = v.createSegment();
q.setOrder("Content");
MatchSet m = q.createMatchSet(m.SET_ALL);
int hu = v.getIntegerProperty("HorizontalDPI");
int vu = v.getIntegerProperty("VerticalDPI");
n.addMatch(q.createMatchString(m.IS_EQUAL, "Type", "VisualCharacterRun");
m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "LeftOffset", hu/2));
m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "RightOffset", hu/2));
m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "TopOffset", vu/2));
m.addMatch(q.createMatchInteger(m.INT_FOLLOWS_OR_EQUALS, "RightOffset", vu/2));
m.addMatch(q.createMatchBoolean(m.IS_EQUAL, "Selected", true);
q.setCriteria(m);
ContentItem start = q.createContentItem("StartContent");
ContentItem end = q.createContentItem("EndContent");
q.addItem(start);
q.addItem(end);
v.matchFirstSegment(q, 0);
while (q.getExists())
{
  // ... do Something with range from start to end...
  q.getNext();
}

Medium-specific APIs are flatter and easier to use, but usually sacrifice capabilities of the more-general API.

// Find all selected runs of characters in the view at least half an inch from the edges.

VisualView v = (VisualView)((DocumentView)document).getDefaultView();
int hu = v.getHorizontalDPI();
int vu = v.getVerticalDPI();
CharacterRun cr = v.createCharacterRun();
cr.setMatchInside(true);
cr.setMatchX(hu / 2);
cr.setMatchY(vu / 2);
cr.setMatchXR(v.getWidth() - hu);
cr.setMatchYR(v.getHeight() - vu);
cr.setMatchSelected(true);
v.matchSegment(cr);
while (cr.getExists())
{
  // ... do Something with range from start to end...
  cr.getNext();
}

1.2 Formal Interface Definition for a Generic View

This is the verbose, general-purpose mechanism that can handle all properties of all media types. This relies on a separate table of segment types and the associated properties and property types, because it is a single API.

Interface View (introduced in DOM Level 3)

View is used as the root Segment, as well as providing additional global functionality such as selection.

IDL Definition
// Introduced in DOM Level 3:
interface View {
  void               select(in Node boundary,
                            in unsigned long offset,
                            in boolean extend,
                            in boolean add);
  Segment            createSegment();
  boolean            matchFirstSegment(inout Segment todo)
                                        raises(DOMException);
  long               getIntegerProperty(in DOMString name)
                                        raises(DOMException);
  DOMString          getStringProperty(in DOMString name)
                                        raises(DOMException);
  boolean            getBooleanProperty(in boolean name)
                                        raises(DOMException);
  Node               getContentPropertyNode(in DOMString name)
                                        raises(DOMException);
  unsigned long      getContentPropertyOffset(in DOMString name)
                                        raises(DOMException);
};

Methods
createSegment
Creates a segment that can be used to obtain segment items from the view.
Return Value

Segment

A new segment object, that can be set up to obtain information about the view.

No Parameters
No Exceptions
getBooleanProperty
Returns the value of a boolean property of the segment, used by Matches and Items.
Parameters
name of type boolean
The name of the boolean property of the segment to be retrieved.
Return Value

boolean

The value of the named property of the Segment.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not a boolean.

getContentPropertyNode
Returns the Node value of a content property of the segment, used by Matches and Items.
Parameters
name of type DOMString
The name of the content property of the segment to be retrieved.
Return Value

Node

The Node value of the named property of the Segment.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not content.

getContentPropertyOffset
Returns the offset value of a content property of the segment, used by Matches and Items.
Parameters
name of type DOMString
The name of the content property of the segment to be retrieved.
Return Value

unsigned long

The offset value of the named property of the Segment.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not content.

getIntegerProperty
Returns the value of an integer property of the segment, used by Matches and Items.
Parameters
name of type DOMString
The name of the integer property of the segment to be retrieved.
Return Value

long

The value of the named property of the Segment.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not an integer.

getStringProperty
Returns the value of a string property of the segment, used by Matches and Items.
Parameters
name of type DOMString
The name of the string property of the segment to be retrieved.
Return Value

DOMString

The value of the named property of the Segment.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the named property does not exist on the view or is not a string.

matchFirstSegment
Executes a Segment against all nested Segments, fetchingItems associated the requested match number, if it exists.
Parameters
todo of type Segment
The Segment to match within the view.
Return Value

boolean

true if the desired match number was found, otherwise false.

Exceptions

DOMException

NOT_SUPPORTED_ERR: If the segment request could not be interpreted.

select
Selects a new region of the document or adds to the existing selection.
Parameters
boundary of type Node
The Node at which to create or extend the selection.
offset of type unsigned long
The offset within the node at which to create or extend the selection.
extend of type boolean
If false, sets a selection anchor. If true, extends the selection with respect to the most-recently-set anchor.
add of type boolean
If false, clears any existing selection. If true adds a new region to existing selection regions.
No Return Value
No Exceptions
Interface Segment (introduced in DOM Level 3)

Segment is used to retrieve specific items from specific segments. Segments may be nested as a match and may be repeatedly applied for traversing multiple matching segments.

Note: Types and names of properties of segments of Visual media types

 Integer TopOffset
 Integer BottomOffset
 Integer LeftOffset
 Integer RightOffset
 Integer Width
 Integer Height
 Boolean Visible
 Boolean Selected
 Integer ForegroundColor
 Integer BackgroundColor
 String FontName
 String FontHeight
 String FontBaseline
 String FontSpace Width
 String FontMaximum Width

Segment types
 // Display info and root (the default segment)
 Display
 // An area that objects or text lines flow in
 //  or are anchored to
 Frame
 // A single character
 Character
 // Sequentially-appearing characters
 //  with identical properties
 CharacterRun
 FormField {Text | Label | Button | Menu ...}
 Embedded Object
 Image

Possible properties of specific types:
 (Image) String URL
 (Image) Boolean isLoaded
 (Image) Integer ScalingFactor
 (Button) Boolean isPressed
 (Frame) Boolean isScrollable

IDL Definition
// Introduced in DOM Level 3:
interface Segment : Match {
           attribute Match           criteria;
           attribute DOMString       order;
  void               addItem(in Item add);
  MatchString        createMatchString(in unsigned short test,
                                       in DOMString name,
                                       in DOMString value);
  MatchInteger       createMatchInteger(in unsigned short test,
                                        in DOMString name,
                                        in long value);
  MatchBoolean       createMatchBoolean(in unsigned short test,
                                        in DOMString name,
                                        in boolean value);
  MatchContent       createMatchContent(in unsigned short test,
                                        in DOMString name,
                                        in unsigned long offset,
                                        in Node nodeArg);
  MatchSet           createMatchSet(in unsigned short test);
  StringItem         createStringItem(in DOMString name);
  IntegerItem        createIntegerItem(in DOMString name);
  BooleanItem        createBooleanItem(in DOMString name);
  ContentItem        createContentItem(in DOMString name);
  void               getItem(in unsigned long index);
  boolean            getNext();
};

Attributes
criteria of type Match
The criteria Match of a Segment, specified during creation, controls which Segments will match.
After setting this attribute, the results of any related call to getNext are unpredictable until the segment has been requested again by calling matchFirstSegment.
order of type DOMString
The order string of a Segment, specified during creation, controls the order in which matching segments will be returned. If this attribute is not specified, the order defaults to an implementation-specific order.
After setting this attribute, the results of any related call to getNext are unpredictable until the segment has been requested again by calling matchFirstSegment.
Methods
addItem
Adds a specific Item to the Segment.
Parameters
add of type Item
The Item to be added.
After adding a result, the results of any related call to getNext are unpredictable until the segment has been requested again by calling matchFirstSegment.
No Return Value
No Exceptions
createBooleanItem
Creates an item for a segment that can receive a boolean value.
Parameters
name of type DOMString
The name of a boolean property to be received.
Return Value

BooleanItem

The requested BooleanItem.

No Exceptions
createContentItem
Creates an item for a segment that can receive a content value.
Parameters
name of type DOMString
The name of a content property to be received.
Return Value

ContentItem

The requested ContentItem.

No Exceptions
createIntegerItem
Creates an item for a segment that can receive an integral value.
Parameters
name of type DOMString
The name of an integral property to be received.
Return Value

IntegerItem

The requested IntegerItem.

No Exceptions
createMatchBoolean
Creates a match for a boolean value, which can be used to specify a criterium to find desired segments.
Parameters
test of type unsigned short
The match test desired.
name of type DOMString
The name of a boolean property to be compared against.
value of type boolean
The boolean value to be compared against.
Return Value

MatchBoolean

The requested MatchBoolean.

No Exceptions
createMatchContent
Creates a match for a content value, which can be used to specify a criterium to find desired segments.
Parameters
test of type unsigned short
The match test desired.
name of type DOMString
The name of an integer property to be compared against.
offset of type unsigned long
The offset of the content value to be compared against.
nodeArg of type Node
The Node of the content value to be compared against.
Return Value

MatchContent

The requested MatchContent.

No Exceptions
createMatchInteger
Creates a match for an integral value, which can be used to specify a criterium to find desired segments.
Parameters
test of type unsigned short
The match test desired.
name of type DOMString
The name of an integer property to be compared against.
value of type long
The integer value to be compared against.
Return Value

MatchInteger

The requested MatchInteger.

No Exceptions
createMatchSet
Creates a match for an set of matches, which can be used to specify a criterium to find desired segments.
Parameters
test of type unsigned short
The match test desired.
Return Value

MatchSet

The requested MatchSet.

No Exceptions
createMatchString
Creates a match for a string value, which can be used to specify a criterium to find desired segments.
Parameters
test of type unsigned short
The match test desired.
name of type DOMString
The name of a string property to be compared against.
value of type DOMString
The string value to be compared against.
Return Value

MatchString

The requested MatchString.

No Exceptions
createStringItem
Creates an item for a segment that can receive a string value.
Parameters
name of type DOMString
The name of a string property to be received.
Return Value

StringItem

The requested StringItem.

No Exceptions
getItem
Returns a specific Item, of the list specified during the creation of the Segment, which is to be fetched during Segment execution, or returns null if the specified index does not correspond to a Item.
Parameters
index of type unsigned long
The index of the Item to be retrieved.
No Return Value
No Exceptions
getNext
Fetches the results of the next matching Segment, if any.
Return Value

boolean

true if another match, otherwise false (same value as exists).

No Parameters
No Exceptions
Interface Match (introduced in DOM Level 3)

The Match identifies Segments of which a Segment should fetch the Items.

IDL Definition
// Introduced in DOM Level 3:
interface Match {

  // MatchTestGroup
  const unsigned short      IS_EQUAL                       = 0;
  const unsigned short      IS_NOT_EQUAL                   = 1;
  const unsigned short      INT_PRECEDES                   = 2;
  const unsigned short      INT_PRECEDES_OR_EQUALS         = 3;
  const unsigned short      INT_FOLLOWS                    = 4;
  const unsigned short      INT_FOLLOWS_OR_EQUALS          = 5;
  const unsigned short      STR_STARTS_WITH                = 6;
  const unsigned short      STR_ENDS_WITH                  = 7;
  const unsigned short      STR_CONTAINS                   = 8;
  const unsigned short      SET_ANY                        = 9;
  const unsigned short      SET_ALL                        = 10;
  const unsigned short      SET_NOT_ANY                    = 11;
  const unsigned short      SET_NOT_ALL                    = 12;

  readonly attribute unsigned short  test;
};

Definition group MatchTestGroup
Defined Constants
INT_FOLLOWS
INT_FOLLOWS_OR_EQUALS
INT_PRECEDES
INT_PRECEDES_OR_EQUALS
IS_EQUAL
IS_NOT_EQUAL
SET_ALL
SET_ANY
SET_NOT_ALL
SET_NOT_ANY
STR_CONTAINS
STR_ENDS_WITH
STR_STARTS_WITH
Attributes
test of type unsigned short, readonly
The test value of a Match, specified during creation, controls the test to be applied.
Interface MatchString (introduced in DOM level 3)

The MatchString identifies Segments where a string property matches a specific value.

IDL Definition
// Introduced in DOM level 3:
interface MatchString : Match {
  readonly attribute DOMString       name;
  readonly attribute DOMString       value;
};

Attributes
name of type DOMString, readonly
The name of a string property of each Segment to be compared against, which is specified during construction.
value of type DOMString, readonly
The string value to be compared against, which is specified during construction.
Interface MatchInteger (introduced in DOM level 3)

The MatchInteger identifies Segments where an integer property matches a specific value.

IDL Definition
// Introduced in DOM level 3:
interface MatchInteger : Match {
  readonly attribute DOMString       name;
  readonly attribute long            value;
};

Attributes
name of type DOMString, readonly
The name of an integer property of each Segment to be compared against, which is specified during construction.
value of type long, readonly
The integer value to be compared against, which is specified during construction.
Interface MatchBoolean (introduced in DOM level 3)

The MatchBoolean identifies Segments where a boolean property matches a specific value.

IDL Definition
// Introduced in DOM level 3:
interface MatchBoolean : Match {
  readonly attribute DOMString       name;
  readonly attribute boolean         value;
};

Attributes
name of type DOMString, readonly
The name of an boolean property of each Segment to be compared against, which is specified during construction.
value of type boolean, readonly
The boolean value to be compared against, which is specified during construction.
Interface MatchContent (introduced in DOM level 3)

The MatchContent identifies Segments where a content property matches a specific value.

IDL Definition
// Introduced in DOM level 3:
interface MatchContent : Match {
  readonly attribute DOMString       name;
  readonly attribute Node            nodeArg;
  readonly attribute unsigned long   offset;
};

Attributes
name of type DOMString, readonly
The name of an content property of each Segment to be compared against, which is specified during construction.
nodeArg of type Node, readonly
The Node value to be compared against, which is specified during construction.
offset of type unsigned long, readonly
The offset value to be compared against, which is specified during construction.
Interface MatchSet (introduced in DOM level 3)

The MatchSet identifies Segments where a set of matches evaluate in a specified way.

IDL Definition
// Introduced in DOM level 3:
interface MatchSet : Match {
  readonly attribute Node            nodeArg;
  void               addMatch(in Match add);
  Match              getMatch(in unsigned long index);
};

Attributes
nodeArg of type Node, readonly
The Node value to be compared against, which is specified during construction.
Methods
addMatch
Adds a specific Match to the set.
Parameters
add of type Match
The Match to be added.
After adding a match, the results of any related call to getNext are unpredictable until the segment has been requested again by calling matchFirstSegment.
No Return Value
No Exceptions
getMatch
Returns a specific Match, of the set, which is to be matched during MatchSet evaluation, or returns null if the specified index does not correspond to a Match.
Parameters
index of type unsigned long
The index of the Match to be retrieved.
Return Value

Match

The requested match, if any, or null.

No Exceptions
Interface Item (introduced in DOM Level 3)

The Item represents information to be fetched by a Segment.

IDL Definition
// Introduced in DOM Level 3:
interface Item {
  readonly attribute boolean         exists;
  readonly attribute DOMString       name;
};

Attributes
exists of type boolean, readonly
The exists boolean of a Segment, initially set to false during creation, is set after an attempt to fetch the values of a Item to indicate whether or not the required data was present. A true value indicates that it was.
name of type DOMString, readonly
The name of a property of the matched Segment to be fetched, which is specified during construction.
Interface StringItem (introduced in DOM Level 3)

The StringItem represents a string property to be fetched by a Segment.

IDL Definition
// Introduced in DOM Level 3:
interface StringItem : Item {
  readonly attribute DOMString       value;
};

Attributes
value of type DOMString, readonly
The string value returned by the Segment, which is undefined if exists is false.
Interface IntegerItem (introduced in DOM Level 3)

The IntegerItem represents an integer property to be fetched by a Segment.

IDL Definition
// Introduced in DOM Level 3:
interface IntegerItem : Item {
  readonly attribute long            value;
};

Attributes
value of type long, readonly
The integer value returned by the Segment, which is undefined if exists is false.
Interface BooleanItem (introduced in DOM Level 3)

The BooleanItem represents a boolean property to be fetched by a Segment.

IDL Definition
// Introduced in DOM Level 3:
interface BooleanItem : Item {
           attribute boolean         value;
};

Attributes
value of type boolean
The boolean value returned by the Segment, which is undefined if exists is false.
Interface ContentItem (introduced in DOM Level 3)

The ContentItem represents a content property to be fetched by a Segment.

IDL Definition
// Introduced in DOM Level 3:
interface ContentItem : Item {
           attribute Node            nodeArg;
           attribute unsigned long   offset;
};

Attributes
nodeArg of type Node
The Node value returned by the Segment, which is undefined if exists is false.
offset of type unsigned long
The offset value returned by the Segment, which is undefined if exists is false.

1.3 Formal Interface Definition for a Visual View

This is the flatter mechanism that handles only one specific medium, in this case, visual. This does not rely on a table of property names, because all supported criteria and properties are attributes of the interfaces.

Interface VisualView

Presents a flatter model of a visual view.

IDL Definition
interface VisualView {
  readonly attribute DOMString       fontScheme;
  readonly attribute unsigned long   width;
  readonly attribute unsigned long   height;
  readonly attribute unsigned long   horizontalDPI;
  readonly attribute unsigned long   verticalDPI;
  VisualCharacter    createVisualCharacter();
  VisualCharacterRun createVisualCharacterRun();
  VisualFrame        createVisualFrame();
  VisualImage        createVisualImage();
  VisualFormButton   createVisualFormButton();
  VisualFormField    createVisualFormField();
  void               select(in Node boundary,
                            in unsigned long offset,
                            in boolean extend,
                            in boolean add);
  void               matchSegment(in VisualResource segment);
};

Attributes
fontScheme of type DOMString, readonly
A string identifying the type of fonts on the system so that font name strings may be properly interpreted.
height of type unsigned long, readonly
The height, in vertical units, of the view.
horizontalDPI of type unsigned long, readonly
The number of horizontal dots per inch in the view, used to interpret horizontal values.
verticalDPI of type unsigned long, readonly
The number of vertical dots per inch in the view, used to interpret vertical values.
width of type unsigned long, readonly
The width, in horizontal units, of the view.
Methods
createVisualCharacter
Creates a visual character to match and return information on a single visual character of the view.
Return Value

VisualCharacter

The requested VisualCharacter.

No Parameters
No Exceptions
createVisualCharacterRun
Creates a visual character run to match and return information on a run of similar ajdacent visual characters of the view.
This will match the largest character run that meets the specified criteria, is not contiguously displayed on the view and has homogeneous display properties.
Return Value

VisualCharacterRun

The requested VisualCharacterRun.

No Parameters
No Exceptions
createVisualFormButton
Creates a visual form button to match and return information on a form button of the view.
Return Value

VisualFormButton

The requested VisualFormButton.

No Parameters
No Exceptions
createVisualFormField
Creates a visual form field to match and return information on a form field of the view.
Return Value

VisualFormField

The requested VisualFormField.

No Parameters
No Exceptions
createVisualFrame
Creates a visual frame to match and return information on a frame of the view.
Return Value

VisualFrame

The requested VisualFrame.

No Parameters
No Exceptions
createVisualImage
Creates a visual image to match and return information on an image of the view.
Return Value

VisualImage

The requested VisualImage.

No Parameters
No Exceptions
matchSegment
Parameters
segment of type VisualResource
No Return Value
No Exceptions
select
Parameters
boundary of type Node
offset of type unsigned long
extend of type boolean
add of type boolean
No Return Value
No Exceptions
Interface VisualResource

Visual segments allow things within a visual view to be accessed.

IDL Definition
interface VisualResource {
};

Interface VisualFont

Visual font resources contain match criteria and result attributes for getting information about fonts available to a view.

IDL Definition
interface VisualFont : VisualResource {
           attribute DOMString       matchFontName;
  readonly attribute boolean         exists;
  readonly attribute DOMString       fontName;
  boolean            getNext();
};

Attributes
exists of type boolean, readonly
Returns true result if the desired font was located, or false if it was not. If this value is set to false, no other results are set. If this value is set to true, all other results are set.
fontName of type DOMString, readonly
When a font is matched, the name of the font is returned here.
matchFontName of type DOMString
May be set to cause fonts with the corresponding name to be matched.
Methods
getNext
Fetches the results of the next matching VisualFont, if any.
Return Value

boolean
No Parameters
No Exceptions
Interface VisualSegment

Visual segments contain match criteria attributes and result attributes common to visual views of a document. When this structure is created, all booleans are set to false, all integral values are set to 0, and all strings and object references are set to null. Match criteria are then set. After setting match criteria, matchSegment is called passing this segment or another segment that references this segment, which finds a matching segment and sets result attributes.

IDL Definition
interface VisualSegment : VisualResource {
           attribute boolean         matchPosition;
           attribute boolean         matchInside;
           attribute boolean         matchContaining;
           attribute long            matchX;
           attribute long            matchY;
           attribute long            matchXR;
           attribute long            matchYR;
           attribute boolean         matchContent;
           attribute boolean         matchRange;
           attribute Node            matchNode;
           attribute unsigned long   matchOffset;
           attribute Node            matchNodeR;
           attribute unsigned long   matchOffsetR;
           attribute boolean         matchContainsSelected;
           attribute boolean         matchContainsVisible;
  readonly attribute boolean         exists;
  readonly attribute Node            startNode;
  readonly attribute unsigned long   startOffset;
  readonly attribute Node            endNode;
  readonly attribute unsigned long   endOffset;
  readonly attribute long            topOffset;
  readonly attribute long            bottomOffset;
  readonly attribute long            leftOffset;
  readonly attribute long            rightOffset;
  readonly attribute unsigned long   width;
  readonly attribute unsigned long   height;
  readonly attribute boolean         selected;
  readonly attribute boolean         visible;
  readonly attribute unsigned long   foregroundColor;
  readonly attribute unsigned long   backgroundColor;
  readonly attribute DOMString       fontName;
  readonly attribute DOMString       fontHeight;
  boolean            getNext();
};

Attributes
backgroundColor of type unsigned long, readonly
Whenever a segment is matched, this is set to the integral value of the background color of that segment, or transparent if there is no background color. The 32 bits of this value are divided into the following 8-bit sub-fields, from most significant to least significant: alpha, red, green, blue. The color fields range from 0 for no intensity to 255 to indicate the contribution of each color. The alpha field ranges from 0 for transparent to 255 for completely opaque. For a transparent alpha value of 0, the color fields are be normalized to 0 as well.
bottomOffset of type long, readonly
Whenever a segment is matched, this is set to the bottom offset of the segment within the view, specified in vertical view units.
endNode of type Node, readonly
Whenever a segment is matched, this is set to the last node presented by the matched segment or null if the segment does not present any specific document content.
endOffset of type unsigned long, readonly
Whenever a segment is matched, this is set to first offset not presented within the last node presented by the matched segment or 0 if the segment does not present any specific document content.
exists of type boolean, readonly
Returns true result if the desired segment was located, or false if it was not. If this value is set to false, no other results are set. If this value is set to true, all other results are set.
fontHeight of type DOMString, readonly
fontName of type DOMString, readonly
The font name is a view-specific designation of the font name.
foregroundColor of type unsigned long, readonly
Whenever a segment is matched, this is set to the integral value of the foreground color of that segment, or transparent if there is no foreground color. The 32 bits of this value are divided into the following 8-bit sub-fields, from most significant to least significant: alpha, red, green, blue. The color fields range from 0 for no intensity to 255 to indicate the contribution of each color. The alpha field ranges from 0 for transparent to 255 for completely opaque. For complete transparency, the color fields will be normalized to 0 as well.
height of type unsigned long, readonly
Whenever a segment is matched, this is set to the width of the segment within the view, specified in vertical view units.
leftOffset of type long, readonly
Whenever a segment is matched, this is set to the left offset of the segment within the view, specified in horizontal view units.
matchContaining of type boolean
May be set to cause the corresponding segment to be matched only if it contains the specified rectangular region bounded by matchX, matchY, matchXR, and matchYR.
matchContainsSelected of type boolean
May be set to cause the corresponding segment to only be matched if the content being presented contains a cursor or part of a selected region.
matchContainsVisible of type boolean
May be set to cause the corresponding segment to only be matched if the segment being presented contains some part that is visible.
matchContent of type boolean
May be set to cause the corresponding segment to only be matched if it presents the matchNode content, offset by matchOffset.
matchInside of type boolean
May be set to cause the corresponding segment to be matched only if it is inside the specified rectangular region bounded by matchX, matchY, matchXR, and matchYR.
matchNode of type Node
The node, or first node in a range to use to match segments which present specified content.
If matching content is enabled, but this is set to null, then only segments that are not associated with content will be matched.
matchNodeR of type Node
The second node in a range to use to match segments which present specified content.
If matching a content range is enabled, but this is set to null, then only segments that are not associated with content will be matched.
matchOffset of type unsigned long
The offset, or first offset in a range to use to match segments which present specified content.
matchOffsetR of type unsigned long
The offset, or first offset in a range to use to match segments which present specified content.
matchPosition of type boolean
May be set to cause the corresponding segment to be matched only if it contains the specified matchX and matchY positions.
matchRange of type boolean
May be set to cause the corresponding segment to only be matched if the content it presents is within the range of content between Node matchNode offset matchOffset and Node matchNodeR offset matchOffsetR.
matchX of type long
An integral X coordinate, specified in horizontal view units, that may be used to match a point or region.
matchXR of type long
An integral X coordinate, specified in horizontal view units, that may be used to match a region.
matchY of type long
An integral Y coordinate, specified in vertical view units, that may be used to match a point or region.
matchYR of type long
An integral Y coordinate, specified in vertical view units, that may be used to match a region.
rightOffset of type long, readonly
Whenever a segment is matched, this is set to the right offset of the segment within the view, specified in horizontal view units.
selected of type boolean, readonly
Whenever a segment is matched, this is set to true if the segment presents the content with the cursor or selected content, otherwise, this is set to false.
startNode of type Node, readonly
Whenever a segment is matched, this is set to the first node presented by the matched segment or null if the segment does not present any specific document content.
startOffset of type unsigned long, readonly
Whenever a segment is matched, this is set to the first offset presented within the first node presented by the matched segment or 0 if the segment does not present any specific document content.
topOffset of type long, readonly
Whenever a segment is matched, this is set to the top offset of the segment within the view, specified in vertical view units.
visible of type boolean, readonly
Whenever a segment is matched, this is set to true if the segment contains some part that is visible, otherwise, this is set to false.
width of type unsigned long, readonly
Whenever a segment is matched, this is set to the width of the segment within the view, specified in horizontal view units.
Methods
getNext
Fetches the results of the next matching VisualResource, if any.
Return Value

boolean
No Parameters
No Exceptions
Interface VisualCharacter

IDL Definition
interface VisualCharacter : VisualSegment {
};

Interface VisualCharacterRun

IDL Definition
interface VisualCharacterRun : VisualSegment {
};

Interface VisualFrame

IDL Definition
interface VisualFrame : VisualSegment {
  readonly attribute VisualSegment   embedded;
};

Attributes
embedded of type VisualSegment, readonly
May be set to contain embedded visual segments inside the frame. If this value is set, the embedded segment serves as a conditional for the frame while receiving the results of the embedded segment that was matched.
Interface VisualImage

IDL Definition
interface VisualImage : VisualSegment {
  readonly attribute DOMString       imageURL;
  readonly attribute boolean         isLoaded;
};

Attributes
imageURL of type DOMString, readonly
isLoaded of type boolean, readonly
Interface VisualFormButton

IDL Definition
interface VisualFormButton : VisualSegment {
  readonly attribute boolean         isPressed;
};

Attributes
isPressed of type boolean, readonly
Interface VisualFormField

IDL Definition
interface VisualFormField : VisualSegment {
  readonly attribute DOMString       formValue;
};

Attributes
formValue of type DOMString, readonly


Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Views and Formatting definitions.

The IDL files are also available as: http://www.w3.org/TR/2004/NOTE-DOM-Level-3-Views-20040226/idl.zip

views.idl:

// File: views.idl

#ifndef _VIEWS_IDL_
#define _VIEWS_IDL_

#include "dom.idl"

#pragma prefix "dom.w3c.org"
module views
{

  typedef dom::Node Node;
  typedef dom::DOMString DOMString;

  interface Segment;
  interface VisualResource;
  interface VisualCharacter;
  interface VisualCharacterRun;
  interface VisualFrame;
  interface VisualImage;
  interface VisualFormButton;
  interface VisualFormField;

  // Introduced in DOM Level 3:
  interface View {
    void               select(in Node boundary,
                              in unsigned long offset,
                              in boolean extend,
                              in boolean add);
    Segment            createSegment();
    boolean            matchFirstSegment(inout Segment todo)
                                        raises(dom::DOMException);
    long               getIntegerProperty(in DOMString name)
                                        raises(dom::DOMException);
    DOMString          getStringProperty(in DOMString name)
                                        raises(dom::DOMException);
    boolean            getBooleanProperty(in boolean name)
                                        raises(dom::DOMException);
    Node               getContentPropertyNode(in DOMString name)
                                        raises(dom::DOMException);
    unsigned long      getContentPropertyOffset(in DOMString name)
                                        raises(dom::DOMException);
  };

  // Introduced in DOM Level 3:
  interface Match {

    // MatchTestGroup
    const unsigned short      IS_EQUAL                       = 0;
    const unsigned short      IS_NOT_EQUAL                   = 1;
    const unsigned short      INT_PRECEDES                   = 2;
    const unsigned short      INT_PRECEDES_OR_EQUALS         = 3;
    const unsigned short      INT_FOLLOWS                    = 4;
    const unsigned short      INT_FOLLOWS_OR_EQUALS          = 5;
    const unsigned short      STR_STARTS_WITH                = 6;
    const unsigned short      STR_ENDS_WITH                  = 7;
    const unsigned short      STR_CONTAINS                   = 8;
    const unsigned short      SET_ANY                        = 9;
    const unsigned short      SET_ALL                        = 10;
    const unsigned short      SET_NOT_ANY                    = 11;
    const unsigned short      SET_NOT_ALL                    = 12;

    readonly attribute unsigned short  test;
  };

  // Introduced in DOM level 3:
  interface MatchString : Match {
    readonly attribute DOMString       name;
    readonly attribute DOMString       value;
  };

  // Introduced in DOM level 3:
  interface MatchInteger : Match {
    readonly attribute DOMString       name;
    readonly attribute long            value;
  };

  // Introduced in DOM level 3:
  interface MatchBoolean : Match {
    readonly attribute DOMString       name;
    readonly attribute boolean         value;
  };

  // Introduced in DOM level 3:
  interface MatchContent : Match {
    readonly attribute DOMString       name;
    readonly attribute Node            nodeArg;
    readonly attribute unsigned long   offset;
  };

  // Introduced in DOM level 3:
  interface MatchSet : Match {
    readonly attribute Node            nodeArg;
    void               addMatch(in Match add);
    Match              getMatch(in unsigned long index);
  };

  // Introduced in DOM Level 3:
  interface Item {
    readonly attribute boolean         exists;
    readonly attribute DOMString       name;
  };

  // Introduced in DOM Level 3:
  interface StringItem : Item {
    readonly attribute DOMString       value;
  };

  // Introduced in DOM Level 3:
  interface IntegerItem : Item {
    readonly attribute long            value;
  };

  // Introduced in DOM Level 3:
  interface BooleanItem : Item {
             attribute boolean         value;
  };

  // Introduced in DOM Level 3:
  interface ContentItem : Item {
             attribute Node            nodeArg;
             attribute unsigned long   offset;
  };

  interface VisualView {
    readonly attribute DOMString       fontScheme;
    readonly attribute unsigned long   width;
    readonly attribute unsigned long   height;
    readonly attribute unsigned long   horizontalDPI;
    readonly attribute unsigned long   verticalDPI;
    VisualCharacter    createVisualCharacter();
    VisualCharacterRun createVisualCharacterRun();
    VisualFrame        createVisualFrame();
    VisualImage        createVisualImage();
    VisualFormButton   createVisualFormButton();
    VisualFormField    createVisualFormField();
    void               select(in Node boundary,
                              in unsigned long offset,
                              in boolean extend,
                              in boolean add);
    void               matchSegment(in VisualResource segment);
  };

  interface VisualResource {
  };

  interface VisualFont : VisualResource {
             attribute DOMString       matchFontName;
    readonly attribute boolean         exists;
    readonly attribute DOMString       fontName;
    boolean            getNext();
  };

  interface VisualSegment : VisualResource {
             attribute boolean         matchPosition;
             attribute boolean         matchInside;
             attribute boolean         matchContaining;
             attribute long            matchX;
             attribute long            matchY;
             attribute long            matchXR;
             attribute long            matchYR;
             attribute boolean         matchContent;
             attribute boolean         matchRange;
             attribute Node            matchNode;
             attribute unsigned long   matchOffset;
             attribute Node            matchNodeR;
             attribute unsigned long   matchOffsetR;
             attribute boolean         matchContainsSelected;
             attribute boolean         matchContainsVisible;
    readonly attribute boolean         exists;
    readonly attribute Node            startNode;
    readonly attribute unsigned long   startOffset;
    readonly attribute Node            endNode;
    readonly attribute unsigned long   endOffset;
    readonly attribute long            topOffset;
    readonly attribute long            bottomOffset;
    readonly attribute long            leftOffset;
    readonly attribute long            rightOffset;
    readonly attribute unsigned long   width;
    readonly attribute unsigned long   height;
    readonly attribute boolean         selected;
    readonly attribute boolean         visible;
    readonly attribute unsigned long   foregroundColor;
    readonly attribute unsigned long   backgroundColor;
    readonly attribute DOMString       fontName;
    readonly attribute DOMString       fontHeight;
    boolean            getNext();
  };

  interface VisualCharacter : VisualSegment {
  };

  interface VisualCharacterRun : VisualSegment {
  };

  interface VisualFrame : VisualSegment {
    readonly attribute VisualSegment   embedded;
  };

  interface VisualImage : VisualSegment {
    readonly attribute DOMString       imageURL;
    readonly attribute boolean         isLoaded;
  };

  interface VisualFormButton : VisualSegment {
    readonly attribute boolean         isPressed;
  };

  interface VisualFormField : VisualSegment {
    readonly attribute DOMString       formValue;
  };

  // Introduced in DOM Level 3:
  interface Segment : Match {
             attribute Match           criteria;
             attribute DOMString       order;
    void               addItem(in Item add);
    MatchString        createMatchString(in unsigned short test,
                                         in DOMString name,
                                         in DOMString value);
    MatchInteger       createMatchInteger(in unsigned short test,
                                          in DOMString name,
                                          in long value);
    MatchBoolean       createMatchBoolean(in unsigned short test,
                                          in DOMString name,
                                          in boolean value);
    MatchContent       createMatchContent(in unsigned short test,
                                          in DOMString name,
                                          in unsigned long offset,
                                          in Node nodeArg);
    MatchSet           createMatchSet(in unsigned short test);
    StringItem         createStringItem(in DOMString name);
    IntegerItem        createIntegerItem(in DOMString name);
    BooleanItem        createBooleanItem(in DOMString name);
    ContentItem        createContentItem(in DOMString name);
    void               getItem(in unsigned long index);
    boolean            getNext();
  };
};

#endif // _VIEWS_IDL_


Appendix B: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Views and Formatting.

The Java files are also available as http://www.w3.org/TR/2004/NOTE-DOM-Level-3-Views-20040226/java-binding.zip

org/w3c/dom/views/View.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface View {
    public void select(Node boundary,
                       int offset,
                       boolean extend,
                       boolean add);

    public Segment createSegment();

    public boolean matchFirstSegment(Segment todo)
                                     throws DOMException;

    public int getIntegerProperty(String name)
                                  throws DOMException;

    public String getStringProperty(String name)
                                    throws DOMException;

    public boolean getBooleanProperty(boolean name)
                                      throws DOMException;

    public Node getContentPropertyNode(String name)
                                       throws DOMException;

    public int getContentPropertyOffset(String name)
                                        throws DOMException;

}

org/w3c/dom/views/Segment.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface Segment extends Match {
    public Match getCriteria();
    public void setCriteria(Match criteria);

    public String getOrder();
    public void setOrder(String order);

    public void addItem(Item add);

    public MatchString createMatchString(short test,
                                         String name,
                                         String value);

    public MatchInteger createMatchInteger(short test,
                                           String name,
                                           int value);

    public MatchBoolean createMatchBoolean(short test,
                                           String name,
                                           boolean value);

    public MatchContent createMatchContent(short test,
                                           String name,
                                           int offset,
                                           Node nodeArg);

    public MatchSet createMatchSet(short test);

    public StringItem createStringItem(String name);

    public IntegerItem createIntegerItem(String name);

    public BooleanItem createBooleanItem(String name);

    public ContentItem createContentItem(String name);

    public void getItem(int index);

    public boolean getNext();

}

org/w3c/dom/views/Match.java:

package org.w3c.dom.views;

public interface Match {
    // MatchTestGroup
    public static final short IS_EQUAL                  = 0;
    public static final short IS_NOT_EQUAL              = 1;
    public static final short INT_PRECEDES              = 2;
    public static final short INT_PRECEDES_OR_EQUALS    = 3;
    public static final short INT_FOLLOWS               = 4;
    public static final short INT_FOLLOWS_OR_EQUALS     = 5;
    public static final short STR_STARTS_WITH           = 6;
    public static final short STR_ENDS_WITH             = 7;
    public static final short STR_CONTAINS              = 8;
    public static final short SET_ANY                   = 9;
    public static final short SET_ALL                   = 10;
    public static final short SET_NOT_ANY               = 11;
    public static final short SET_NOT_ALL               = 12;

    public short getTest();

}

org/w3c/dom/views/MatchString.java:

package org.w3c.dom.views;

public interface MatchString extends Match {
    public String getName();

    public String getValue();

}

org/w3c/dom/views/MatchInteger.java:

package org.w3c.dom.views;

public interface MatchInteger extends Match {
    public String getName();

    public int getValue();

}

org/w3c/dom/views/MatchBoolean.java:

package org.w3c.dom.views;

public interface MatchBoolean extends Match {
    public String getName();

    public boolean getValue();

}

org/w3c/dom/views/MatchContent.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface MatchContent extends Match {
    public String getName();

    public Node getNodeArg();

    public int getOffset();

}

org/w3c/dom/views/MatchSet.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface MatchSet extends Match {
    public Node getNodeArg();

    public void addMatch(Match add);

    public Match getMatch(int index);

}

org/w3c/dom/views/Item.java:

package org.w3c.dom.views;

public interface Item {
    public boolean getExists();

    public String getName();

}

org/w3c/dom/views/StringItem.java:

package org.w3c.dom.views;

public interface StringItem extends Item {
    public String getValue();

}

org/w3c/dom/views/IntegerItem.java:

package org.w3c.dom.views;

public interface IntegerItem extends Item {
    public int getValue();

}

org/w3c/dom/views/BooleanItem.java:

package org.w3c.dom.views;

public interface BooleanItem extends Item {
    public boolean getValue();
    public void setValue(boolean value);

}

org/w3c/dom/views/ContentItem.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface ContentItem extends Item {
    public Node getNodeArg();
    public void setNodeArg(Node nodeArg);

    public int getOffset();
    public void setOffset(int offset);

}

org/w3c/dom/views/VisualView.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface VisualView {
    public String getFontScheme();

    public int getWidth();

    public int getHeight();

    public int getHorizontalDPI();

    public int getVerticalDPI();

    public VisualCharacter createVisualCharacter();

    public VisualCharacterRun createVisualCharacterRun();

    public VisualFrame createVisualFrame();

    public VisualImage createVisualImage();

    public VisualFormButton createVisualFormButton();

    public VisualFormField createVisualFormField();

    public void select(Node boundary,
                       int offset,
                       boolean extend,
                       boolean add);

    public void matchSegment(VisualResource segment);

}

org/w3c/dom/views/VisualResource.java:

package org.w3c.dom.views;

public interface VisualResource {
}

org/w3c/dom/views/VisualFont.java:

package org.w3c.dom.views;

public interface VisualFont extends VisualResource {
    public String getMatchFontName();
    public void setMatchFontName(String matchFontName);

    public boolean getExists();

    public String getFontName();

    public boolean getNext();

}

org/w3c/dom/views/VisualSegment.java:

package org.w3c.dom.views;

import org.w3c.dom.Node;

public interface VisualSegment extends VisualResource {
    public boolean getMatchPosition();
    public void setMatchPosition(boolean matchPosition);

    public boolean getMatchInside();
    public void setMatchInside(boolean matchInside);

    public boolean getMatchContaining();
    public void setMatchContaining(boolean matchContaining);

    public int getMatchX();
    public void setMatchX(int matchX);

    public int getMatchY();
    public void setMatchY(int matchY);

    public int getMatchXR();
    public void setMatchXR(int matchXR);

    public int getMatchYR();
    public void setMatchYR(int matchYR);

    public boolean getMatchContent();
    public void setMatchContent(boolean matchContent);

    public boolean getMatchRange();
    public void setMatchRange(boolean matchRange);

    public Node getMatchNode();
    public void setMatchNode(Node matchNode);

    public int getMatchOffset();
    public void setMatchOffset(int matchOffset);

    public Node getMatchNodeR();
    public void setMatchNodeR(Node matchNodeR);

    public int getMatchOffsetR();
    public void setMatchOffsetR(int matchOffsetR);

    public boolean getMatchContainsSelected();
    public void setMatchContainsSelected(boolean matchContainsSelected);

    public boolean getMatchContainsVisible();
    public void setMatchContainsVisible(boolean matchContainsVisible);

    public boolean getExists();

    public Node getStartNode();

    public int getStartOffset();

    public Node getEndNode();

    public int getEndOffset();

    public int getTopOffset();

    public int getBottomOffset();

    public int getLeftOffset();

    public int getRightOffset();

    public int getWidth();

    public int getHeight();

    public boolean getSelected();

    public boolean getVisible();

    public int getForegroundColor();

    public int getBackgroundColor();

    public String getFontName();

    public String getFontHeight();

    public boolean getNext();

}

org/w3c/dom/views/VisualCharacter.java:

package org.w3c.dom.views;

public interface VisualCharacter extends VisualSegment {
}

org/w3c/dom/views/VisualCharacterRun.java:

package org.w3c.dom.views;

public interface VisualCharacterRun extends VisualSegment {
}

org/w3c/dom/views/VisualFrame.java:

package org.w3c.dom.views;

public interface VisualFrame extends VisualSegment {
    public VisualSegment getEmbedded();

}

org/w3c/dom/views/VisualImage.java:

package org.w3c.dom.views;

public interface VisualImage extends VisualSegment {
    public String getImageURL();

    public boolean isLoaded();

}

org/w3c/dom/views/VisualFormButton.java:

package org.w3c.dom.views;

public interface VisualFormButton extends VisualSegment {
    public boolean isPressed();

}

org/w3c/dom/views/VisualFormField.java:

package org.w3c.dom.views;

public interface VisualFormField extends VisualSegment {
    public String getFormValue();

}


Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Views and Formatting definitions.

Objects that implement the View interface:
Functions of objects that implement the View interface:
select(boundary, offset, extend, add)
This function has no return value.
The boundary parameter is an object that implements the Node interface.
The offset parameter is a Number.
The extend parameter is a Boolean.
The add parameter is a Boolean.
createSegment()
This function returns an object that implements the Segment interface.
matchFirstSegment(todo)
This function returns a Boolean.
The todo parameter is an object that implements the Segment interface.
This function can raise an object that implements the DOMException interface.
getIntegerProperty(name)
This function returns a Number.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
getStringProperty(name)
This function returns a String.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
getBooleanProperty(name)
This function returns a Boolean.
The name parameter is a Boolean.
This function can raise an object that implements the DOMException interface.
getContentPropertyNode(name)
This function returns an object that implements the Node interface.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
getContentPropertyOffset(name)
This function returns a Number.
The name parameter is a String.
This function can raise an object that implements the DOMException interface.
Objects that implement the Segment interface:
Objects that implement the Segment interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the Segment interface:
criteria
This property is an object that implements the Match interface.
order
This property is a String.
Functions of objects that implement the Segment interface:
addItem(add)
This function has no return value.
The add parameter is an object that implements the Item interface.
createMatchString(test, name, value)
This function returns an object that implements the MatchString interface.
The test parameter is a Number.
The name parameter is a String.
The value parameter is a String.
createMatchInteger(test, name, value)
This function returns an object that implements the MatchInteger interface.
The test parameter is a Number.
The name parameter is a String.
The value parameter is a Number.
createMatchBoolean(test, name, value)
This function returns an object that implements the MatchBoolean interface.
The test parameter is a Number.
The name parameter is a String.
The value parameter is a Boolean.
createMatchContent(test, name, offset, nodeArg)
This function returns an object that implements the MatchContent interface.
The test parameter is a Number.
The name parameter is a String.
The offset parameter is a Number.
The nodeArg parameter is an object that implements the Node interface.
createMatchSet(test)
This function returns an object that implements the MatchSet interface.
The test parameter is a Number.
createStringItem(name)
This function returns an object that implements the StringItem interface.
The name parameter is a String.
createIntegerItem(name)
This function returns an object that implements the IntegerItem interface.
The name parameter is a String.
createBooleanItem(name)
This function returns an object that implements the BooleanItem interface.
The name parameter is a String.
createContentItem(name)
This function returns an object that implements the ContentItem interface.
The name parameter is a String.
getItem(index)
This function has no return value.
The index parameter is a Number.
getNext()
This function returns a Boolean.
Properties of the Match Constructor function:
Match.IS_EQUAL
The value of the constant Match.IS_EQUAL is 0.
Match.IS_NOT_EQUAL
The value of the constant Match.IS_NOT_EQUAL is 1.
Match.INT_PRECEDES
The value of the constant Match.INT_PRECEDES is 2.
Match.INT_PRECEDES_OR_EQUALS
The value of the constant Match.INT_PRECEDES_OR_EQUALS is 3.
Match.INT_FOLLOWS
The value of the constant Match.INT_FOLLOWS is 4.
Match.INT_FOLLOWS_OR_EQUALS
The value of the constant Match.INT_FOLLOWS_OR_EQUALS is 5.
Match.STR_STARTS_WITH
The value of the constant Match.STR_STARTS_WITH is 6.
Match.STR_ENDS_WITH
The value of the constant Match.STR_ENDS_WITH is 7.
Match.STR_CONTAINS
The value of the constant Match.STR_CONTAINS is 8.
Match.SET_ANY
The value of the constant Match.SET_ANY is 9.
Match.SET_ALL
The value of the constant Match.SET_ALL is 10.
Match.SET_NOT_ANY
The value of the constant Match.SET_NOT_ANY is 11.
Match.SET_NOT_ALL
The value of the constant Match.SET_NOT_ALL is 12.
Objects that implement the Match interface:
Properties of objects that implement the Match interface:
test
This read-only property is a Number.
Objects that implement the MatchString interface:
Objects that implement the MatchString interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the MatchString interface:
name
This read-only property is a String.
value
This read-only property is a String.
Objects that implement the MatchInteger interface:
Objects that implement the MatchInteger interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the MatchInteger interface:
name
This read-only property is a String.
value
This read-only property is a Number.
Objects that implement the MatchBoolean interface:
Objects that implement the MatchBoolean interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the MatchBoolean interface:
name
This read-only property is a String.
value
This read-only property is a Boolean.
Objects that implement the MatchContent interface:
Objects that implement the MatchContent interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the MatchContent interface:
name
This read-only property is a String.
nodeArg
This read-only property is an object that implements the Node interface.
offset
This read-only property is a Number.
Objects that implement the MatchSet interface:
Objects that implement the MatchSet interface have all properties and functions of the Match interface as well as the properties and functions defined below.
Properties of objects that implement the MatchSet interface:
nodeArg
This read-only property is an object that implements the Node interface.
Functions of objects that implement the MatchSet interface:
addMatch(add)
This function has no return value.
The add parameter is an object that implements the Match interface.
getMatch(index)
This function returns an object that implements the Match interface.
The index parameter is a Number.
Objects that implement the Item interface:
Properties of objects that implement the Item interface:
exists
This read-only property is a Boolean.
name
This read-only property is a String.
Objects that implement the StringItem interface:
Objects that implement the StringItem interface have all properties and functions of the Item interface as well as the properties and functions defined below.
Properties of objects that implement the StringItem interface:
value
This read-only property is a String.
Objects that implement the IntegerItem interface:
Objects that implement the IntegerItem interface have all properties and functions of the Item interface as well as the properties and functions defined below.
Properties of objects that implement the IntegerItem interface:
value
This read-only property is a Number.
Objects that implement the BooleanItem interface:
Objects that implement the BooleanItem interface have all properties and functions of the Item interface as well as the properties and functions defined below.
Properties of objects that implement the BooleanItem interface:
value
This property is a Boolean.
Objects that implement the ContentItem interface:
Objects that implement the ContentItem interface have all properties and functions of the Item interface as well as the properties and functions defined below.
Properties of objects that implement the ContentItem interface:
nodeArg
This property is an object that implements the Node interface.
offset
This property is a Number.
Objects that implement the VisualView interface:
Properties of objects that implement the VisualView interface:
fontScheme
This read-only property is a String.
width
This read-only property is a Number.
height
This read-only property is a Number.
horizontalDPI
This read-only property is a Number.
verticalDPI
This read-only property is a Number.
Functions of objects that implement the VisualView interface:
createVisualCharacter()
This function returns an object that implements the VisualCharacter interface.
createVisualCharacterRun()
This function returns an object that implements the VisualCharacterRun interface.
createVisualFrame()
This function returns an object that implements the VisualFrame interface.
createVisualImage()
This function returns an object that implements the VisualImage interface.
createVisualFormButton()
This function returns an object that implements the VisualFormButton interface.
createVisualFormField()
This function returns an object that implements the VisualFormField interface.
select(boundary, offset, extend, add)
This function has no return value.
The boundary parameter is an object that implements the Node interface.
The offset parameter is a Number.
The extend parameter is a Boolean.
The add parameter is a Boolean.
matchSegment(segment)
This function has no return value.
The segment parameter is an object that implements the VisualResource interface.
Objects that implement the VisualResource interface:
Objects that implement the VisualFont interface:
Objects that implement the VisualFont interface have all properties and functions of the VisualResource interface as well as the properties and functions defined below.
Properties of objects that implement the VisualFont interface:
matchFontName
This property is a String.
exists
This read-only property is a Boolean.
fontName
This read-only property is a String.
Functions of objects that implement the VisualFont interface:
getNext()
This function returns a Boolean.
Objects that implement the VisualSegment interface:
Objects that implement the VisualSegment interface have all properties and functions of the VisualResource interface as well as the properties and functions defined below.
Properties of objects that implement the VisualSegment interface:
matchPosition
This property is a Boolean.
matchInside
This property is a Boolean.
matchContaining
This property is a Boolean.
matchX
This property is a Number.
matchY
This property is a Number.
matchXR
This property is a Number.
matchYR
This property is a Number.
matchContent
This property is a Boolean.
matchRange
This property is a Boolean.
matchNode
This property is an object that implements the Node interface.
matchOffset
This property is a Number.
matchNodeR
This property is an object that implements the Node interface.
matchOffsetR
This property is a Number.
matchContainsSelected
This property is a Boolean.
matchContainsVisible
This property is a Boolean.
exists
This read-only property is a Boolean.
startNode
This read-only property is an object that implements the Node interface.
startOffset
This read-only property is a Number.
endNode
This read-only property is an object that implements the Node interface.
endOffset
This read-only property is a Number.
topOffset
This read-only property is a Number.
bottomOffset
This read-only property is a Number.
leftOffset
This read-only property is a Number.
rightOffset
This read-only property is a Number.
width
This read-only property is a Number.
height
This read-only property is a Number.
selected
This read-only property is a Boolean.
visible
This read-only property is a Boolean.
foregroundColor
This read-only property is a Number.
backgroundColor
This read-only property is a Number.
fontName
This read-only property is a String.
fontHeight
This read-only property is a String.
Functions of objects that implement the VisualSegment interface:
getNext()
This function returns a Boolean.
Objects that implement the VisualCharacter interface:
Objects that implement the VisualCharacter interface have all properties and functions of the VisualSegment interface.
Objects that implement the VisualCharacterRun interface:
Objects that implement the VisualCharacterRun interface have all properties and functions of the VisualSegment interface.
Objects that implement the VisualFrame interface:
Objects that implement the VisualFrame interface have all properties and functions of the VisualSegment interface as well as the properties and functions defined below.
Properties of objects that implement the VisualFrame interface:
embedded
This read-only property is an object that implements the VisualSegment interface.
Objects that implement the VisualImage interface:
Objects that implement the VisualImage interface have all properties and functions of the VisualSegment interface as well as the properties and functions defined below.
Properties of objects that implement the VisualImage interface:
imageURL
This read-only property is a String.
isLoaded
This read-only property is a Boolean.
Objects that implement the VisualFormButton interface:
Objects that implement the VisualFormButton interface have all properties and functions of the VisualSegment interface as well as the properties and functions defined below.
Properties of objects that implement the VisualFormButton interface:
isPressed
This read-only property is a Boolean.
Objects that implement the VisualFormField interface:
Objects that implement the VisualFormField interface have all properties and functions of the VisualSegment interface as well as the properties and functions defined below.
Properties of objects that implement the VisualFormField interface:
formValue
This read-only property is a String.


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

The references listed in this section are normatives.

[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.


Index

addItem | addMatch
backgroundColor | BooleanItem | bottomOffset
ContentItem | createBooleanItem | createContentItem
createIntegerItem | createMatchBoolean | createMatchContent
createMatchInteger | createMatchSet | createMatchString
createSegment | createStringItem | createVisualCharacter
createVisualCharacterRun | createVisualFormButton | createVisualFormField
createVisualFrame | createVisualImage | criteria
ECMAScript | embedded | endNode
endOffset | exists 1, 2, 3
fontHeight | fontName 1, 2 | fontScheme
foregroundColor | formValue
getBooleanProperty | getContentPropertyNode | getContentPropertyOffset
getIntegerProperty | getItem | getMatch
getNext 1, 2, 3 | getStringProperty
height 1, 2 | horizontalDPI
imageURL | INT_FOLLOWS | INT_FOLLOWS_OR_EQUALS
INT_PRECEDES | INT_PRECEDES_OR_EQUALS | IntegerItem
IS_EQUAL | IS_NOT_EQUAL | isLoaded
isPressed | Item
Java
leftOffset
Match | MatchBoolean | matchContaining
matchContainsSelected | matchContainsVisible | MatchContent 1, 2
matchFirstSegment | matchFontName | matchInside
MatchInteger | matchNode | matchNodeR
matchOffset | matchOffsetR | matchPosition
matchRange | matchSegment | MatchSet
MatchString | matchX | matchXR
matchY | matchYR
name 1, 2, 3, 4, 5 | nodeArg 1, 2, 3
offset 1, 2 | OMG IDL | order
rightOffset
Segment | select 1, 2 | selected
SET_ALL | SET_ANY | SET_NOT_ALL
SET_NOT_ANY | startNode | startOffset
STR_CONTAINS | STR_ENDS_WITH | STR_STARTS_WITH
StringItem
test | topOffset
value 1, 2, 3, 4, 5, 6 | verticalDPI | View
visible | VisualCharacter | VisualCharacterRun
VisualFont | VisualFormButton | VisualFormField
VisualFrame | VisualImage | VisualResource
VisualSegment | VisualView
width 1, 2


Document Object Model (DOM) Level 3 Events Specification

Version 1.0

W3C Working Group Note 07 November 2003

This version:
http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107
Latest version:
http://www.w3.org/TR/DOM-Level-3-Events
Previous version:
http://www.w3.org/TR/2003/WD-DOM-Level-3-Events-20030331
Editors:
Philippe Le Hégaret, W3C
Tom Pixley, Netscape Communications Corporation (until July 2002)

This document is also available in these non-normative formats: XML file, plain text, PostScript file, PDF file, single HTML file, and ZIP file.

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

Abstract

This specification defines the Document Object Model Events Level 3, a generic platform- and language-neutral event system which allows registration of event handlers, describes event flow through a tree structure, and provides basic contextual information for each event. The Document Object Model Events Level 3 builds on the Document Object Model Events Level 2 [DOM Level 2 Events].

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 contains the Document Object Model Level 3 Events specification and is a W3C Working Group Note. It is based on the feedback during the Last Call period. The W3C DOM Working Group participants do not expect to provide interoperable implementations of this module. Implementation feedbacks are however welcome and have to be sent to the public mailing list www-dom@w3.org (public archive). Other W3C Working Groups may continue the work and provide implementations of this document.

Individuals or organizations are also invited to send a message to the public mailing list if they intend to produce an implementation of this module.

Publication as a Working Group Note 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.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.

Patent disclosures relevant to this specification may be found on the DOM Working Group's patent disclosure page.

Table of contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
  • 1. Document Object Model Events
  • Appendix A: Keyboard events and key identifiers
  • Appendix B: Changes
  • Appendix C: IDL Definitions
  • Appendix D: Java Language Binding
  • Appendix E: ECMAScript Language Binding
  • Appendix F: Acknowledgements
  • Glossary
  • References
  • Index


W3C Copyright Notices and Licenses

Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

This document is published under the W3C® Document Copyright Notice and License. The bindings within this document are published under the W3C® Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.

W3C® Document Copyright Notice and License

Note: This section is a copy of the W3C® Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231.

Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231

Public documents on the W3C site are provided by the copyright holders under the following license. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice (hypertext is preferred, but a textual representation is permitted) of the form: "Copyright © [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231"
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

W3C® Software Copyright Notice and License

Note: This section is a copy of the W3C® Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231

Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231

This work (and included software, documentation such as READMEs, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions.

Permission to copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C® Short Software Notice should be included (hypertext is preferred, text is permitted) within the body of any redistributed or derivative code.
  3. Notice of any changes or modifications to the files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

W3C® Short Software Notice

Note: This section is a copy of the W3C® Short Software Notice and could be found at http://www.w3.org/Consortium/Legal/2002/copyright-software-short-notice-20021231

Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved.

Copyright © [$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University). All Rights Reserved. This work is distributed under the W3C® Software License [1] in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

[1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231


Document Object Model Events

07 November 2003

1. Document Object Model Events

Editors:
Philippe Le Hégaret, W3C
Tom Pixley, Netscape Communications Corporation (until July 2002)

Table of contents

  • 1.1 Introduction
    • 1.1.1 Event flows
    • 1.1.2 Conformance
  • 1.2 DOM event flow
    • 1.2.1 Phases
    • 1.2.2 Event listeners
  • 1.3 Default actions and cancelable events
  • 1.4 Event types
    • 1.4.1 Event types and event categories
    • 1.4.2 Complete list of event types
    • 1.4.3 Compatibility with DOM Level 2 Events
  • 1.5 Event listener registration
    • 1.5.1 Using the EventTarget methods
    • 1.5.2 Using XML Events
    • 1.5.3 Using VoiceXML Events
    • 1.5.4 Using XML or HTML attributes
  • 1.6 Basic interfaces
    • Event, EventTarget, EventListener, EventException, EventExceptionCode
    • 1.6.1 Event creation
      • DocumentEvent, CustomEvent
  • 1.7 Event module definitions
    • 1.7.1 User Interface event types
      • UIEvent
    • 1.7.2 Text events types
      • TextEvent
    • 1.7.3 Mouse event types
      • MouseEvent
    • 1.7.4 Keyboard event types
      • KeyboardEvent
    • 1.7.5 Mutation and mutation name event types
      • MutationEvent, MutationNameEvent
    • 1.7.6 Basic event types
    • 1.7.7 HTML Events

1.1 Introduction

DOM Events is designed with two main goals. The first goal is the design of an event system which allows registration of event listeners and describes event flow through a tree structure. Additionally, the specification will provide standard modules of events for user interface control and document mutation notifications, including defined contextual information for each of these event modules.

The second goal of the DOM Events is to provide a common subset of the current event systems used in DOM Level 0 browsers. This is intended to foster interoperability of existing scripts and content. It is not expected that this goal will be met with full backwards compatibility. However, the specification attempts to achieve this when possible.

The following sections of the specification define both the specification for the DOM Event Model and a number of conformant event modules designed for use within the model. The DOM Event Model consists of:

  • The DOM event flow, which describe the flow of events in a tree-based structure.
  • A set of interfaces to access contextual information on events and to register event listeners.

1.1.1 Event flows

This document specifies an event flow for tree-based structures: DOM event flow. While it is expected that HTML and XML applications will follow this event flow, applications might reuse the interfaces defined in this document for non tree-based structures. In that case, it is the responsibility of such applications to define their event flow and how it relates to the DOM event flow. An example of such use can be found in [DOM Level 3 Load and Save].

1.1.2 Conformance

An implementation is DOM Level 3 Events conformant if it supports the Core module defined in [DOM Level 2 Core], the DOM event flow and the interfaces with their associated semantics defined in Basic interfaces. An implementation conforms to a DOM Level 3 Events module if it conforms to DOM Level 3 Events and the event types defined in the module. An implementation conforms to an event type if it conforms to its associated semantics and DOM interfaces. For example, an implementation conforms to the DOM Level 3 User Interface Events module (see User Interface event types) if it conforms to DOM Level 3 Events (i.e. implements all the basic interfaces), can generate the event types {"http://www.w3.org/2001/xml-events", "DOMActivate"} {"http://www.w3.org/2001/xml-events", "DOMFocusIn"} {"http://www.w3.org/2001/xml-events", "DOMFocusOut"} accordingly to their semantics, supports the UIEvent interface, and conforms to the DOM Level 2 Core module.

Note: An implementation which does not conform to an event module can still implement the DOM interfaces associated with it. The DOM application can then create an event object using the DocumentEvent.createEvent() method and dispatch an event type associated with this interface using the EventTarget.dispatchEvent() method.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "Events" and "3.0" (respectively) to determine whether or not DOM Level 3 Events is supported by the implementation. In order to fully support DOM Level 3 Events, an implementation must also support the "Core" feature defined in the DOM Level 2 Core specification [DOM Level 2 Core] and use the DOM event flow. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. DOM Level 3 Events is built on top of DOM Level 2 Events [DOM Level 2 Events], i.e. a DOM Level 3 Events implementation where hasFeature("Events", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

Each event module describes its own feature string in the event module listing.

1.2 DOM event flow

The DOM event flow is the process through which the event originates from the DOM Events implementation and is dispatched into a tree. Each event has an event target, a targeted node in the case of the DOM Event flow, toward which the event is dispatched by the DOM Events implementation.

1.2.1 Phases

The event is dispatched following a path from the root of the tree to this target node. It can then be handled locally at the target node level or from any target's ancestors higher in the tree. The event dispatching (also called event propagation) occurs in three phases and the following order:

  1. The capture phase: the event is dispatched to the target's ancestors from the root of the tree to the direct parent of the target node.
  2. The target phase: the event is dispatched to the target node.
  3. The bubbling phase: the event is dispatched to the target's ancestors from the direct parent of the target node to the root of the tree.
graphical representation of an event dispatched in a DOM tree using the DOM event flow

Figure: graphical representation of an event dispatched in a DOM tree using the DOM event flow [SVG 1.0 version]

Note: An SVG 1.0 version of the representation above is also available.

The target's ancestors are determined before the initial dispatch of the event. If the target node is removed during the dispatching, or a target's ancestor is added or removed, the event propagation will always be based on the target node and the target's ancestors determined before the dispatch.

Some events may not necessarily accomplish the three phases of the DOM event flow, e.g. the event could only be defined for one or two phases. As an example, events defined in this specification will always accomplish the capture and target phases but some will not accomplish the bubbling phase ("bubbling events" versus "non-bubbling events", see also the Event.bubbles attribute).

1.2.2 Event listeners

Each node encountered during the dispatch of the event may contain event listeners.

1.2.2.1 Registration of event listeners

Event listeners can be registered on all nodes in the tree for a specific type of event (Event types) or event category (Event types and event categories), phase, and group (Event groups).

If the event listener is being registered on a node while an event gets processed on this node, the event listener will not be triggered during the current phase but may be triggered during a later phase in the event flow, i.e. the bubbling phase.

1.2.2.2 Event groups

An event listener is always part of a group. It is either explicitly in a group if a group has been specified at the registration or implicitly in the default group if no group has been specified. Within a group, event listeners are ordered in their order of registration. If two event listeners {A1, A2}, which are part of the same group, are registered one after the other (A1, then A2) for the same phase, the DOM event flow guarantees their triggering order (A1, then A2). If the two listeners are not part of the same group, no specification is made as to the order in which they will be triggered.

In general, a DOM application does not need to define and use a separate group unless other event listeners, external to the DOM application, may change the event propagation (e.g. from a concurrent DOM application, from imported functionalities that rely on the event system, etc.).

Note: While this specification does not specify a full ordering (i.e. groups are still unordered), it does specify ordering within a group. This implies that if the event listeners {A1, A2, B1, B2}, with A and B being two different groups, are registered for the same phase in the order A1, A2, B1, and B2, the following triggering orders are possible and conform to the DOM event flow: {A1, A2, B1, B2}, {A1, B1, A2, B2}, {B1, A1, A2, B2}, {A1, B1, B2, A2}, {B1, A1, B2, A2}, {B1, B2, A1, A2}. DOM Events implementations may impose priorities on groups but DOM applications must not rely on it. Unlike this specification, [DOM Level 2 Events] did not specify any triggering order for event listeners.

1.2.2.3 Triggering an event listener

When the event is dispatched through the tree, from node to node, event listeners registered on the node are triggered if the following three conditions are all met:

  1. they were registered for the same type of event, or the same category.
  2. they were registered for the same phase;
  3. the event propagation has not been stopped for the group.

1.2.2.4 Removing an event listener

If an event listener is removed from a node while an event is being processed on the node, it will not be triggered by the current actions. Once removed, the event listener is never invoked again (unless registered again for future processing).

1.2.2.5 Reentrance

It is expected that actions taken by an event listener may cause additional events to be dispatched. Additional events should be handled in a synchronous manner and may cause reentrance into the event model. If an event listener fires a new event using EventTarget.dispatchEvent(), the event propagation that causes the event listener to be triggered will resume only after the event propagation of the new event is completed.

Since implementations may have restrictions such as stack-usage or other memory requirements, applications should not depend on how many synchronous events may be triggered.

1.2.2.6 Event propagation and event groups

All event listeners are part of a group (see Registration of event listeners). An event listener may prevent event listeners that are part of a same group from being triggered. The effect can be:

  • immediate: no more event listeners from the same group will be triggered by the event object (see Event.stopImmediatePropagation());
  • deferred until all event listeners from the same group have been triggered on the current node, i.e. the event listeners of the same group attached on other nodes will not be triggered (see Event.stopPropagation()).

If two event listeners are registered for two different groups, one cannot prevent the other from being triggered.

1.3 Default actions and cancelable events

Implementations may have a default action associated with an event type. An example is the [HTML 4.01] form element. When the user submits the form (e.g. by pressing on a submit button), the event {"http://www.w3.org/2001/xml-events", "submit"} is dispatched to the element and the default action for this event type is generally to send a request to a Web server with the parameters from the form.

The default actions are not part of the DOM Event flow. Before invoking a default action, the implementation must first dispatch the event as described in the DOM event flow.

A cancelable event is an event associated with a default action which is allowed to be canceled during the DOM event flow. At any phase during the event flow, the triggered event listeners have the option of canceling the default action or allowing the default action to proceed. In the case of the hyperlink in the browser, canceling the action would have the result of not activating the hyperlink. Not all events defined in this specification are cancelable events.

Different implementations will specify their own default actions, if any, associated with each event. The DOM Events specification does not attempt to specify these actions.

This specification does not provide mechanisms for accessing default actions or adding new ones.

Note: Some implementations also provide default actions before the dispatch of the event. It is not possible to cancel those default actions and this specification does not address them. An example of such default actions can be found in [DOM Level 2 HTML] on the HTMLInputElement.checked attribute.

1.4 Event types

Each event is associated with a type, called event type. The event type is composed of a local name and a namespace URI as used in [DOM Level 3 Core]. All events defined in this specification use the namespace URI "http://www.w3.org/2001/xml-events".

1.4.1 Event types and event categories

An event type could be part of one or more categories. A category is represented using a local name and a namespace URI as defined in [XML Namespaces]. The event types defined in this specification are not associated with one or more event categories and this specification does not provide methods to associate them. Other specifications may create and associate event categories with event listeners but in such case would need to inform the dispatch mechanism of those event categories. An example of the use of categories is given at Using VoiceXML Events.

1.4.2 Complete list of event types

Depending on the level of DOM support, or the devices used for display (e.g. screen) or interaction (e.g. mouse, keyboard, touch screen, voice, ...), these event types can be generated by the implementation. When used with an [XML 1.0] or [HTML 4.01] application, the specifications of those languages may restrict the semantics and scope (in particular the possible target nodes) associated with an event type. For example, {"http://www.w3.org/2001/xml-events", "click"} can be targeted to all [XHTML 1.0] elements except applet, base, basefont, bdo, br, font, frame, frameset, head, html, iframe, isindex, meta, param, script, style, and title. Refer to the specification defining the language used in order to find those restrictions or to find event types that are not defined in this document.

The following list defines all event types (with the exception of two event types preserved for backward compatibility with [HTML 4.01], see HTML Events) provided in this specification. All event types defined in this specification are bound to the namespace URI "http://www.w3.org/2001/xml-events" and the following list only enumerates the local name of the event type.

DOMActivate
An element is activated, for instance, using a mouse device, a keyboard device, or a voice command.

Note: The activation of an element is device dependent but is also application dependent, e.g. a link in a document can be activated using a mouse click or a mouse double click.

DOMFocusIn
An event target receives focus, for instance via a pointing device being moved onto an element or using keyboard navigation. The focus is given to the element before the dispatch of this event type.
DOMFocusOut
A event target loses focus, for instance via a pointing device being moved out of an element or by tabbing navigation out of the element. The focus is taken from the element before the dispatch of this event type.
textInput
One or more characters have been entered. The characters can originate from a variety of sources. For example, it could be characters resulting from a key being pressed or released on a keyboard device, characters resulting from the processing of an input method editor, or resulting from a voice command. Where a "paste" operation generates a simple sequence of characters, i.e. a text without any structure or style information, this event type should be generated as well.
click
A pointing device button is clicked over an element. The definition of a click depends on the environment configuration; i.e. may depend on the screen location or the delay between the press and release of the pointing device button. In any case, the target node must be the same between the mousedown, mouseup, and click. The sequence of these events is: {"http://www.w3.org/2001/xml-events", "mousedown"}, {"http://www.w3.org/2001/xml-events", "mouseup"}, and {"http://www.w3.org/2001/xml-events", "click"}. Note that, given the definition of a click, If one or more of the event types {"http://www.w3.org/2001/xml-events", "mouseover"}, {"http://www.w3.org/2001/xml-events", "mousemove"}, and {"http://www.w3.org/2001/xml-events", "mouseout"} occur between the press and release of the pointing device button, the event type {"http://www.w3.org/2001/xml-events", "click"} cannot occur. In the case of nested elements, this event type is always targeted at the most deeply nested element.
mousedown
A pointing device button is pressed over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element.
mouseup
A pointing device button is released over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element.
mouseover
A pointing device is moved onto an element. In the case of nested elements, this event type is always targeted at the most deeply nested element.
mousemove
A pointing device is moved while it is over an element. In the case of nested elements, this event type is always targeted at the most deeply nested element.
mouseout
A pointing device is moved away from an element. In the case of nested elements, this event type is always targeted at the most deeply nested element.
keydown
A key is pressed down. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of an input method editor. This event should logically happen before the event {"http://www.w3.org/2001/xml-events", "keyup"} is produced. Whether a keydown contributes or not to the generation of a text event is implementation dependent.
keyup
A key is released. This event type is device dependent and relies on the capabilities of the input devices and how they are mapped in the operating system. This event type is generated after the keyboard mapping but before the processing of an input method editor. This event should logically happen after the event {"http://www.w3.org/2001/xml-events", "keydown"} is produced. Whether a keyup contributes or not to the generation of a text event is implementation dependent.
DOMSubtreeModified
This is a general event for notification of all changes to the document. It can be used instead of the more specific events listed below. It may be dispatched after a single modification to the document or, at the implementation's discretion, after multiple changes have occurred. The latter use should generally be used to accommodate multiple changes which occur either simultaneously or in rapid succession. The target of this event is the lowest common parent of the changes which have taken place. This event is dispatched after any other events caused by the mutation(s) have occurred.
DOMNodeInserted
A node has been added as a child of another node. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted.
DOMNodeRemoved
A node is being removed from its parent node. This event is dispatched before the node is removed from the tree. The target node of this event is the node being removed.
DOMNodeRemovedFromDocument
A node is being removed from a document, either through direct removal of the node or removal of a subtree in which it is contained. This event is dispatched before the removal takes place. The target node of this event type is the node being removed. If the node is being directly removed, the event type {"http://www.w3.org/2001/xml-events", "DOMNodeRemoved"} will fire before this event type.
DOMNodeInsertedIntoDocument
A node is being inserted into a document, either through direct insertion of the node or insertion of a subtree in which it is contained. This event is dispatched after the insertion has taken place. The target node of this event is the node being inserted. If the node is being directly inserted, the event type {"http://www.w3.org/2001/xml-events", "DOMNodeInserted"} will fire before this event type.
DOMAttrModified
Occurs after an Attr has been modified on a node. The target node of this event is the parent Element node whose Attr changed. It is expected that string based replacement of an Attr value will be viewed as a modification of the Attr since its identity does not change. Subsequently replacement of the Attr node with a different Attr node is viewed as the removal of the first Attr node and the addition of the second.
DOMCharacterDataModified
Occurs after CharacterData.data or ProcessingInstruction.data have been modified but the node itself has not been inserted or deleted. The target node of this event is the CharacterData node or the ProcessingInstruction node.
DOMElementNameChanged
Occurs after the namespaceURI and/or the nodeName of an Element node have been modified (e.g., the element was renamed using Document.renameNode()). The target of this event is the renamed Element node.
DOMAttributeNameChanged
Occurs after the namespaceURI and/or the nodeName of a Attr node have been modified (e.g., the attribute was renamed using Document.renameNode). The target of this event is the parent Element node whose Attr has been renamed.
load
The DOM Implementation finishes loading the resource (such as the document) and any dependent resources (such as images, style sheets, or scripts). Dependent resources that fail to load will not prevent this event from firing if the resource that loaded them is still accessible via the DOM. If this event type is dispatched, implementations are required to dispatch this event at least on the Document node.
unload
The DOM implementation removes from the environment the resource (such as the document) or any dependent resources (such as images, style sheets, scripts). The document is unloaded after the dispatch of this event type. If this event type is dispatched, implementations are required to dispatch this event at least on the Document node.
abort
The loading of the document, or a resource linked from it, is stopped before being entirely loaded.
error
The document, or a resource linked from it, has been loaded but cannot be interpreted according to its semantic, such as an invalid image, a script execution error, or non-well-formed XML.
select
A user selects some text. DOM Level 3 Events does not provide contextual information to access the selected text. The selection occured before the dispatch of this event type.
change
A control loses the input focus and its value has been modified since gaining focus.
submit
A form, such as [HTML 4.01], [XHTML 1.0], or [XForms 1.0] form, is submitted.
reset
A form, such as [HTML 4.01], [XHTML 1.0], or [XForms 1.0] form, is reset.
resize
A document view or an element has been resized. The resize occured before the dispatch of this event type.
scroll
A document view or an element has been scrolled. The scroll occured before the dispatch of this event type.

The following table provides additional information on the event types. All events will accomplish the capture and target phases, but not all of them will accomplish the bubbling phase (see also DOM event flow). Some events are not cancelable (see Default actions and cancelable events). Some events will only be dispatched to a specific set of possible targets, specified using node types. Contextual information related to the event type is accessible using DOM interfaces.

type | Bubbling phase | Cancelable | Target node types | DOM interface
DOMActivate | Yes | Yes | Element | UIEvent
DOMFocusIn | Yes | No | Element | UIEvent
DOMFocusOut | Yes | No | Element | UIEvent
textInput | Yes | Yes | Element | TextEvent
click | Yes | Yes | Element | MouseEvent
mousedown | Yes | Yes | Element | MouseEvent
mouseup | Yes | Yes | Element | MouseEvent
mouseover | Yes | Yes | Element | MouseEvent
mousemove | Yes | Yes | Element | MouseEvent
mouseout | Yes | Yes | Element | MouseEvent
keydown | Yes | Yes | Element | KeyboardEvent
keyup | Yes | Yes | Element | KeyboardEvent
DOMSubtreeModified | Yes | No | Document, DocumentFragment, Element, Attr | MutationEvent
DOMNodeInserted | Yes | No | Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction | MutationEvent
DOMNodeRemoved | Yes | No | Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction | MutationEvent
DOMNodeRemovedFromDocument | No | No | Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction | MutationEvent
DOMNodeInsertedIntoDocument | No | No | Element, Attr, Text, Comment, CDATASection, DocumentType, EntityReference, ProcessingInstruction | MutationEvent
DOMAttrModified | Yes | No | Element | MutationEvent
DOMCharacterDataModified | Yes | No | Text, Comment, CDATASection, ProcessingInstruction | MutationEvent
DOMElementNameChanged | Yes | No | Element | MutationNameEvent
DOMAttributeNameChanged | Yes | No | Element | MutationNameEvent
load | No | No | Document, Element | Event
unload | No | No | Document, Element | Event
abort | Yes | No | Element | Event
error | Yes | No | Element | Event
select | Yes | No | Element | Event
change | Yes | No | Element | Event
submit | Yes | Yes | Element | Event
reset | Yes | Yes | Element | Event
resize | Yes | No | Document, Element | UIEvent
scroll | Yes | No | Document, Element | UIEvent

As an example, the event {"http://www.w3.org/2001/xml-events", "load"} will trigger event listeners attached on Element nodes for that event and on the capture and target phases. This event cannot be cancelled. If an event listener for the load event is attached to a node other than Element nodes, or if it is attached to the bubbling phase only, this event listener cannot be triggered.

The event objects associated with the event types described above may contain context information. Refer to the description of the DOM interfaces for further information.

1.4.3 Compatibility with DOM Level 2 Events

Namespace URIs were only introduced in DOM Level 3 Events and were not part of DOM Level 2 Events. DOM Level 2 Events methods are namespace ignorant and the event type is only represented by an XML name, specified in the Event.type attribute.

Therefore, while it is safe to use these methods when not dealing with namespaces, using them and the new ones at the same time should be avoided. DOM Level 2 Events methods solely identify events by their Event.type. On the contrary, the namespaces aware DOM Level 3 Events methods, identify attribute nodes by their Event.namespaceURI and Event.type. Because of this fundamental difference, mixing both sets of methods can lead to unpredictable results. For example, using EventTarget.addEventListenerNS(namespaceURI, type, listener, ...), two event listeners (or more) could be registered using the same type and same useCapture values, but different namespaceURIs. Calling EventTarget.removeEventListener(type, listener, ...) with that type and useCapture could then remove any or none of those event listeners. The result depends on the implementation. The only guarantee in such cases is that all methods which access an event listener by its namespaceURI and type will access the same event listener. For instance, EventTarget.removeEventListenerNS(namespaceURI, type, listener, ...) removes the event that EventTarget.addEventListenerNS(namespaceURI, type, listener, ...) added.

For compatibility reasons, the dispatching of an event will ignore namespace URIs if either the event or the event listener has a null namespace URI. If a DOM Level 2 event (i.e. with a null namespace URI) is dispatched in the DOM tree, all event listeners that match the type will be triggered as described in the DOM event flow. If a DOM Level 3 event (i.e. with a namespace URI) is dispatched in the DOM tree, all event listeners with the same type and the same or null namespace URI will be triggered as described in the DOM event flow.

1.5 Event listener registration

Note: This section is informative.

There are mainly two ways to associate an event listener to a node in the tree:

  1. at the programming level using the EventTarget methods.
  2. at the document level using [XML Events] or an ad-hoc syntax, as the ones provided in [XHTML 1.0] or [SVG 1.1].

1.5.1 Using the EventTarget methods

The user can attach an event listener using the methods on the EventTarget interface:

myCircle.addEventListenerNS("http://www.w3.org/2001/xml-events",
                            "DOMActivate",
                            myListener,
                            true,
                            null);

The methods do not provide the ability to register the same event listener more than once for the same event type and the same phase. It is not possible to register an event listener:

  • for only one of the target and bubbling phases since those phases are coupled during the registration (but the listener itself could ignore events during one of these phases if desired).
  • for a specific event category.

To register an event listener, DOM applications must use the methods EventTarget.addEventListener() and EventTarget.addEventListenerNS().

An EventListener being registered on an EventTarget may choose to have that EventListener triggered during the capture phase by specifying the useCapture parameter of the EventTarget.addEventListener() or EventTarget.addEventListenerNS() methods to be true. If false, the EventListener will be triggered during the target and bubbling phases.

1.5.2 Using XML Events

In [XML Events], event listeners are attached using elements and attributes:

<listener event="DOMActivate" observer="myCircle" handler="#myListener"
          phase="capture" propagate="stop"/>

Event listeners can only be registered on Element nodes, i.e. other Node types are not addressable, and cannot be registered for a specific group either, i.e. they are always attached to the default group. The target phase and the bubbling phase are coupled during the registration. [XML Events] does not address namespaces in event types. If the value of the event attribute of the listener element contains a colon (':'), it should be interpreted as a QName as defined in [XML Schema Part 2].

1.5.3 Using VoiceXML Events

In [VoiceXML 2.0], event listeners are attached using elements:

<form>
  <field>
    <prompt>Please say something</prompt>
    <catch event="error.noauthorization">
     <prompt>You don't have the authorization!</prompt>
    </catch>
    <catch event="connection.disconnect.hangup">
     <prompt>Connection error</prompt>
    </catch>
    <catch event="connection.disconnect">
     <prompt>Connection error</prompt>
    </catch>
  </field>
  <catch event="error">
    <prompt>Unknown error</prompt>
  </catch>
</form>

Event listeners can only be registered on Element nodes, i.e. other Node types are not addressable, and cannot be registered for a specific group either, i.e. they are always attached to the default group. The target phase and the bubbling phase are coupled during the registration. [VoiceXML 2.0] does not address namespaces in event types but uses the notion of event categories. The event type "connection.disconnect.hangup" could be associated to the event categories {"http://www.example.org/2003/voicexml", "connection"} and {"http://www.example.org/2003/voicexml", "connection.disconnect"}.

1.5.4 Using XML or HTML attributes

In languages such as [HTML 4.01], [XHTML 1.0], or [SVG 1.1], event listeners are specified as attributes:

<circle id="myCircle" onactivate="myListener(evt)"
        cx="300" cy="225" r="100" fill="red"/>

Since only one attribute with the same name can appear on an element, it is therefore not possible to register more than one event listener on a single EventTarget for the event type. Also, event listeners can only be registered on Element nodes for the target phase and bubbling phase, i.e. other Node types and the capture phase are not addressable with these languages. Event listeners cannot be registered for a specific group either, i.e. they are always attached to the default group.

In order to achieve compatibility with those languages, implementors may view the setting of attributes which represent event handlers as the creation and registration of an EventListener on the EventTarget. The value of useCapture defaults to false. This EventListener behaves in the same manner as any other EventListeners which may be registered on the EventTarget. If the attribute representing the event listener is changed, this may be viewed as the removal of the previously registered EventListener and the registration of a new one. Furthermore, no specification is made as to the order in which event attributes will receive the event with regards to the other EventListeners on the EventTarget.

1.6 Basic interfaces

The interfaces described in this section are fundamental to DOM Level 3 Events and must always be supported by the implementation.

Interface Event (introduced in DOM Level 2)

The Event interface is used to provide contextual information about an event to the listener processing the event. An object which implements the Event interface is passed as the parameter to an EventListener. More specific context information is passed to event listeners by deriving additional interfaces from Event which contain information directly relating to the type of event they represent. These derived interfaces are also implemented by the object passed to the event listener.

To create an instance of the Event interface, use the DocumentEvent.createEvent("Event") method call.

IDL Definition
// Introduced in DOM Level 2:
interface Event {

  // PhaseType
  const unsigned short      CAPTURING_PHASE                = 1;
  const unsigned short      AT_TARGET                      = 2;
  const unsigned short      BUBBLING_PHASE                 = 3;

  readonly attribute DOMString       type;
  readonly attribute EventTarget     target;
  readonly attribute EventTarget     currentTarget;
  readonly attribute unsigned short  eventPhase;
  readonly attribute boolean         bubbles;
  readonly attribute boolean         cancelable;
  readonly attribute DOMTimeStamp    timeStamp;
  void               stopPropagation();
  void               preventDefault();
  void               initEvent(in DOMString eventTypeArg,
                               in boolean canBubbleArg,
                               in boolean cancelableArg);
  // Introduced in DOM Level 3:
  readonly attribute DOMString       namespaceURI;
  // Introduced in DOM Level 3:
  boolean            isCustom();
  // Introduced in DOM Level 3:
  void               stopImmediatePropagation();
  // Introduced in DOM Level 3:
  boolean            isDefaultPrevented();
  // Introduced in DOM Level 3:
  void               initEventNS(in DOMString namespaceURIArg,
                                 in DOMString eventTypeArg,
                                 in boolean canBubbleArg,
                                 in boolean cancelableArg);
};

Definition group PhaseType

An integer indicating which phase of the event flow is being processed as defined in DOM event flow.

Defined Constants
AT_TARGET
The current event is in the target phase, i.e. it is being evaluated at the event target.
BUBBLING_PHASE
The current event phase is the bubbling phase.
CAPTURING_PHASE
The current event phase is the capture phase.
Attributes
bubbles of type boolean, readonly
Used to indicate whether or not an event is a bubbling event. If the event can bubble the value is true, otherwise the value is false.
cancelable of type boolean, readonly
Used to indicate whether or not an event can have its default action prevented (see also Default actions and cancelable events). If the default action can be prevented the value is true, otherwise the value is false.
currentTarget of type EventTarget, readonly
Used to indicate the EventTarget whose EventListeners are currently being processed. This is particularly useful during the capture and bubbling phases. This attribute could contain the target node or a target ancestor when used with the DOM event flow.
eventPhase of type unsigned short, readonly
Used to indicate which phase of event flow is currently being accomplished.
namespaceURI of type DOMString, readonly, introduced in DOM Level 3
The namespace URI associated with this event at creation time, or null if it is unspecified.
For events initialized with a DOM Level 2 Events method, such as Event.initEvent(), this is always null.
target of type EventTarget, readonly
Used to indicate the event target. This attribute contains the target node when used with the DOM event flow.
timeStamp of type DOMTimeStamp, readonly
Used to specify the time (in milliseconds relative to the epoch) at which the event was created. Due to the fact that some systems may not provide this information the value of timeStamp may be not available for all events. When not available, a value of 0 will be returned. Examples of epoch time are the time of the system start or 0:0:0 UTC 1st January 1970.
type of type DOMString, readonly
The name should be an NCName as defined in [XML Namespaces] and is case-sensitive.
If the attribute Event.namespaceURI is different from null, this attribute represents a local name.
Methods
initEvent
The initEvent method is used to initialize the value of an Event created through the DocumentEvent.createEvent method. This method may only be called before the Event has been dispatched via the EventTarget.dispatchEvent() method. If the method is called several times before invoking EventTarget.dispatchEvent, only the final invocation takes precedence. This method has no effect if called after the event has been dispatched. If called from a subclass of the Event interface only the values specified in this method are modified, all other attributes are left unchanged.
This method sets the Event.type attribute to eventTypeArg, and Event.namespaceURI to null. To initialize an event with a namespace URI, use the Event.initEventNS(namespaceURIArg, eventTypeArg, ...) method.
Parameters
eventTypeArg of type DOMString
Specifies Event.type.
canBubbleArg of type boolean
Specifies Event.bubbles. This parameter overrides the intrinsic bubbling behavior of the event.
cancelableArg of type boolean
Specifies Event.cancelable. This parameter overrides the intrinsic cancelable behavior of the event.

No Return Value
No Exceptions
initEventNS introduced in DOM Level 3
The initEventNS method is used to initialize the value of an Event object and has the same behavior as Event.initEvent().
Parameters
namespaceURIArg of type DOMString
Specifies Event.namespaceuRI, the namespace URI associated with this event, or null if no namespace.
eventTypeArg of type DOMString
Specifies Event.type, the local name of the event type.
canBubbleArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.

No Return Value
No Exceptions
isCustom introduced in DOM Level 3
This method will always return false, unless the event implements the CustomEvent interface.
Return Value

boolean

false, unless the event object implements the CustomEvent interface.

No Parameters
No Exceptions
isDefaultPrevented introduced in DOM Level 3
This method will return true if the method Event.preventDefault() has been called for this event, false otherwise.
Return Value

boolean

true if Event.preventDefault() has been called for this event.

No Parameters
No Exceptions
preventDefault
If an event is cancelable, the preventDefault method is used to signify that the event is to be canceled, meaning any default action normally taken by the implementation as a result of the event will not occur (see also Default actions and cancelable events), and thus independently of event groups. Calling this method for a non-cancelable event has no effect.

Note: This method does not stop the event propagation; use stopPropagation or stopImmediatePropagation for that effect.

No Parameters
No Return Value
No Exceptions
stopImmediatePropagation introduced in DOM Level 3
This method is used to prevent event listeners of the same group to be triggered and, unlike stopPropagation its effect is immediate (see Event propagation and event groups). Once it has been called, further calls to that method have no additional effect.

Note: This method does not prevent the default action from being invoked; use Event.preventDefault() for that effect.

No Parameters
No Return Value
No Exceptions
stopPropagation
This method is used to prevent event listeners of the same group to be triggered but its effect is deferred until all event listeners attached on the currentTarget have been triggered (see Event propagation and event groups). Once it has been called, further calls to that method have no additional effect.

Note: This method does not prevent the default action from being invoked; use preventDefault for that effect.

No Parameters
No Return Value
No Exceptions
Interface EventTarget (introduced in DOM Level 2)

The EventTarget interface is implemented by all the objects which could be event targets in an implementation which supports the Event flows. The interface allows registration, removal or query of event listeners, and dispatch of events to an event target.

When used with DOM event flow, this interface is implemented by all target nodes and target ancestors, i.e. all DOM Nodes of the tree support this interface when the implementation conforms to DOM Level 3 Events and, therefore, this interface can be obtained by using binding-specific casting methods on an instance of the Node interface.

Invoking addEventListener or addEventListenerNS multiple times on the same EventTarget with the same parameters (namespaceURI, type, listener, and useCapture) is considered to be a no-op and thus independently of the event group. They do not cause the EventListener to be called more than once and do not cause a change in the triggering order. In order to guarantee that an event listener will be added to the event target for the specified event group, one needs to invoke removeEventListener or removeEventListenerNS first.

IDL Definition
// Introduced in DOM Level 2:
interface EventTarget {
  void               addEventListener(in DOMString type,
                                      in EventListener listener,
                                      in boolean useCapture);
  void               removeEventListener(in DOMString type,
                                         in EventListener listener,
                                         in boolean useCapture);
  // Modified in DOM Level 3:
  boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
  // Introduced in DOM Level 3:
  void               addEventListenerNS(in DOMString namespaceURI,
                                        in DOMString type,
                                        in EventListener listener,
                                        in boolean useCapture,
                                        in DOMObject evtGroup);
  // Introduced in DOM Level 3:
  void               removeEventListenerNS(in DOMString namespaceURI,
                                           in DOMString type,
                                           in EventListener listener,
                                           in boolean useCapture);
  // Introduced in DOM Level 3:
  boolean            willTriggerNS(in DOMString namespaceURI,
                                   in DOMString type);
  // Introduced in DOM Level 3:
  boolean            hasEventListenerNS(in DOMString namespaceURI,
                                        in DOMString type);
};

Methods
addEventListener
This method allows the registration of an event listener in the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
Parameters
type of type DOMString
Specifies the Event.type associated with the event for which the user is registering.
listener of type EventListener
The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.
useCapture of type boolean
If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.

No Return Value
No Exceptions
addEventListenerNS introduced in DOM Level 3
This method allows the registration of an event listener in a specified group or the default group and, depending on the useCapture parameter, on the capture phase of the DOM event flow or its target and bubbling phases.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event for which the user is registering.
type of type DOMString
Specifies the Event.type associated with the event for which the user is registering.
listener of type EventListener
The listener parameter takes an object implemented by the user which implements the EventListener interface and contains the method to be called when the event occurs.
useCapture of type boolean
If true, useCapture indicates that the user wishes to add the event listener for the capture phase only, i.e. this event listener will not be triggered during the target and bubbling phases. If false, the event listener will only be triggered during the target and bubbling phases.
evtGroup of type DOMObject
The object that represents the event group to associate with the EventListener (see also Event propagation and event groups). Use null to attach the event listener to the default group.
No Return Value
No Exceptions
dispatchEvent modified in DOM Level 3
This method allows the dispatch of events into the implementation's event model. The event target of the event is the EventTarget object on which dispatchEvent is called.
Parameters
evt of type Event
The event to be dispatched.
Return Value

boolean

Indicates whether any of the listeners which handled the event called Event.preventDefault(). If Event.preventDefault() was called the returned value is false, else it is true.

Exceptions

EventException

UNSPECIFIED_EVENT_TYPE_ERR: Raised if the Event.type was not specified by initializing the event before dispatchEvent was called. Specification of the Event.type as null or an empty string will also trigger this exception.

DISPATCH_REQUEST_ERR: Raised if the Event object is already being dispatched in the tree.

NOT_SUPPORTED_ERR: Raised if the Event object has not been created using DocumentEvent.createEvent() or does not support the interface CustomEvent.

hasEventListenerNS introduced in DOM Level 3
This method allows the DOM application to know if this EventTarget contains an event listener registered for the specified event type. This is useful for determining at which nodes within a hierarchy altered handling of specific event types has been introduced, but should not be used to determine whether the specified event type triggers an event listener (see EventTarget.willTriggerNS()).
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event.
type of type DOMString
Specifies the Event.type associated with the event.
Return Value

boolean

true if an event listener is registered on this EventTarget for the specified event type, false otherwise.

No Exceptions
removeEventListener
This method allows the removal of event listeners from the default group.
Calling removeEventListener with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.
Parameters
type of type DOMString
Specifies the Event.type for which the user registered the event listener.
listener of type EventListener
The EventListener to be removed.
useCapture of type boolean
Specifies whether the EventListener being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture phase and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture phase does not affect the same event listener registered for the target and bubbling phases, and vice versa.

No Return Value
No Exceptions
removeEventListenerNS introduced in DOM Level 3
This method allows the removal of an event listener, independently of the associated event group.
Calling removeEventListenerNS with arguments which do not identify any currently registered EventListener on the EventTarget has no effect.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event for which the user registered the event listener.
type of type DOMString
Specifies the Event.type associated with the event for which the user registered the event listener.
listener of type EventListener
The EventListener parameter indicates the EventListener to be removed.
useCapture of type boolean
Specifies whether the EventListener being removed was registered for the capture phase or not. If a listener was registered twice, once for the capture phase and once for the target and bubbling phases, each must be removed separately. Removal of an event listener registered for the capture phase does not affect the same event listener registered for the target and bubbling phases, and vice versa.

No Return Value
No Exceptions
willTriggerNS introduced in DOM Level 3
This method allows the DOM application to know if an event listener, attached to this EventTarget or one of its ancestors, will be triggered by the specified event type during the dispatch of the event to this event target or one of its descendants.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI associated with the event.
type of type DOMString
Specifies the Event.type associated with the event.
Return Value

boolean

true if an event listener will be triggered on the EventTarget with the specified event type, false otherwise.

No Exceptions
Interface EventListener (introduced in DOM Level 2)

The EventListener interface is the primary way for handling events. Users implement the EventListener interface and register their event listener on an EventTarget. The users should also remove their EventListener from its EventTarget after they have completed using the listener.

Copying a Node, with methods such as Node.cloneNode or Range.cloneContents, does not copy the event listeners attached to it. Event listeners must be attached to the newly created Node afterwards if so desired.

Moving a Node, with methods Document.adoptNode, Node.appendChild, or Range.extractContents, does not affect the event listeners attached to it.

IDL Definition
// Introduced in DOM Level 2:
interface EventListener {
  void               handleEvent(in Event evt);
};

Methods
handleEvent
This method is called whenever an event occurs of the event type for which the EventListener interface was registered.
Parameters
evt of type Event
The Event contains contextual information about the event.

No Return Value
No Exceptions
Exception EventException introduced in DOM Level 2

Event operations may throw an EventException as specified in their method descriptions.

IDL Definition
// Introduced in DOM Level 2:
exception EventException {
  unsigned short   code;
};
// EventExceptionCode
const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;
// Introduced in DOM Level 3:
const unsigned short      DISPATCH_REQUEST_ERR           = 1;

Definition group EventExceptionCode

An integer indicating the type of error generated.

Defined Constants
DISPATCH_REQUEST_ERR, introduced in DOM Level 3.
If the Event object is already dispatched in the tree.
UNSPECIFIED_EVENT_TYPE_ERR
If the Event.type was not specified by initializing the event before the method was called. Specification of the Event.type as null or an empty string will also trigger this exception.

1.6.1 Event creation

In most cases, the events dispatched by the DOM Events implementation are also created by the implementation. It is however possible to simulate events such as mouse events by creating the Event objects and dispatch them using the DOM Events implementation.

DOM Events provides two ways for creating Event objects. An application can either create Event objects that are known to the implementation, or create its own objects and have them dispatched by the DOM Events implementation.

Creating Event objects that are known to the DOM Events implementation is done using DocumentEvent.createEvent(). The application must then initialize the object by calling the appropriate initialization method before invoking EventTarget.dispatchEvent(). The Event objects created must be known by the DOM Events implementation; otherwise an event exception is thrown.

The DOM application might want to create its own Event objects, in order to change the default Event implementation provided by the DOM Events implementation or to generate new event types with specific contextual information. In any case, the application is responsible for creating and initializing the Event object. The application can then dispatch the event using the DOM Events implementation by using EventTarget.dispatchEvent().

However, the DOM Events implementation requires to have access to two attributes in the Event object in order to accomplish the dispatch appropriately: Event.currentTarget and Event.eventPhase. Those attributes are defined as readonly in the Event interface since event listeners must not change them and it is the responsibility of the DOM Events implementation to update them during the event flow. Therefore, implementing the Event interface when creating its own events is not enough for an application since the DOM Events implementation will not be able to update the current phase and the current node during the dispatch, unless the event object also implements the CustomEvent interface to give access to the relevant attributes.

Interface DocumentEvent (introduced in DOM Level 2)

The DocumentEvent interface provides a mechanism by which the user can create an Event object of a type supported by the implementation. If the feature "Events" is supported by the Document object, the DocumentEvent interface must be implemented on the same object. If the feature "+Events" is supported by the Document object, an object that supports the DocumentEvent interface must be returned by invoking the method Node.getFeature("+Events", "3.0") on the Document object.

IDL Definition
// Introduced in DOM Level 2:
interface DocumentEvent {
  Event              createEvent(in DOMString eventType)
                                        raises(DOMException);
  // Introduced in DOM Level 3:
  boolean            canDispatch(in DOMString namespaceURI,
                                 in DOMString type);
};

Methods
canDispatch introduced in DOM Level 3
Test if the implementation can generate events of a specified type.
Parameters
namespaceURI of type DOMString
Specifies the Event.namespaceURI of the event.
type of type DOMString
Specifies the Event.type of the event.
Return Value

boolean

true if the implementation can generate and dispatch this event type, false otherwise.

No Exceptions
createEvent
Parameters
eventType of type DOMString
The eventType parameter specifies the name of the DOM Events interface to be supported by the created event object, e.g. "Event", "MouseEvent", "MutationEvent" and so on. If the Event is to be dispatched via the EventTarget.dispatchEvent() method the appropriate event init method must be called after creation in order to initialize the Event's values.
As an example, a user wishing to synthesize some kind of UIEvent would invoke DocumentEvent.createEvent("UIEvent"). The UIEvent.initUIEventNS() method could then be called on the newly created UIEvent object to set the specific type of user interface event to be dispatched, {"http://www.w3.org/2001/xml-events", "DOMActivate"} for example, and set its context information, e.g. UIEvent.detail in this example.
The createEvent method is used in creating Events when it is either inconvenient or unnecessary for the user to create an Event themselves. In cases where the implementation provided Event is insufficient, users may supply their own Event implementations for use with the EventTarget.dispatchEvent() method. However, the DOM implementation needs access to the attributes Event.currentTarget and Event.eventPhase to appropriately propagate the event in the DOM tree. Therefore users' Event implementations might need to support the CustomEvent interface for that effect.

Note: For backward compatibility reason, "UIEvents", "MouseEvents", "MutationEvents", and "HTMLEvents" feature names are valid values for the parameter eventType and represent respectively the interfaces "UIEvent", "MouseEvent", "MutationEvent", and "Event".

Return Value

Event

The newly created event object.

Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if the implementation does not support the Event interface requested.

Interface CustomEvent (introduced in DOM Level 3)

The CustomEvent interface gives access to the attributes Event.currentTarget and Event.eventPhase. It is intended to be used by the DOM Events implementation to access the underlying current target and event phase while dispatching a custom Event in the tree; it is also intended to be implemented, and not used, by DOM applications.

The methods contained in this interface are not intended to be used by a DOM application, especially during the dispatch on the Event object. Changing the current target or the current phase may result in unpredictable results of the event flow. The DOM Events implementation should ensure that both methods return the appropriate current target and phase before invoking each event listener on the current target to protect DOM applications from malicious event listeners.

Note: If this interface is supported by the event object, Event.isCustom() must return true.

IDL Definition
// Introduced in DOM Level 3:
interface CustomEvent : Event {
  void               setDispatchState(in EventTarget target,
                                      in unsigned short phase);
  boolean            isPropagationStopped();
  boolean            isImmediatePropagationStopped();
};

Methods
isImmediatePropagationStopped
The isImmediatePropagationStopped method is used by the DOM Events implementation to know if the method stopImmediatePropagation() has been called for this event. It returns true if the method has been called, false otherwise.
Return Value

boolean

true if the event propagation has been stopped immediately in the current group.

No Parameters
No Exceptions
isPropagationStopped
This method will return true if the method stopPropagation() has been called for this event, false in any other cases.
Return Value

boolean

true if the event propagation has been stopped in the current group.

No Parameters
No Exceptions
setDispatchState
The setDispatchState method is used by the DOM Events implementation to set the values of Event.currentTarget and Event.eventPhase. It also reset the states of isPropagationStopped and isImmediatePropagationStopped.
Parameters
target of type EventTarget
Specifies the new value for the Event.currentTarget attribute.
phase of type unsigned short
Specifies the new value for the Event.eventPhase attribute.
No Return Value
No Exceptions

1.7 Event module definitions

The DOM Event Model allows a DOM implementation to support multiple modules of events. The model has been designed to allow addition of new event modules if required. The DOM will not attempt to define all possible events. For purposes of interoperability, the DOM defines a module of user interface events including lower level device dependent events and a module of document mutation events.

1.7.1 User Interface event types

The User Interface event module contains basic event types associated with user interfaces.

Interface UIEvent (introduced in DOM Level 2)

The UIEvent interface provides specific contextual information associated with User Interface events.

To create an instance of the UIEvent interface, use the DocumentEvent.createEvent("UIEvent") method call.

IDL Definition
// Introduced in DOM Level 2:
interface UIEvent : Event {
  readonly attribute views::AbstractView view;
  readonly attribute long            detail;
  void               initUIEvent(in DOMString typeArg,
                                 in boolean canBubbleArg,
                                 in boolean cancelableArg,
                                 in views::AbstractView viewArg,
                                 in long detailArg);
  // Introduced in DOM Level 3:
  void               initUIEventNS(in DOMString namespaceURI,
                                   in DOMString typeArg,
                                   in boolean canBubbleArg,
                                   in boolean cancelableArg,
                                   in views::AbstractView viewArg,
                                   in long detailArg);
};

Attributes
detail of type long, readonly
Specifies some detail information about the Event, depending on the type of event.
view of type views::AbstractView, readonly
The view attribute identifies the AbstractView from which the event was generated.
Methods
initUIEvent
The initUIEvent method is used to initialize the value of a UIEvent object and has the same behavior as Event.initEvent().
Parameters
typeArg of type DOMString
Refer to the Event.initEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.
viewArg of type views::AbstractView
Specifies UIEvent.view.
detailArg of type long
Specifies UIEvent.detail.

No Return Value
No Exceptions
initUIEventNS introduced in DOM Level 3
The initUIEventNS method is used to initialize the value of a UIEvent object and has the same behavior as Event.initEventNS().
Parameters
namespaceURI of type DOMString
Refer to the Event.initEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the Event.initEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the Event.initEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the Event.initEventNS() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
detailArg of type long
Refer to the UIEvent.initUIEvent() method for a description of this parameter.

No Return Value
No Exceptions

The User Interface event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "UIEvents" and "3.0" (respectively) to determine whether or not the DOM Level 3 User Interface event types are supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification and the "Views" feature defined in the DOM Level 2 Views specification [DOM Level 2 Views]. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. The DOM Level 3 User Interface Events module is built on top of the DOM Level 2 User Interface Events [DOM Level 2 Events] module, i.e. a DOM Level 3 User Interface Events implementation where hasFeature("UIEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

type | Context information
DOMActivate | UIEvent.view is in use.
DOMFocusIn | (same as above)
DOMFocusOut | (same as above)

1.7.2 Text events types

The text event module originates from the [HTML 4.01] onkeypress attribute. Unlike this attribute, the event type {"http://www.w3.org/2001/xml-events", "textInput"} applies only to characters and is designed for use with any text input devices, not just keyboards. Refer to Appendix A, "Keyboard events and key identifiers", for examples on how text events are used in combination with keyboard events.

Interface TextEvent (introduced in DOM Level 3)

The TextEvent interface provides specific contextual information associated with Text Events.

To create an instance of the TextEvent interface, use the DocumentEvent.createEvent("TextEvent") method call.

IDL Definition
// Introduced in DOM Level 3:
interface TextEvent : UIEvent {
  readonly attribute DOMString       data;
  void               initTextEvent(in DOMString typeArg,
                                   in boolean canBubbleArg,
                                   in boolean cancelableArg,
                                   in views::AbstractView viewArg,
                                   in DOMString dataArg);
  void               initTextEventNS(in DOMString namespaceURI,
                                     in DOMString type,
                                     in boolean canBubbleArg,
                                     in boolean cancelableArg,
                                     in views::AbstractView viewArg,
                                     in DOMString dataArg);
};

Attributes
data of type DOMString, readonly
data holds the value of the characters generated by the character device. This may be a single Unicode character or a non-empty sequence of Unicode characters [Unicode]. Characters should be normalized as defined by the Unicode normalization form NFC, defined in [UTR #15]. This attribute cannot be null or contain the empty string.
Methods
initTextEvent
The initTextEvent method is used to initialize the value of a TextEvent object and has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.
Parameters
typeArg of type DOMString
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
dataArg of type DOMString
Specifies TextEvent.data.
No Return Value
No Exceptions
initTextEventNS
The initTextEventNS method is used to initialize the value of a TextEvent object and has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined.
Parameters
namespaceURI of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
type of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
dataArg of type DOMString
Refer to the TextEvent.initTextEvent() method for a description of this parameter.
No Return Value
No Exceptions

The text event type is listed below. For a full description of the semantics associated with this event type, refer to the Complete list of event types. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "TextEvents" and "3.0" (respectively) to determine whether or not the Text event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core].

type | Context information
textInput | UIEvent.view and TextEvent.data are in use.

1.7.3 Mouse event types

The Mouse event module originates from the [HTML 4.01] onclick, ondblclick, onmousedown, onmouseup, onmouseover, onmousemove, and onmouseout attributes. This event module is specifically designed for use with pointing input devices, such as a mouse or a trackball.

Interface MouseEvent (introduced in DOM Level 2)

The MouseEvent interface provides specific contextual information associated with Mouse events.

In the case of nested elements mouse events are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within theirs descendent elements.

To create an instance of the MouseEvent interface, use the DocumentEvent.createEvent("MouseEvent") method call.

Note: When initializing MouseEvent objects using initMouseEvent or initMouseEventNS, implementations should use the client coordinates clientX and clientY for calculation of other coordinates (such as target coordinates exposed by DOM Level 0 implementations).

IDL Definition
// Introduced in DOM Level 2:
interface MouseEvent : UIEvent {
  readonly attribute long            screenX;
  readonly attribute long            screenY;
  readonly attribute long            clientX;
  readonly attribute long            clientY;
  readonly attribute boolean         ctrlKey;
  readonly attribute boolean         shiftKey;
  readonly attribute boolean         altKey;
  readonly attribute boolean         metaKey;
  readonly attribute unsigned short  button;
  readonly attribute EventTarget     relatedTarget;
  void               initMouseEvent(in DOMString typeArg,
                                    in boolean canBubbleArg,
                                    in boolean cancelableArg,
                                    in views::AbstractView viewArg,
                                    in long detailArg,
                                    in long screenXArg,
                                    in long screenYArg,
                                    in long clientXArg,
                                    in long clientYArg,
                                    in boolean ctrlKeyArg,
                                    in boolean altKeyArg,
                                    in boolean shiftKeyArg,
                                    in boolean metaKeyArg,
                                    in unsigned short buttonArg,
                                    in EventTarget relatedTargetArg);
  // Introduced in DOM Level 3:
  boolean            getModifierState(in DOMString keyIdentifierArg);
  // Introduced in DOM Level 3:
  void               initMouseEventNS(in DOMString namespaceURI,
                                      in DOMString typeArg,
                                      in boolean canBubbleArg,
                                      in boolean cancelableArg,
                                      in views::AbstractView viewArg,
                                      in long detailArg,
                                      in long screenXArg,
                                      in long screenYArg,
                                      in long clientXArg,
                                      in long clientYArg,
                                      in unsigned short buttonArg,
                                      in EventTarget relatedTargetArg,
                                      in DOMString modifiersList);
};

Attributes
altKey of type boolean, readonly
true if the alt (alternative) key modifier is activated.

Note: The Option key modifier on Macintosh systems must be represented using this key modifier.

button of type unsigned short, readonly
During mouse events caused by the depression or release of a mouse button, button is used to indicate which mouse button changed state. 0 indicates the normal button of the mouse (in general on the left or the one button on Macintosh mice, used to activate a button or select text). 2 indicates the contextual property (in general on the right, used to display a context menu) button of the mouse if present. 1 indicates the extra (in general in the middle and often combined with the mouse wheel) button. Some mice may provide or simulate more buttons, and values higher than 2 can be used to represent such buttons.
clientX of type long, readonly
The horizontal coordinate at which the event occurred relative to the DOM implementation's client area.
clientY of type long, readonly
The vertical coordinate at which the event occurred relative to the DOM implementation's client area.
ctrlKey of type boolean, readonly
true if the control (Ctrl) key modifier is activated.
metaKey of type boolean, readonly
true if the meta (Meta) key modifier is activated.

Note: The Command key modifier on Macintosh system must be represented using this meta key.

relatedTarget of type EventTarget, readonly
Used to identify a secondary EventTarget related to a UI event. Currently this attribute is used with the mouseover event to indicate the EventTarget which the pointing device exited and with the mouseout event to indicate the EventTarget which the pointing device entered.
screenX of type long, readonly
The horizontal coordinate at which the event occurred relative to the origin of the screen coordinate system.
screenY of type long, readonly
The vertical coordinate at which the event occurred relative to the origin of the screen coordinate system.
shiftKey of type boolean, readonly
true if the shift (Shift) key modifier is activated.
Methods
getModifierState introduced in DOM Level 3
This methods queries the state of a modifier using a key identifier. See also Modifier keys.
Parameters
keyIdentifierArg of type DOMString
A modifier key identifier, as defined by the KeyboardEvent.keyIdentifier attribute. Common modifier keys are "Alt", "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift".

Note: If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and KeyboardEvent.keyLocation.

Return Value

boolean

true if it is modifier key and the modifier is activated, false otherwise.

No Exceptions
initMouseEvent
The initMouseEvent method is used to initialize the value of a MouseEvent object and has the same behavior as UIEvent.initUIEvent().
Parameters
typeArg of type DOMString
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
detailArg of type long
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
screenXArg of type long
Specifies MouseEvent.screenX.
screenYArg of type long
Specifies MouseEvent.screenY.
clientXArg of type long
Specifies MouseEvent.clientX.
clientYArg of type long
Specifies MouseEvent.clientY.
ctrlKeyArg of type boolean
Specifies MouseEvent.ctrlKey.
altKeyArg of type boolean
Specifies MouseEvent.altKey.
shiftKeyArg of type boolean
Specifies MouseEvent.shiftKey.
metaKeyArg of type boolean
Specifies MouseEvent.metaKey.
buttonArg of type unsigned short
Specifies MouseEvent.button.
relatedTargetArg of type EventTarget
Specifies MouseEvent.relatedTarget.

No Return Value
No Exceptions
initMouseEventNS introduced in DOM Level 3
The initMouseEventNS method is used to initialize the value of a MouseEvent object and has the same behavior as UIEvent.initUIEventNS().
Parameters
namespaceURI of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
detailArg of type long
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
screenXArg of type long
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
screenYArg of type long
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
clientXArg of type long
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
clientYArg of type long
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
buttonArg of type unsigned short
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
relatedTargetArg of type EventTarget
Refer to the MouseEvent.initMouseEvent() method for a description of this parameter.
modifiersList of type DOMString
A white space separated list of modifier key identifiers to be activated on this object. As an example, "Control Alt" will activated the control and alt modifiers.

No Return Value
No Exceptions

The Mouse event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types. In the case of nested elements, mouse event types are always targeted at the most deeply nested element. Ancestors of the targeted element may use bubbling to obtain notification of mouse events which occur within its descendent elements.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MouseEvents" and "3.0" (respectively) to determine whether or not the Mouse event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. The DOM Level 3 Mouse Events module is built on top of the DOM Level 2 Mouse Events [DOM Level 2 Events] module, i.e. a DOM Level 3 Mouse Events implementation where hasFeature("MouseEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

type | Context information
click | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, MouseEvent.button, and UIEvent.view are in use. The UIEvent.detail attribute indicates the number of consecutive clicks of a pointing device button during a user action. The attribute value is 1 when the user begins this action and increments by 1 for each click. The notion of consecutive clicks depends on the environment configuration. For example, a "double click" will not happen if there is a long delay between the two clicks, even if the pointing device did not move.
mousedown | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, MouseEvent.button, and UIEvent.view are in use. The UIEvent.detail attribute indicates the number of consecutive clicks, incremented by one, of a pointing device button during a user action. For example, if no click happened before the mousedown, UIEvent.detail will contain the value 1.
mouseup | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, MouseEvent.button, and UIEvent.view are in use. The UIEvent.detail attribute indicates the number of consecutive clicks, incremented by one, of a pointing device button during a user action.
mouseover | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, and UIEvent.view are in use. MouseEvent.relatedTarget indicates the event target a pointing device is exiting.
mousemove | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, and UIEvent.view are in use.
mouseout | MouseEvent.screenX, MouseEvent.screenY, MouseEvent.clientX, MouseEvent.clientY, MouseEvent.altKey, MouseEvent.ctrlKey, MouseEvent.shiftKey, MouseEvent.metaKey, MouseEvent.altGraphKey, and UIEvent.view are in use. MouseEvent.relatedTarget indicates the event target a pointing device is entering.

As an example, a "double-click" on a mouse device will produce the following events (the value of UIEvent.detail is indicated in parenthesis):

  1. {"http://www.w3.org/2001/xml-events", "mousedown"} (1)
  2. {"http://www.w3.org/2001/xml-events", "mouseup"} (1)
  3. {"http://www.w3.org/2001/xml-events", "click"} (1)
  4. {"http://www.w3.org/2001/xml-events", "mousedown"} (2)
  5. {"http://www.w3.org/2001/xml-events", "mouseup"} (2)
  6. {"http://www.w3.org/2001/xml-events", "click"} (2)

1.7.4 Keyboard event types

Keyboard events are device dependent, i.e. they rely on the capabilities of the input devices and how they are mapped in the operating systems. It is therefore highly recommended to rely on Text events types when dealing with character input.

Interface KeyboardEvent (introduced in DOM Level 3)

The KeyboardEvent interface provides specific contextual information associated with keyboard devices. Each keyboard event references a key using an identifier. Keyboard events are commonly directed at the element that has the focus.

The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. These attributes are equivalent to use the method KeyboardEvent.getModifierState(keyIdentifierArg) with "Control", "Shift", "Alt", or "Meta" respectively.

To create an instance of the KeyboardEvent interface, use the DocumentEvent.createEvent("KeyboardEvent") method call.

IDL Definition
// Introduced in DOM Level 3:
interface KeyboardEvent : UIEvent {

  // KeyLocationCode
  const unsigned long       DOM_KEY_LOCATION_STANDARD      = 0x00;
  const unsigned long       DOM_KEY_LOCATION_LEFT          = 0x01;
  const unsigned long       DOM_KEY_LOCATION_RIGHT         = 0x02;
  const unsigned long       DOM_KEY_LOCATION_NUMPAD        = 0x03;

  readonly attribute DOMString       keyIdentifier;
  readonly attribute unsigned long   keyLocation;
  readonly attribute boolean         ctrlKey;
  readonly attribute boolean         shiftKey;
  readonly attribute boolean         altKey;
  readonly attribute boolean         metaKey;
  boolean            getModifierState(in DOMString keyIdentifierArg);
  void               initKeyboardEvent(in DOMString typeArg,
                                       in boolean canBubbleArg,
                                       in boolean cancelableArg,
                                       in views::AbstractView viewArg,
                                       in DOMString keyIdentifierArg,
                                       in unsigned long keyLocationArg,
                                       in DOMString modifiersList);
  void               initKeyboardEventNS(in DOMString namespaceURI,
                                         in DOMString typeArg,
                                         in boolean canBubbleArg,
                                         in boolean cancelableArg,
                                         in views::AbstractView viewArg,
                                         in DOMString keyIdentifierArg,
                                         in unsigned long keyLocationArg,
                                         in DOMString modifiersList);
};

Definition group KeyLocationCode

This set of constants is used to indicate the location of a key on the device. In case a DOM implementation wishes to provide a new location information, a value different from the following constant values must be used.

Defined Constants
DOM_KEY_LOCATION_LEFT
The key activated is in the left key location (there is more than one possible location for this key). Example: the left Shift key on a PC 101 Key US keyboard.
DOM_KEY_LOCATION_NUMPAD
The key activation originated on the numeric keypad or with a virtual key corresponding to the numeric keypad. Example: the '1' key on a PC 101 Key US keyboard located on the numeric pad.
DOM_KEY_LOCATION_RIGHT
The key activation is in the right key location (there is more than one possible location for this key). Example: the right Shift key on a PC 101 Key US keyboard.
DOM_KEY_LOCATION_STANDARD
The key activation is not distinguished as the left or right version of the key, and did not originate from the numeric keypad (or did not originate with a virtual key corresponding to the numeric keypad). Example: the 'Q' key on a PC 101 Key US keyboard.
Attributes
altKey of type boolean, readonly
true if the alternative (Alt) key modifier is activated.

Note: The Option key modifier on Macintosh systems must be represented using this key modifier.

ctrlKey of type boolean, readonly
true if the control (Ctrl) key modifier is activated.
keyIdentifier of type DOMString, readonly
keyIdentifier holds the identifier of the key. The key identifiers are defined in Appendix A.2 "Key identifiers set". Implementations that are unable to identify a key must use the key identifier "Unidentified".
keyLocation of type unsigned long, readonly
The keyLocation attribute contains an indication of the location of they key on the device, as described in Keyboard event types.
metaKey of type boolean, readonly
true if the meta (Meta) key modifier is activated.

Note: The Command key modifier on Macintosh systems must be represented using this key modifier.

shiftKey of type boolean, readonly
true if the shift (Shift) key modifier is activated.
Methods
getModifierState
This methods queries the state of a modifier using a key identifier. See also Modifier keys.
Parameters
keyIdentifierArg of type DOMString
A modifier key identifier. Common modifier keys are "Alt", "AltGraph", "CapsLock", "Control", "Meta", "NumLock", "Scroll", or "Shift".

Note: If an application wishes to distinguish between right and left modifiers, this information could be deduced using keyboard events and KeyboardEvent.keyLocation.

Return Value

boolean

true if it is modifier key and the modifier is activated, false otherwise.

No Exceptions
initKeyboardEvent
The initKeyboardEvent method is used to initialize the value of a KeyboardEvent object and has the same behavior as UIEvent.initUIEvent(). The value of UIEvent.detail remains undefined.
Parameters
typeArg of type DOMString
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEvent() method for a description of this parameter.
keyIdentifierArg of type DOMString
Specifies KeyboardEvent.keyIdentifier.
keyLocationArg of type unsigned long
Specifies KeyboardEvent.keyLocation.
modifiersList of type DOMString
A white space separated list of modifier key identifiers to be activated on this object.
No Return Value
No Exceptions
initKeyboardEventNS
The initKeyboardEventNS method is used to initialize the value of a KeyboardEvent object and has the same behavior as UIEvent.initUIEventNS(). The value of UIEvent.detail remains undefined.
Parameters
namespaceURI of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
viewArg of type views::AbstractView
Refer to the UIEvent.initUIEventNS() method for a description of this parameter.
keyIdentifierArg of type DOMString
Refer to the KeyboardEvent.initKeyboardEvent() method for a description of this parameter.
keyLocationArg of type unsigned long
Refer to the KeyboardEvent.initKeyboardEvent() method for a description of this parameter.
modifiersList of type DOMString
A white space separated list of modifier key identifiers to be activated on this object. As an example, "Control Alt" will activated the control and alt modifiers.
No Return Value
No Exceptions

Depending on the character generation device, keyboard events may or may not be generated.

The keyboard event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "KeyboardEvents" and "3.0" (respectively) to determine whether or not the Keyboard event module is supported by the implementation. In order to fully support this module, an implementation must also support the "UIEvents" feature defined in this specification. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core].

type | Context information
keydown | UIEvent.view, KeyboardEvent.keyIdentifier, KeyboardEvent.location, KeyboardEvent.altKey, KeyboardEvent.altGraphKey, KeyboardEvent.shiftKey, KeyboardEvent.ctrlKey, and KeyboardEvent.metaKey are in use.
keyup | UIEvent.view, KeyboardEvent.keyIdentifier, and KeyboardEvent.location are in use. KeyboardEvent.altKey, KeyboardEvent.altGraphKey, KeyboardEvent.shiftKey, KeyboardEvent.ctrlKey, and KeyboardEvent.metaKey are in use unless the Keyboard.keyIdentifier corresponds to the key modifier itself.

1.7.5 Mutation and mutation name event types

The mutation and mutation name event modules are designed to allow notification of any changes to the structure of a document, including attribute, text, or name modifications. It may be noted that none of the event types associated with the modules are designated as cancelable. This stems from the fact that it is very difficult to make use of existing DOM interfaces which cause document modifications if any change to the document might or might not take place due to cancelation of the resulting event. Although this is still a desired capability, it was decided that it would be better left until the addition of transactions into the DOM.

Many single modifications of the tree can cause multiple mutation events to be dispatched. Rather than attempt to specify the ordering of mutation events due to every possible modification of the tree, the ordering of these events is left to the implementation.

Interface MutationEvent (introduced in DOM Level 2)

The MutationEvent interface provides specific contextual information associated with Mutation events.

To create an instance of the MutationEvent interface, use the DocumentEvent.createEvent("MutationEvent") method call.

IDL Definition
// Introduced in DOM Level 2:
interface MutationEvent : Event {

  // attrChangeType
  const unsigned short      MODIFICATION                   = 1;
  const unsigned short      ADDITION                       = 2;
  const unsigned short      REMOVAL                        = 3;

  readonly attribute Node            relatedNode;
  readonly attribute DOMString       prevValue;
  readonly attribute DOMString       newValue;
  readonly attribute DOMString       attrName;
  readonly attribute unsigned short  attrChange;
  void               initMutationEvent(in DOMString typeArg,
                                       in boolean canBubbleArg,
                                       in boolean cancelableArg,
                                       in Node relatedNodeArg,
                                       in DOMString prevValueArg,
                                       in DOMString newValueArg,
                                       in DOMString attrNameArg,
                                       in unsigned short attrChangeArg);
  // Introduced in DOM Level 3:
  void               initMutationEventNS(in DOMString namespaceURI,
                                         in DOMString typeArg,
                                         in boolean canBubbleArg,
                                         in boolean cancelableArg,
                                         in Node relatedNodeArg,
                                         in DOMString prevValueArg,
                                         in DOMString newValueArg,
                                         in DOMString attrNameArg,
                                         in unsigned short attrChangeArg);
};

Definition group attrChangeType

An integer indicating in which way the Attr was changed.

Defined Constants
ADDITION
The Attr was just added.
MODIFICATION
The Attr was modified in place.
REMOVAL
The Attr was just removed.
Attributes
attrChange of type unsigned short, readonly
attrChange indicates the type of change which triggered the {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event. The values can be MODIFICATION, ADDITION, or REMOVAL.
attrName of type DOMString, readonly
attrName indicates the name of the changed Attr node in a {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event.
newValue of type DOMString, readonly
newValue indicates the new value of the Attr node in {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the CharacterData node in {"http://www.w3.org/2001/xml-events", "DOMCharacterDataModified"} events.
prevValue of type DOMString, readonly
prevValue indicates the previous value of the Attr node in {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} events, and of the CharacterData node in {"http://www.w3.org/2001/xml-events", "DOMCharacterDataModified"} events.
relatedNode of type Node, readonly
relatedNode is used to identify a secondary node related to a mutation event. For example, if a mutation event is dispatched to a node indicating that its parent has changed, the relatedNode is the changed parent. If an event is instead dispatched to a subtree indicating a node was changed within it, the relatedNode is the changed node. In the case of the {"http://www.w3.org/2001/xml-events", "DOMAttrModified"} event it indicates the Attr node which was modified, added, or removed.
Methods
initMutationEvent
The initMutationEvent method is used to initialize the value of a MutationEvent object and has the same behavior as Event.initEvent().
Parameters
typeArg of type DOMString
Refer to the Event.initEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the Event.initEvent() method for a description of this parameter.
relatedNodeArg of type Node
Specifies MutationEvent.relatedNode.
prevValueArg of type DOMString
Specifies MutationEvent.prevValue. This value may be null.
newValueArg of type DOMString
Specifies MutationEvent.newValue. This value may be null.
attrNameArg of type DOMString
Specifies MutationEvent.attrname. This value may be null.
attrChangeArg of type unsigned short
Specifies MutationEvent.attrChange. This value may be null.

No Return Value
No Exceptions
initMutationEventNS introduced in DOM Level 3
The initMutationEventNS method is used to initialize the value of a MutationEvent object and has the same behavior as Event.initEventNS().
Parameters
namespaceURI of type DOMString
Refer to the Event.initEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the Event.initEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the Event.initEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the Event.initEventNS() method for a description of this parameter.
relatedNodeArg of type Node
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
prevValueArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
newValueArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
attrNameArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
attrChangeArg of type unsigned short
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

No Return Value
No Exceptions

The mutation event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationEvents" and "3.0" (respectively) to determine whether or not the MutationEvent is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. This MutationEvent interface is built on top of the DOM Level 2 Mutation Events [DOM Level 2 Events] module, i.e. a DOM Level 3 MutationEvent interface implementation where hasFeature("MutationEvents","3.0") returns true must also return true when the version number is "2.0", "" or, null.

type | Context information
DOMSubtreeModified | None
DOMNodeInserted | MutationEvent.relatedNode holds the parent node of the node being inserted.
DOMNodeRemoved | MutationEvent.relatedNode holds the parent node of the node being removed.
DOMNodeRemovedFromDocument | None
DOMNodeInsertedIntoDocument | None
DOMAttrModified | MutationEvent.attrName is in use. The value of MutationEvent.relatedNode indicates the Attr node whose value has been affected. The value of MutationEvent.attrChange indicates whether the Attr was modified, added, or removed. If the Attr node is being added, MutationEvent.newValue is in use. If the Attr node is being removed, MutationEvent.prevValue is in value. If the Attr node is being modified, MutationEvent.newValue and MutationEvent.prevValue are in use.
DOMCharacterDataModified | MutationEvent.prevValue, and MutationEvent.newValue are in use.
Interface MutationNameEvent (introduced in DOM Level 3)

The MutationNameEvent interface provides specific contextual information associated with Mutation name event types.

To create an instance of the MutationNameEvent interface, use the Document.createEvent("MutationNameEvent") method call.

IDL Definition
// Introduced in DOM Level 3:
interface MutationNameEvent : MutationEvent {
  readonly attribute DOMString       prevNamespaceURI;
  readonly attribute DOMString       prevNodeName;
  // Introduced in DOM Level 3:
  void               initMutationNameEvent(in DOMString typeArg,
                                           in boolean canBubbleArg,
                                           in boolean cancelableArg,
                                           in Node relatedNodeArg,
                                           in DOMString prevNamespaceURIArg,
                                           in DOMString prevNodeNameArg);
  // Introduced in DOM Level 3:
  void               initMutationNameEventNS(in DOMString namespaceURI,
                                             in DOMString typeArg,
                                             in boolean canBubbleArg,
                                             in boolean cancelableArg,
                                             in Node relatedNodeArg,
                                             in DOMString prevNamespaceURIArg,
                                             in DOMString prevNodeNameArg);
};

Attributes
prevNamespaceURI of type DOMString, readonly
The previous value of the relatedNode's namespaceURI.
prevNodeName of type DOMString, readonly
The previous value of the relatedNode's nodeName.
Methods
initMutationNameEvent introduced in DOM Level 3
The initMutationNameEvent method is used to initialize the value of a MutationNameEvent object and has the same behavior as MutationEvent.initMutationEvent().
Parameters
typeArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
cancelableArg of type boolean
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
relatedNodeArg of type Node
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
prevNamespaceURIArg of type DOMString
Specifies MutationNameEvent.prevNamespaceURI. This value may be null.
prevNodeNameArg of type DOMString
Specifies MutationNameEvent.prevNodeName.

No Return Value
No Exceptions
initMutationNameEventNS introduced in DOM Level 3
The initMutationNameEventNS method is used to initialize the value of a MutationNameEvent object and has the same behavior as MutationEvent.initMutationEventNS().
Parameters
namespaceURI of type DOMString
Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.
typeArg of type DOMString
Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.
canBubbleArg of type boolean
Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.
cancelableArg of type boolean
Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.
relatedNodeArg of type Node
Refer to the MutationEvent.initMutationEventNS() method for a description of this parameter.
prevNamespaceURIArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.
prevNodeNameArg of type DOMString
Refer to the MutationEvent.initMutationEvent() method for a description of this parameter.

No Return Value
No Exceptions

The mutation name event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types. A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "MutationNameEvents" and "3.0" (respectively) to determine whether or not the MutationNameEvent is supported by the implementation. In order to fully support this module, an implementation must also support the "MutationEvents" feature defined in this specification and the "Core" feature defined in the DOM Level 3 Core specification [DOM Level 3 Core]. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core].

type | Context information
DOMElementNameChanged | MutationNameEvent.prevNamespaceURI, and MutationNameEvent.prevNodeName are in use.
DOMAttributeNameChanged | MutationNameEvent.prevNamespaceURI, and MutationNameEvent.prevNodeName are in use. The value of MutationEvent.relatedNode contains the renamed Attr node.

1.7.6 Basic event types

This event module contains basic event types associated with document manipulation.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "BasicEvents" and "3.0" (respectively) to determine whether or not the basic event module is supported by the implementation. In order to fully support this module, an implementation must also support the "Events" feature defined in this specification. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core].

The basic event types are listed below. For a full description of the semantics associated with these event types, refer to the Complete list of event types.

The event types {"http://www.w3.org/2001/xml-events", "resize"} and {"http://www.w3.org/2001/xml-events", "scroll"} implement the UIEvent interface. All other HTML event types implement at least the basic Event interface. However, they may be generated from a user interface; in that case, the event objects also implements the UIEvent interface and UIEvent.view is in use.

type | Context information
load | UIEvent.view may be in use.
unload | (same as above)
abort | (same as above)
error | (same as above)
select | (same as above)
change | (same as above)
submit | (same as above)
reset | (same as above)
resize | UIEvent.view is in use.
scroll | UIEvent.view is in use.

1.7.7 HTML Events

The HTML event module is composed of events listed in [HTML 4.01] and additional events which are supported in DOM Level 0 browsers. It refines the semantics and scope of the basic event types and provides two new event types. This event module is only applicable if the Document supports the [DOM Level 2 HTML] specification. Use Node.isSupported(feature, version) with the parameter values "HTML" and "2.0" (respectively) to determine whether or not the Document node supports the HTML module.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "HTMLEvents" and "3.0" (respectively) to determine whether or not the HTML event module is supported by the implementation. In order to fully support this module, an implementation must also support the "BasicEvents" feature defined in this specification and the "HTML" feature defined in [DOM Level 2 HTML]. For additional information about conformance, please see the DOM Level 3 Core specification [DOM Level 3 Core]. The DOM Level 3 HTML Events module is built on top of the DOM Level 2 HTML Events [DOM Level 2 Events] module, i.e. a DOM Level 3 HTML Events implementation where hasFeature("HTMLEvents", "3.0") returns true must also return true when the version number is "2.0", "" or, null.

The following descriptions of event types are refinements of the general descriptions provided in Complete list of event types, with the addition of the events {"http://www.w3.org/2001/xml-events", "focus"} and {"http://www.w3.org/2001/xml-events", "blur"}. All events types are bound to the namespace URI "http://www.w3.org/2001/xml-events" and the following list only enumerates the local name of the event type.

load
The DOM implementation finishes loading all content within the BODY element, all frames within a FRAMESET, or any resource linked from the document.
unload
The DOM implementation removes a document from a window or frame. This event is valid for BODY and FRAMESET elements.
abort
The page loading is stopped before an image has been allowed to completely load. This event applies to OBJECT elements.
error
An image does not load properly or when an error occurs during script execution. This event is valid for OBJECT elements, BODY elements, and FRAMESET element.
select
A user selects some text in a text field either via the user interface or via attributes defined in [DOM Level 2 HTML]. This event is valid for INPUT and TEXTAREA elements.
change
A control loses the input focus and its value has been modified since gaining focus. This event can occur either via a user interface manipulation or the focus() methods and the attributes defined in [DOM Level 2 HTML]. This event is valid for INPUT, SELECT, and TEXTAREA element.
submit
A form is submitted either via a button. This event only applies to the FORM element. Note that the HTMLFormElement.submit() method defined in [DOM Level 2 HTML] does not fire this event type.
reset
A form is reset either via a button, or the HTMLFormElement.reset() method defined in [DOM Level 2 HTML]. This event only applies to the FORM element.
resize
see resize in Complete list of event types.
scroll
see scroll in Complete list of event types.
focus
An element receives focus either via a pointing device, the focus() methods defined in [DOM Level 2 HTML], or by tabbing navigation. This event is only valid for the following elements: A, AREA, LABEL, INPUT, SELECT, TEXTAREA, and BUTTON. This event type is dispatched after the event type {"http://www.w3.org/2001/xml-events", "DOMFocusIn"}.
blur
An element loses focus either via a pointing device, the blur() methods defined in [DOM Level 2 HTML], or by tabbing navigation. This event is only valid for the following elements: A, AREA, LABEL, INPUT, SELECT, TEXTAREA, and BUTTON. This event type is dispatched after the event type {"http://www.w3.org/2001/xml-events", "DOMFocusOut"}.

The following table provides refinements or additional information on the event types. Some events will only be dispatched to a specific set of possible targets, specified using HTML node types.

type | Bubbling phase | Cancelable | Target node types | DOM interface
load | [no changes] | [no changes] | HTMLDocument, HTMLBodyElement, HTMLFrameSetElement, HTMLObjectElement, HTMLLinkElement, HTMLMetaElement, HTMLScriptElement, HTMLFrameElement, HTMLIFrameElement, HTMLImageElement | [no changes]
unload | [no changes] | [no changes] | HTMLDocument, HTMLBodyElement, HTMLFrameSetElement | [no changes]
abort | [no changes] | [no changes] | HTMLObjectElement | [no changes]
error | [no changes] | [no changes] | HTMLObjectElement, HTMLBodyElement, HTMLFrameSetElement | [no changes]
select | [no changes] | [no changes] | HTMLInputElement, HTMLTextAreaElement | [no changes]
change | [no changes] | [no changes] | HTMLInputElement, HTMLSelectElement, HTMLTextAreaElement | [no changes]
submit | [no changes] | [no changes] | HTMLFormElement | [no changes]
reset | [no changes] | [no changes] | HTMLFormElement | [no changes]
resize | [no changes] | [no changes] | HTMLDocument, HTMLElement | [no changes]
scroll | [no changes] | [no changes] | HTMLDocument, HTMLElement | [no changes]
focus | No | No | HTMLAnchorElement, HTMLAreaElement, HTMLLabelElement, HTMLInputElement, HTMLSelectElement, HTMLtextAreaElement, HTMLButtonElement. | Event
blur | No | No | HTMLAnchorElement, HTMLAreaElement, HTMLLabelElement, HTMLInputElement, HTMLSelectElement, HTMLtextAreaElement, HTMLButtonElement. | Event

The event types {"http://www.w3.org/2001/xml-events", "focus"} and {"http://www.w3.org/2001/xml-events", "blur"} may be generated from a user interface; in that case, the event objects also implements the UIEvent interface and UIEvent.view is in use.

1.7.7.1 Activation and default actions

The concept of activation ({"http://www.w3.org/2001/xml-events", "DOMActivate"}) was introduced in [DOM Level 2 Events] to separate generic actions from the devices used to activate them. For example, an hyperlink can be activated using a mouse or a keyboard, and the activation will force the user agent to follow the link. It is expected that the action of following the link is done using a default action attached to the hyperlink element. In such case, the default action of the device event type is to trigger the event type {"http://www.w3.org/2001/xml-events", "DOMActivate"}. Preventing the default action of a mouse click when the target node is an hyperlink will prevent the activation. The same approach is made for control elements.

Implementations could react to an event before dispatching it and do changes on the display and the DOM tree. In such case, if a DOM attribute is changed before the event is fired, cancelling the device event type will also reverse the change. A good example is the attribute HTMLInputElement.checked: As described in [DOM Level 2 HTML], the value of this property may be changed before the dispatch of the event; the user clicks on the radio button, the radio button is being checked (or unchecked) on the display, the attribute HTMLInputElement.checked is changed as well, and then the device event type {"http://www.w3.org/2001/xml-events", "click"} is being dispatched. If the default action of the device event type is prevented, or if the default action attached to the {"http://www.w3.org/2001/xml-events", "DOMActivate"} event type is prevented, the property HTMLInputElement.checked will need to be changed back to its original value.


Keyboard events and key identifiers

07 November 2003

Appendix A: Keyboard events and key identifiers

Editor:
Philippe Le Hégaret, W3C

Table of contents

  • A.1 Introduction
    • A.1.1 Modifier keys
    • A.1.2 Dead keys
    • A.1.3 Input Method Editors
    • A.1.4 Guidelines for defining key identifiers
  • A.2 Key identifiers set

This section contains necessary information regarding keyboard events:

  • Relations between keys, such as dead keys or modifiers keys.
  • Relations between keyboard events, their default actions, and text events.
  • The set of key identifiers, and guidelines on how to extend this set.

Note: This section uses serbian and kanji characters which are not always available (or are misrepresented) in the alternative versions or printed versions of this specification.

A.1 Introduction

Each keyboard event references a key using a DOMString key identifier. The set contained in this appendix is based on the sets of keycodes from:

  • the interface java.awt.event.KeyEvent of the Java 2 Platform v1.4 [KeyEvent for Java];
  • the enumeration System.Windows.Forms.Keys of the Microsoft .NET Framework 1.0 [Keys enumeration for .Net].

While implementations are recommended to use the most relevant identifier for a key independently of the platform or keyboard layout mappings, DOM applications should not make assumption on the ability of keyboard devices to generate them. When using keyboard events, "consider using numbers and function keys (F4, F5, and so on) instead of letters in shortcut-key combinations" ([DWW95]) given that most keyboard layouts will provide keys for those.

"U+0000", "U+0001", ..., "U+FFFFFF" are Unicode based key identifiers ([Unicode]). When a key cannot be mapped to Unicode, a specific identifier is used (see also Guidelines for defining key identifiers). In any case, no assumption should be made between the sequence of keyboard events and the text events. The following three examples illustrate the concept of keyboard layout mappings and its relation with keyboard events (following the Guidelines for defining key identifiers, the 'Q' key is mapped to the Latin Capital Letter Q key).

The keystroke "U+0051" (Latin Capital Letter Q key) will produce (on a PC/AT US keyboard using a US keyboard layout mapping and without any modifier activated) the Unicode character q (Latin Small Letter Q):

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0051" (Latin Capital Letter Q key)
  2. {"http://www.w3.org/2001/xml-events", "textInput"}: "q"
  3. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0051"

If the keyboard layout mapping is switched to a french mapping, pressing the same key will produce:

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0041" (Latin Capital Letter A key)
  2. {"http://www.w3.org/2001/xml-events", "textInput"}: "a"
  3. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0041"

If the keyboard layout mapping is switched to a serbian (cyrillic) mapping, pressing the same key will produce:

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0409" (Cyrillic Capital Letter LJE)
  2. {"http://www.w3.org/2001/xml-events", "textInput"}: "љ"
  3. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0409"

Note: The order between the text event and keyboard events may differ depending on the keyboard devices.

A.1.1 Modifier keys

Keyboard input uses modifier keys to change the normal behavior of a key. Keys associated with modifiers generate, like other keys, "keydown" and "keyup" events as shown in the example below. Some modifiers are activated while the key is being pressed down or maintained pressed such as "Alt", "Control", "Shift", "AltGraph", or "Meta". Others modifiers are activated depending on their state such as "CapsLock", "NumLock", or "Scroll". Change in the state happens when the modifier key is being pressed down. The KeyboardEvent interface provides convenient attributes for some common modifiers keys: KeyboardEvent.ctrlKey, KeyboardEvent.shiftKey, KeyboardEvent.altKey, KeyboardEvent.metaKey. Some operating systems simulate the "AltGraph" modifier key with the combination of the "Alt and "Control" modifier keys. Implementations are encouraged to use the "AltGraph" modifier key.

The following example describes a possible sequence of keys to generate the Unicode character Q (Latin Capital Letter Q) on a PC/AT US keyboard using a US mapping:

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "Shift", shiftKey
  2. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0051" (Latin Capital Letter Q key), shiftKey
  3. {"http://www.w3.org/2001/xml-events", "textInput"}: "Q"
  4. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0051", shiftKey
  5. {"http://www.w3.org/2001/xml-events", "keyup"}: "Shift"

The following example describes a possible sequence of keys that does not generate a Unicode character (using the same configuration):

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "Control", ctrlKey
  2. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0056" (Latin Capital Letter V key), ctrlKey
  3. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0056", ctrlKey
  4. {"http://www.w3.org/2001/xml-events", "keyup"}: "Control"

Preventing a keydown or keyup event with a modifier does affect the subsequent

A.1.2 Dead keys

Keyboard input uses dead keys for the input of composed character sequences. Unlike the handwriting sequence, in which users enter the base character first, keyboard input requires to enter a special state when a dead key is pressed and emit the character(s) only when one of a limited number of "legal" base character is entered.

The dead keys are represented in the key identifiers set using combining diacritical marks. The sequence of keystrokes "U+0302" (Combining Circumflex Accent key) and "U+0045" (Latin Capital Letter E key) will likely produce (on a PC/AT french keyboard using a french mapping and without any modifier activated) the Unicode character ê (Latin Small Letter E With Circumflex), as preferred by the Unicode Normalization Form NFC:

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0302" (Combining Circumflex Accent key)
  2. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0302"
  3. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0045" (Latin Capital Letter E key)
  4. {"http://www.w3.org/2001/xml-events", "textInput"}: "é"
  5. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0045"

A.1.3 Input Method Editors

Also known as front end processor, an input method editor (IME) is an application that performs the conversion between keystrokes and ideographs or other characters, usually by user-guided dictionary lookup.

This specification does not provide a representation of the input method editor (IME) events, e.g. representing the input context, i.e. the IME's functions are not represented in this set. As an example, receiving a keydown for the "Accept" key identifier does not necessarily imply that the text currently selected in the IME is being accepted. It only indicates that a keystroke happened, disconnected from the IME Accept functionality. Depending on the device in use, the IME Accept functionality can be obtain using the Accept key or the Return key. Keyboard events cannot be used to determine the current state of the input method editor.

Keyboard events correspond to the events generated by the input device after the keyboard layout mapping but before the processing of the input method editor.

The following example describes a possible sequence of keys to generate the Unicode character 市 (Kanji character, part of CJK Unified Ideographs) using Japanese input methods. This example assumes that the input method editor is activated and in the Japanese-Romaji input mode. The keys "Convert" and "Accept" may be replaced by others depending on the input device in use and the configuration of the IME, e.g. it could be respectively "U+0020" (Space key) and "Enter".

  1. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0053" (Latin Capital Letter S key)
  2. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0053" (Latin Capital Letter S key)
  3. {"http://www.w3.org/2001/xml-events", "keydown"}: "U+0049" (Latin Capital Letter I key)
  4. {"http://www.w3.org/2001/xml-events", "keyup"}: "U+0049" (Latin Capital Letter I key)
  5. {"http://www.w3.org/2001/xml-events", "keydown"}: "Convert"
  6. {"http://www.w3.org/2001/xml-events", "keyup"}: "Convert"
  7. {"http://www.w3.org/2001/xml-events", "keydown"}: "Accept"
  8. {"http://www.w3.org/2001/xml-events", "textInput"}: "市"
  9. {"http://www.w3.org/2001/xml-events", "keyup"}: "Accept"

A.1.4 Guidelines for defining key identifiers

Note: This section is informative.

The list of key identifiers contained in this appendix is not exhaustive and input devices may have to define their own key identifiers. Here is a algorithm to determine which key identifier to use:

  1. Determine a representation for the key by looking at the keyboard layout mapping in use (and not the keyboard device in use). This representation should be unique, as human friendly as possible, platform independent, and consistent. For example, on PC/AT US keyboards with a US mapping, the 'Q' key is mapped to the key identifier "U+0051" (Latin Capital Letter Q key), the '1/!' key is mapped to the key identifier "U+0031" (Digit One key), the key '`/~' is mapped to the key identifier "U+0060" (Grave Accent key), and the 'Enter' key is mapped to the key identifier "Enter".
  2. Find an appropriate mapping in the Unicode character set. There might not always be an appropriate and obvious mapping: the Unicode set contains characters and symbols, the key might generate different characters depending on the operating system, ... In general, unless the representation of the key can be mapped to a unique Unicode character, it is better to create a new one.
  3. If no appropriate mapping was found, create a key identifier as human friendly as possible. The key identifier must not contain white spaces. As an example, the Enter key is mapped to the key identifier "Enter" and not to "U+000A" (Line Feed), given that this key generates the character 00000A on Unix operating systems and the characters 00000D and 00000A on Windows operating systems.

A.2 Key identifiers set

Note: The keycodes Multiply, Add, Substract, Decimal, Separator, Divide, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, and NumPad9 are not part of this set. Use KeyBoard.keyLocation to know if a key originated from the numeric keypad.

"Accept"
The Accept (Commit) key.
"Again"
The Again key.
"AllCandidates"
The All Candidates key.
"Alphanumeric"
The Alphanumeric key.
"Alt"
The Alt (Menu) key.
"AltGraph"
The Alt-Graph key.
"Apps"
The Application key.
"Attn"
The ATTN key.
"BrowserBack"
The Browser Back key.
"BrowserFavorites"
The Browser Favorites key.
"BrowserForward"
The Browser Forward key.
"BrowserHome"
The Browser Home key.
"BrowserRefresh"
The Browser Refresh key.
"BrowserSearch"
The Browser Search key.
"BrowserStop"
The Browser Stop key.
"CapsLock"
The Caps Lock (Capital) key.
"Clear"
The Clear key.
"CodeInput"
The Code Input key.
"Compose"
The Compose key.
"Control"
The Control (Ctrl) key.
"Crsel"
The Crsel key.
"Convert"
The Convert key.
"Copy"
The Copy key.
"Cut"
The Cut key.
"Down"
The Down Arrow key.
"End"
The End key.
"Enter"
The Enter key.

Note: This key identifier is also used for the Return (Macintosh numpad) key.

"EraseEof"
The Erase EOF key.
"Execute"
The Execute key.
"Exsel"
The Exsel key.
"F1"
The F1 key.
"F2"
The F2 key.
"F3"
The F3 key.
"F4"
The F4 key.
"F5"
The F5 key.
"F6"
The F6 key.
"F7"
The F7 key.
"F8"
The F8 key.
"F9"
The F9 key.
"F10"
The F10 key.
"F11"
The F11 key.
"F12"
The F12 key.
"F13"
The F13 key.
"F14"
The F14 key.
"F15"
The F15 key.
"F16"
The F16 key.
"F17"
The F17 key.
"F18"
The F18 key.
"F19"
The F19 key.
"F20"
The F20 key.
"F21"
The F21 key.
"F22"
The F22 key.
"F23"
The F23 key.
"F24"
The F24 key.
"FinalMode"
The Final Mode (Final) key used on some asian keyboards.
"Find"
The Find key.
"FullWidth"
The Full-Width Characters key.
"HalfWidth"
The Half-Width Characters key.
"HangulMode"
The Hangul (Korean characters) Mode key.
"HanjaMode"
The Hanja (Korean characters) Mode key.
"Help"
The Help key.
"Hiragana"
The Hiragana (Japanese Kana characters) key.
"Home"
The Home key.
"Insert"
The Insert (Ins) key.
"JapaneseHiragana"
The Japanese-Hiragana key.
"JapaneseKatakana"
The Japanese-Katakana key.
"JapaneseRomaji"
The Japanese-Romaji key.
"JunjaMode"
The Junja Mode key.
"KanaMode"
The Kana Mode (Kana Lock) key.
"KanjiMode"
The Kanji (Japanese name for ideographic characters of Chinese origin) Mode key.
"Katakana"
The Katakana (Japanese Kana characters) key.
"LaunchApplication1"
The Start Application One key.
"LaunchApplication2"
The Start Application Two key.
"LaunchMail"
The Start Mail key.
"Left"
The Left Arrow key.
"Meta"
The Meta key.
"MediaNextTrack"
The Media Next Track key.
"MediaPlayPause"
The Media Play Pause key.
"MediaPreviousTrack"
The Media Previous Track key.
"MediaStop"
The Media Stok key.
"ModeChange"
The Mode Change key.
"Nonconvert"
The Nonconvert (Don't Convert) key.
"NumLock"
The Num Lock key.
"PageDown"
The Page Down (Next) key.
"PageUp"
The Page Up key.
"Paste"
The Paste key.
"Pause"
The Pause key.
"Play"
The Play key.
"PreviousCandidate"
The Previous Candidate function key.
"PrintScreen"
The Print Screen (PrintScrn, SnapShot) key.
"Process"
The Process key.
"Props"
The Props key.
"Right"
The Right Arrow key.
"RomanCharacters"
The Roman Characters function key.
"Scroll"
The Scroll Lock key.
"Select"
The Select key.
"SelectMedia"
The Select Media key.
"Shift"
The Shift key.
"Stop"
The Stop key.
"Up"
The Up Arrow key.
"Undo"
The Undo key.
"VolumeDown"
The Volume Down key.
"VolumeMute"
The Volume Mute key.
"VolumeUp"
The Volume Up key.
"Win"
The Windows Logo key.
"Zoom"
The Zoom key.
"U+0008"
The Backspace (Back) key.
"U+0009"
The Horizontal Tabulation (Tab) key.
"U+0018"
The Cancel key.
"U+001B"
The Escape (Esc) key.
"U+0020"
The Space (Spacebar) key.
"U+0021"
The Exclamation Mark (Factorial, Bang) key (!).
"U+0022"
The Quotation Mark (Quote Double) key (").
"U+0023"
The Number Sign (Pound Sign, Hash, Crosshatch, Octothorpe) key (#).
"U+0024"
The Dollar Sign (milreis, escudo) key ($).
"U+0026"
The Ampersand key (&).
"U+0027"
The Apostrophe (Apostrophe-Quote, APL Quote) key (').
"U+0028"
The Left Parenthesis (Opening Parenthesis) key (().
"U+0029"
The Right Parenthesis (Closing Parenthesis) key ()).
"U+002A"
The Asterix (Star) key (*).
"U+002B"
The Plus Sign (Plus) key (+).
"U+002C"
The Comma (decimal separator) sign key (,).
"U+002D"
The Hyphen-minus (hyphen or minus sign) key (-).
"U+002E"
The Full Stop (period, dot, decimal point) key (.).
"U+002F"
The Solidus (slash, virgule, shilling) key (/).
"U+0030"
The Digit Zero key (0).
"U+0031"
The Digit One key (1).
"U+0032"
The Digit Two key (2).
"U+0033"
The Digit Three key (3).
"U+0034"
The Digit Four key (4).
"U+0035"
The Digit Five key (5).
"U+0036"
The Digit Six key (6).
"U+0037"
The Digit Seven key (7).
"U+0038"
The Digit Eight key (8).
"U+0039"
The Digit Nine key (9).
"U+003A"
The Colon key (:).
"U+003B"
The Semicolon key (;).
"U+003C"
The Less-Than Sign key (<).
"U+003D"
The Equals Sign key (=).
"U+003E"
The Greater-Than Sign key (>).
"U+003F"
The Question Mark key (?).
"U+0040"
The Commercial At (@) key.
"U+0041"
The Latin Capital Letter A key (A).
"U+0042"
The Latin Capital Letter B key (B).
"U+0043"
The Latin Capital Letter C key (C).
"U+0044"
The Latin Capital Letter D key (D).
"U+0045"
The Latin Capital Letter E key (E).
"U+0046"
The Latin Capital Letter F key (F).
"U+0047"
The Latin Capital Letter G key (G).
"U+0048"
The Latin Capital Letter H key (H).
"U+0049"
The Latin Capital Letter I key (I).
"U+004A"
The Latin Capital Letter J key (J).
"U+004B"
The Latin Capital Letter K key (K).
"U+004C"
The Latin Capital Letter L key (L).
"U+004D"
The Latin Capital Letter M key (M).
"U+004E"
The Latin Capital Letter N key (N).
"U+004F"
The Latin Capital Letter O key (O).
"U+0050"
The Latin Capital Letter P key (P).
"U+0051"
The Latin Capital Letter Q key (Q).
"U+0052"
The Latin Capital Letter R key (R).
"U+0053"
The Latin Capital Letter S key (S).
"U+0054"
The Latin Capital Letter T key (T).
"U+0055"
The Latin Capital Letter U key (U).
"U+0056"
The Latin Capital Letter V key (V).
"U+0057"
The Latin Capital Letter W key (W).
"U+0058"
The Latin Capital Letter X key (X).
"U+0059"
The Latin Capital Letter Y key (Y).
"U+005A"
The Latin Capital Letter Z key (Z).
"U+005B"
The Left Square Bracket (Opening Square Bracket) key ([).
"U+005C"
The Reverse Solidus (Backslash) key (\).
"U+005D"
The Right Square Bracket (Closing Square Bracket) key (]).
"U+005E"
The Circumflex Accent key (^).
"U+005F"
The Low Sign (Spacing Underscore, Underscore) key (_).
"U+0060"
The Grave Accent (Back Quote) key (`).
"U+007B"
The Left Curly Bracket (Opening Curly Bracket, Opening Brace, Brace Left) key ({).
"U+007C"
The Vertical Line (Vertical Bar, Pipe) key (|).
"U+007D"
The Right Curly Bracket (Closing Curly Bracket, Closing Brace, Brace Right) key (}).
"U+007F"
The Delete (Del) Key.
"U+00A1"
The Inverted Exclamation Mark key (¡).
"U+0300"
The Combining Grave Accent (Greek Varia, Dead Grave) key.
"U+0301"
The Combining Acute Accent (Stress Mark, Greek Oxia, Tonos, Dead Eacute) key.
"U+0302"
The Combining Circumflex Accent (Hat, Dead Circumflex) key.
"U+0303"
The Combining Tilde (Dead Tilde) key.
"U+0304"
The Combining Macron (Long, Dead Macron) key.
"U+0306"
The Combining Breve (Short, Dead Breve) key.
"U+0307"
The Combining Dot Above (Derivative, Dead Above Dot) key.
"U+0308"
The Combining Diaeresis (Double Dot Abode, Umlaut, Greek Dialytika, Double Derivative, Dead Diaeresis) key.
"U+030A"
The Combining Ring Above (Dead Above Ring) key.
"U+030B"
The Combining Double Acute Accent (Dead Doubleacute) key.
"U+030C"
The Combining Caron (Hacek, V Above, Dead Caron) key.
"U+0327"
The Combining Cedilla (Dead Cedilla) key.
"U+0328"
The Combining Ogonek (Nasal Hook, Dead Ogonek) key.
"U+0345"
The Combining Greek Ypogegrammeni (Greek Non-Spacing Iota Below, Iota Subscript, Dead Iota) key.
"U+20AC"
The Euro Currency Sign key (€).
"U+3099"
The Combining Katakana-Hiragana Voiced Sound Mark (Dead Voiced Sound) key.
"U+309A"
The Combining Katakana-Hiragana Semi-Voiced Sound Mark (Dead Semivoiced Sound) key.


Changes

07 November 2003

Appendix B: Changes

Editor:
Philippe Le Hégaret, W3C

B.1 Changes between DOM Level 2 Events and DOM Level 3 Events

This new specification provides a better separation between the DOM event flow, the event types, and the DOM interfaces.

B.1.1 Changes to DOM Level 2 event flow

This new specification introduced two new concepts in the event flow:

  • event groups: unlike DOM Level 2 Events, Event.stopPropagation() does no longer stop the event propagation entirely. It only stops it for a given event group.
  • partial ordering of event listeners: within an event group, event listeners are now ordered while ordering was unspecified in DOM Level 2 Events.

B.1.2 Changes to DOM Level 2 event types

Lots of clarifications have been made on the event types. The conformance is now explicitly defined against the event types, and not only in terms of interfaces required by the event types. Support for namespaces and the features "BasicEvents", "TextEvents", "KeyboardEvents", and "MutationNameEvents" have been introduced.

The DOM Level 2 Event load event type can now be dispatched to more [HTML 4.01] elements. blur and focus have been clarified and restricted to [HTML 4.01] applications only.

B.1.3 Changes to DOM Level 2 Events interfaces

Interface Event
The Event interface has a new attribute Event.namespaceURI, and a four new methods: Event.isCustom(), Event.stopImmediatePropagation(), Event.isDefaultPrevented(), and Event.initEventNS.
Interface EventTarget
The EventTarget interface has four new methods: EventTarget.addEventListenerNS(namespaceURI, type, listener, useCapture, evtGroup), EventTarget.removeEventListenerNS(namespaceURI, type, listener, useCapture), EventTarget.willTriggerNS(namespaceURI, type), EventTarget.hasEventListenerNS(namespaceURI, type). The method EventTarget.dispatchEvent(evt) was modified.
Interface DocumentEvent
The DocumentEvent interface has one new method: DocumentEvent.canDispatch(namespaceURI, type).
Interface UIEvent
The UIEvent interface has a new method UIEvent.initUIEventNS(...).
Interface MouseEvent
The MouseEvent interface has two new methods MouseEvent.getModifierState(keyIdentifierArg) and MouseEvent.initMouseEventNS(...).
Interface MutationEvent
The MutationEvent interface has a new method MutationEvent.initMutationEventNS(...).
Exception EventException
The DISPATCH_REQUEST_ERR constant has been added.

B.1.4 New Interfaces

The interfaces CustomEvent, TextEvent, KeyboardEvent, and MutationNameEvent were added to the Events module.


IDL Definitions

07 November 2003

Appendix C: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Events definitions.

The IDL files are also available as: http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/idl.zip

events.idl:

// File: events.idl

#ifndef _EVENTS_IDL_
#define _EVENTS_IDL_

#include "dom.idl"
#include "views.idl"

#pragma prefix "dom.w3c.org"
module events
{

  typedef dom::DOMString DOMString;
  typedef dom::DOMTimeStamp DOMTimeStamp;
  typedef dom::DOMObject DOMObject;
  typedef dom::Node Node;

  interface EventTarget;
  interface EventListener;

  // Introduced in DOM Level 2:
  exception EventException {
    unsigned short   code;
  };
  // EventExceptionCode
  const unsigned short      UNSPECIFIED_EVENT_TYPE_ERR     = 0;
  // Introduced in DOM Level 3:
  const unsigned short      DISPATCH_REQUEST_ERR           = 1;

  // Introduced in DOM Level 2:
  interface Event {

    // PhaseType
    const unsigned short      CAPTURING_PHASE                = 1;
    const unsigned short      AT_TARGET                      = 2;
    const unsigned short      BUBBLING_PHASE                 = 3;

    readonly attribute DOMString       type;
    readonly attribute EventTarget     target;
    readonly attribute EventTarget     currentTarget;
    readonly attribute unsigned short  eventPhase;
    readonly attribute boolean         bubbles;
    readonly attribute boolean         cancelable;
    readonly attribute DOMTimeStamp    timeStamp;
    void               stopPropagation();
    void               preventDefault();
    void               initEvent(in DOMString eventTypeArg,
                                 in boolean canBubbleArg,
                                 in boolean cancelableArg);
    // Introduced in DOM Level 3:
    readonly attribute DOMString       namespaceURI;
    // Introduced in DOM Level 3:
    boolean            isCustom();
    // Introduced in DOM Level 3:
    void               stopImmediatePropagation();
    // Introduced in DOM Level 3:
    boolean            isDefaultPrevented();
    // Introduced in DOM Level 3:
    void               initEventNS(in DOMString namespaceURIArg,
                                   in DOMString eventTypeArg,
                                   in boolean canBubbleArg,
                                   in boolean cancelableArg);
  };

  // Introduced in DOM Level 2:
  interface EventTarget {
    void               addEventListener(in DOMString type,
                                        in EventListener listener,
                                        in boolean useCapture);
    void               removeEventListener(in DOMString type,
                                           in EventListener listener,
                                           in boolean useCapture);
    // Modified in DOM Level 3:
    boolean            dispatchEvent(in Event evt)
                                        raises(EventException);
    // Introduced in DOM Level 3:
    void               addEventListenerNS(in DOMString namespaceURI,
                                          in DOMString type,
                                          in EventListener listener,
                                          in boolean useCapture,
                                          in DOMObject evtGroup);
    // Introduced in DOM Level 3:
    void               removeEventListenerNS(in DOMString namespaceURI,
                                             in DOMString type,
                                             in EventListener listener,
                                             in boolean useCapture);
    // Introduced in DOM Level 3:
    boolean            willTriggerNS(in DOMString namespaceURI,
                                     in DOMString type);
    // Introduced in DOM Level 3:
    boolean            hasEventListenerNS(in DOMString namespaceURI,
                                          in DOMString type);
  };

  // Introduced in DOM Level 2:
  interface EventListener {
    void               handleEvent(in Event evt);
  };

  // Introduced in DOM Level 2:
  interface DocumentEvent {
    Event              createEvent(in DOMString eventType)
                                        raises(dom::DOMException);
    // Introduced in DOM Level 3:
    boolean            canDispatch(in DOMString namespaceURI,
                                   in DOMString type);
  };

  // Introduced in DOM Level 3:
  interface CustomEvent : Event {
    void               setDispatchState(in EventTarget target,
                                        in unsigned short phase);
    boolean            isPropagationStopped();
    boolean            isImmediatePropagationStopped();
  };

  // Introduced in DOM Level 2:
  interface UIEvent : Event {
    readonly attribute views::AbstractView view;
    readonly attribute long            detail;
    void               initUIEvent(in DOMString typeArg,
                                   in boolean canBubbleArg,
                                   in boolean cancelableArg,
                                   in views::AbstractView viewArg,
                                   in long detailArg);
    // Introduced in DOM Level 3:
    void               initUIEventNS(in DOMString namespaceURI,
                                     in DOMString typeArg,
                                     in boolean canBubbleArg,
                                     in boolean cancelableArg,
                                     in views::AbstractView viewArg,
                                     in long detailArg);
  };

  // Introduced in DOM Level 3:
  interface TextEvent : UIEvent {
    readonly attribute DOMString       data;
    void               initTextEvent(in DOMString typeArg,
                                     in boolean canBubbleArg,
                                     in boolean cancelableArg,
                                     in views::AbstractView viewArg,
                                     in DOMString dataArg);
    void               initTextEventNS(in DOMString namespaceURI,
                                       in DOMString type,
                                       in boolean canBubbleArg,
                                       in boolean cancelableArg,
                                       in views::AbstractView viewArg,
                                       in DOMString dataArg);
  };

  // Introduced in DOM Level 2:
  interface MouseEvent : UIEvent {
    readonly attribute long            screenX;
    readonly attribute long            screenY;
    readonly attribute long            clientX;
    readonly attribute long            clientY;
    readonly attribute boolean         ctrlKey;
    readonly attribute boolean         shiftKey;
    readonly attribute boolean         altKey;
    readonly attribute boolean         metaKey;
    readonly attribute unsigned short  button;
    readonly attribute EventTarget     relatedTarget;
    void               initMouseEvent(in DOMString typeArg,
                                      in boolean canBubbleArg,
                                      in boolean cancelableArg,
                                      in views::AbstractView viewArg,
                                      in long detailArg,
                                      in long screenXArg,
                                      in long screenYArg,
                                      in long clientXArg,
                                      in long clientYArg,
                                      in boolean ctrlKeyArg,
                                      in boolean altKeyArg,
                                      in boolean shiftKeyArg,
                                      in boolean metaKeyArg,
                                      in unsigned short buttonArg,
                                      in EventTarget relatedTargetArg);
    // Introduced in DOM Level 3:
    boolean            getModifierState(in DOMString keyIdentifierArg);
    // Introduced in DOM Level 3:
    void               initMouseEventNS(in DOMString namespaceURI,
                                        in DOMString typeArg,
                                        in boolean canBubbleArg,
                                        in boolean cancelableArg,
                                        in views::AbstractView viewArg,
                                        in long detailArg,
                                        in long screenXArg,
                                        in long screenYArg,
                                        in long clientXArg,
                                        in long clientYArg,
                                        in unsigned short buttonArg,
                                        in EventTarget relatedTargetArg,
                                        in DOMString modifiersList);
  };

  // Introduced in DOM Level 3:
  interface KeyboardEvent : UIEvent {

    // KeyLocationCode
    const unsigned long       DOM_KEY_LOCATION_STANDARD      = 0x00;
    const unsigned long       DOM_KEY_LOCATION_LEFT          = 0x01;
    const unsigned long       DOM_KEY_LOCATION_RIGHT         = 0x02;
    const unsigned long       DOM_KEY_LOCATION_NUMPAD        = 0x03;

    readonly attribute DOMString       keyIdentifier;
    readonly attribute unsigned long   keyLocation;
    readonly attribute boolean         ctrlKey;
    readonly attribute boolean         shiftKey;
    readonly attribute boolean         altKey;
    readonly attribute boolean         metaKey;
    boolean            getModifierState(in DOMString keyIdentifierArg);
    void               initKeyboardEvent(in DOMString typeArg,
                                         in boolean canBubbleArg,
                                         in boolean cancelableArg,
                                         in views::AbstractView viewArg,
                                         in DOMString keyIdentifierArg,
                                         in unsigned long keyLocationArg,
                                         in DOMString modifiersList);
    void               initKeyboardEventNS(in DOMString namespaceURI,
                                           in DOMString typeArg,
                                           in boolean canBubbleArg,
                                           in boolean cancelableArg,
                                           in views::AbstractView viewArg,
                                           in DOMString keyIdentifierArg,
                                           in unsigned long keyLocationArg,
                                           in DOMString modifiersList);
  };

  // Introduced in DOM Level 2:
  interface MutationEvent : Event {

    // attrChangeType
    const unsigned short      MODIFICATION                   = 1;
    const unsigned short      ADDITION                       = 2;
    const unsigned short      REMOVAL                        = 3;

    readonly attribute Node            relatedNode;
    readonly attribute DOMString       prevValue;
    readonly attribute DOMString       newValue;
    readonly attribute DOMString       attrName;
    readonly attribute unsigned short  attrChange;
    void               initMutationEvent(in DOMString typeArg,
                                         in boolean canBubbleArg,
                                         in boolean cancelableArg,
                                         in Node relatedNodeArg,
                                         in DOMString prevValueArg,
                                         in DOMString newValueArg,
                                         in DOMString attrNameArg,
                                         in unsigned short attrChangeArg);
    // Introduced in DOM Level 3:
    void               initMutationEventNS(in DOMString namespaceURI,
                                           in DOMString typeArg,
                                           in boolean canBubbleArg,
                                           in boolean cancelableArg,
                                           in Node relatedNodeArg,
                                           in DOMString prevValueArg,
                                           in DOMString newValueArg,
                                           in DOMString attrNameArg,
                                           in unsigned short attrChangeArg);
  };

  // Introduced in DOM Level 3:
  interface MutationNameEvent : MutationEvent {
    readonly attribute DOMString       prevNamespaceURI;
    readonly attribute DOMString       prevNodeName;
    // Introduced in DOM Level 3:
    void               initMutationNameEvent(in DOMString typeArg,
                                             in boolean canBubbleArg,
                                             in boolean cancelableArg,
                                             in Node relatedNodeArg,
                                             in DOMString prevNamespaceURIArg,
                                             in DOMString prevNodeNameArg);
    // Introduced in DOM Level 3:
    void               initMutationNameEventNS(in DOMString namespaceURI,
                                               in DOMString typeArg,
                                               in boolean canBubbleArg,
                                               in boolean cancelableArg,
                                               in Node relatedNodeArg,
                                               in DOMString prevNamespaceURIArg,
                                               in DOMString prevNodeNameArg);
  };
};

#endif // _EVENTS_IDL_


Java Language Binding

07 November 2003

Appendix D: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Events.

The Java files are also available as http://www.w3.org/TR/2003/NOTE-DOM-Level-3-Events-20031107/java-binding.zip

org/w3c/dom/events/EventException.java:

package org.w3c.dom.events;

public class EventException extends RuntimeException {
    public EventException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // EventExceptionCode
    public static final short UNSPECIFIED_EVENT_TYPE_ERR = 0;
    public static final short DISPATCH_REQUEST_ERR      = 1;

}

org/w3c/dom/events/Event.java:

package org.w3c.dom.events;

public interface Event {
    // PhaseType
    public static final short CAPTURING_PHASE           = 1;
    public static final short AT_TARGET                 = 2;
    public static final short BUBBLING_PHASE            = 3;

    public String getType();

    public EventTarget getTarget();

    public EventTarget getCurrentTarget();

    public short getEventPhase();

    public boolean getBubbles();

    public boolean getCancelable();

    public long getTimeStamp();

    public void stopPropagation();

    public void preventDefault();

    public void initEvent(String eventTypeArg,
                          boolean canBubbleArg,
                          boolean cancelableArg);

    public String getNamespaceURI();

    public boolean isCustom();

    public void stopImmediatePropagation();

    public boolean isDefaultPrevented();

    public void initEventNS(String namespaceURIArg,
                            String eventTypeArg,
                            boolean canBubbleArg,
                            boolean cancelableArg);

}

org/w3c/dom/events/EventTarget.java:

package org.w3c.dom.events;

public interface EventTarget {
    public void addEventListener(String type,
                                 EventListener listener,
                                 boolean useCapture);

    public void removeEventListener(String type,
                                    EventListener listener,
                                    boolean useCapture);

    public boolean dispatchEvent(Event evt)
                                 throws EventException;

    public void addEventListenerNS(String namespaceURI,
                                   String type,
                                   EventListener listener,
                                   boolean useCapture,
                                   Object evtGroup);

    public void removeEventListenerNS(String namespaceURI,
                                      String type,
                                      EventListener listener,
                                      boolean useCapture);

    public boolean willTriggerNS(String namespaceURI,
                                 String type);

    public boolean hasEventListenerNS(String namespaceURI,
                                      String type);

}

org/w3c/dom/events/EventListener.java:

package org.w3c.dom.events;

public interface EventListener {
    public void handleEvent(Event evt);

}

org/w3c/dom/events/DocumentEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.DOMException;

public interface DocumentEvent {
    public Event createEvent(String eventType)
                             throws DOMException;

    public boolean canDispatch(String namespaceURI,
                               String type);

}

org/w3c/dom/events/CustomEvent.java:

package org.w3c.dom.events;

public interface CustomEvent extends Event {
    public void setDispatchState(EventTarget target,
                                 short phase);

    public boolean isPropagationStopped();

    public boolean isImmediatePropagationStopped();

}

org/w3c/dom/events/UIEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface UIEvent extends Event {
    public AbstractView getView();

    public int getDetail();

    public void initUIEvent(String typeArg,
                            boolean canBubbleArg,
                            boolean cancelableArg,
                            AbstractView viewArg,
                            int detailArg);

    public void initUIEventNS(String namespaceURI,
                              String typeArg,
                              boolean canBubbleArg,
                              boolean cancelableArg,
                              AbstractView viewArg,
                              int detailArg);

}

org/w3c/dom/events/TextEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface TextEvent extends UIEvent {
    public String getData();

    public void initTextEvent(String typeArg,
                              boolean canBubbleArg,
                              boolean cancelableArg,
                              AbstractView viewArg,
                              String dataArg);

    public void initTextEventNS(String namespaceURI,
                                String type,
                                boolean canBubbleArg,
                                boolean cancelableArg,
                                AbstractView viewArg,
                                String dataArg);

}

org/w3c/dom/events/MouseEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface MouseEvent extends UIEvent {
    public int getScreenX();

    public int getScreenY();

    public int getClientX();

    public int getClientY();

    public boolean getCtrlKey();

    public boolean getShiftKey();

    public boolean getAltKey();

    public boolean getMetaKey();

    public short getButton();

    public EventTarget getRelatedTarget();

    public void initMouseEvent(String typeArg,
                               boolean canBubbleArg,
                               boolean cancelableArg,
                               AbstractView viewArg,
                               int detailArg,
                               int screenXArg,
                               int screenYArg,
                               int clientXArg,
                               int clientYArg,
                               boolean ctrlKeyArg,
                               boolean altKeyArg,
                               boolean shiftKeyArg,
                               boolean metaKeyArg,
                               short buttonArg,
                               EventTarget relatedTargetArg);

    public boolean getModifierState(String keyIdentifierArg);

    public void initMouseEventNS(String namespaceURI,
                                 String typeArg,
                                 boolean canBubbleArg,
                                 boolean cancelableArg,
                                 AbstractView viewArg,
                                 int detailArg,
                                 int screenXArg,
                                 int screenYArg,
                                 int clientXArg,
                                 int clientYArg,
                                 short buttonArg,
                                 EventTarget relatedTargetArg,
                                 String modifiersList);

}

org/w3c/dom/events/KeyboardEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.views.AbstractView;

public interface KeyboardEvent extends UIEvent {
    // KeyLocationCode
    public static final int DOM_KEY_LOCATION_STANDARD = 0x00;
    public static final int DOM_KEY_LOCATION_LEFT     = 0x01;
    public static final int DOM_KEY_LOCATION_RIGHT    = 0x02;
    public static final int DOM_KEY_LOCATION_NUMPAD   = 0x03;

    public String getKeyIdentifier();

    public int getKeyLocation();

    public boolean getCtrlKey();

    public boolean getShiftKey();

    public boolean getAltKey();

    public boolean getMetaKey();

    public boolean getModifierState(String keyIdentifierArg);

    public void initKeyboardEvent(String typeArg,
                                  boolean canBubbleArg,
                                  boolean cancelableArg,
                                  AbstractView viewArg,
                                  String keyIdentifierArg,
                                  int keyLocationArg,
                                  String modifiersList);

    public void initKeyboardEventNS(String namespaceURI,
                                    String typeArg,
                                    boolean canBubbleArg,
                                    boolean cancelableArg,
                                    AbstractView viewArg,
                                    String keyIdentifierArg,
                                    int keyLocationArg,
                                    String modifiersList);

}

org/w3c/dom/events/MutationEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.Node;

public interface MutationEvent extends Event {
    // attrChangeType
    public static final short MODIFICATION              = 1;
    public static final short ADDITION                  = 2;
    public static final short REMOVAL                   = 3;

    public Node getRelatedNode();

    public String getPrevValue();

    public String getNewValue();

    public String getAttrName();

    public short getAttrChange();

    public void initMutationEvent(String typeArg,
                                  boolean canBubbleArg,
                                  boolean cancelableArg,
                                  Node relatedNodeArg,
                                  String prevValueArg,
                                  String newValueArg,
                                  String attrNameArg,
                                  short attrChangeArg);

    public void initMutationEventNS(String namespaceURI,
                                    String typeArg,
                                    boolean canBubbleArg,
                                    boolean cancelableArg,
                                    Node relatedNodeArg,
                                    String prevValueArg,
                                    String newValueArg,
                                    String attrNameArg,
                                    short attrChangeArg);

}

org/w3c/dom/events/MutationNameEvent.java:

package org.w3c.dom.events;

import org.w3c.dom.Node;

public interface MutationNameEvent extends MutationEvent {
    public String getPrevNamespaceURI();

    public String getPrevNodeName();

    public void initMutationNameEvent(String typeArg,
                                      boolean canBubbleArg,
                                      boolean cancelableArg,
                                      Node relatedNodeArg,
                                      String prevNamespaceURIArg,
                                      String prevNodeNameArg);

    public void initMutationNameEventNS(String namespaceURI,
                                        String typeArg,
                                        boolean canBubbleArg,
                                        boolean cancelableArg,
                                        Node relatedNodeArg,
                                        String prevNamespaceURIArg,
                                        String prevNodeNameArg);

}


ECMAScript Language Binding

07 November 2003

Appendix E: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Events definitions.

Properties of the Event Constructor function:
Event.CAPTURING_PHASE
The value of the constant Event.CAPTURING_PHASE is 1.
Event.AT_TARGET
The value of the constant Event.AT_TARGET is 2.
Event.BUBBLING_PHASE
The value of the constant Event.BUBBLING_PHASE is 3.
Objects that implement the Event interface:
Properties of objects that implement the Event interface:
type
This read-only property is a String.
target
This read-only property is an object that implements the EventTarget interface.
currentTarget
This read-only property is an object that implements the EventTarget interface.
eventPhase
This read-only property is a Number.
bubbles
This read-only property is a Boolean.
cancelable
This read-only property is a Boolean.
timeStamp
This read-only property is an object that implements the Date interface.
namespaceURI
This read-only property is a String.
Functions of objects that implement the Event interface:
stopPropagation()
This function has no return value.
preventDefault()
This function has no return value.
initEvent(eventTypeArg, canBubbleArg, cancelableArg)
This function has no return value.
The eventTypeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
isCustom()
This function returns a Boolean.
stopImmediatePropagation()
This function has no return value.
isDefaultPrevented()
This function returns a Boolean.
initEventNS(namespaceURIArg, eventTypeArg, canBubbleArg, cancelableArg)
This function has no return value.
The namespaceURIArg parameter is a String.
The eventTypeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
Objects that implement the EventTarget interface:
Functions of objects that implement the EventTarget interface:
addEventListener(type, listener, useCapture)
This function has no return value.
The type parameter is a String.
The listener parameter is an object that implements the EventListener interface.
The useCapture parameter is a Boolean.
removeEventListener(type, listener, useCapture)
This function has no return value.
The type parameter is a String.
The listener parameter is an object that implements the EventListener interface.
The useCapture parameter is a Boolean.
dispatchEvent(evt)
This function returns a Boolean.
The evt parameter is an object that implements the Event interface.
This function can raise an object that implements the EventException interface.
addEventListenerNS(namespaceURI, type, listener, useCapture, evtGroup)
This function has no return value.
The namespaceURI parameter is a String.
The type parameter is a String.
The listener parameter is an object that implements the EventListener interface.
The useCapture parameter is a Boolean.
The evtGroup parameter is an object that implements the Object interface.
removeEventListenerNS(namespaceURI, type, listener, useCapture)
This function has no return value.
The namespaceURI parameter is a String.
The type parameter is a String.
The listener parameter is an object that implements the EventListener interface.
The useCapture parameter is a Boolean.
willTriggerNS(namespaceURI, type)
This function returns a Boolean.
The namespaceURI parameter is a String.
The type parameter is a String.
hasEventListenerNS(namespaceURI, type)
This function returns a Boolean.
The namespaceURI parameter is a String.
The type parameter is a String.
EventListener function:
This function has no return value. The parameter is an object that implements the Event interface.
Properties of the EventException Constructor function:
EventException.UNSPECIFIED_EVENT_TYPE_ERR
The value of the constant EventException.UNSPECIFIED_EVENT_TYPE_ERR is 0.
EventException.DISPATCH_REQUEST_ERR
The value of the constant EventException.DISPATCH_REQUEST_ERR is 1.
Objects that implement the EventException interface:
Properties of objects that implement the EventException interface:
code
This property is a Number.
Objects that implement the DocumentEvent interface:
Functions of objects that implement the DocumentEvent interface:
createEvent(eventType)
This function returns an object that implements the Event interface.
The eventType parameter is a String.
This function can raise an object that implements the DOMException interface.
canDispatch(namespaceURI, type)
This function returns a Boolean.
The namespaceURI parameter is a String.
The type parameter is a String.
Objects that implement the CustomEvent interface:
Objects that implement the CustomEvent interface have all properties and functions of the Event interface as well as the properties and functions defined below.
Functions of objects that implement the CustomEvent interface:
setDispatchState(target, phase)
This function has no return value.
The target parameter is an object that implements the EventTarget interface.
The phase parameter is a Number.
isPropagationStopped()
This function returns a Boolean.
isImmediatePropagationStopped()
This function returns a Boolean.
Objects that implement the UIEvent interface:
Objects that implement the UIEvent interface have all properties and functions of the Event interface as well as the properties and functions defined below.
Properties of objects that implement the UIEvent interface:
view
This read-only property is an object that implements the AbstractView interface.
detail
This read-only property is a Number.
Functions of objects that implement the UIEvent interface:
initUIEvent(typeArg, canBubbleArg, cancelableArg, viewArg, detailArg)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The detailArg parameter is a Number.
initUIEventNS(namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg, detailArg)
This function has no return value.
The namespaceURI parameter is a String.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The detailArg parameter is a Number.
Objects that implement the TextEvent interface:
Objects that implement the TextEvent interface have all properties and functions of the UIEvent interface as well as the properties and functions defined below.
Properties of objects that implement the TextEvent interface:
data
This read-only property is a String.
Functions of objects that implement the TextEvent interface:
initTextEvent(typeArg, canBubbleArg, cancelableArg, viewArg, dataArg)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The dataArg parameter is a String.
initTextEventNS(namespaceURI, type, canBubbleArg, cancelableArg, viewArg, dataArg)
This function has no return value.
The namespaceURI parameter is a String.
The type parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The dataArg parameter is a String.
Objects that implement the MouseEvent interface:
Objects that implement the MouseEvent interface have all properties and functions of the UIEvent interface as well as the properties and functions defined below.
Properties of objects that implement the MouseEvent interface:
screenX
This read-only property is a Number.
screenY
This read-only property is a Number.
clientX
This read-only property is a Number.
clientY
This read-only property is a Number.
ctrlKey
This read-only property is a Boolean.
shiftKey
This read-only property is a Boolean.
altKey
This read-only property is a Boolean.
metaKey
This read-only property is a Boolean.
button
This read-only property is a Number.
relatedTarget
This read-only property is an object that implements the EventTarget interface.
Functions of objects that implement the MouseEvent interface:
initMouseEvent(typeArg, canBubbleArg, cancelableArg, viewArg, detailArg, screenXArg, screenYArg, clientXArg, clientYArg, ctrlKeyArg, altKeyArg, shiftKeyArg, metaKeyArg, buttonArg, relatedTargetArg)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The detailArg parameter is a Number.
The screenXArg parameter is a Number.
The screenYArg parameter is a Number.
The clientXArg parameter is a Number.
The clientYArg parameter is a Number.
The ctrlKeyArg parameter is a Boolean.
The altKeyArg parameter is a Boolean.
The shiftKeyArg parameter is a Boolean.
The metaKeyArg parameter is a Boolean.
The buttonArg parameter is a Number.
The relatedTargetArg parameter is an object that implements the EventTarget interface.
getModifierState(keyIdentifierArg)
This function returns a Boolean.
The keyIdentifierArg parameter is a String.
initMouseEventNS(namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg, detailArg, screenXArg, screenYArg, clientXArg, clientYArg, buttonArg, relatedTargetArg, modifiersList)
This function has no return value.
The namespaceURI parameter is a String.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The detailArg parameter is a Number.
The screenXArg parameter is a Number.
The screenYArg parameter is a Number.
The clientXArg parameter is a Number.
The clientYArg parameter is a Number.
The buttonArg parameter is a Number.
The relatedTargetArg parameter is an object that implements the EventTarget interface.
The modifiersList parameter is a String.
Properties of the KeyboardEvent Constructor function:
KeyboardEvent.DOM_KEY_LOCATION_STANDARD
The value of the constant KeyboardEvent.DOM_KEY_LOCATION_STANDARD is 0x00.
KeyboardEvent.DOM_KEY_LOCATION_LEFT
The value of the constant KeyboardEvent.DOM_KEY_LOCATION_LEFT is 0x01.
KeyboardEvent.DOM_KEY_LOCATION_RIGHT
The value of the constant KeyboardEvent.DOM_KEY_LOCATION_RIGHT is 0x02.
KeyboardEvent.DOM_KEY_LOCATION_NUMPAD
The value of the constant KeyboardEvent.DOM_KEY_LOCATION_NUMPAD is 0x03.
Objects that implement the KeyboardEvent interface:
Objects that implement the KeyboardEvent interface have all properties and functions of the UIEvent interface as well as the properties and functions defined below.
Properties of objects that implement the KeyboardEvent interface:
keyIdentifier
This read-only property is a String.
keyLocation
This read-only property is a Number.
ctrlKey
This read-only property is a Boolean.
shiftKey
This read-only property is a Boolean.
altKey
This read-only property is a Boolean.
metaKey
This read-only property is a Boolean.
Functions of objects that implement the KeyboardEvent interface:
getModifierState(keyIdentifierArg)
This function returns a Boolean.
The keyIdentifierArg parameter is a String.
initKeyboardEvent(typeArg, canBubbleArg, cancelableArg, viewArg, keyIdentifierArg, keyLocationArg, modifiersList)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The keyIdentifierArg parameter is a String.
The keyLocationArg parameter is a Number.
The modifiersList parameter is a String.
initKeyboardEventNS(namespaceURI, typeArg, canBubbleArg, cancelableArg, viewArg, keyIdentifierArg, keyLocationArg, modifiersList)
This function has no return value.
The namespaceURI parameter is a String.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The viewArg parameter is an object that implements the AbstractView interface.
The keyIdentifierArg parameter is a String.
The keyLocationArg parameter is a Number.
The modifiersList parameter is a String.
Properties of the MutationEvent Constructor function:
MutationEvent.MODIFICATION
The value of the constant MutationEvent.MODIFICATION is 1.
MutationEvent.ADDITION
The value of the constant MutationEvent.ADDITION is 2.
MutationEvent.REMOVAL
The value of the constant MutationEvent.REMOVAL is 3.
Objects that implement the MutationEvent interface:
Objects that implement the MutationEvent interface have all properties and functions of the Event interface as well as the properties and functions defined below.
Properties of objects that implement the MutationEvent interface:
relatedNode
This read-only property is an object that implements the Node interface.
prevValue
This read-only property is a String.
newValue
This read-only property is a String.
attrName
This read-only property is a String.
attrChange
This read-only property is a Number.
Functions of objects that implement the MutationEvent interface:
initMutationEvent(typeArg, canBubbleArg, cancelableArg, relatedNodeArg, prevValueArg, newValueArg, attrNameArg, attrChangeArg)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The relatedNodeArg parameter is an object that implements the Node interface.
The prevValueArg parameter is a String.
The newValueArg parameter is a String.
The attrNameArg parameter is a String.
The attrChangeArg parameter is a Number.
initMutationEventNS(namespaceURI, typeArg, canBubbleArg, cancelableArg, relatedNodeArg, prevValueArg, newValueArg, attrNameArg, attrChangeArg)
This function has no return value.
The namespaceURI parameter is a String.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The relatedNodeArg parameter is an object that implements the Node interface.
The prevValueArg parameter is a String.
The newValueArg parameter is a String.
The attrNameArg parameter is a String.
The attrChangeArg parameter is a Number.
Objects that implement the MutationNameEvent interface:
Objects that implement the MutationNameEvent interface have all properties and functions of the MutationEvent interface as well as the properties and functions defined below.
Properties of objects that implement the MutationNameEvent interface:
prevNamespaceURI
This read-only property is a String.
prevNodeName
This read-only property is a String.
Functions of objects that implement the MutationNameEvent interface:
initMutationNameEvent(typeArg, canBubbleArg, cancelableArg, relatedNodeArg, prevNamespaceURIArg, prevNodeNameArg)
This function has no return value.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The relatedNodeArg parameter is an object that implements the Node interface.
The prevNamespaceURIArg parameter is a String.
The prevNodeNameArg parameter is a String.
initMutationNameEventNS(namespaceURI, typeArg, canBubbleArg, cancelableArg, relatedNodeArg, prevNamespaceURIArg, prevNodeNameArg)
This function has no return value.
The namespaceURI parameter is a String.
The typeArg parameter is a String.
The canBubbleArg parameter is a Boolean.
The cancelableArg parameter is a Boolean.
The relatedNodeArg parameter is an object that implements the Node interface.
The prevNamespaceURIArg parameter is a String.
The prevNodeNameArg parameter is a String.


Acknowledgements

07 November 2003

Appendix F: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett-Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB and invited expert), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C Team Contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

Many thanks to Brad Pettit, Dylan Schiemann, David Flanagan, Steven Pemberton, Curt Arnold, Al Gilman, Misha Wolf, Sigurd Lerstad, Michael B. Allen, Alexander J. Vincent, Martin Dürst, and Ken Rehor for their review and comments of this document.

Special thanks to the DOM Conformance Test Suites contributors: Fred Drake, Mary Brady (NIST), Rick Rivello (NIST), Robert Clary (Netscape), Neil Delima (IBM), with a special mention to Curt Arnold.

F.1 Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Some of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

bubbling phase
The process by which an event can be handled by one of the target ancestors after being handled by the target node.
capture phase
The process by which an event can be handled by one of the target ancestors before being handled by the target node.
child
A child is an immediate descendant node of a node.
DOM Level 0
The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".
event
An event is the representation of some asynchronous occurrence (such as a mouse click on the presentation of the element, or the removal of child node from an element, or any of unthinkably many other possibilities) that gets associated with an event target.
event target
The object to which an event is targeted.
local name
A local name is the local part of a qualified name. This is called the local part in Namespaces in XML [XML Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in Namespaces in XML [XML Namespaces]. See also sections 1.3.2 "DOM URIs" and 1.3.3 "XML Namespaces" regarding URIs and namespace URIs handling and comparison in the DOM APIs.
target node
The target node is the node representing the event target to which an event is targeted using the DOM event flow.
target phase
The process by which an event can be handled by the event target.
XML name
See XML name in the XML specification ([XML 1.0]).


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

H.1 Normative references

[DOM Level 2 Core]
Document Object Model Level 2 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, 13 November 2000. This version of the DOM Level 2 Core Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113. The latest version of DOM Level 2 Core is available at http://www.w3.org/TR/DOM-Level-2-Core.
[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, November 2003. This version of the Document Object Model Level 3 Core Specification is http://www.w3.org/TR/2003/CR-DOM-Level-3-Core-20031107. The latest version of DOM Level 3 Core is available at http://www.w3.org/TR/DOM-Level-3-Core.
[DOM Level 2 Events]
Document Object Model Level 2 Events Specification, T. Pixley, Editor. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Events Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113. The latest version of Document Object Model Level 2 Events is available at http://www.w3.org/TR/DOM-Level-2-Events.
[DOM Level 2 HTML]
Document Object Model Level 2 HTML Specification, J. Stenback, et al., Editors. World Wide Web Consortium, 9 January 2003. This version of the Document Object Model Level 2 HTML Recommendation is http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109. The latest version of Document Object Model Level 2 HTML is available at http://www.w3.org/TR/DOM-Level-2-HTML.
[DOM Level 2 Views]
Document Object Model Level 2 Views Specification, A. Le Hors, L. Cable, Editors. World Wide Web Consortium, 13 November 2000. This version of the Document Object Model Level 2 Views Recommendation is http://www.w3.org/TR/2000/REC-DOM-Level-2-Views-20001113. The latest version of Document Object Model Level 2 Views is available at http://www.w3.org/TR/DOM-Level-2-Views.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, Standard ECMA-262, December 1999. This version of the ECMAScript Language is available from http://www.ecma-international.org/.
[HTML 4.01]
HTML 4.01 Specification, D. Raggett, A. Le Hors, and I. Jacobs, Editors. World Wide Web Consortium, 17 December 1997, revised 24 April 1998, revised 24 December 1999. This version of the HTML 4.01 Recommendation is http://www.w3.org/TR/1999/REC-html401-19991224. The latest version of HTML 4 is available at http://www.w3.org/TR/html4.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[Unicode]
The Unicode Standard, Version 4, ISBN 0-321-18578-1, as updated from time to time by the publication of new versions. The Unicode Consortium, 2000. See also Versions of the Unicode Standard, available at http://www.unicode.org/unicode/standard/versions, for latest version and additional information on versions of the standard and of the Unicode Character Database.
[UTR #15]
Unicode Normalization Forms, The Unicode Standard Annex #15. The Unicode Consortium, 2003. The latest version of this annex is available at http://www.unicode.org/unicode/reports/tr15/.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.

H.2 Informative references

[DOM Level 3 Load and Save]
Document Object Model Level 3 Load and Save Specification, J. Stenback, A. Heninger, Editors. World Wide Web Consortium, November 2003. This version of the DOM Level 3 Load and Save Specification is http://www.w3.org/TR/2003/CR-DOM-Level-3-LS-20031107. The latest version of DOM Level 3 Load and Save is available at http://www.w3.org/TR/DOM-Level-3-LS.
[DWW95]
Developing International Software for Windows 95 and Windows NT: A Handbook for International Software Design, N. Kano, Author. Microsoft Press, 1995. ISBN 1-55615-840-8.
[KeyEvent for Java]
Java 2 SDK, Standard Edition Documentation, Version 1.4.1, Class java.awt.events.KeyEvent. Sun Microsystems. Available at http://java.sun.com/j2se/1.4.1/docs/api/java/awt/event/KeyEvent.html.
[Keys enumeration for .Net]
.NET Framework Class Library, Keys Enumeration. Microsoft. Available at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpref/html/frlrfSystemWindowsFormsKeysClassTopic.asp.
[SVG 1.1]
Scalable Vector Graphics (SVG) 1.1 Specification, J. Ferraiolo, 藤沢 淳 (FUJISAWA Jun), and D. Jackson, Editors. World Wide Web Consortium, 14 January 2003. This version of the SVG 1.1 Recommendation is http://www.w3.org/TR/2003/REC-SVG11-20030114/. The latest version of SVG 1.1 is available at http://www.w3.org/TR/SVG.
[VoiceXML 2.0]
Voice Extensible Markup Language (VoiceXML) Version 2.0, S. McGlashan, et al., Editors. World Wide Web Consortium, February 2003. This version of the Voice Extensible Markup Language Version 2.0 specification is http://www.w3.org/TR/2003/CR-voicexml20-20030220. The latest version of Voice Extensible Markup Language Version 2.0 is available at http://www.w3.org/TR/voicexml20/.
[XForms 1.0]
XForms 1.0, M. Dubinko, et al., Editors. World Wide Web Consortium, August 2003. This version of the XForms 1.0 specification is http://www.w3.org/TR/2003/PR-xforms-20030801/. The latest version of XForms 1.0 is available at http://www.w3.org/TR/xforms/.
[XHTML 1.0]
XHTML 1.0: The Extensible HyperText Markup Language, S. Pemberton, et al., Authors. World Wide Web Consortium, 26 January 2000, revised 1 August 2002. This version of the XHTML 1.0 Recommendation is http://www.w3.org/TR/2002/REC-xhtml1-20020801. The latest version of XHTML 1.0 is available at http://www.w3.org/TR/xhtml1.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML Events]
XML Events, S. McCarron, S. Pemberton, and T.V. Raman, Editors. World Wide Web Consortium, August 2003. This version of the XML Events specification is http://www.w3.org/TR/2003/PR-xml-events-20030804. The latest version of XML Events is available at http://www.w3.org/TR/xml-events.
[XML Schema Part 2]
XML Schema Part 2: Datatypes, P. Byron and Ashok Malhotra, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Part 2 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-2-20010502. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2.


Index

abort 1, 2, 3, 4, 5 | addEventListener | addEventListenerNS
ADDITION | altKey 1, 2 | AT_TARGET
attrChange | attrName
blur 1, 2 | bubbles | bubbling phase 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
BUBBLING_PHASE | button
cancelable | cancelable event 1, 2 | canDispatch
capture phase 1, 2, 3, 4, 5, 6, 7 | CAPTURING_PHASE | change 1, 2, 3, 4, 5
child 1, 2 | click 1, 2, 3 | clientX
clientY | createEvent | ctrlKey 1, 2
currentTarget | CustomEvent
data | detail | DISPATCH_REQUEST_ERR
dispatchEvent | DocumentEvent | DOM event flow
DOM Level 0 1, 2, 3, 4 | DOM Level 2 Core 1, 2 | DOM Level 2 Events 1, 2, 3, 4, 5, 6, 7
DOM Level 2 HTML 1, 2, 3 | DOM Level 2 Views 1, 2 | DOM Level 3 Core 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
DOM Level 3 Load and Save 1, 2 | DOM_KEY_LOCATION_LEFT | DOM_KEY_LOCATION_NUMPAD
DOM_KEY_LOCATION_RIGHT | DOM_KEY_LOCATION_STANDARD | DOMActivate 1, 2, 3
DOMAttributeNameChanged 1, 2, 3 | DOMAttrModified 1, 2, 3 | DOMCharacterDataModified 1, 2, 3
DOMElementNameChanged 1, 2, 3 | DOMFocusIn 1, 2, 3 | DOMFocusOut 1, 2, 3
DOMNodeInserted 1, 2, 3 | DOMNodeInsertedIntoDocument 1, 2, 3 | DOMNodeRemoved 1, 2, 3
DOMNodeRemovedFromDocument 1, 2, 3 | DOMSubtreeModified 1, 2, 3 | DWW95
ECMAScript | error 1, 2, 3, 4, 5 | Event 1, 2, 3, 4, 5
event target 1, 2, 3, 4, 5, 6, 7, 8 | EventException | EventListener
eventPhase | EventTarget
focus 1, 2
getModifierState 1, 2
handleEvent | hasEventListenerNS | HTML 4.01 1, 2, 3, 4, 5, 6, 7
initEvent | initEventNS | initKeyboardEvent
initKeyboardEventNS | initMouseEvent | initMouseEventNS
initMutationEvent | initMutationEventNS | initMutationNameEvent
initMutationNameEventNS | initTextEvent | initTextEventNS
initUIEvent | initUIEventNS | Input Method Editor 1
isCustom | isDefaultPrevented | isImmediatePropagationStopped
isPropagationStopped
Java
KeyboardEvent | keydown 1, 2, 3 | KeyEvent for Java
keyIdentifier | keyLocation | Keys enumeration for .Net
keyup 1, 2, 3
load 1, 2, 3, 4, 5 | local name 1, 2, 3, 4, 5
metaKey 1, 2 | MODIFICATION | mousedown 1, 2, 3
MouseEvent | mousemove 1, 2, 3 | mouseout 1, 2, 3
mouseover 1, 2, 3 | mouseup 1, 2, 3 | MutationEvent
MutationNameEvent
namespace URI 1, 2, 3, 4, 5, 6 | namespaceURI | newValue
OMG IDL
preventDefault | prevNamespaceURI | prevNodeName
prevValue
relatedNode | relatedTarget | REMOVAL
removeEventListener | removeEventListenerNS | reset 1, 2, 3, 4, 5
resize 1, 2, 3, 4, 5
screenX | screenY | scroll 1, 2, 3, 4, 5
select 1, 2, 3, 4, 5 | setDispatchState | shiftKey 1, 2
stopImmediatePropagation | stopPropagation | submit 1, 2, 3, 4, 5
SVG 1.1 1, 2, 3
target | target node 1, 2, 3, 4, 5, 6 | target phase 1, 2, 3, 4, 5, 6, 7, 8
TextEvent | textInput 1, 2, 3 | timeStamp
type
UIEvent | Unicode 1, 2 | unload 1, 2, 3, 4, 5
UNSPECIFIED_EVENT_TYPE_ERR | UTR #15 1, 2
view | VoiceXML 2.0 1, 2
willTriggerNS
XForms 1.0 1, 2 | XHTML 1.0 1, 2, 3, 4 | XML 1.0 1, 2, 3
XML Events 1, 2, 3 | XML name 1, 2 | XML Namespaces 1, 2, 3, 4, 5
XML Schema Part 2 1, 2


Document Object Model Level 3 Abstract Schemas

next contents index

Document Object Model (DOM) Level 3 Abstract Schemas Specification

Version 1.0

W3C Note 25 July 2002

This version:
http://www.w3.org/TR/2002/NOTE-DOM-Level-3-AS-20020725
Latest version:
http://www.w3.org/TR/DOM-Level-3-AS
Previous version:
http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409
Editors:
Ben Chang, Oracle
Elena Litani, IBM
Joe Kesselman, IBM (until September 2001)
Rezaur Rahman, Intel Corporation (until July 2001)

Copyright ?002 W3C ?/SUP> (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Abstract

This specification defines the Document Object Model Abstract Schemas Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.

This document is a W3C NOTE made available by the W3C for discussion only. Publication of this Note by W3C indicates no endorsement of its content by W3C, nor that W3C will be reallocating any resources to the issues addressed by the Note. This document is no longer a work in progress.

Comments on this document are invited and are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM WG members. The DOM WG has no plans for further work on this document and this version has been published to clarify the status section of the previously published version.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • 1. Abstract Schemas Object Model
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
  • Glossary
  • References
  • Index
next contents index


Copyright Notice

Copyright ?2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

This document is published under the W3C Document Copyright Notice and License. The bindings within this document are published under the W3C Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.

W3C Document Copyright Notice and License

Note: This section is a copy of the W3C Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-documents-19990405.

Copyright ?1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice of the form: "Copyright ?[$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/" (Hypertext is preferred, but a textual representation is permitted.)
  3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

W3C Software Copyright Notice and License

Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720

Copyright ?1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.

http://www.w3.org/Consortium/Legal/

This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers. If none exist, then a notice of the following form: "Copyright ?[$date-of-software] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/."
  3. Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.

previous next contents index


1. Abstract Schemas Object Model

Editors:
Ben Chang, Oracle
Elena Litani, IBM
Joe Kesselman, IBM (until September 2001)
Rezaur Rahman, Intel Corporation (until July 2001)

Table of contents

  • 1.1. Overview
    • 1.1.1. General Characteristics
    • 1.1.2. Use Cases and Requirements
  • 1.2. Issue List
    • 1.2.1. Open Issues
    • 1.2.2. Resolved Issues
  • 1.3. Abstract Schema API
    • 1.3.1. Basic Abstract Schema Interfaces
      • ASConstants, ASObject, ASDataType, ASObjectList, ASNamedObjectMap
    • 1.3.2. Read Only Abstract Schemas interfaces
      • ASModel, ASContentModel, ASElementDecl, ASAttributeDecl, ASEntityDecl, ASNotationDecl
    • 1.3.3. Abstract Schema Editing Interfaces
      • ASWModel, ASWNamedObjectMap, ASWElementDecl, ASWContentModel, ASWAttributeDecl, ASWEntityDecl, ASWNotationDecl
  • 1.4. Validation and Other Interfaces
    • ASException, ASExceptionCode, DocumentAS, DOMImplementationAS
  • 1.5. Editing and Generating an Abstract Schema
  • 1.6. Abstract Schema-directed Document Manipulation
  • 1.7. Validating a Document Against an Abstract Schema
  • 1.8. Well-formedness Testing
  • 1.9. Load and Save for Abstract Schemas
    • ASDOMBuilder, ASDOMWriter

1.1. Overview

This chapter describes the optional DOM Level 3 Abstract Schemas (AS) feature. This module provides a representation for XML abstract schemas, e.g., DTDs [XML 1.0] and XML Schemas [XML Schema Part 0], together with operations on the abstract schemas, and how such information within the abstract schemas could be applied to XML documents used in both the document editing and abstract schema editing worlds.

A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether a given DOM supports these capabilities or not. This module defines 3 feature strings: "AS-READ" for read only access to abstract schemas, "AS-EDIT" editing of abstract schemas, and "AS-DOC" for document-editing interfaces.

This chapter interacts strongly with [DOM Level 3 Load and Save]. Not only will that code serialize/deserialize abstract schemas, but it may also wind up defining its well-formedness and validity checks in terms of what is defined in this chapter. In addition, the AS and Load/Save functional areas uses the error-reporting mechanism allowing user-registered error callbacks introduced in [DOM Level 3 Core]. Note that this may not imply that the parser actually calls the DOM's validation code -- it may be able to achieve better performance via its own -- but the appearance to the user should probably be "as if" the DOM has been asked to validate the document, and parsers should probably be able to validate newly loaded documents in terms of a previously loaded DOM AS.

Finally, this chapter will have separate sections to address the needs of the document-editing and AS-editing worlds, along with a section that details overlapping areas such as validation. In this manner, the document-editing world's focuses on editing aspects and usage of information in the AS are made distinct from the AS-editing world's focuses on defining and manipulating the information in the AS.

1.1.1. General Characteristics

In the October 9, 1997 DOM requirements document, the following appeared: "There will be a way to determine the presence of a DTD. There will be a way to add, remove, and change declarations in the underlying DTD (if available). There will be a way to test conformance of all or part of the given document against a DTD (if available)." In later discussions, the following was added, "There will be a way to query element/attribute (and maybe other) declarations in the underlying DTD (if available)," supplementing the primitive support for these in Level 1.

That work was deferred past Level 2, in the hope that XML Schemas would be addressed as well. It is anticipated that lowest common denominator general APIs generated in this chapter can support both DTDs and XML Schemas, and other XML abstract schemas down the road.

The kinds of information that an Abstract Schema must make available are mostly self-evident from the definitions of Infoset, DTDs, and XML Schemas. Note that some kinds of information on which the DOM already relies, e.g., default values for attributes, will finally be given a visible representation here.

1.1.2. Use Cases and Requirements

The abstract schema referenced in these use cases/requirements is an abstraction and does not refer solely to DTDs or XML Schemas.

For the AS-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:

  1. CU1. Associating an abstract schema with a document, or changing the current association.
  2. CU2. Using the same abstract schema with several documents, without having to reload it.

Requirements:

  1. CR1. Validate against the abstract schema.
  2. CR2. Retrieve information from abstract schema.
  3. CR3. Load an existing abstract schema, perhaps independently from a document.
  4. CR4. Being able to determine if a document has an abstract schema associated with it.
  5. CR5. Associate an AS with a document and make it the active AS.

Specific to the AS-editing world, the following are use cases and requirements and could be labeled as the "AS-editing" section:

Use Cases:

  1. ASU1. Clone/map all or parts of an existing abstract schema to a new or existing abstract schema.
  2. ASU2. Save an abstract schema in a separate file. For example, if 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. Note that a DTD, which may include both an internal and external subset, would be an example of an abstract schema.
  3. ASU3. Modify an existing abstract schema.
  4. ASU4. Create a new abstract schema.

Requirements:

  1. ASR1. View and modify all parts of the abstract schema.
  2. ASR2. Validate the abstract schema itself.
  3. ASR3. Serialize the abstract schema.
  4. ASR4. Clone all or parts of an existing abstract schema.
  5. ASR5. Create a new abstract schema object.
  6. ASR6. Validate portions of the XML document against the abstract schema.

Specific to the document-editing world, the following are use cases and requirements and could be labeled as the "Document-editing" section:

Use Cases:

  1. DU1. For editing documents with an associated abstract schema, provide the guidance necessary so that valid documents can be modified and remain valid.
  2. DU2. For editing documents with an associated abstract schema, provide the guidance necessary to transform an invalid document into a valid one.

Requirements:

  1. DR1. Be able to determine if the document is well-formed, and if not, be given enough guidance to locate the error.
  2. DR2. Be able to determine if the document is namespace well-formed, and if not, be given enough guidance to locate the error.
  3. DR3. Be able to determine if the document is valid with respect to its associated abstract schema.
  4. DR4. Be able to determine if specific modifications to a document would make it become invalid.
  5. DR5. Retrieve information from all abstract schemas. One example might be getting a list of all the defined element names for document editing purposes.

1.2. Issue List

1.2.1. Open Issues

Issue AS-Issue-8:
For Abstract Schemas interfaces (AS-READ/AS-EDIT) there should be no dependency on DOM Core. How can we remove inheritance between DOMImplementationAS and DOMImplementation?
Issue AS-Issue-9:
ASDatatype. Can we remove OTHER_SIMPLE_DATATYPE, COMPLEX_DATATYPE?
Issue AS-Issue-10:
ASDatatype. Do we need to add ANY_TYPE, ANY_SIMPLETYPE?
Issue AS-Issue-11:
ASWObjectList is live. What does it mean for ASObjectList to be live?
Issue AS-Issue-12:
Should we rename ASAttributeDecl.defaultType attribute to constraintType?
Issue AS-Issue-13:
Should default value constraint be added to ASDataType? This would include defaultType constraint and defaultValue.
Issue AS-Issue-14:
Clarify what exactly ASWModel represents: does it represent "a schema" as defined in XML Schema or a schema document? If it represents a "document" we should consider removing inheritance between ASModel and ASWModel interfaces (the inheritance between components should be kept).
Issue AS-Issue-15:
Is there any need for ASWModel.insertASObject method? Can we remove this method?
Issue AS-Issue-16:
Since each object carries a namespace do we need setNamedItemNS and removeNamedItemNS methods on ASWObjectList?
Issue AS-Issue-17:
Is there need for separation between ASObject.rawname and ASObject.name? Can "name" be defined as one attribute? If we need to keep ASObject.rawname, can we come up with another name? Qualified name can not be used because it does not include multiple colons. Also, the factory method have parameter name, should those include rawname as well?
Issue AS-Issue-18:
ASDOMBuilder allows to parse a schema document. The return type is ASWModel. This means that implementation that want to implement Loading of schemas must implement AS-EDIT. The return type should be a read-only object.
Issue AS-Issue-19:
ASDOMBuilder.abstractSchema allows to set a schema on a parser instance. How can user set multiple schemas?
Issue AS-Issue-20:
Does ASDOMWriter write a DTD or an XML Schema (or something else)? Is it possible to use this method to convert a DTD to an XML Schema?
Issue AS-Issue-21:
The constants have a common suffix. Would not it easier to find the constants within same group alphabetically? In other words, should constants include common prefix instead?
Issue AS-Issue-22:
DOMImplementationAS.createASModel takes as a parameter schemaType. What happens if user specifies null for the schemaType?

1.2.2. Resolved Issues

Issue AS-Issue-1:
Should we add a constant for a datatype? Should ASDataType inherit from ASObject?
Resolution: ASObject does not need to model datatypes.
Issue AS-Issue-2:
INTERNAL_SUBSET, EXTERNAL_SUBSET, INTERNAL_ENTITY and EXTERNAL_ENTITY seem to carry the same meaning. Should _ENTITY constants be removed?
Resolution: No. The constants are used for different purposes and on different interfaces. It would be confusing for users to have same constant for 2 different purposes.
Issue AS-Issue-3:
Some components in Abstract Schema do not have name. ASObject serves as a base component for the model. Should it include names/namespace fields?
Resolution: Yes. It gives more flexibility to a user while manipulating/accessing objects in a list: no cast to type-specific interface is needed.
Issue AS-Issue-4:
We should remove ASElementDecl.isPCDataOnly and corresponding setPCDataOnly methods. Instead, lets introduce SIMPLE content type that will represent PCDataOnly for DTDs. In general, simple content means that conent consists only of character data (there are no elements in the content).
Resolution: Remove isPCDataOnly methods. Add SIMPLE_CONTENTTYPE constant.
Issue AS-Issue-5:
ASAttributeDecl.enumData is DTD only field. Can we remove this field?
Resolution: No.
Issue AS-Issue-6:
ASAttributeDecl.ownerElements became a readonly field. Implementation are expected to compute this field.
Resolution: Yes, this should be a readonly field.
Issue AS-Issue-7:
For the RW AS editing interfaces, exceptions need to be thrown for such operations if the AS-READ feature string is set.
Resolution: No. The implementation will always support AS-EDIT in this mode, no changing back and forth

1.2.2.1. General Issues

Issue I1:
Some concerns exist regarding whether a single abstract Abstract Schema structure can successfully represent both namespace-unaware, e.g., DTD, and namespace-aware, e.g., XML Schema, models of document's content. For example, when you ask what elements can be inserted in a specific place, the former will report the element's QName, e.g., foo:bar, whereas the latter will report its namespace and local name, e.g., {http://my.namespace}bar. We have added the NamespaceAware attribute to the generic AS object to help applications determine which of these fields are important, but we are still analyzing this challenge. Nonetheless, after much discussion, we have made the decision that only 1 active ASModel is allowed, even on ASDOMBuilder (the parser would set the 1 active schema).
Issue I2:
An XML document may be associated with multiple ASs. We have decided that only one of these is "active" (for validation and guidance) at a time. DOM applications may switch which AS is active, remove ASs that are no longer relevant, or add ASs to the list. If it becomes necessary to simultaneously consult more than one AS, it should be possible to write a "union" AS which provides that capability within this framework.
Issue I3:
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.
Resolution: Won't deal w/this
Issue I4:
Basic interface for a common error handler for both AS and Load/Save. Agreement has been to utilize user-registered callbacks but other details to be worked out. Moved to a separate chapter by Load/Save team.
Issue I5:
Add the ability to cache/edit an imported abstract schema instead of loading it every time, i.e., don't want to include the abstract schema every time. Implementations can do this without having this formalized though.
Issue I6:
Add a read-only feature string AS-QUERY, along with query methods on the abstract schema. In more detail, there are methods that let you *query* the schema as well as those that let you modify the schema and these should be a feature, i.e., AS-QUERY: Abstract Schema objects with query interfaces.
Resolution: Won't deal w/this for now.
Issue I7:
Have the NodeEditAS.can*(), CharacterDataEditAS.can*() , and ElementEditAS.can*() methods throw exceptions like the isNodeValid() method. Resolution: no exceptions should be thrown; it should be allowed if it's not forbidden. Better descriptions are in order for the true/false returns.
Issue I8:
Rename the document-editing interfaces so they should have uniform names such as NodeEditAS, DocumentEditAS, ElementEditAS, etc.
Issue I9:
Remove the ASDOMStringList interface; create a new interface for document editing, which is a slimmed down version of ElementEditAS; add a slimmed down method to get an ElementEditAS. Elena to examine.
Issue I10:
If another ASModel is activated, will there be cleanup done to remove the previous ASModel's default attributes and entity definitions, if any? AS ET members felt that whatever is done implementation-wise, correct behavior should result.
Issue I11:
List of ASExceptions in the AS spec thus far: INVALID_CHARACTER_ERR, DUPLICATE_NAME_ERR, VALIDATION_ERR.
Issue I12:
Should names/namespaces of the various declarations be mutable during AS editing? AS ET agreed they should and are awaiting action by the XML CORE team. Will be done in CORE.
Issue I13:
AS ET thinks the validate method and the error handler should be on Document, in CORE. If this doesn't happen, it needs to be on DocumentAS. It was decided that the validate method be on DocumentAS.
Issue I14:
If entities are changed in the ASWModel, the underlying model is unchanged until normalization.
Issue I15:
Add option to control whether DOM AS is built from this document - solution is that the model is loaded (if there is one) and can be retrieved through the DocumentAS interface.
Issue I16:
There is a way to add a new schema file to the existing active compound schema via addASWModel().
Issue I17:
Altering the document during error reporting, or mutation during validation terminates validation, and a warning will be produced if this happens.
Issue I18:
Proposal needed to rename the asHint, asLocation attributes and tie that into how to describe an ASWModel container of other ASWModels.
Issue I19:
Proposal to revise getElementDecl method and introduce other methods on the DocumentAS interface, such as getAttributeDecl, getNotationDecl, getEntityDecl. Some have mentioned that that these methods should better be added on ASWModel to distinguish between where these declarations came from, the internal or external subset. RESOLUTION: added get*Decl methods on DocumentAS.
Issue I20:
If implementation doesn't support AS-editing, need to have each set method throw an unsupported exception. DONE.
Issue I21:
Notion of read-only AS to be discussed. Currently, the activeASModel is read/write. Need to see where appropriate exceptions need to be thrown in a read-only AS. The methods affected are the following: addASWModel, removeAS, importASObject, insertASObject, removedNamedItem, setNamedItem, addASWAttributeDecl, removeASWAttributeDecl, removesubModel, insertBeforesubModel, appendsubModel, setInternalAS, addAS, removeAS. For a read-only AS, the NO_MODIFICATION exception would be thrown when the feature string AS-READ is set.
Resolution: The interfaces for Abstract Schema were split into read and read/write. New feature string introduced "AS-READ".
Issue I22:
For developers, need to keep ASWElementDecl in sync for both an ASWModel and ASWContentModel, if operations modify the ASWElementDecl. Documentation was added in the ASWElementDecl editing methods to reflect this.
Issue I23:
Need to clarify the descriptions on the ASWModel internal/external subset and "global" attributes. Need to also introduce the concept of a dummy element declaration and dummy constant for element types not yet declared but appearing in the content model of another element type.
Issue I24:
Is there a need for ElementEditAS.getASWElementDecl()? No longer in existence.
Issue I25:
What happens when a user adds DOCTYPE nodes, when do you create a DOCTYPE after a change in ASWModel or after the document has been created? The "can be resolved" is done via the "normalizeDocument" method since it will be able to update the DOCTYPE node according to the abstractschema.
Issue I26:
TO BE DONE: Need to add a table for ASObject that is analogous to the table in DOM CORE for Node.
Issue I27:
TO BE DONE: "Unknown" validity needs to be accounted for validity states.
Issue I28:
Why have both setNamedItemNS and setNamedItem; and removeNameItemNS and removeNamedItem? One set can be eliminated, but CORE has similar functionality.

1.3. Abstract Schema API

This section defines APIs for accessing, manipulating and modifying an abstract schema (database schema, DTD, XML Schema).

1.3.1. Basic Abstract Schema Interfaces

The set of Abstract Schema interfaces that are common for AS-READ and AS-EDIT.

Interface ASConstants

This interface defines a set of constants used in AS model.

IDL Definition
interface ASConstants {

  // ASObject Types
  const unsigned short      ELEMENT_DECLARATION            = 1;
  const unsigned short      ATTRIBUTE_DECLARATION          = 2;
  const unsigned short      NOTATION_DECLARATION           = 3;
  const unsigned short      ENTITY_DECLARATION             = 4;
  const unsigned short      CONTENT_MODEL                  = 5;
  const unsigned short      SCHEMA_MODEL                   = 6;

  // Schema Model types
  const unsigned short      INTERNAL_SUBSET                = 30;
  const unsigned short      EXTERNAL_SUBSET                = 31;
  const unsigned short      NOT_USED                       = 32;

  // Entity Types
  const unsigned short      INTERNAL_ENTITY                = 33;
  const unsigned short      EXTERNAL_ENTITY                = 34;

  // Content Model Types
  const unsigned short      EMPTY_CONTENTTYPE              = 40;
  const unsigned short      SIMPLE_CONTENTTYPE             = 41;
  const unsigned short      ELEMENT_CONTENTTYPE            = 42;
  const unsigned short      MIXED_CONTENTTYPE              = 43;
  const unsigned short      ANY_CONTENTTYPE                = 44;

  // Content model compositors
  const unsigned short      SEQUENCE_CM                    = 50;
  const unsigned short      CHOICE_CM                      = 51;
  const unsigned short      ALL_CM                         = 52;
  const unsigned short      UNDEFINED_CM                   = 53;
  const unsigned short      ATOMIC_CM                      = 54;

  // Value Constraint
  const unsigned short      NONE_VC                        = 0;
  const unsigned short      DEFAULT_VC                     = 60;
  const unsigned short      FIXED_VC                       = 61;
  const unsigned short      REQUIRED_VC                    = 62;

  // Definition of unbounded
  const unsigned long       UNBOUNDED                      = MAX_VALUE;
};

Definition group ASObject Types

An integer indicating which type of ASConstants this is.

Defined Constants
ATTRIBUTE_DECLARATION
The object describes an attribute declaration.
CONTENT_MODEL
The object describes a content model definition.
ELEMENT_DECLARATION
The object describes an element declaration.
ENTITY_DECLARATION
The object describes an entity declaration.
NOTATION_DECLARATION
The object describes a notation declaration.
SCHEMA_MODEL
The object describes a schema model.
Definition group Schema Model types

A code representing how the ASModel is used.

Defined Constants
EXTERNAL_SUBSET
The ASModel is used as an external subset.
INTERNAL_SUBSET
The ASModel is used as an internal subset.
NOT_USED
The ASModel is neither used as an internal or external subset.
Definition group Entity Types

An integer indicating which type of entity this is.

Defined Constants
EXTERNAL_ENTITY
A constant defining an external entity.
INTERNAL_ENTITY
A constant defining an internal entity.
Definition group Content Model Types

A code representing the type of content model.

Defined Constants
ANY_CONTENTTYPE
Represents an ANY content type for an Element declaration.
ELEMENT_CONTENTTYPE
Represents an element-only content type. An element-only content type validates elements with children that conform to the supplied content model.
EMPTY_CONTENTTYPE
Represents an EMPTY content type for an Element declaration. A content type with the distinguished value empty validates elements with no character or element information item children.
MIXED_CONTENTTYPE
Represents a MIXED content type for an Element declaration.
SIMPLE_CONTENTTYPE
The content model type simple. A content type which is a simple validates elements with character-only children.
Definition group Content model compositors

List of content model compositors.

Defined Constants
ALL_CM
This content model represents a simplified version of the SGML &-Connector and is limited to the top-level of any content model. No element in the content model may appear more than once. Please refer to the definition element-all.
ATOMIC_CM
In this content model the subModel includes a single definition.
CHOICE_CM
This constant value signifies a choice operator. For example, in a DTD, this would be the '|' operator.
SEQUENCE_CM
This constant value signifies a sequence operator. For example, in a DTD, this would be the ',' operator.
UNDEFINED_CM
This content model is undefined, and is associated with incomplete element declarations in the ASModel, meaning elements implicitly declared through an attribute list but without any corresponding element declarations.
Definition group Value Constraint
Defined Constants
DEFAULT_VC
Indicates that there is a default value constraint.
FIXED_VC
Indicates that there is a fixed value constraint for this attribute.
NONE_VC
Describes that the component does not have any value constraint.
REQUIRED_VC
Indicates that attribute is required.
Definition group Definition of unbounded
Defined Constants
UNBOUNDED
Signifies unbounded upper limit for a content model. The MAX_VALUE value is 0xFFFFFFFF FFFFFFFF.
(ED: This needs to be better defined in the generated bindings.)
Interface ASObject

The ASObject interface is analogous to a Node in [DOM Level 3 Core], e.g., an element declaration.

IDL Definition
interface ASObject {
  readonly attribute unsigned short  objectType;
  readonly attribute ASModel         ownerModel;
  readonly attribute DOMString       rawname;
  readonly attribute DOMString       name;
  readonly attribute DOMString       namespace;
  ASObject           cloneASObject(in boolean deep)
                                        raises(ASException);
};

Attributes
name of type DOMString, readonly
The name of type NCName of this declaration as defined in [XML Namespaces].
namespace of type DOMString, readonly
The namespace URI of this object, or null if it is unspecified. [XML Schema Part 1]defines how a namespace URI is attached to schema components.
objectType of type unsigned short, readonly
The type of this object, ei. ELEMENT_DECLARATION.
ownerModel of type ASModel, readonly
The ASModel object associated with this ASObject. For a object of type AS_MODEL, this is null.
rawname of type DOMString, readonly
The rawname of this declaration of type Name as defined in [XML 1.0]. This value will be available only for schemas that allow to declare name of type Name.
Methods
cloneASObject
Creates a copy of this ASObject. See text for cloneNode off of Node but substitute AS functionality.
Parameters
deep of type boolean
Setting the deep flag on, causes the whole subtree to be duplicated. Setting it to false only duplicates its immediate child nodes.
Return Value

ASObject

Cloned ASObject.

Exceptions

ASException

NOT_SUPPORTED_ERR: Raised if implementation doesn't support AS-EDIT.

Interface ASDataType

The datatypes supported by DOM AS implementations. Further datatypes may be added in the Schema/PSVI spec.

IDL Definition
interface ASDataType {
  readonly attribute unsigned short  dataType;

  // DATA_TYPES
  const unsigned short      STRING_DATATYPE                = 1;
  const unsigned short      NOTATION_DATATYPE              = 10;
  const unsigned short      ID_DATATYPE                    = 11;
  const unsigned short      IDREF_DATATYPE                 = 12;
  const unsigned short      IDREFS_DATATYPE                = 13;
  const unsigned short      ENTITY_DATATYPE                = 14;
  const unsigned short      ENTITIES_DATATYPE              = 15;
  const unsigned short      NMTOKEN_DATATYPE               = 16;
  const unsigned short      NMTOKENS_DATATYPE              = 17;
  const unsigned short      BOOLEAN_DATATYPE               = 100;
  const unsigned short      FLOAT_DATATYPE                 = 101;
  const unsigned short      DOUBLE_DATATYPE                = 102;
  const unsigned short      DECIMAL_DATATYPE               = 103;
  const unsigned short      HEXBINARY_DATATYPE             = 104;
  const unsigned short      BASE64BINARY_DATATYPE          = 105;
  const unsigned short      ANYURI_DATATYPE                = 106;
  const unsigned short      QNAME_DATATYPE                 = 107;
  const unsigned short      DURATION_DATATYPE              = 108;
  const unsigned short      DATETIME_DATATYPE              = 109;
  const unsigned short      DATE_DATATYPE                  = 110;
  const unsigned short      TIME_DATATYPE                  = 111;
  const unsigned short      GYEARMONTH_DATATYPE            = 112;
  const unsigned short      GYEAR_DATATYPE                 = 113;
  const unsigned short      GMONTHDAY_DATATYPE             = 114;
  const unsigned short      GDAY_DATATYPE                  = 115;
  const unsigned short      GMONTH_DATATYPE                = 116;
  const unsigned short      INTEGER                        = 117;
  const unsigned short      NAME_DATATYPE                  = 200;
  const unsigned short      NCNAME_DATATYPE                = 201;
  const unsigned short      NORMALIZEDSTRING_DATATYPE      = 202;
  const unsigned short      TOKEN_DATATYPE                 = 203;
  const unsigned short      LANGUAGE_DATATYPE              = 204;
  const unsigned short      NONPOSITIVEINTEGER_DATATYPE    = 205;
  const unsigned short      NEGATIVEINTEGER_DATATYPE       = 206;
  const unsigned short      LONG_DATATYPE                  = 207;
  const unsigned short      INT_DATATYPE                   = 208;
  const unsigned short      SHORT_DATATYPE                 = 209;
  const unsigned short      BYTE_DATATYPE                  = 210;
  const unsigned short      NONNEGATIVEINTEGER_DATATYPE    = 211;
  const unsigned short      UNSIGNEDLONG_DATATYPE          = 212;
  const unsigned short      UNSIGNEDINT_DATATYPE           = 213;
  const unsigned short      UNSIGNEDSHORT_DATATYPE         = 214;
  const unsigned short      UNSIGNEDBYTE_DATATYPE          = 215;
  const unsigned short      POSITIVEINTEGER_DATATYPE       = 216;
  const unsigned short      ANYSIMPLETYPE_DATATYPE         = 216;
  const unsigned short      ANYTYPE_DATATYPE               = 216;
};

Definition group DATA_TYPES

An integer indicating which datatype this is.

Defined Constants
ANYSIMPLETYPE_DATATYPE
A code representing a anySimpleType data type as defined in [XML Schema Part 2].
ANYTYPE_DATATYPE
A code representing a anyType data type as defined in [XML Schema Part 2].
ANYURI_DATATYPE
A code representing an uri reference data type as defined in [XML Schema Part 2].
BASE64BINARY_DATATYPE
A code representing a base64binary data type as defined in [XML Schema Part 2].
BOOLEAN_DATATYPE
A code representing the boolean data type as defined in [XML Schema Part 2].
BYTE_DATATYPE
A code representing a byte data type as defined in [XML Schema Part 2].
DATETIME_DATATYPE
A code representing a datetime data type as defined in [XML Schema Part 2].
DATE_DATATYPE
A code representing a date data type as defined in [XML Schema Part 2].
DECIMAL_DATATYPE
A code representing a decimal data type as defined in [XML Schema Part 2].
DOUBLE_DATATYPE
A code representing the double data type as defined in [XML Schema Part 2].
DURATION_DATATYPE
A code representing a duration data type as defined in [XML Schema Part 2].
ENTITIES_DATATYPE
A code representing a ENTITIES data type as defined in [XML Schema Part 2].
ENTITY_DATATYPE
A code representing a ENTITY data type as defined in [XML Schema Part 2].
FLOAT_DATATYPE
A code representing the float data type as defined in [XML Schema Part 2].
GDAY_DATATYPE
A code representing a day data type as defined in [XML Schema Part 2].
GMONTHDAY_DATATYPE
A code representing a monthday data type as defined in [XML Schema Part 2].
GMONTH_DATATYPE
A code representing a month data type as defined in [XML Schema Part 2].
GYEARMONTH_DATATYPE
A code representing a yearmonth data type as defined in [XML Schema Part 2].
GYEAR_DATATYPE
A code representing a year data type as defined in [XML Schema Part 2].
HEXBINARY_DATATYPE
A code representing a hexbinary data type as defined in [XML Schema Part 2].
IDREFS_DATATYPE
A code representing a IDREFS data type as defined in [XML Schema Part 2].
IDREF_DATATYPE
A code representing a IDREF data type as defined in [XML Schema Part 2].
ID_DATATYPE
A code representing a ID data type as defined in [XML Schema Part 2].
INTEGER
A code representing a integer data type as defined in [XML Schema Part 2].
INT_DATATYPE
A code representing a integer data type as defined in [XML Schema Part 2].
LANGUAGE_DATATYPE
A code representing a Language data type as defined in [XML Schema Part 2].
LONG_DATATYPE
A code representing an long data type as defined in [XML Schema Part 2].
NAME_DATATYPE
A code representing the Name data type as defined in [XML Schema Part 2].
NCNAME_DATATYPE
A code representing the NCName data type as defined in [XML Schema Part 2].
NEGATIVEINTEGER_DATATYPE
A code representing an negative integer data type as defined in [XML Schema Part 2].
NMTOKENS_DATATYPE
A code representing a NMTOKENS data type as defined in [XML Schema Part 2].
NMTOKEN_DATATYPE
A code representing a NMTOKEN data type as defined in [XML Schema Part 2].
NONNEGATIVEINTEGER_DATATYPE
A code representing a non-negative integer data type as defined in [XML Schema Part 2].
NONPOSITIVEINTEGER_DATATYPE
A code representing a Non-positive integer data type as defined in [XML Schema Part 2].
NORMALIZEDSTRING_DATATYPE
A code representing the Normalized string data type as defined in [XML Schema Part 2].
NOTATION_DATATYPE
A code representing a NOTATION data type as defined in [XML Schema Part 2].
POSITIVEINTEGER_DATATYPE
A code representing a positive integer data type as defined in [XML Schema Part 2].
QNAME_DATATYPE
A code representing an XML qualified name data type as defined in [XML Schema Part 2].
SHORT_DATATYPE
A code representing a short data type as defined in [XML Schema Part 2].
STRING_DATATYPE
A code representing the string data type as defined in [XML Schema Part 2].
TIME_DATATYPE
A code representing a time data type as defined in [XML Schema Part 2].
TOKEN_DATATYPE
A code representing a token data type as defined in [XML Schema Part 2].
UNSIGNEDBYTE_DATATYPE
A code representing a unsigned byte data type as defined in [XML Schema Part 2].
UNSIGNEDINT_DATATYPE
A code representing a unsigned integer data type as defined in [XML Schema Part 2].
UNSIGNEDLONG_DATATYPE
A code representing a unsigned long data type as defined in [XML Schema Part 2].
UNSIGNEDSHORT_DATATYPE
A code representing a unsigned short data type as defined in [XML Schema Part 2].
Attributes
dataType of type unsigned short, readonly
One of the enumerated codes representing the data type.
Interface ASObjectList

The ASObjectList interface provides the abstraction of an ordered collection of AS objects, without defining or constraining how this collection is implemented. ASObjectList objects in the DOM AS are live.

IDL Definition
interface ASObjectList {
  readonly attribute unsigned long   length;
  ASObject           item(in unsigned long index);
};

Attributes
length of type unsigned long, readonly
The number of ASObjects in the list. The range of valid child object indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. The index starts at 0. If index is greater than or equal to the number of objects in the list, this returns null.
Parameters
index of type unsigned long
index into the collection.
Return Value

ASObject

The ASObjectat the indexth position in the ASObjectList, or null if that is not a valid index.

No Exceptions
Interface ASNamedObjectMap

Objects implementing the ASNamedObjectMap interface are used to represent collections of abstract schema objects that can be accessed by name. Note that ASNamedObjectMap does not inherit from ASObjectList; ASNamedObjectMaps are not maintained in any particular order.

IDL Definition
interface ASNamedObjectMap {
  readonly attribute unsigned long   length;
  ASObject           item(in unsigned long index);
  ASObject           getNamedItem(in DOMString name);
  ASObject           getNamedItemNS(in DOMString namespaceURI,
                                    in DOMString localName);
};

Attributes
length of type unsigned long, readonly
The number of ASObjects in the ASObjectList. The range of valid child object indices is 0 to length-1 inclusive.
Methods
getNamedItem
Retrieves an ASObject specified by name.
Parameters
name of type DOMString
The objectName of an ASObject to retrieve.
Return Value

ASObject

An ASObject with specified object name and null if the map does not contain an element with the given name.

No Exceptions
getNamedItemNS
Retrieves a node specified by local name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to retrieve.
localName of type DOMString
The local name of the node to retrieve.
Return Value

ASObject

A ASObject (of any type) with the specified local name and namespace URI, or null if they do not identify any node in this map.

No Exceptions
item
Returns the indexth item in the collection. The index starts at 0. If index is greater than or equal to the number of objects in the list, this returns null.
Parameters
index of type unsigned long
index into the collection.
Return Value

ASObject

The ASObject at the indexth position in the ASObjectList, or null if that is not a valid index.

No Exceptions

1.3.2. Read Only Abstract Schemas interfaces

The interfaces in this section provide a read-only access to abstract schemas.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-READ" and "3.0" (respectively) to determine whether or not this module is supported by the implementation.

Interface ASModel

A read-only interface that represents an abstract schema.

IDL Definition
interface ASModel : ASObject {
  readonly attribute boolean         namespaceAware;
  readonly attribute unsigned short  usage;
  readonly attribute DOMString       location;
  readonly attribute DOMString       hint;
  readonly attribute boolean         container;
  ASNamedObjectMap   getComponents(in unsigned short objectType);

  // Convenience method to retrive named top-level declarations

  ASElementDecl      getElementDecl(in DOMString name,
                                    in DOMString targetNamespace);
  ASAttributeDecl    getAttributeDecl(in DOMString name,
                                      in DOMString targetNamespace);
  ASEntityDecl       getEntityDecl(in DOMString name);
  ASNotationDecl     getNotationDecl(in DOMString name,
                                     in DOMString targetNamespace);
};

Definition group Convenience method to retrive named top-level declarations
Attributes
container of type boolean, readonly
If usage is EXTERNAL_SUBSET or NOT_USED, then the ASModel is simply a container of other ASModels.
hint of type DOMString, readonly
The hint to locating an ASModel. For example, if an ASModel modeled a DTD, this could represent the public identifier; if an ASModel modeled a XML schema, this could represent a target namespace of a schema document. This attribute can also be NULL.
location of type DOMString, readonly
The URI reference. For example, if an ASModel modeled a DTD, this could represent the system identifier; if an ASModel modeled a XML schema, this could act as a hint to the location of a schema document. In addition, if a system identifier doesn't exist for an internet subset, then this attribute can be NULL.
namespaceAware of type boolean, readonly
true if this ASModel defines the document structure is namespace-aware [XML Namespaces]; false if the document structure is non-namespace-aware.
usage of type unsigned short, readonly
Uses INTERNAL_SUBSET, EXTERNAL_SUBSET, or NOT_USED. An exception will be raised if it is incompatibly shared or in use as an internal subset.
Methods
getAttributeDecl
Returns a top-level attribute declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASAttributeDecl

A top-level attribute declaration or null if such declaration does not exist.

No Exceptions
getComponents
Returns a list of top-level component declarations: ei. element declarations, attribute declarations, etc.
Parameters
objectType of type unsigned short
The type of the declaration: ELEMENT_DECLARATION, ATTRIBUTE_DECLARATION, etc.
The parameter value SCHEMA_MODEL will retrieve a list of nested or imported ASModels if such list is available.
Return Value

ASNamedObjectMap

A list of top-level definition of the specified type in objectType or null.

No Exceptions
getElementDecl
Returns a top-level element declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASElementDecl

A top-level element declaration or null if such declaration does not exist.

No Exceptions
getEntityDecl
Returns an entity declaration.
Parameters
name of type DOMString
The name of the declaration.
Return Value

ASEntityDecl

An entity declaration or null if such declaration does not exist.

No Exceptions
getNotationDecl
Returns a top-level notation declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASNotationDecl

A top-level notation declaration or null if such declaration does not exist.

No Exceptions
Interface ASContentModel

The content model of a declared element.

IDL Definition
interface ASContentModel : ASObject {
  readonly attribute unsigned short  contentModelType;
  readonly attribute unsigned long   minOccurs;
  readonly attribute unsigned long   maxOccurs;
  readonly attribute ASObjectList    subModels;
};

Attributes
contentModelType of type unsigned short, readonly
One of CHOICE_CM, SEQUENCE_CM, ALL_CM or ATOMIC_CM. The operator is applied to all the components(ASObjects) in the the subModels. For example, if the list operator is CHOICE_CM and the components in subModels are a, b and c then the abstract schema for the element being declared is (a|b|c)
maxOccurs of type unsigned long, readonly
maximum occurrence for this content particle. Its value may be 0, a positive integer, or AS_UNBOUNDED to indicate that no upper limit has been set.
minOccurs of type unsigned long, readonly
min occurrence for this content particle. Its value may be 0 or a positive integer.
subModels of type ASObjectList, readonly
Pointers to ASObjects of the following types: ELEMENT_DECLARATION and CONTENT_MODEL.
Interface ASElementDecl

This interface represents an element declararation.

IDL Definition
interface ASElementDecl : ASObject {
  readonly attribute ASDataType      type;
  readonly attribute unsigned short  contentType;
  readonly attribute boolean         strictMixedContent;
  readonly attribute ASContentModel  contentModel;
  readonly attribute boolean         isPCDataOnly;
  readonly attribute ASNamedObjectMap attributeDecls;
  ASAttributeDecl    getAttributeDecl(in DOMString name,
                                      in DOMString targetNamespace);
};

Attributes
attributeDecls of type ASNamedObjectMap, readonly
TheASNamedObjectMap containing ASAttributeDecls for all the attributes that can appear on this type of element.
contentModel of type ASContentModel, readonly
The content model of element.
contentType of type unsigned short, readonly
The content type of the element. One of EMPTY_CONTENTTYPE, SIMPLE_CONTENTTYPE, ELEMENT_CONTENTTYPE, MIXED_CONTENTTYPE,ANY_CONTENTTYPE.
isPCDataOnly of type boolean, readonly
Boolean defining whether the element type contains child elements and PCDATA or PCDATA only for mixed element types. true if the element is of type PCDATA only. Relevant only for mixed content type elements.
strictMixedContent of type boolean, readonly
A boolean defining whether the element order and number of the child elements for mixed content type has to be respected or not. For example XML Schema defined mixed content types the order is important and needs to be respected whether for DTD based AS the order and number of child elements are not important.
type of type ASDataType, readonly
Datatype of the element.
Methods
getAttributeDecl
A convenience method to get an attribute declaration by name.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASAttributeDecl

A top-level attribute declaration or null if such declaration does not exist.

No Exceptions
Interface ASAttributeDecl

An attribute declaration in the context of a ASObject.

IDL Definition
interface ASAttributeDecl : ASObject {
  readonly attribute ASDataType      type;
  readonly attribute DOMString       enumAttr;
  readonly attribute ASObjectList    ownerElementDeclarations;
  readonly attribute unsigned short  defaultType;
  readonly attribute DOMString       value;
};

Attributes
defaultType of type unsigned short, readonly
Constraint type if any for this attribute.
enumAttr of type DOMString, readonly
Valid attribute values, separated by commas, in a string.
ownerElementDeclarations of type ASObjectList, readonly
An ASObjectList of element declarations that use this ASAttributeDeclaration.
type of type ASDataType, readonly
Datatype of the attribute.
value of type DOMString, readonly
Default or fixed value or null if there is none.
Interface ASEntityDecl

Models a general entity declaration in an abstract schema.

(ED: The abstract schema does not handle any parameter entity. It is assumed that the parameter entities are expanded by the implementation as the abstract schema in built.)

IDL Definition
interface ASEntityDecl : ASObject {
  readonly attribute unsigned short  entityType;
  readonly attribute DOMString       entityValue;
  readonly attribute DOMString       systemId;
  readonly attribute DOMString       publicId;
};

Attributes
entityType of type unsigned short, readonly
One of the INTERNAL_ENTITY or EXTERNAL_ENTITY.
entityValue of type DOMString, readonly
The replacement text for the internal entity. The entity references within the replacement text are kept intact. For an entity of type EXTERNAL_ENTITY this is null.
publicId of type DOMString, readonly
The string representing the public identifier for this entity declaration, if present; null otherwise.
systemId of type DOMString, readonly
The URI reference representing the system identifier for the entity declaration, if present, null otherwise.
Interface ASNotationDecl

This interface represents a notation declaration.

IDL Definition
interface ASNotationDecl : ASObject {
  readonly attribute DOMString       systemId;
  readonly attribute DOMString       publicId;
};

Attributes
publicId of type DOMString, readonly
The string representing the public identifier for this notation declaration, if present; null otherwise.
systemId of type DOMString, readonly
The URI reference representing the system identifier for the notation declaration, if present, null otherwise.

1.3.3. Abstract Schema Editing Interfaces

A list of the proposed Abstract Schema data structures and functions follow, starting off with the data structures and abstract schema editing methods.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-EDIT" and "3.0" (respectively) to determine whether or not this module is supported by the implementation.

Note that operations on the ASWModel that could result in its being invalid will be discovered during document validation and not during the AS editing operation, for example, removeNode. Finally, note that an example element declaration: for (A, (B* | C), D+) can be described by the following:

    ASWElementDecl example = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = exE;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exE = {
    contentModelType      = SEQUENCE_CM;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASWElementDecl A),
    (ASWContentModel exBC),
    (ASWContentModel exD)};
    }

    ASWElementDecl A = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exBC = {
    contentModelType      = CHOICE_CM;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASWContentModel exB),
    (ASWElementDecl C)};
    }

    ASWContentModel exB = {
    contentModelType      = ATOMIC_CM;
    minOccurs             = 0;
    maxOccurs             = AS_UNBOUNDED;
    subModels             = {(ASWElementDecl B)};
    }
    ASWElementDecl B = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWElementDecl C = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exD = {
    contentModelType     = ATOMIC_CM;
    minOccurs            = 1;
    maxOccurs            = AS_UNBOUNDED;
    subModels            = {(ASWElementDecl D)};
    }
    ASWElementDecl D = {
    strictMixedContent   = false;
    elementType          = STRING_DATATYPE;
    isPCDataOnly         = false;
    contentType          = ELEMENTS_CONTENTTYPE;
    ASWContentModel       = null;
    ASWAttributeDecls     = null;
    }
Interface ASWModel

To begin with, an abstract schema is a generic structure that could contain both internal and external subsets. An ASWModel is an abstract object that could map to a DTD [XML 1.0], an XML Schema [XML Schema Part 0], a database schema, etc. An ASWModel could represent either an internal or an external subset; hence an abstract schema could be composed of an ASWModel representing the internal subset and an ASWModel representing the external subset. Note that the ASWModel representing the external subset could consult the ASWModel representing the internal subset. Furthermore, the ASWModel representing the internal subset could be set to null by the setInternalAS() method as a mechanism for "removal". In addition, only one ASWModel representing the external subset can be specified as "active" and it is possible that none are "active". Finally, the ASWModel contains the factory methods needed to create a various types of ASObjects like ASWElementDecl, ASWAttributeDecl, etc.

IDL Definition
interface ASWModel : ASModel {
  void               setLocation(in DOMString location);
  void               setHint(in DOMString hint);
  void               addComponent(in ASObject declaration);
  void               removeComponent(in ASObject declaration);
  void               addASModel(in ASModel declaration);
  void               removeASModel(in ASModel declaration);
  ASObjectList       getASModels();
  ASObject           importASObject(in ASObject asobject);
  void               insertASObject(in ASObject asobject);
  boolean            validate();
  ASWElementDecl     createASWElementDecl(in DOMString namespaceURI,
                                          in DOMString name)
                                        raises(ASException);
  ASWAttributeDecl   createASWAttributeDecl(in DOMString namespaceURI,
                                            in DOMString name)
                                        raises(ASException);
  ASWNotationDecl    createASWNotationDecl(in DOMString namespaceURI,
                                           in DOMString name,
                                           in DOMString systemId,
                                           in DOMString publicId)
                                        raises(ASException);
  ASWEntityDecl      createASWEntityDecl(in DOMString name)
                                        raises(ASException);
  ASWContentModel    createASWContentModel(in DOMString name,
                                           in DOMString namespaceURI,
                                           in unsigned long minOccurs,
                                           in unsigned long maxOccurs,
                                           in unsigned short operator)
                                        raises(ASException);
};

Methods
addASModel
Adds ASModel to the list of ASModels.
Parameters
declaration of type ASModel
An ASModel to be added
No Return Value
No Exceptions
addComponent
Add top-level component declaration to a list of those definitions.
Parameters
declaration of type ASObject
A component declaration.
No Return Value
No Exceptions
createASWAttributeDecl
Creates an attribute declaration.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute being declared.
name of type DOMString
The name of the attribute. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASWModel-dependent.
Return Value

ASWAttributeDecl

A new ASWAttributeDecl object with appropriate attributes set by input parameters.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the input name parameter contains an illegal character.

createASWContentModel
Creates an object which describes part of an ASWElementDecl's content model.
Parameters
name of type DOMString
The name of this ASWContentModel.
namespaceURI of type DOMString
The namespace URI of this ASWContentModel.
minOccurs of type unsigned long
The minimum occurrence for the subModels of this ASWContentModel.
maxOccurs of type unsigned long
The maximum occurrence for the subModels of this ASWContentModel.
operator of type unsigned short
operator of type CHOICE_CM, SEQUENCE_CM, ALL_CM or ATOMIC_CM.
Return Value

ASWContentModel

A new ASWContentModel object.

Exceptions

ASException

A ASException, e.g., minOccurs > maxOccurs.

createASWElementDecl
Creates an element declaration for the element type specified.
Parameters
namespaceURI of type DOMString
The namespace URI of the element type being declared.
name of type DOMString
The name of the element. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASWModel-dependent.
Return Value

ASWElementDecl

A new ASWElementDecl object with the ASObject objectName attribute set to name and namespaceURI set to namespaceURI. Other attributes of the element declaration are set through ASWElementDecl interface methods. Depending on the value of NamespaceAware, this method will take into account the namespaceURI parameter.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

createASWEntityDecl
Creates an ASWEntityDecl.
Parameters
name of type DOMString
The name (of type Name) of the entity being declared.
Return Value

ASWEntityDecl

A new ASWEntityDecl object with entityName attribute set to name.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

createASWNotationDecl
Creates a new notation declaration.
Parameters
namespaceURI of type DOMString
The namespace URI of the notation being declared.
name of type DOMString
The name of the notation. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASWModel-dependent.
systemId of type DOMString
The URI reference for the notation declaration.
publicId of type DOMString
The public identifier for the notation declaration.
Return Value

ASWNotationDecl

A new ASWNotationDecl object with notationName attribute set to name and publicId and systemId set to the corresponding fields.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

getASModels
Returns a list of ASModels.
Return Value

ASObjectList

A list of ASModels.

No Parameters
No Exceptions
importASObject
Imports ASObject into ASWModel.
Parameters
asobject of type ASObject
ASObject to be imported.
Return Value

ASObject

The ASObject that is imported.

No Exceptions
insertASObject
Inserts ASObject into ASWModel.
Parameters
asobject of type ASObject
ASObject to be inserted.
No Return Value
No Exceptions
removeASModel
Removes ASModel from the list of ASModels.
Parameters
declaration of type ASModel
An ASModel to be removed
No Return Value
No Exceptions
removeComponent
Removes the specified ASObject from the list of top-level declarations.
Parameters
declaration of type ASObject
A component declaration to be removed
No Return Value
No Exceptions
setHint
Set hint for the ASWModel.
Parameters
hint of type DOMString
The hint to locating an ASWModel. For example, if an ASWModel modeled a DTD, this could represent the public identifier; if an ASWModel modeled a XML schema, this could represent a target namespace of a schema document. This attribute can also be NULL.
No Return Value
No Exceptions
setLocation
Set location of schema model.
Parameters
location of type DOMString
The URI reference. For example, if an ASWModel modeled a DTD, this could represent the system identifier; if an ASWModel modeled a XML schema, this could act as a hint to the location of a schema document. In addition, if a system identifier doesn't exist for an internet subset, then this attribute can be NULL.
No Return Value
No Exceptions
validate
Determines if an ASModel itself is valid, i.e., confirming that it's well-formed and valid per its own formal grammar.
Return Value

boolean

true if the ASModel is valid, false otherwise.

No Parameters
No Exceptions
Interface ASWNamedObjectMap

Objects implementing the ASWNamedObjectMap interface are used to represent collections of abstract schema objects that can be accessed by name. Note that ASNamedObjectMap does not inherit from ASObjectList; ASNamedObjectMaps are not maintained in any particular order. Objects contained in an object implementing ASNamedObjectMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a ASNamedObjectMap, and does not imply that the DOM specifies an order to these ASObjects.

ASWNamedObjectMap object in the DOM are live.

Issue NamedObjectMap-live:
Should named node map be live?

IDL Definition
interface ASWNamedObjectMap : ASNamedObjectMap {
  ASObject           removeNamedItem(in DOMString name)
                                        raises(ASException);
  ASObject           setNamedItem(in ASObject newASObject)
                                        raises(ASException,
                                               ASException);
  ASObject           setNamedItemNS(in ASObject arg)
                                        raises(ASException);
  ASObject           removeNamedItemNS(in DOMString namespaceURI,
                                       in DOMString localName)
                                        raises(DOMException);
};

Methods
removeNamedItem
Removes an ASObject specified by a objectName.
Parameters
name of type DOMString
The objectName of the ASObject to be removed.
Return Value

ASObject

The ASObject removed from this map if an ASObject with such a name exists.

Exceptions

ASException

NOT_FOUND_ERR: Raised if there is no node named name in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

removeNamedItemNS
Removes a node specified by local name and namespace URI. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the ASObject interface. If so, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to remove.
localName of type DOMString
The local name of the ASObject to remove.
Return Value

ASObject

The node removed from this map if a node with such a local name and namespace URI exists.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node named name in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

setNamedItem
Adds an ASObject using its objectName attribute. If an ASObject with that name is already present in this map, it is replaced by the new one.
Parameters
newASObject of type ASObject
The ASObject to be inserted in the map with its objectName as the key.
Return Value

ASObject

If the new object replaces an existing one, the replaced object is returned, otherwise null.

Exceptions

ASException

WRONG_MODEL_ERR: Raised if arg was created from a different ASWModel than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

ASException
setNamedItemNS
Adds a node using its namespaceURI and localName. If a node with that namespace URI and that local name is already present in this map, it is replaced by the new one.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
arg of type ASObject
A node to store in this map. The node will later be accessible using the value of its namespaceURI and localName attributes.
Return Value

ASObject

If the new ASObject replaces an existing node the replaced ASObject is returned, otherwise null is returned.

Exceptions

ASException

WRONG_MODEL_ERR: Raised if arg was created from a different ASWModel than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

Interface ASWElementDecl

The element declaration.

IDL Definition
interface ASWElementDecl : ASElementDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespace(in DOMString namespaceURI);
  void               setStrictMixedContent(in boolean mixedContent);
  void               setType(in ASDataType type);
  void               setContentType(in unsigned short contentType);
  void               setContentModel(in ASWContentModel contentModel);
  void               addAttributeDecl(in ASWAttributeDecl attributeDecl);
  ASWAttributeDecl   removeAttributeDecl(in ASWAttributeDecl attributeDecl);
};

Methods
addAttributeDecl
Adds an ASWAttributeDecl for the element being declared.
Parameters
attributeDecl of type ASWAttributeDecl
The new attribute declaration to add. If the attribute declaration already exists for the element, the call does not have any effect.
No Return Value
No Exceptions
removeAttributeDecl
Removes an ASWAttributeDecl from the element being declared.
Parameters
attributeDecl of type ASWAttributeDecl
The attribute declaration to be removed. If the attribute declaration does not exist for the element, the call does not have any effect.
Return Value

ASWAttributeDecl

null if the attribute does not exist. Otherwise returns the attribute being removed.

No Exceptions
setContentModel
Set the content model for this element declaration.
Parameters
contentModel of type ASWContentModel
The content model of element.
No Return Value
No Exceptions
setContentType
Set content type for this element declaration.
Parameters
contentType of type unsigned short
The content type of the element. One of EMPTY_CONTENTTYPE, SIMPLE_CONTENT, ANY_CONTENTTYPE, MIXED_CONTENTTYPE, ELEMENT_CONTENTTYPE .
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespace
Set the namespace for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setStrictMixedContent
Set mixed content.
Parameters
mixedContent of type boolean
A boolean defining whether the element order and number of the child elements for mixed content type has to be respected or not. For example XML Schema defined mixed content types the order is important and needs to be respected whether for DTD based AS the order and number of child elements are not important.
No Return Value
No Exceptions
setType
Set the type for this element declaration.
Parameters
type of type ASDataType
The datatype for this element declaration.
No Return Value
No Exceptions
Interface ASWContentModel

The content model of a declared element.

IDL Definition
interface ASWContentModel : ASContentModel {
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setContentModelType(in unsigned short operator);
  void               setMinOccurs(in unsigned long minOccurs);
  void               setMaxOccurs(in unsigned long maxOccurs);
  void               removeSubModel(in ASObject oldObject);
  ASObject           insertBeforeSubModel(in ASObject newObject,
                                          in ASObject refObject)
                                        raises(ASException);
  unsigned long      appendSubModel(in ASObject newObject)
                                        raises(ASException);
};

Methods
appendSubModel
Appends a new ASObject to the end of the list representing thesubModels.
Parameters
newObject of type ASObject
The new object to be appended.
Return Value

unsigned long

the length of the subModels.

Exceptions

ASException

DUPLICATE_NAME_ERR:Raised if a element declaration already exists with the same name within an AS_CHOICE operator.

TYPE_ERR:Raised if type is neither an ASWContentModel nor an ASWElementDecl.

insertBeforeSubModel
Inserts a new object in the submodel before the existing reference object. Objects that already exist in the list are moved as needed.
Parameters
newObject of type ASObject
The new object to be inserted.
refObject of type ASObject
The reference object before which the new object is to be inserted.
Return Value

ASObject

The object being inserted.

Exceptions

ASException

DUPLICATE_NAME_ERR:Raised if a element declaration already exists with the same name within an AS_CHOICE operator.

TYPE_ERR:Raised if type is neither an ASWContentModel nor an ASWElementDecl.

removeSubModel
Removes the ASObject in the submodel. Objects that already exist in the list are moved as needed.
Parameters
oldObject of type ASObject
The object to be removed.
No Return Value
No Exceptions
setContentModelType
Set content model type
Parameters
operator of type unsigned short
One of CHOICE_CM, SEQUENCE_CM, ALL_CM, ATOMIC_CM, or UNDEFINED_CM. The operator is applied to all the components(ASObjects) in the the subModels. For example, if the content model type is CHOICE_CM and the components in subModels are a, b and c then the abstract schema for the element being declared is (a|b|c)
No Return Value
No Exceptions
setMaxOccurs
Set maxOccurs for the content model
Parameters
maxOccurs of type unsigned long
maximum occurrence for this content particle. Its value may be 0, a positive integer, or AS_UNBOUNDED to indicate that no upper limit has been set.
No Return Value
No Exceptions
setMinOccurs
Set minOccurs for the content model
Parameters
minOccurs of type unsigned long
min occurrence for this content particle. Its value may be 0 or a positive integer.
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
Interface ASWAttributeDecl

An attribute declaration.

IDL Definition
interface ASWAttributeDecl : ASAttributeDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setType(in ASDataType type);
  void               setValue(in DOMString value);
  void               setEnumAttr(in DOMString enumeration);
  void               setDefaultType(in unsigned short constraint);
};

Methods
setDefaultType
Set constraint for the attribute's value
Parameters
constraint of type unsigned short
Constraint type if any for this attribute.
No Return Value
No Exceptions
setEnumAttr
Set enumeration value for this attribute
Parameters
enumeration of type DOMString
Valid attribute values, separated by vertical bars, in a string.
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setType
Set the type for this attribute declaration.
Parameters
type of type ASDataType
The datatype for this attribute declaration.
No Return Value
No Exceptions
setValue
Set default or fixed value for this attribute
Parameters
value of type DOMString
Default or fixed value or null if there is none.
No Return Value
No Exceptions
Interface ASWEntityDecl

Models a general entity declaration in an abstract schema.

The abstract schema does not handle any parameter entity. It is assumed that the parameter entities are expanded by the implementation as the abstract schema is built.

IDL Definition
interface ASWEntityDecl : ASEntityDecl {
  void               setRawname(in DOMString rawname);
  void               setEntityType(in unsigned short type);
  void               setEntityValue(in DOMString value);
  void               setSystemId(in DOMString systemId);
  void               setPublicId(in DOMString publicId);
};

Methods
setEntityType
Set the type for this entity declaration
Parameters
type of type unsigned short
One of the INTERNAL_ENTITY or EXTERNAL_ENTITY.
No Return Value
No Exceptions
setEntityValue
Set entity value.
Parameters
value of type DOMString
The replacement text for the internal entity. The entity references within the replacement text are kept intact. For an entity of type EXTERNAL_ENTITY this is null.
No Return Value
No Exceptions
setPublicId
Set publicId for this entity
Parameters
publicId of type DOMString
The string representing the public identifier for this entity declaration, if present; null otherwise.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setSystemId
Set systemId for this entity
Parameters
systemId of type DOMString
The URI reference representing the system identifier for the entity declaration, if present, null otherwise.
No Return Value
No Exceptions
Interface ASWNotationDecl

This interface represents a notation declaration.

IDL Definition
interface ASWNotationDecl : ASNotationDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setSystemId(in DOMString systemId);
  void               setPublicId(in DOMString publicId);
};

Methods
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setPublicId
Set publicId for this entity
Parameters
publicId of type DOMString
The string representing the public identifier for this notation declaration, if present; null otherwise.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setSystemId
Set systemId for this entity
Parameters
systemId of type DOMString
The URI reference representing the system identifier for the notation declaration, if present, null otherwise.
No Return Value
No Exceptions

1.4. Validation and Other Interfaces

This section contains "Validation and Other" interfaces common to "AS-READ", "AS-EDIT" and "AS-DOC" parts.

Exception ASException

Abstract Schemas operations may throw a ASException as described in their descriptions.

IDL Definition
exception ASException {
  unsigned short   code;
};
// ASExceptionCode
const unsigned short      DUPLICATE_NAME_ERR             = 1;
const unsigned short      TYPE_ERR                       = 2;
const unsigned short      NO_AS_AVAILABLE                = 3;
const unsigned short      WRONG_MIME_TYPE_ERR            = 4;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      VALIDATION_ERR                 = 6;
const unsigned short      ACTIVEAS_DELETION_ERR          = 7;

Definition group ASExceptionCode

An integer indicating the type of error generated.

Defined Constants
ACTIVEAS_DELETION_ERR
Raised if boundASModels is being set or removed and the activeASModel is not one of them.
DUPLICATE_NAME_ERR
If an element declaration already exists with the same name within an AS_CHOICE operator.
INVALID_CHARACTER_ERR
Raised if specified name contains an illegal character.
NO_AS_AVAILABLE
If the DocumentEditAS related to the node does not have any active ASModel and wfValidityCheckLevel is set to PARTIAL or STRICT_VALIDITY_CHECK.
TYPE_ERR
If the type of the ASObject is neither an ASContentModel nor an ASElementDecl.
VALIDATION_ERR
Raised if document is invalid.
WRONG_MIME_TYPE_ERR
When mimeTypeCheck is true and the input source has an incorrect MIME Type. See the attribute mimeTypeCheck.
Interface DocumentAS

This interface extends the Document interface with additional methods for both document and AS editing.

IDL Definition
interface DocumentAS : Document {
           attribute ASModel         activeASModel;
           attribute ASObjectList    boundASModels;
  ASModel            getInternalAS();
  void               setInternalAS(in ASModel as)
                                        raises(DOMException);
  void               addAS(in ASModel as);
  void               removeAS(in ASModel as)
                                        raises(ASException);
  ASElementDecl      getElementDecl(in Element node)
                                        raises(DOMException);
  ASAttributeDecl    getAttributeDecl(in Attr node)
                                        raises(DOMException);
  ASEntityDecl       getEntityDecl(in Entity node)
                                        raises(DOMException);
  ASNotationDecl     getNotationDecl(in Notation node)
                                        raises(DOMException);
  void               validate()
                                        raises(ASException);
};

Attributes
activeASModel of type ASModel
The active external ASModel. Validation is responsible for not only validating the document instance against the active external ASModel but also for consulting the internal ASModel, so if an attribute is declared in the internal ASModel and the corresponding ownerElements points to a ASElementDecls defined in the active external ASModel, changing the active external ASModel will cause the ownerElements to be recomputed during the validation of the document instance. If the ownerElements is not defined in the newly active external ASModel, the ownerElements will be an empty object list.
boundASModels of type ASObjectList
A list of ASObjects of type SCHEMA_MODELs associated with a document. The addAS method associates an ASModel with a document. An exception ACTIVEAS_DELETION_ERR is thrown if the activeASModel is not one of the boundASModels.
Methods
addAS
Associate an ASModel with a document. Can be invoked multiple times to result in a list of ASModels. Note that only one internal ASModel is associated with the document, however, and that only one of the possible list of ASModels is active at any one time.
Parameters
as of type ASModel
ASModel to be associated with the document.
No Return Value
No Exceptions
getAttributeDecl
Gets the abstract schema declaration for the attribute node.
Parameters
node of type Attr
The Attr node for which attribute declaration is to be retrieved.
Return Value

ASAttributeDecl

An attribute declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getElementDecl
Gets the abstract schema declaration for the element node.
Parameters
node of type Element
The Element node for which element declaration is to be retrieved.
Return Value

ASElementDecl

An element declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getEntityDecl
Gets the abstract schema declaration for the entity node.
Parameters
node of type Entity
The Entity node for which notation declaration is to be retrieved.
Return Value

ASEntityDecl

A entity declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getInternalAS
Retrieve the internal ASModel of a document.
Return Value

ASModel

ASModel.

No Parameters
No Exceptions
getNotationDecl
Gets the abstract schema declaration for the notation node.
Parameters
node of type Notation
The Notation node for which notation declaration is to be retrieved.
Return Value

ASNotationDecl

A notation declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

removeAS
Removes an ASModel associated with a document. Can be invoked multiple times to remove a number of these in the list of ASModels.
Parameters
as of type ASModel
The ASModel to be removed.
Exceptions

ASException

ACTIVEAS_DELETION_ERR: Raised if removing boundASModels and the activeASModel is not one of them.

No Return Value
setInternalAS
Sets the internal subset ASModel of a document. This could be null as a mechanism for "removal".
Parameters
as of type ASModel
ASModel to be the internal subset of the document.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if implementation doesn't support AS-editing.

No Return Value
validate
Validates the document against the ASModel. If the document is mutated during validation, a warning will be issued.
Exceptions

ASException

VALIDATION_ERR: Raised if an error occurs when the document is being validated against the abstract schema.

No Parameters
No Return Value
Interface DOMImplementationAS

This interface allows creation of an ASWModel. It extends the DOMImplementation interface. An object that implements DOMImplementationAS is obtained by doing a binding specific cast from DOMImplementation to DOMImplementationAS.

IDL Definition
interface DOMImplementationAS : DOMImplementation {
  ASWModel           createASWModel(in boolean isNamespaceAware,
                                    in boolean container,
                                    in DOMString schemaType);
};

Methods
createASWModel
Creates an ASWModel.
Parameters
isNamespaceAware of type boolean
Allow creation of ASWModel with this attribute set to a specific value.
container of type boolean
Specifies that ASWModel serves as a container for other ASWModels.
schemaType of type DOMString
An absolute URI representing the type of the schema language. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value

ASWModel

An ASWModel.

No Exceptions

1.5. Editing and Generating an Abstract Schema

Editing and generating an abstract schema falls in the AS-editing world. The most obvious requirement for this set of requirements is for tools that author abstract schemas, either under user control, i.e., explicitly designed document types, or generated from other representations. The latter class includes transcoding tools, e.g., synthesizing an XML representation to match a database schema.

It's important to note here that a DTD's "internal subset" is part of the Abstract Schema, yet is loaded, stored, and maintained as part of the individual document instance. This implies that even tools which do not want to let users change the definition of the Document Type may need to support editing operations upon this portion of the AS. It also means that our representation of the AS must be aware of where each portion of its content resides, so that when the serializer processes this document it can write out just the internal subset. A similar issue may arise with external parsed entities, or if schemas introduce the ability to reference other schemas. Finally, the internal-subset case suggests that we may want at least a two-level representation of abstract schemas, so a single DOM representation of a DTD can be shared among several documents, each potentially also having its own internal subset; it's possible that entity layering may be represented the same way.

The API for altering the abstract schema may also be the AS's official interface with parsers. One of the ongoing problems in the DOM is that there is some information which must currently be created via completely undocumented mechanisms, which limits the ability to mix and match DOMs and parsers. Given that specialized DOMs are going to become more common (sub-classed, or wrappers around other kinds of storage, or optimized for specific tasks), we must avoid that situation and provide a "builder" API. Particular pairs of DOMs and parsers may bypass it, but it's required as a portability mechanism.

Note that several of these applications require that an AS be able to be created, loaded, and manipulated without/before being bound to a specific Document. A related issue is that we'd want to be able to share a single representation of an AS among several documents, both for storage efficiency and so that changes in the AS can quickly be tested by validating it against a set of known-good documents. Similarly, there is a known problem in [DOM Level 3 Core] where we assume that the DocumentType will be created before the Document, which is fine for newly-constructed documents but not a good match for the order in which an XML parser encounters this data; being able to "rebind" a Document to a new AS, after it has been created may be desirable.

As noted earlier, questions about whether one can alter the content of the AS via its syntax, via higher-level abstractions, or both, exist. It's also worth noting that many of the editing concepts from the Document tree still apply; users should probably be able to clone part of an AS, remove and re-insert parts, and so on.

1.6. Abstract Schema-directed Document Manipulation

In addition to using the abstract schema to validate a document instance, applications would like to be able to use it to guide construction and editing of documents, which falls into the document-editing world. Examples of this sort of guided editing already exist, and are becoming more common. The necessary queries can be phrased in several ways, the most useful of which may be a combination of "what does the DTD allow me to insert here" and "if I insert this here, will the document still be valid". The former is better suited to presentation to humans via a user interface, and when taken together with sub-tree validation may subsume the latter.

It has been proposed that in addition to asking questions about specific parts of the abstract schema, there should be a reasonable way to obtain a list of all the defined symbols of a given type (element, attribute, entity) independent of whether they're valid in a given location; that might be useful in building a list in a user-interface, which could then be updated to reflect which of these are relevant for the program's current state.

Remember that namespaces also weigh in on this issue, in the case of attributes, a "can-this-go-there" may prompt a namespace-well-formedness check and warn you if you're about to conflict with or overwrite another attribute with the same namespaceURI/localName but different prefix, or same nodeName but different namespaceURI.

We have to deal with the fact that "the shortest distance between two valid documents may be through an invalid one". Users may want to know several levels of detail (all the possible children, those which would be valid given what precedes this point, those which would be valid given both preceding and following siblings). Also, once XML Schemas introduce context sensitive validity, we may have to consider the effect of children as well as the individual node being inserted.

1.7. Validating a Document Against an Abstract Schema

The most obvious use for an abstract schema (DTD or XML Schema or any Abstract Schema) is to use it to validate that a given XML document is in fact a properly constructed instance of the document type described by this AS. This again falls into the document-editing world. The XML spec only discusses performing this test at the time the document is loaded into the "processor", which most of us have taken to mean that this check should be performed at parse time. But it is obviously desirable to be able to validate again a document -- or selected subtrees -- at other times. One such case would be validating an edited or newly constructed document before serializing it or otherwise passing it to other users. This issue also arises if the "internal subset" is altered -- or if the whole Abstract Schema changes.

In the past, the DOM has allowed users to create invalid documents, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax... or that they would be checked for validity when read back in. We considered adding validity checks to the DOM's existing editing operations to prevent creation of invalid documents, but are currently inclined against this for several reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations, e.g., if the change is occurring in a context where we know the result will be valid. Second, "the shortest distance between two good documents may be through a bad document". Preventing a document from becoming temporarily invalid may impose a considerable amount of additional work on higher-level code and users Hence our current plan is to continue to permit editing to produce invalid DOMs, but provide operations which permit a user to check the validity of a node on demand. If needed one can use continuousValidityChecking flag to ensure that the DOM remains valid during the editing process.

Note that validation includes checking that ID attributes are unique, and that IDREFs point to IDs which actually exist.

1.8. Well-formedness Testing

XML defined the "well-formed" (WF) state for documents which are parsed without reference to their DTDs. Knowing that a document is well-formed may be useful by itself even when a DTD is available. For example, users may wish to deliberately save an invalid document, perhaps as a checkpoint before further editing. Hence, the AS feature will permit both full validity checking (see previous section) and "lightweight" WF checking, as requested by the caller, as well as processing entity declarations in the AS even if validation is not turned on. This falls within the document-editing world.

While the DOM inherently enforces some of XML's well-formedness conditions (proper nesting of elements, constraints on which children may be placed within each node), there are some checks that are not yet performed. These include:

  • Character restrictions for text content and attribute values. Some characters aren't permitted even when expressed as numeric character entities
  • The three-character sequence "]]>" in CDATASections.
  • The two-character sequence "--" in comments. (Which, be it noted, some XML validators don't currently remember to test...)

In addition, Namespaces introduce their own concepts of well-formedness. Specifically:

  • No two attributes on a single Element may have the same combination of namespaceURI and localName, even if their prefixes are different and hence they don't conflict under XML 1.0 rules.
  • NamespaceURIs must be legal URI syntax. (Note that once we have this code, it may be reusable for the URI "datatype" in document content; see discussion of datatypes.)
  • The mapping of namespace prefixes to their URIs must be declared and consistent. That isn't required during normal DOM operation, since we perform "early binding" and thereafter refer to nodes primarily via their namespaceURIs and localName. But it does become an issue when we want to serialize the DOM to XML syntax, and may be an issue if an application is assuming that all the declarations are present and correct. This may imply that we should provide a namespaceNormalize operation, which would create the implied declarations and reconcile conflicts in some reasonably standardized manner. This may be a major undertaking, since some DOMs may be using the namespace to direct subclassing of the nodes or similar special treatment; as with the existing normalize method, you may be left with a different-but-equivalent set of node objects.

In the past, the DOM has allowed users to create documents which violate these rules, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax. We considered adding WF checks to the DOM's existing editing operations to prevent WF violations from arising, but are currently inclined against this for two reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations (for example, if the change is occurring in a context where we know the illegal characters have already been prevented from arising). Second, "the shortest distance between two good documents may be through a bad document" -- preventing a document from becoming temporarily ill-formed may impose a considerable amount of additional work on higher-level code and users. (Note possible issue for Serialization: In some applications, being able to save and reload marginally poorly-formed DOMs might be useful -- editor checkpoint files, for example.) Hence our current plan is to continue to permit editing to produce ill-formed DOMs, but provide operations which permit a user to check the well-formedness of a node on demand, and possibly provide some of the primitive (e.g., string-checking) functions directly.

1.9. Load and Save for Abstract Schemas

The module extends the [DOM Level 3 Load and Save] module to permit to load a Document using a specific ASWModel and to load an ASWModel from an URI or DOMInputSource.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "LS-AS" and "3.0" (respectively) to determine whether or not the Load and Save for Abstract Schemas module is supported by the implementation. In order to fully support this module, an implementation must also support the "AS-EDIT" features defined in this specification.

Interface ASDOMBuilder

An Abstract Schema parser interface.

ASDOMBuilder provides an API for parsing Abstract Schemas and building the corresponding ASWModel tree. The actual ASDOMBuilder can be created by appropriately casting the object created by an implementation that supports AS.

IDL Definition
interface ASDOMBuilder : ls::DOMBuilder {
           attribute ASWModel        abstractSchema;
  ASWModel           parseASURI(in DOMString uri,
                                in DOMString schemaType)
                                        raises(ASException,
                                               DOMSystemException);
  ASWModel           parseASInputSource(in ls::DOMInputSource is,
                                        in DOMString schemaType)
                                        raises(ASException,
                                               DOMSystemException);
};

Attributes
abstractSchema of type ASWModel
The one active ASWModel associated with a document instance. Note that the parser should set the one active ASWModel.
Methods
parseASInputSource
Parse a Abstract Schema from a location identified by an DOMInputSource.
Parameters
is of type ls::DOMInputSource
The DOMInputSource from which the source Abstract Schema is to be read.
schemaType of type DOMString
An absolute URI representing the type of the schema language or null if the implementation can infer a schema type. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value

ASWModel

The newly created ASWModel.

Exceptions

ASException

Exceptions raised by parseASURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a ASException if any form of Abstract Schema inconsistencies or warning occurs during the parse, but application defined errorHandlers are not required to do so.

WRONG_MIME_TYPE_ERR: Raised when mimeTypeCheck is true and the inputsource has an incorrect MIME Type. See attribute mimeTypeCheck.

DOMSystemException

Exceptions raised by parseURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined error handlers are not required to do so.

parseASURI
Parse a Abstract Schema from a location identified by an URI.
Parameters
uri of type DOMString
The location of the Abstract Schema to be read.
schemaType of type DOMString
An absolute URI representing the type of the schema language or null if the implementation can infer a schema type. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value

ASWModel

The newly created Abstract Schema.

Exceptions

ASException

Exceptions raised by parseASURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a ASException if any form of Abstract Schema inconsistencies or warning occurs during the parse, but application defined errorHandlers are not required to do so.

Raise a WRONG_MIME_TYPE_ERR when mimeTypeCheck is true and the inputsource has an incorrect MIME Type. See attribute mimeTypeCheck.

DOMSystemException

Exceptions raised by parseURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined error handlers are not required to do so.

Interface ASDOMWriter

A Abstract Schema serialization interface.

ASDOMWriters provides an API for serializing Abstract Schemas out in the form of a source Abstract Schema. The Abstract Schema is written to an output stream, the type of which depends on the specific language bindings in use.

ASDOMWriter is a generic Abstract Schema serialization interface. It can be applied to both an internal Abstract Schema and/or an external Abstract Schema. DOMASWriter is applied to serialize a single Abstract Schema. Serializing a document with an active Internal Abstract Schema will serialize this internal Abstract Schema with the document as it is part of the Document (see DOMWriter).

IDL Definition
interface ASDOMWriter : ls::DOMWriter {
  void               writeASModel(in DOMOutputStream destination,
                                  in ASModel model)
                                        raises(DOMSystemException);
};

Methods
writeASModel
Write out the specified Abstract Schema to the specified destination.
Parameters
destination of type DOMOutputStream
The destination for the data to be written.
model of type ASModel
The Abstract Schema to serialize.
Exceptions

DOMSystemException

This exception will be raised in response to any sort of IO or system error that occurs while writing to the destination. It may wrap an underlying system exception.

No Return Value
previous next contents index


Appendix A: IDL Definitions

This appendix contains the complete OMG IDL [OMG IDL] for the Level 3 Document Object Model Abstract Schemas definitions.

The IDL files are also available as: http://www.w3.org/TR/2002/NOTE-DOM-Level-3-AS-20020725/idl.zip

as.idl:

// File: as.idl

#ifndef _AS_IDL_
#define _AS_IDL_

#include "dom.idl"
#include "ls.idl"

#pragma prefix "dom.w3c.org"
module as
{

  typedef dom::DOMString DOMString;
  typedef dom::Document Document;
  typedef dom::Element Element;
  typedef dom::Attr Attr;
  typedef dom::Entity Entity;
  typedef dom::Notation Notation;
  typedef dom::DOMImplementation DOMImplementation;
  typedef dom::DOMOutputStream DOMOutputStream;

  interface ASModel;
  interface ASElementDecl;
  interface ASAttributeDecl;
  interface ASEntityDecl;
  interface ASNotationDecl;
  interface ASWElementDecl;
  interface ASWAttributeDecl;
  interface ASWNotationDecl;
  interface ASWEntityDecl;
  interface ASWContentModel;

  exception ASException {
    unsigned short   code;
  };
  // ASExceptionCode
  const unsigned short      DUPLICATE_NAME_ERR             = 1;
  const unsigned short      TYPE_ERR                       = 2;
  const unsigned short      NO_AS_AVAILABLE                = 3;
  const unsigned short      WRONG_MIME_TYPE_ERR            = 4;
  const unsigned short      INVALID_CHARACTER_ERR          = 5;
  const unsigned short      VALIDATION_ERR                 = 6;
  const unsigned short      ACTIVEAS_DELETION_ERR          = 7;

  interface ASConstants {

    // ASObject Types
    const unsigned short      ELEMENT_DECLARATION            = 1;
    const unsigned short      ATTRIBUTE_DECLARATION          = 2;
    const unsigned short      NOTATION_DECLARATION           = 3;
    const unsigned short      ENTITY_DECLARATION             = 4;
    const unsigned short      CONTENT_MODEL                  = 5;
    const unsigned short      SCHEMA_MODEL                   = 6;

    // Schema Model types
    const unsigned short      INTERNAL_SUBSET                = 30;
    const unsigned short      EXTERNAL_SUBSET                = 31;
    const unsigned short      NOT_USED                       = 32;

    // Entity Types
    const unsigned short      INTERNAL_ENTITY                = 33;
    const unsigned short      EXTERNAL_ENTITY                = 34;

    // Content Model Types
    const unsigned short      EMPTY_CONTENTTYPE              = 40;
    const unsigned short      SIMPLE_CONTENTTYPE             = 41;
    const unsigned short      ELEMENT_CONTENTTYPE            = 42;
    const unsigned short      MIXED_CONTENTTYPE              = 43;
    const unsigned short      ANY_CONTENTTYPE                = 44;

    // Content model compositors
    const unsigned short      SEQUENCE_CM                    = 50;
    const unsigned short      CHOICE_CM                      = 51;
    const unsigned short      ALL_CM                         = 52;
    const unsigned short      UNDEFINED_CM                   = 53;
    const unsigned short      ATOMIC_CM                      = 54;

    // Value Constraint
    const unsigned short      NONE_VC                        = 0;
    const unsigned short      DEFAULT_VC                     = 60;
    const unsigned short      FIXED_VC                       = 61;
    const unsigned short      REQUIRED_VC                    = 62;

    // Definition of unbounded
    const unsigned long       UNBOUNDED                      = MAX_VALUE;
  };

  interface ASObject {
    readonly attribute unsigned short  objectType;
    readonly attribute ASModel         ownerModel;
    readonly attribute DOMString       rawname;
    readonly attribute DOMString       name;
    readonly attribute DOMString       namespace;
    ASObject           cloneASObject(in boolean deep)
                                        raises(ASException);
  };

  interface ASDataType {
    readonly attribute unsigned short  dataType;

    // DATA_TYPES
    const unsigned short      STRING_DATATYPE                = 1;
    const unsigned short      NOTATION_DATATYPE              = 10;
    const unsigned short      ID_DATATYPE                    = 11;
    const unsigned short      IDREF_DATATYPE                 = 12;
    const unsigned short      IDREFS_DATATYPE                = 13;
    const unsigned short      ENTITY_DATATYPE                = 14;
    const unsigned short      ENTITIES_DATATYPE              = 15;
    const unsigned short      NMTOKEN_DATATYPE               = 16;
    const unsigned short      NMTOKENS_DATATYPE              = 17;
    const unsigned short      BOOLEAN_DATATYPE               = 100;
    const unsigned short      FLOAT_DATATYPE                 = 101;
    const unsigned short      DOUBLE_DATATYPE                = 102;
    const unsigned short      DECIMAL_DATATYPE               = 103;
    const unsigned short      HEXBINARY_DATATYPE             = 104;
    const unsigned short      BASE64BINARY_DATATYPE          = 105;
    const unsigned short      ANYURI_DATATYPE                = 106;
    const unsigned short      QNAME_DATATYPE                 = 107;
    const unsigned short      DURATION_DATATYPE              = 108;
    const unsigned short      DATETIME_DATATYPE              = 109;
    const unsigned short      DATE_DATATYPE                  = 110;
    const unsigned short      TIME_DATATYPE                  = 111;
    const unsigned short      GYEARMONTH_DATATYPE            = 112;
    const unsigned short      GYEAR_DATATYPE                 = 113;
    const unsigned short      GMONTHDAY_DATATYPE             = 114;
    const unsigned short      GDAY_DATATYPE                  = 115;
    const unsigned short      GMONTH_DATATYPE                = 116;
    const unsigned short      INTEGER                        = 117;
    const unsigned short      NAME_DATATYPE                  = 200;
    const unsigned short      NCNAME_DATATYPE                = 201;
    const unsigned short      NORMALIZEDSTRING_DATATYPE      = 202;
    const unsigned short      TOKEN_DATATYPE                 = 203;
    const unsigned short      LANGUAGE_DATATYPE              = 204;
    const unsigned short      NONPOSITIVEINTEGER_DATATYPE    = 205;
    const unsigned short      NEGATIVEINTEGER_DATATYPE       = 206;
    const unsigned short      LONG_DATATYPE                  = 207;
    const unsigned short      INT_DATATYPE                   = 208;
    const unsigned short      SHORT_DATATYPE                 = 209;
    const unsigned short      BYTE_DATATYPE                  = 210;
    const unsigned short      NONNEGATIVEINTEGER_DATATYPE    = 211;
    const unsigned short      UNSIGNEDLONG_DATATYPE          = 212;
    const unsigned short      UNSIGNEDINT_DATATYPE           = 213;
    const unsigned short      UNSIGNEDSHORT_DATATYPE         = 214;
    const unsigned short      UNSIGNEDBYTE_DATATYPE          = 215;
    const unsigned short      POSITIVEINTEGER_DATATYPE       = 216;
    const unsigned short      ANYSIMPLETYPE_DATATYPE         = 216;
    const unsigned short      ANYTYPE_DATATYPE               = 216;
  };

  interface ASObjectList {
    readonly attribute unsigned long   length;
    ASObject           item(in unsigned long index);
  };

  interface ASNamedObjectMap {
    readonly attribute unsigned long   length;
    ASObject           item(in unsigned long index);
    ASObject           getNamedItem(in DOMString name);
    ASObject           getNamedItemNS(in DOMString namespaceURI,
                                      in DOMString localName);
  };

  interface ASModel : ASObject {
    readonly attribute boolean         namespaceAware;
    readonly attribute unsigned short  usage;
    readonly attribute DOMString       location;
    readonly attribute DOMString       hint;
    readonly attribute boolean         container;
    ASNamedObjectMap   getComponents(in unsigned short objectType);

    // Convenience method to retrive named top-level declarations

    ASElementDecl      getElementDecl(in DOMString name,
                                      in DOMString targetNamespace);
    ASAttributeDecl    getAttributeDecl(in DOMString name,
                                        in DOMString targetNamespace);
    ASEntityDecl       getEntityDecl(in DOMString name);
    ASNotationDecl     getNotationDecl(in DOMString name,
                                       in DOMString targetNamespace);
  };

  interface ASContentModel : ASObject {
    readonly attribute unsigned short  contentModelType;
    readonly attribute unsigned long   minOccurs;
    readonly attribute unsigned long   maxOccurs;
    readonly attribute ASObjectList    subModels;
  };

  interface ASElementDecl : ASObject {
    readonly attribute ASDataType      type;
    readonly attribute unsigned short  contentType;
    readonly attribute boolean         strictMixedContent;
    readonly attribute ASContentModel  contentModel;
    readonly attribute boolean         isPCDataOnly;
    readonly attribute ASNamedObjectMap attributeDecls;
    ASAttributeDecl    getAttributeDecl(in DOMString name,
                                        in DOMString targetNamespace);
  };

  interface ASAttributeDecl : ASObject {
    readonly attribute ASDataType      type;
    readonly attribute DOMString       enumAttr;
    readonly attribute ASObjectList    ownerElementDeclarations;
    readonly attribute unsigned short  defaultType;
    readonly attribute DOMString       value;
  };

  interface ASEntityDecl : ASObject {
    readonly attribute unsigned short  entityType;
    readonly attribute DOMString       entityValue;
    readonly attribute DOMString       systemId;
    readonly attribute DOMString       publicId;
  };

  interface ASNotationDecl : ASObject {
    readonly attribute DOMString       systemId;
    readonly attribute DOMString       publicId;
  };

  interface ASWModel : ASModel {
    void               setLocation(in DOMString location);
    void               setHint(in DOMString hint);
    void               addComponent(in ASObject declaration);
    void               removeComponent(in ASObject declaration);
    void               addASModel(in ASModel declaration);
    void               removeASModel(in ASModel declaration);
    ASObjectList       getASModels();
    ASObject           importASObject(in ASObject asobject);
    void               insertASObject(in ASObject asobject);
    boolean            validate();
    ASWElementDecl     createASWElementDecl(in DOMString namespaceURI,
                                            in DOMString name)
                                        raises(ASException);
    ASWAttributeDecl   createASWAttributeDecl(in DOMString namespaceURI,
                                              in DOMString name)
                                        raises(ASException);
    ASWNotationDecl    createASWNotationDecl(in DOMString namespaceURI,
                                             in DOMString name,
                                             in DOMString systemId,
                                             in DOMString publicId)
                                        raises(ASException);
    ASWEntityDecl      createASWEntityDecl(in DOMString name)
                                        raises(ASException);
    ASWContentModel    createASWContentModel(in DOMString name,
                                             in DOMString namespaceURI,
                                             in unsigned long minOccurs,
                                             in unsigned long maxOccurs,
                                             in unsigned short operator)
                                        raises(ASException);
  };

  interface ASWNamedObjectMap : ASNamedObjectMap {
    ASObject           removeNamedItem(in DOMString name)
                                        raises(ASException);
    ASObject           setNamedItem(in ASObject newASObject)
                                        raises(ASException,
                                               ASException);
    ASObject           setNamedItemNS(in ASObject arg)
                                        raises(ASException);
    ASObject           removeNamedItemNS(in DOMString namespaceURI,
                                         in DOMString localName)
                                        raises(dom::DOMException);
  };

  interface ASWElementDecl : ASElementDecl {
    void               setRawname(in DOMString rawname);
    void               setName(in DOMString name);
    void               setNamespace(in DOMString namespaceURI);
    void               setStrictMixedContent(in boolean mixedContent);
    void               setType(in ASDataType type);
    void               setContentType(in unsigned short contentType);
    void               setContentModel(in ASWContentModel contentModel);
    void               addAttributeDecl(in ASWAttributeDecl attributeDecl);
    ASWAttributeDecl   removeAttributeDecl(in ASWAttributeDecl attributeDecl);
  };

  interface ASWContentModel : ASContentModel {
    void               setName(in DOMString name);
    void               setNamespaceURI(in DOMString namespaceURI);
    void               setContentModelType(in unsigned short operator);
    void               setMinOccurs(in unsigned long minOccurs);
    void               setMaxOccurs(in unsigned long maxOccurs);
    void               removeSubModel(in ASObject oldObject);
    ASObject           insertBeforeSubModel(in ASObject newObject,
                                            in ASObject refObject)
                                        raises(ASException);
    unsigned long      appendSubModel(in ASObject newObject)
                                        raises(ASException);
  };

  interface ASWAttributeDecl : ASAttributeDecl {
    void               setRawname(in DOMString rawname);
    void               setName(in DOMString name);
    void               setNamespaceURI(in DOMString namespaceURI);
    void               setType(in ASDataType type);
    void               setValue(in DOMString value);
    void               setEnumAttr(in DOMString enumeration);
    void               setDefaultType(in unsigned short constraint);
  };

  interface ASWEntityDecl : ASEntityDecl {
    void               setRawname(in DOMString rawname);
    void               setEntityType(in unsigned short type);
    void               setEntityValue(in DOMString value);
    void               setSystemId(in DOMString systemId);
    void               setPublicId(in DOMString publicId);
  };

  interface ASWNotationDecl : ASNotationDecl {
    void               setRawname(in DOMString rawname);
    void               setName(in DOMString name);
    void               setNamespaceURI(in DOMString namespaceURI);
    void               setSystemId(in DOMString systemId);
    void               setPublicId(in DOMString publicId);
  };

  interface DocumentAS : Document {
             attribute ASModel         activeASModel;
             attribute ASObjectList    boundASModels;
    ASModel            getInternalAS();
    void               setInternalAS(in ASModel as)
                                        raises(dom::DOMException);
    void               addAS(in ASModel as);
    void               removeAS(in ASModel as)
                                        raises(ASException);
    ASElementDecl      getElementDecl(in Element node)
                                        raises(dom::DOMException);
    ASAttributeDecl    getAttributeDecl(in Attr node)
                                        raises(dom::DOMException);
    ASEntityDecl       getEntityDecl(in Entity node)
                                        raises(dom::DOMException);
    ASNotationDecl     getNotationDecl(in Notation node)
                                        raises(dom::DOMException);
    void               validate()
                                        raises(ASException);
  };

  interface DOMImplementationAS : DOMImplementation {
    ASWModel           createASWModel(in boolean isNamespaceAware,
                                      in boolean container,
                                      in DOMString schemaType);
  };

  interface ASDOMBuilder : ls::DOMBuilder {
             attribute ASWModel        abstractSchema;
    ASWModel           parseASURI(in DOMString uri,
                                  in DOMString schemaType)
                                        raises(ASException,
                                               dom::DOMSystemException);
    ASWModel           parseASInputSource(in ls::DOMInputSource is,
                                          in DOMString schemaType)
                                        raises(ASException,
                                               dom::DOMSystemException);
  };

  interface ASDOMWriter : ls::DOMWriter {
    void               writeASModel(in DOMOutputStream destination,
                                    in ASModel model)
                                        raises(dom::DOMSystemException);
  };
};

#endif // _AS_IDL_
previous next contents index


Appendix B: Java Language Binding

This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model Abstract Schemas.

The Java files are also available as http://www.w3.org/TR/2002/NOTE-DOM-Level-3-AS-20020725/java-binding.zip

org/w3c/dom/as/ASException.java:

package org.w3c.dom.as;

public class ASException extends RuntimeException {
    public ASException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // ASExceptionCode
    public static final short DUPLICATE_NAME_ERR        = 1;
    public static final short TYPE_ERR                  = 2;
    public static final short NO_AS_AVAILABLE           = 3;
    public static final short WRONG_MIME_TYPE_ERR       = 4;
    public static final short INVALID_CHARACTER_ERR     = 5;
    public static final short VALIDATION_ERR            = 6;
    public static final short ACTIVEAS_DELETION_ERR     = 7;

}

org/w3c/dom/as/ASConstants.java:

package org.w3c.dom.as;

public interface ASConstants {
    // ASObject Types
    public static final short ELEMENT_DECLARATION       = 1;
    public static final short ATTRIBUTE_DECLARATION     = 2;
    public static final short NOTATION_DECLARATION      = 3;
    public static final short ENTITY_DECLARATION        = 4;
    public static final short CONTENT_MODEL             = 5;
    public static final short SCHEMA_MODEL              = 6;

    // Schema Model types
    public static final short INTERNAL_SUBSET           = 30;
    public static final short EXTERNAL_SUBSET           = 31;
    public static final short NOT_USED                  = 32;

    // Entity Types
    public static final short INTERNAL_ENTITY           = 33;
    public static final short EXTERNAL_ENTITY           = 34;

    // Content Model Types
    public static final short EMPTY_CONTENTTYPE         = 40;
    public static final short SIMPLE_CONTENTTYPE        = 41;
    public static final short ELEMENT_CONTENTTYPE       = 42;
    public static final short MIXED_CONTENTTYPE         = 43;
    public static final short ANY_CONTENTTYPE           = 44;

    // Content model compositors
    public static final short SEQUENCE_CM               = 50;
    public static final short CHOICE_CM                 = 51;
    public static final short ALL_CM                    = 52;
    public static final short UNDEFINED_CM              = 53;
    public static final short ATOMIC_CM                 = 54;

    // Value Constraint
    public static final short NONE_VC                   = 0;
    public static final short DEFAULT_VC                = 60;
    public static final short FIXED_VC                  = 61;
    public static final short REQUIRED_VC               = 62;

    // Definition of unbounded
    public static final int UNBOUNDED                 = MAX_VALUE;

}

org/w3c/dom/as/ASObject.java:

package org.w3c.dom.as;

public interface ASObject {
    public short getObjectType();

    public ASModel getOwnerModel();

    public String getRawname();

    public String getName();

    public String getNamespace();

    public ASObject cloneASObject(boolean deep)
                                  throws ASException;

}

org/w3c/dom/as/ASDataType.java:

package org.w3c.dom.as;

public interface ASDataType {
    public short getDataType();

    // DATA_TYPES
    public static final short STRING_DATATYPE           = 1;
    public static final short NOTATION_DATATYPE         = 10;
    public static final short ID_DATATYPE               = 11;
    public static final short IDREF_DATATYPE            = 12;
    public static final short IDREFS_DATATYPE           = 13;
    public static final short ENTITY_DATATYPE           = 14;
    public static final short ENTITIES_DATATYPE         = 15;
    public static final short NMTOKEN_DATATYPE          = 16;
    public static final short NMTOKENS_DATATYPE         = 17;
    public static final short BOOLEAN_DATATYPE          = 100;
    public static final short FLOAT_DATATYPE            = 101;
    public static final short DOUBLE_DATATYPE           = 102;
    public static final short DECIMAL_DATATYPE          = 103;
    public static final short HEXBINARY_DATATYPE        = 104;
    public static final short BASE64BINARY_DATATYPE     = 105;
    public static final short ANYURI_DATATYPE           = 106;
    public static final short QNAME_DATATYPE            = 107;
    public static final short DURATION_DATATYPE         = 108;
    public static final short DATETIME_DATATYPE         = 109;
    public static final short DATE_DATATYPE             = 110;
    public static final short TIME_DATATYPE             = 111;
    public static final short GYEARMONTH_DATATYPE       = 112;
    public static final short GYEAR_DATATYPE            = 113;
    public static final short GMONTHDAY_DATATYPE        = 114;
    public static final short GDAY_DATATYPE             = 115;
    public static final short GMONTH_DATATYPE           = 116;
    public static final short INTEGER                   = 117;
    public static final short NAME_DATATYPE             = 200;
    public static final short NCNAME_DATATYPE           = 201;
    public static final short NORMALIZEDSTRING_DATATYPE = 202;
    public static final short TOKEN_DATATYPE            = 203;
    public static final short LANGUAGE_DATATYPE         = 204;
    public static final short NONPOSITIVEINTEGER_DATATYPE = 205;
    public static final short NEGATIVEINTEGER_DATATYPE  = 206;
    public static final short LONG_DATATYPE             = 207;
    public static final short INT_DATATYPE              = 208;
    public static final short SHORT_DATATYPE            = 209;
    public static final short BYTE_DATATYPE             = 210;
    public static final short NONNEGATIVEINTEGER_DATATYPE = 211;
    public static final short UNSIGNEDLONG_DATATYPE     = 212;
    public static final short UNSIGNEDINT_DATATYPE      = 213;
    public static final short UNSIGNEDSHORT_DATATYPE    = 214;
    public static final short UNSIGNEDBYTE_DATATYPE     = 215;
    public static final short POSITIVEINTEGER_DATATYPE  = 216;
    public static final short ANYSIMPLETYPE_DATATYPE    = 216;
    public static final short ANYTYPE_DATATYPE          = 216;

}

org/w3c/dom/as/ASObjectList.java:

package org.w3c.dom.as;

public interface ASObjectList {
    public int getLength();

    public ASObject item(int index);

}

org/w3c/dom/as/ASNamedObjectMap.java:

package org.w3c.dom.as;

public interface ASNamedObjectMap {
    public int getLength();

    public ASObject item(int index);

    public ASObject getNamedItem(String name);

    public ASObject getNamedItemNS(String namespaceURI,
                                   String localName);

}

org/w3c/dom/as/ASModel.java:

package org.w3c.dom.as;

public interface ASModel extends ASObject {
    public boolean getNamespaceAware();

    public short getUsage();

    public String getLocation();

    public String getHint();

    public boolean getContainer();

    public ASNamedObjectMap getComponents(short objectType);

    // Convenience method to retrive named top-level declarations

    public ASElementDecl getElementDecl(String name,
                                        String targetNamespace);

    public ASAttributeDecl getAttributeDecl(String name,
                                            String targetNamespace);

    public ASEntityDecl getEntityDecl(String name);

    public ASNotationDecl getNotationDecl(String name,
                                          String targetNamespace);

}

org/w3c/dom/as/ASContentModel.java:

package org.w3c.dom.as;

public interface ASContentModel extends ASObject {
    public short getContentModelType();

    public int getMinOccurs();

    public int getMaxOccurs();

    public ASObjectList getSubModels();

}

org/w3c/dom/as/ASElementDecl.java:

package org.w3c.dom.as;

public interface ASElementDecl extends ASObject {
    public ASDataType getType();

    public short getContentType();

    public boolean getStrictMixedContent();

    public ASContentModel getContentModel();

    public boolean getIsPCDataOnly();

    public ASNamedObjectMap getAttributeDecls();

    public ASAttributeDecl getAttributeDecl(String name,
                                            String targetNamespace);

}

org/w3c/dom/as/ASAttributeDecl.java:

package org.w3c.dom.as;

public interface ASAttributeDecl extends ASObject {
    public ASDataType getType();

    public String getEnumAttr();

    public ASObjectList getOwnerElementDeclarations();

    public short getDefaultType();

    public String getValue();

}

org/w3c/dom/as/ASEntityDecl.java:

package org.w3c.dom.as;

public interface ASEntityDecl extends ASObject {
    public short getEntityType();

    public String getEntityValue();

    public String getSystemId();

    public String getPublicId();

}

org/w3c/dom/as/ASNotationDecl.java:

package org.w3c.dom.as;

public interface ASNotationDecl extends ASObject {
    public String getSystemId();

    public String getPublicId();

}

org/w3c/dom/as/ASWModel.java:

package org.w3c.dom.as;

public interface ASWModel extends ASModel {
    public void setLocation(String location);

    public void setHint(String hint);

    public void addComponent(ASObject declaration);

    public void removeComponent(ASObject declaration);

    public void addASModel(ASModel declaration);

    public void removeASModel(ASModel declaration);

    public ASObjectList getASModels();

    public ASObject importASObject(ASObject asobject);

    public void insertASObject(ASObject asobject);

    public boolean validate();

    public ASWElementDecl createASWElementDecl(String namespaceURI,
                                               String name)
                                               throws ASException;

    public ASWAttributeDecl createASWAttributeDecl(String namespaceURI,
                                                   String name)
                                                   throws ASException;

    public ASWNotationDecl createASWNotationDecl(String namespaceURI,
                                                 String name,
                                                 String systemId,
                                                 String publicId)
                                                 throws ASException;

    public ASWEntityDecl createASWEntityDecl(String name)
                                             throws ASException;

    public ASWContentModel createASWContentModel(String name,
                                                 String namespaceURI,
                                                 int minOccurs,
                                                 int maxOccurs,
                                                 short operator)
                                                 throws ASException;

}

org/w3c/dom/as/ASWNamedObjectMap.java:

package org.w3c.dom.as;

import org.w3c.dom.DOMException;

public interface ASWNamedObjectMap extends ASNamedObjectMap {
    public ASObject removeNamedItem(String name)
                                    throws ASException;

    public ASObject setNamedItem(ASObject newASObject)
                                 throws ASException, ASException;

    public ASObject setNamedItemNS(ASObject arg)
                                   throws ASException;

    public ASObject removeNamedItemNS(String namespaceURI,
                                      String localName)
                                      throws DOMException;

}

org/w3c/dom/as/ASWElementDecl.java:

package org.w3c.dom.as;

public interface ASWElementDecl extends ASElementDecl {
    public void setRawname(String rawname);

    public void setName(String name);

    public void setNamespace(String namespaceURI);

    public void setStrictMixedContent(boolean mixedContent);

    public void setType(ASDataType type);

    public void setContentType(short contentType);

    public void setContentModel(ASWContentModel contentModel);

    public void addAttributeDecl(ASWAttributeDecl attributeDecl);

    public ASWAttributeDecl removeAttributeDecl(ASWAttributeDecl attributeDecl);

}

org/w3c/dom/as/ASWContentModel.java:

package org.w3c.dom.as;

public interface ASWContentModel extends ASContentModel {
    public void setName(String name);

    public void setNamespaceURI(String namespaceURI);

    public void setContentModelType(short operator);

    public void setMinOccurs(int minOccurs);

    public void setMaxOccurs(int maxOccurs);

    public void removeSubModel(ASObject oldObject);

    public ASObject insertBeforeSubModel(ASObject newObject,
                                         ASObject refObject)
                                         throws ASException;

    public int appendSubModel(ASObject newObject)
                              throws ASException;

}

org/w3c/dom/as/ASWAttributeDecl.java:

package org.w3c.dom.as;

public interface ASWAttributeDecl extends ASAttributeDecl {
    public void setRawname(String rawname);

    public void setName(String name);

    public void setNamespaceURI(String namespaceURI);

    public void setType(ASDataType type);

    public void setValue(String value);

    public void setEnumAttr(String enumeration);

    public void setDefaultType(short constraint);

}

org/w3c/dom/as/ASWEntityDecl.java:

package org.w3c.dom.as;

public interface ASWEntityDecl extends ASEntityDecl {
    public void setRawname(String rawname);

    public void setEntityType(short type);

    public void setEntityValue(String value);

    public void setSystemId(String systemId);

    public void setPublicId(String publicId);

}

org/w3c/dom/as/ASWNotationDecl.java:

package org.w3c.dom.as;

public interface ASWNotationDecl extends ASNotationDecl {
    public void setRawname(String rawname);

    public void setName(String name);

    public void setNamespaceURI(String namespaceURI);

    public void setSystemId(String systemId);

    public void setPublicId(String publicId);

}

org/w3c/dom/as/DocumentAS.java:

package org.w3c.dom.as;

import org.w3c.dom.Document;
import org.w3c.dom.Element;
import org.w3c.dom.DOMException;
import org.w3c.dom.Notation;
import org.w3c.dom.Attr;
import org.w3c.dom.Entity;

public interface DocumentAS extends Document {
    public ASModel getActiveASModel();
    public void setActiveASModel(ASModel activeASModel);

    public ASObjectList getBoundASModels();
    public void setBoundASModels(ASObjectList boundASModels);

    public ASModel getInternalAS();

    public void setInternalAS(ASModel as)
                              throws DOMException;

    public void addAS(ASModel as);

    public void removeAS(ASModel as)
                         throws ASException;

    public ASElementDecl getElementDecl(Element node)
                                        throws DOMException;

    public ASAttributeDecl getAttributeDecl(Attr node)
                                            throws DOMException;

    public ASEntityDecl getEntityDecl(Entity node)
                                      throws DOMException;

    public ASNotationDecl getNotationDecl(Notation node)
                                          throws DOMException;

    public void validate()
                         throws ASException;

}

org/w3c/dom/as/DOMImplementationAS.java:

package org.w3c.dom.as;

import org.w3c.dom.DOMImplementation;

public interface DOMImplementationAS extends DOMImplementation {
    public ASWModel createASWModel(boolean isNamespaceAware,
                                   boolean container,
                                   String schemaType);

}

org/w3c/dom/as/ASDOMBuilder.java:

package org.w3c.dom.as;

import org.w3c.dom.ls.DOMInputSource;
import org.w3c.dom.ls.DOMBuilder;

public interface ASDOMBuilder extends DOMBuilder {
    public ASWModel getAbstractSchema();
    public void setAbstractSchema(ASWModel abstractSchema);

    public ASWModel parseASURI(String uri,
                               String schemaType)
                               throws ASException, Exception;

    public ASWModel parseASInputSource(DOMInputSource is,
                                       String schemaType)
                                       throws ASException, Exception;

}

org/w3c/dom/as/ASDOMWriter.java:

package org.w3c.dom.as;

import org.w3c.dom.ls.DOMWriter;

public interface ASDOMWriter extends DOMWriter {
    public void writeASModel(java.io.OutputStream destination,
                             ASModel model)
                             throws Exception;

}
previous next contents index


Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model Abstract Schemas definitions.

Properties of the ASConstants Constructor function:
ASConstants.ELEMENT_DECLARATION
The value of the constant ASConstants.ELEMENT_DECLARATION is 1.
ASConstants.ATTRIBUTE_DECLARATION
The value of the constant ASConstants.ATTRIBUTE_DECLARATION is 2.
ASConstants.NOTATION_DECLARATION
The value of the constant ASConstants.NOTATION_DECLARATION is 3.
ASConstants.ENTITY_DECLARATION
The value of the constant ASConstants.ENTITY_DECLARATION is 4.
ASConstants.CONTENT_MODEL
The value of the constant ASConstants.CONTENT_MODEL is 5.
ASConstants.SCHEMA_MODEL
The value of the constant ASConstants.SCHEMA_MODEL is 6.
ASConstants.INTERNAL_SUBSET
The value of the constant ASConstants.INTERNAL_SUBSET is 30.
ASConstants.EXTERNAL_SUBSET
The value of the constant ASConstants.EXTERNAL_SUBSET is 31.
ASConstants.NOT_USED
The value of the constant ASConstants.NOT_USED is 32.
ASConstants.INTERNAL_ENTITY
The value of the constant ASConstants.INTERNAL_ENTITY is 33.
ASConstants.EXTERNAL_ENTITY
The value of the constant ASConstants.EXTERNAL_ENTITY is 34.
ASConstants.EMPTY_CONTENTTYPE
The value of the constant ASConstants.EMPTY_CONTENTTYPE is 40.
ASConstants.SIMPLE_CONTENTTYPE
The value of the constant ASConstants.SIMPLE_CONTENTTYPE is 41.
ASConstants.ELEMENT_CONTENTTYPE
The value of the constant ASConstants.ELEMENT_CONTENTTYPE is 42.
ASConstants.MIXED_CONTENTTYPE
The value of the constant ASConstants.MIXED_CONTENTTYPE is 43.
ASConstants.ANY_CONTENTTYPE
The value of the constant ASConstants.ANY_CONTENTTYPE is 44.
ASConstants.SEQUENCE_CM
The value of the constant ASConstants.SEQUENCE_CM is 50.
ASConstants.CHOICE_CM
The value of the constant ASConstants.CHOICE_CM is 51.
ASConstants.ALL_CM
The value of the constant ASConstants.ALL_CM is 52.
ASConstants.UNDEFINED_CM
The value of the constant ASConstants.UNDEFINED_CM is 53.
ASConstants.ATOMIC_CM
The value of the constant ASConstants.ATOMIC_CM is 54.
ASConstants.NONE_VC
The value of the constant ASConstants.NONE_VC is 0.
ASConstants.DEFAULT_VC
The value of the constant ASConstants.DEFAULT_VC is 60.
ASConstants.FIXED_VC
The value of the constant ASConstants.FIXED_VC is 61.
ASConstants.REQUIRED_VC
The value of the constant ASConstants.REQUIRED_VC is 62.
ASConstants.UNBOUNDED
The value of the constant ASConstants.UNBOUNDED is MAX_VALUE.
Objects that implement the ASConstants interface:
Objects that implement the ASObject interface:
Properties of objects that implement the ASObject interface:
objectType
This read-only property is a Number.
ownerModel
This read-only property is an object that implements the ASModel interface.
rawname
This read-only property is a String.
name
This read-only property is a String.
namespace
This read-only property is a String.
Functions of objects that implement the ASObject interface:
cloneASObject(deep)
This function returns an object that implements the ASObject interface.
The deep parameter is a Boolean.
This function can raise an object that implements the ASException interface.
Properties of the ASDataType Constructor function:
ASDataType.STRING_DATATYPE
The value of the constant ASDataType.STRING_DATATYPE is 1.
ASDataType.NOTATION_DATATYPE
The value of the constant ASDataType.NOTATION_DATATYPE is 10.
ASDataType.ID_DATATYPE
The value of the constant ASDataType.ID_DATATYPE is 11.
ASDataType.IDREF_DATATYPE
The value of the constant ASDataType.IDREF_DATATYPE is 12.
ASDataType.IDREFS_DATATYPE
The value of the constant ASDataType.IDREFS_DATATYPE is 13.
ASDataType.ENTITY_DATATYPE
The value of the constant ASDataType.ENTITY_DATATYPE is 14.
ASDataType.ENTITIES_DATATYPE
The value of the constant ASDataType.ENTITIES_DATATYPE is 15.
ASDataType.NMTOKEN_DATATYPE
The value of the constant ASDataType.NMTOKEN_DATATYPE is 16.
ASDataType.NMTOKENS_DATATYPE
The value of the constant ASDataType.NMTOKENS_DATATYPE is 17.
ASDataType.BOOLEAN_DATATYPE
The value of the constant ASDataType.BOOLEAN_DATATYPE is 100.
ASDataType.FLOAT_DATATYPE
The value of the constant ASDataType.FLOAT_DATATYPE is 101.
ASDataType.DOUBLE_DATATYPE
The value of the constant ASDataType.DOUBLE_DATATYPE is 102.
ASDataType.DECIMAL_DATATYPE
The value of the constant ASDataType.DECIMAL_DATATYPE is 103.
ASDataType.HEXBINARY_DATATYPE
The value of the constant ASDataType.HEXBINARY_DATATYPE is 104.
ASDataType.BASE64BINARY_DATATYPE
The value of the constant ASDataType.BASE64BINARY_DATATYPE is 105.
ASDataType.ANYURI_DATATYPE
The value of the constant ASDataType.ANYURI_DATATYPE is 106.
ASDataType.QNAME_DATATYPE
The value of the constant ASDataType.QNAME_DATATYPE is 107.
ASDataType.DURATION_DATATYPE
The value of the constant ASDataType.DURATION_DATATYPE is 108.
ASDataType.DATETIME_DATATYPE
The value of the constant ASDataType.DATETIME_DATATYPE is 109.
ASDataType.DATE_DATATYPE
The value of the constant ASDataType.DATE_DATATYPE is 110.
ASDataType.TIME_DATATYPE
The value of the constant ASDataType.TIME_DATATYPE is 111.
ASDataType.GYEARMONTH_DATATYPE
The value of the constant ASDataType.GYEARMONTH_DATATYPE is 112.
ASDataType.GYEAR_DATATYPE
The value of the constant ASDataType.GYEAR_DATATYPE is 113.
ASDataType.GMONTHDAY_DATATYPE
The value of the constant ASDataType.GMONTHDAY_DATATYPE is 114.
ASDataType.GDAY_DATATYPE
The value of the constant ASDataType.GDAY_DATATYPE is 115.
ASDataType.GMONTH_DATATYPE
The value of the constant ASDataType.GMONTH_DATATYPE is 116.
ASDataType.INTEGER
The value of the constant ASDataType.INTEGER is 117.
ASDataType.NAME_DATATYPE
The value of the constant ASDataType.NAME_DATATYPE is 200.
ASDataType.NCNAME_DATATYPE
The value of the constant ASDataType.NCNAME_DATATYPE is 201.
ASDataType.NORMALIZEDSTRING_DATATYPE
The value of the constant ASDataType.NORMALIZEDSTRING_DATATYPE is 202.
ASDataType.TOKEN_DATATYPE
The value of the constant ASDataType.TOKEN_DATATYPE is 203.
ASDataType.LANGUAGE_DATATYPE
The value of the constant ASDataType.LANGUAGE_DATATYPE is 204.
ASDataType.NONPOSITIVEINTEGER_DATATYPE
The value of the constant ASDataType.NONPOSITIVEINTEGER_DATATYPE is 205.
ASDataType.NEGATIVEINTEGER_DATATYPE
The value of the constant ASDataType.NEGATIVEINTEGER_DATATYPE is 206.
ASDataType.LONG_DATATYPE
The value of the constant ASDataType.LONG_DATATYPE is 207.
ASDataType.INT_DATATYPE
The value of the constant ASDataType.INT_DATATYPE is 208.
ASDataType.SHORT_DATATYPE
The value of the constant ASDataType.SHORT_DATATYPE is 209.
ASDataType.BYTE_DATATYPE
The value of the constant ASDataType.BYTE_DATATYPE is 210.
ASDataType.NONNEGATIVEINTEGER_DATATYPE
The value of the constant ASDataType.NONNEGATIVEINTEGER_DATATYPE is 211.
ASDataType.UNSIGNEDLONG_DATATYPE
The value of the constant ASDataType.UNSIGNEDLONG_DATATYPE is 212.
ASDataType.UNSIGNEDINT_DATATYPE
The value of the constant ASDataType.UNSIGNEDINT_DATATYPE is 213.
ASDataType.UNSIGNEDSHORT_DATATYPE
The value of the constant ASDataType.UNSIGNEDSHORT_DATATYPE is 214.
ASDataType.UNSIGNEDBYTE_DATATYPE
The value of the constant ASDataType.UNSIGNEDBYTE_DATATYPE is 215.
ASDataType.POSITIVEINTEGER_DATATYPE
The value of the constant ASDataType.POSITIVEINTEGER_DATATYPE is 216.
ASDataType.ANYSIMPLETYPE_DATATYPE
The value of the constant ASDataType.ANYSIMPLETYPE_DATATYPE is 216.
ASDataType.ANYTYPE_DATATYPE
The value of the constant ASDataType.ANYTYPE_DATATYPE is 216.
Objects that implement the ASDataType interface:
Properties of objects that implement the ASDataType interface:
dataType
This read-only property is a Number.
Objects that implement the ASObjectList interface:
Properties of objects that implement the ASObjectList interface:
length
This read-only property is a Number.
Functions of objects that implement the ASObjectList interface:
item(index)
This function returns an object that implements the ASObject interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
Objects that implement the ASNamedObjectMap interface:
Properties of objects that implement the ASNamedObjectMap interface:
length
This read-only property is a Number.
Functions of objects that implement the ASNamedObjectMap interface:
item(index)
This function returns an object that implements the ASObject interface.
The index parameter is a Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item function with that index.
getNamedItem(name)
This function returns an object that implements the ASObject interface.
The name parameter is a String.
getNamedItemNS(namespaceURI, localName)
This function returns an object that implements the ASObject interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
Objects that implement the ASModel interface:
Objects that implement the ASModel interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASModel interface:
namespaceAware
This read-only property is a Boolean.
usage
This read-only property is a Number.
location
This read-only property is a String.
hint
This read-only property is a String.
container
This read-only property is a Boolean.
Functions of objects that implement the ASModel interface:
getComponents(objectType)
This function returns an object that implements the ASNamedObjectMap interface.
The objectType parameter is a Number.
getElementDecl(name, targetNamespace)
This function returns an object that implements the ASElementDecl interface.
The name parameter is a String.
The targetNamespace parameter is a String.
getAttributeDecl(name, targetNamespace)
This function returns an object that implements the ASAttributeDecl interface.
The name parameter is a String.
The targetNamespace parameter is a String.
getEntityDecl(name)
This function returns an object that implements the ASEntityDecl interface.
The name parameter is a String.
getNotationDecl(name, targetNamespace)
This function returns an object that implements the ASNotationDecl interface.
The name parameter is a String.
The targetNamespace parameter is a String.
Objects that implement the ASContentModel interface:
Objects that implement the ASContentModel interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASContentModel interface:
contentModelType
This read-only property is a Number.
minOccurs
This read-only property is a Number.
maxOccurs
This read-only property is a Number.
subModels
This read-only property is an object that implements the ASObjectList interface.
Objects that implement the ASElementDecl interface:
Objects that implement the ASElementDecl interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASElementDecl interface:
type
This read-only property is an object that implements the ASDataType interface.
contentType
This read-only property is a Number.
strictMixedContent
This read-only property is a Boolean.
contentModel
This read-only property is an object that implements the ASContentModel interface.
isPCDataOnly
This read-only property is a Boolean.
attributeDecls
This read-only property is an object that implements the ASNamedObjectMap interface.
Functions of objects that implement the ASElementDecl interface:
getAttributeDecl(name, targetNamespace)
This function returns an object that implements the ASAttributeDecl interface.
The name parameter is a String.
The targetNamespace parameter is a String.
Objects that implement the ASAttributeDecl interface:
Objects that implement the ASAttributeDecl interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASAttributeDecl interface:
type
This read-only property is an object that implements the ASDataType interface.
enumAttr
This read-only property is a String.
ownerElementDeclarations
This read-only property is an object that implements the ASObjectList interface.
defaultType
This read-only property is a Number.
value
This read-only property is a String.
Objects that implement the ASEntityDecl interface:
Objects that implement the ASEntityDecl interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASEntityDecl interface:
entityType
This read-only property is a Number.
entityValue
This read-only property is a String.
systemId
This read-only property is a String.
publicId
This read-only property is a String.
Objects that implement the ASNotationDecl interface:
Objects that implement the ASNotationDecl interface have all properties and functions of the ASObject interface as well as the properties and functions defined below.
Properties of objects that implement the ASNotationDecl interface:
systemId
This read-only property is a String.
publicId
This read-only property is a String.
Objects that implement the ASWModel interface:
Objects that implement the ASWModel interface have all properties and functions of the ASModel interface as well as the properties and functions defined below.
Functions of objects that implement the ASWModel interface:
setLocation(location)
This function has no return value.
The location parameter is a String.
setHint(hint)
This function has no return value.
The hint parameter is a String.
addComponent(declaration)
This function has no return value.
The declaration parameter is an object that implements the ASObject interface.
removeComponent(declaration)
This function has no return value.
The declaration parameter is an object that implements the ASObject interface.
addASModel(declaration)
This function has no return value.
The declaration parameter is an object that implements the ASModel interface.
removeASModel(declaration)
This function has no return value.
The declaration parameter is an object that implements the ASModel interface.
getASModels()
This function returns an object that implements the ASObjectList interface.
importASObject(asobject)
This function returns an object that implements the ASObject interface.
The asobject parameter is an object that implements the ASObject interface.
insertASObject(asobject)
This function has no return value.
The asobject parameter is an object that implements the ASObject interface.
validate()
This function returns a Boolean.
createASWElementDecl(namespaceURI, name)
This function returns an object that implements the ASWElementDecl interface.
The namespaceURI parameter is a String.
The name parameter is a String.
This function can raise an object that implements the ASException interface.
createASWAttributeDecl(namespaceURI, name)
This function returns an object that implements the ASWAttributeDecl interface.
The namespaceURI parameter is a String.
The name parameter is a String.
This function can raise an object that implements the ASException interface.
createASWNotationDecl(namespaceURI, name, systemId, publicId)
This function returns an object that implements the ASWNotationDecl interface.
The namespaceURI parameter is a String.
The name parameter is a String.
The systemId parameter is a String.
The publicId parameter is a String.
This function can raise an object that implements the ASException interface.
createASWEntityDecl(name)
This function returns an object that implements the ASWEntityDecl interface.
The name parameter is a String.
This function can raise an object that implements the ASException interface.
createASWContentModel(name, namespaceURI, minOccurs, maxOccurs, operator)
This function returns an object that implements the ASWContentModel interface.
The name parameter is a String.
The namespaceURI parameter is a String.
The minOccurs parameter is a Number.
The maxOccurs parameter is a Number.
The operator parameter is a Number.
This function can raise an object that implements the ASException interface.
Objects that implement the ASWNamedObjectMap interface:
Objects that implement the ASWNamedObjectMap interface have all properties and functions of the ASNamedObjectMap interface as well as the properties and functions defined below.
Functions of objects that implement the ASWNamedObjectMap interface:
removeNamedItem(name)
This function returns an object that implements the ASObject interface.
The name parameter is a String.
This function can raise an object that implements the ASException interface.
setNamedItem(newASObject)
This function returns an object that implements the ASObject interface.
The newASObject parameter is an object that implements the ASObject interface.
This function can raise an object that implements the ASException interface or the ASException interface.
setNamedItemNS(arg)
This function returns an object that implements the ASObject interface.
The arg parameter is an object that implements the ASObject interface.
This function can raise an object that implements the ASException interface.
removeNamedItemNS(namespaceURI, localName)
This function returns an object that implements the ASObject interface.
The namespaceURI parameter is a String.
The localName parameter is a String.
This function can raise an object that implements the DOMException interface.
Objects that implement the ASWElementDecl interface:
Objects that implement the ASWElementDecl interface have all properties and functions of the ASElementDecl interface as well as the properties and functions defined below.
Functions of objects that implement the ASWElementDecl interface:
setRawname(rawname)
This function has no return value.
The rawname parameter is a String.
setName(name)
This function has no return value.
The name parameter is a String.
setNamespace(namespaceURI)
This function has no return value.
The namespaceURI parameter is a String.
setStrictMixedContent(mixedContent)
This function has no return value.
The mixedContent parameter is a Boolean.
setType(type)
This function has no return value.
The type parameter is an object that implements the ASDataType interface.
setContentType(contentType)
This function has no return value.
The contentType parameter is a Number.
setContentModel(contentModel)
This function has no return value.
The contentModel parameter is an object that implements the ASWContentModel interface.
addAttributeDecl(attributeDecl)
This function has no return value.
The attributeDecl parameter is an object that implements the ASWAttributeDecl interface.
removeAttributeDecl(attributeDecl)
This function returns an object that implements the ASWAttributeDecl interface.
The attributeDecl parameter is an object that implements the ASWAttributeDecl interface.
Objects that implement the ASWContentModel interface:
Objects that implement the ASWContentModel interface have all properties and functions of the ASContentModel interface as well as the properties and functions defined below.
Functions of objects that implement the ASWContentModel interface:
setName(name)
This function has no return value.
The name parameter is a String.
setNamespaceURI(namespaceURI)
This function has no return value.
The namespaceURI parameter is a String.
setContentModelType(operator)
This function has no return value.
The operator parameter is a Number.
setMinOccurs(minOccurs)
This function has no return value.
The minOccurs parameter is a Number.
setMaxOccurs(maxOccurs)
This function has no return value.
The maxOccurs parameter is a Number.
removeSubModel(oldObject)
This function has no return value.
The oldObject parameter is an object that implements the ASObject interface.
insertBeforeSubModel(newObject, refObject)
This function returns an object that implements the ASObject interface.
The newObject parameter is an object that implements the ASObject interface.
The refObject parameter is an object that implements the ASObject interface.
This function can raise an object that implements the ASException interface.
appendSubModel(newObject)
This function returns a Number.
The newObject parameter is an object that implements the ASObject interface.
This function can raise an object that implements the ASException interface.
Objects that implement the ASWAttributeDecl interface:
Objects that implement the ASWAttributeDecl interface have all properties and functions of the ASAttributeDecl interface as well as the properties and functions defined below.
Functions of objects that implement the ASWAttributeDecl interface:
setRawname(rawname)
This function has no return value.
The rawname parameter is a String.
setName(name)
This function has no return value.
The name parameter is a String.
setNamespaceURI(namespaceURI)
This function has no return value.
The namespaceURI parameter is a String.
setType(type)
This function has no return value.
The type parameter is an object that implements the ASDataType interface.
setValue(value)
This function has no return value.
The value parameter is a String.
setEnumAttr(enumeration)
This function has no return value.
The enumeration parameter is a String.
setDefaultType(constraint)
This function has no return value.
The constraint parameter is a Number.
Objects that implement the ASWEntityDecl interface:
Objects that implement the ASWEntityDecl interface have all properties and functions of the ASEntityDecl interface as well as the properties and functions defined below.
Functions of objects that implement the ASWEntityDecl interface:
setRawname(rawname)
This function has no return value.
The rawname parameter is a String.
setEntityType(type)
This function has no return value.
The type parameter is a Number.
setEntityValue(value)
This function has no return value.
The value parameter is a String.
setSystemId(systemId)
This function has no return value.
The systemId parameter is a String.
setPublicId(publicId)
This function has no return value.
The publicId parameter is a String.
Objects that implement the ASWNotationDecl interface:
Objects that implement the ASWNotationDecl interface have all properties and functions of the ASNotationDecl interface as well as the properties and functions defined below.
Functions of objects that implement the ASWNotationDecl interface:
setRawname(rawname)
This function has no return value.
The rawname parameter is a String.
setName(name)
This function has no return value.
The name parameter is a String.
setNamespaceURI(namespaceURI)
This function has no return value.
The namespaceURI parameter is a String.
setSystemId(systemId)
This function has no return value.
The systemId parameter is a String.
setPublicId(publicId)
This function has no return value.
The publicId parameter is a String.
Properties of the ASException Constructor function:
ASException.DUPLICATE_NAME_ERR
The value of the constant ASException.DUPLICATE_NAME_ERR is 1.
ASException.TYPE_ERR
The value of the constant ASException.TYPE_ERR is 2.
ASException.NO_AS_AVAILABLE
The value of the constant ASException.NO_AS_AVAILABLE is 3.
ASException.WRONG_MIME_TYPE_ERR
The value of the constant ASException.WRONG_MIME_TYPE_ERR is 4.
ASException.INVALID_CHARACTER_ERR
The value of the constant ASException.INVALID_CHARACTER_ERR is 5.
ASException.VALIDATION_ERR
The value of the constant ASException.VALIDATION_ERR is 6.
ASException.ACTIVEAS_DELETION_ERR
The value of the constant ASException.ACTIVEAS_DELETION_ERR is 7.
Objects that implement the ASException interface:
Properties of objects that implement the ASException interface:
code
This property is a Number.
Objects that implement the DocumentAS interface:
Objects that implement the DocumentAS interface have all properties and functions of the Document interface as well as the properties and functions defined below.
Properties of objects that implement the DocumentAS interface:
activeASModel
This property is an object that implements the ASModel interface.
boundASModels
This property is an object that implements the ASObjectList interface.
Functions of objects that implement the DocumentAS interface:
getInternalAS()
This function returns an object that implements the ASModel interface.
setInternalAS(as)
This function has no return value.
The as parameter is an object that implements the ASModel interface.
This function can raise an object that implements the DOMException interface.
addAS(as)
This function has no return value.
The as parameter is an object that implements the ASModel interface.
removeAS(as)
This function has no return value.
The as parameter is an object that implements the ASModel interface.
This function can raise an object that implements the ASException interface.
getElementDecl(node)
This function returns an object that implements the ASElementDecl interface.
The node parameter is an object that implements the Element interface.
This function can raise an object that implements the DOMException interface.
getAttributeDecl(node)
This function returns an object that implements the ASAttributeDecl interface.
The node parameter is an object that implements the Attr interface.
This function can raise an object that implements the DOMException interface.
getEntityDecl(node)
This function returns an object that implements the ASEntityDecl interface.
The node parameter is an object that implements the Entity interface.
This function can raise an object that implements the DOMException interface.
getNotationDecl(node)
This function returns an object that implements the ASNotationDecl interface.
The node parameter is an object that implements the Notation interface.
This function can raise an object that implements the DOMException interface.
validate()
This function has no return value.
This function can raise an object that implements the ASException interface.
Objects that implement the DOMImplementationAS interface:
Objects that implement the DOMImplementationAS interface have all properties and functions of the DOMImplementation interface as well as the properties and functions defined below.
Functions of objects that implement the DOMImplementationAS interface:
createASWModel(isNamespaceAware, container, schemaType)
This function returns an object that implements the ASWModel interface.
The isNamespaceAware parameter is a Boolean.
The container parameter is a Boolean.
The schemaType parameter is a String.
Objects that implement the ASDOMBuilder interface:
Objects that implement the ASDOMBuilder interface have all properties and functions of the DOMBuilder interface as well as the properties and functions defined below.
Properties of objects that implement the ASDOMBuilder interface:
abstractSchema
This property is an object that implements the ASWModel interface.
Functions of objects that implement the ASDOMBuilder interface:
parseASURI(uri, schemaType)
This function returns an object that implements the ASWModel interface.
The uri parameter is a String.
The schemaType parameter is a String.
This function can raise an object that implements the ASException interface or the DOMSystemException interface.
parseASInputSource(is, schemaType)
This function returns an object that implements the ASWModel interface.
The is parameter is an object that implements the DOMInputSource interface.
The schemaType parameter is a String.
This function can raise an object that implements the ASException interface or the DOMSystemException interface.
Objects that implement the ASDOMWriter interface:
Objects that implement the ASDOMWriter interface have all properties and functions of the DOMWriter interface as well as the properties and functions defined below.
Functions of objects that implement the ASDOMWriter interface:
writeASModel(destination, model)
This function has no return value.
The destination parameter is an object that implements the Object interface.
The model parameter is an object that implements the ASModel interface.
This function can raise an object that implements the DOMSystemException interface.
previous next contents index


Appendix D: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:

Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former Chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mary Brady (NIST), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact and former Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home, and Netscape/AOL, Chair), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

D.1: Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.

Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.

After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.

Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.

previous next contents index


Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.

API
An API is an Application Programming Interface, a set of functions or methods used to access some functionality.
child
A child is an immediate descendant node of a node.
content model
The content model is a simple grammar governing the allowed types of the child elements and the order in which they appear. See Element Content in XML [XML 1.0].
document element
There is only one document element in a Document. This element node is a child of the Document node. See Well-Formed XML Documents in XML [XML 1.0].
document order
There is an ordering, document order, defined on all the nodes in the document corresponding to the order in which the first character of the XML representation of each node occurs in the XML representation of the document after expansion of general entities. Thus, the document element node will be the first node. Element nodes occur before their children. Thus, document order orders element nodes in order of the occurrence of their start-tag in the XML (after expansion of entities). The attribute nodes of an element occur after the element and before its children. The relative order of attribute nodes is implementation-dependent.
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. See Logical Structures in XML [XML 1.0].
live
An object is live if any change to the underlying document structure is reflected in the object.
local name
A local name is the local part of a qualified name. This is called the local part in Namespaces in XML [XML Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in Namespaces in XML [XML Namespaces].
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
well-formed document
A document is well-formed if it is tag valid and entities are limited to single elements (i.e., single sub-trees).
XML
Extensible Markup Language (XML) is an extremely simple dialect of SGML which is completely described in this document. The goal is to enable generic SGML to be served, received, and processed on the Web in the way that is now possible with HTML. XML has been designed for ease of implementation and for interoperability with both SGML and HTML. [XML 1.0]
previous next contents index


References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

The references listed in this section are normatives.

[DOM Level 3 Core]
Document Object Model Level 3 Core Specification, A. Le Hors, et al., Editors. World Wide Web Consortium, January 2002. This version of the Document Object Model Level 3 Core Specification is http://www.w3.org/TR/2002/WD-DOM-Level-3-Core-20020114. The latest version of DOM Level 3 Core is available at http://www.w3.org/TR/DOM-Level-3-Core.
[DOM Level 3 Load and Save]
Document Object Model Level 3 Load and Save Specification, J. Stenback, A. Heninger, Editors. World Wide Web Consortium, June 2002. This version of the DOM Level 3 Load and Save Specification is http://www.w3.org/TR/DOM-Level-3-LS. The latest version of DOM Level 3 Load and Save is available at http://www.w3.org/TR/DOM-Level-3-LS.
[ECMAScript]
ECMAScript Language Specification, Third Edition. European Computer Manufacturers Association, December 1999. This version of the ECMAScript Language is available at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM.
[Java]
The Java Language Specification, J. Gosling, B. Joy, and G. Steele, Authors. Addison-Wesley, September 1996. Available at http://java.sun.com/docs/books/jls
[OMG IDL]
"OMG IDL Syntax and Semantics" defined in The Common Object Request Broker: Architecture and Specification, version 2, Object Management Group. The latest version of CORBA version 2.0 is available at http://www.omg.org/technology/documents/formal/corba_2.htm.
[XML 1.0]
Extensible Markup Language (XML) 1.0 (Second Edition), T. Bray, J. Paoli, C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide Web Consortium, 10 February 1998, revised 6 October 2000. This version of the XML 1.0 Recommendation is http://www.w3.org/TR/2000/REC-xml-20001006. The latest version of XML 1.0 is available at http://www.w3.org/TR/REC-xml.
[XML Namespaces]
Namespaces in XML, T. Bray, D. Hollander, and A. Layman, Editors. World Wide Web Consortium, 14 January 1999. This version of the XML Information Set Recommendation is http://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespaces in XML is available at http://www.w3.org/TR/REC-xml-names.
[XML Schema Part 0]
XML Schema Part 0: Primer, D. Fallside, Editor. World Wide Web Consortium, 2 May 2001. This version of the XML Part 0 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-0-20010502. The latest version of XML Schema Part 0 is available at http://www.w3.org/TR/xmlschema-0.
[XML Schema Part 1]
XML Schema Part 1: Structures, H. Thompson, D. Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Part 1 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-1-20010502. The latest version of XML Schema Part 1 is available at http://www.w3.org/TR/xmlschema-1.
[XML Schema Part 2]
XML Schema Part 2: Datatypes, P. Byron and Ashok Malhotra, Editors. World Wide Web Consortium, 2 May 2001. This version of the XML Part 2 Recommendation is http://www.w3.org/TR/2001/REC-xmlschema-2-20010502. The latest version of XML Schema Part 2 is available at http://www.w3.org/TR/xmlschema-2.
previous next contents index


Index

abstractSchema | ACTIVEAS_DELETION_ERR | activeASModel
addAS | addASModel | addAttributeDecl
addComponent | ALL_CM | ANY_CONTENTTYPE
ANYSIMPLETYPE_DATATYPE | ANYTYPE_DATATYPE | ANYURI_DATATYPE
API 1, 2 | appendSubModel | ASAttributeDecl
ASConstants | ASContentModel | ASDataType
ASDOMBuilder | ASDOMWriter | ASElementDecl
ASEntityDecl | ASException | ASModel
ASNamedObjectMap | ASNotationDecl | ASObject
ASObjectList | ASWAttributeDecl | ASWContentModel
ASWElementDecl | ASWEntityDecl | ASWModel
ASWNamedObjectMap | ASWNotationDecl | ATOMIC_CM
ATTRIBUTE_DECLARATION | attributeDecls
BASE64BINARY_DATATYPE | BOOLEAN_DATATYPE | boundASModels
BYTE_DATATYPE
child 1, 2, 3, 4, 5 | CHOICE_CM | cloneASObject
container | content model 1, 2, 3 | CONTENT_MODEL
contentModel | contentModelType | contentType
createASWAttributeDecl | createASWContentModel | createASWElementDecl
createASWEntityDecl | createASWModel | createASWNotationDecl
dataType | DATE_DATATYPE | DATETIME_DATATYPE
DECIMAL_DATATYPE | DEFAULT_VC | defaultType
document element | document order | DocumentAS
DOM Level 3 Core 1, 2, 3, 4 | DOM Level 3 Load and Save 1, 2, 3 | DOMImplementationAS
DOUBLE_DATATYPE | DUPLICATE_NAME_ERR | DURATION_DATATYPE
ECMAScript | element 1, 2, 3 | ELEMENT_CONTENTTYPE
ELEMENT_DECLARATION | EMPTY_CONTENTTYPE | ENTITIES_DATATYPE
ENTITY_DATATYPE | ENTITY_DECLARATION | entityType
entityValue | enumAttr | EXTERNAL_ENTITY
EXTERNAL_SUBSET
FIXED_VC | FLOAT_DATATYPE
GDAY_DATATYPE | getASModels | getAttributeDecl 1, 2, 3
getComponents | getElementDecl 1, 2 | getEntityDecl 1, 2
getInternalAS | getNamedItem | getNamedItemNS
getNotationDecl 1, 2 | GMONTH_DATATYPE | GMONTHDAY_DATATYPE
GYEAR_DATATYPE | GYEARMONTH_DATATYPE
HEXBINARY_DATATYPE | hint
ID_DATATYPE | IDREF_DATATYPE | IDREFS_DATATYPE
importASObject | insertASObject | insertBeforeSubModel
INT_DATATYPE | INTEGER | INTERNAL_ENTITY
INTERNAL_SUBSET | INVALID_CHARACTER_ERR | isPCDataOnly
item 1, 2
Java
LANGUAGE_DATATYPE | length 1, 2 | live 1, 2, 3
local name 1, 2, 3 | location | LONG_DATATYPE
maxOccurs | minOccurs | MIXED_CONTENTTYPE
name | NAME_DATATYPE | namespace
namespace URI 1, 2, 3, 4, 5, 6 | namespaceAware | NCNAME_DATATYPE
NEGATIVEINTEGER_DATATYPE | NMTOKEN_DATATYPE | NMTOKENS_DATATYPE
NO_AS_AVAILABLE | NONE_VC | NONNEGATIVEINTEGER_DATATYPE
NONPOSITIVEINTEGER_DATATYPE | NORMALIZEDSTRING_DATATYPE | NOT_USED
NOTATION_DATATYPE | NOTATION_DECLARATION
objectType | OMG IDL | ownerElementDeclarations
ownerModel
parseASInputSource | parseASURI | POSITIVEINTEGER_DATATYPE
publicId 1, 2
QNAME_DATATYPE
rawname | removeAS | removeASModel
removeAttributeDecl | removeComponent | removeNamedItem
removeNamedItemNS | removeSubModel | REQUIRED_VC
SCHEMA_MODEL | SEQUENCE_CM | setContentModel
setContentModelType | setContentType | setDefaultType
setEntityType | setEntityValue | setEnumAttr
setHint | setInternalAS | setLocation
setMaxOccurs | setMinOccurs | setName 1, 2, 3, 4
setNamedItem | setNamedItemNS | setNamespace
setNamespaceURI 1, 2, 3 | setPublicId 1, 2 | setRawname 1, 2, 3, 4
setStrictMixedContent | setSystemId 1, 2 | setType 1, 2
setValue | SHORT_DATATYPE | SIMPLE_CONTENTTYPE
strictMixedContent | STRING_DATATYPE | subModels
systemId 1, 2
TIME_DATATYPE | TOKEN_DATATYPE | tokenized
type 1, 2 | TYPE_ERR
UNBOUNDED | UNDEFINED_CM | UNSIGNEDBYTE_DATATYPE
UNSIGNEDINT_DATATYPE | UNSIGNEDLONG_DATATYPE | UNSIGNEDSHORT_DATATYPE
usage
validate 1, 2 | VALIDATION_ERR | value
well-formed document | writeASModel | WRONG_MIME_TYPE_ERR
XML 1, 2 | XML 1.0 1, 2, 3, 4, 5, 6, 7, 8 | XML Namespaces 1, 2, 3, 4, 5, 6, 7
XML Schema Part 0 1, 2, 3 | XML Schema Part 1 1, 2 | XML Schema Part 2 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47
previous contents


Document Object Model Level 4

DOM4

W3C Working Draft 5 April 2012

This Version:
http://www.w3.org/TR/2012/WD-dom-20120405/
Latest Version:
http://www.w3.org/TR/dom/
Latest Editors' Draft:
http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html
Previous Versions:
http://www.w3.org/TR/2012/WD-dom-20120105/
http://www.w3.org/TR/2011/WD-dom-20110915/
http://www.w3.org/TR/2011/WD-domcore-20110531/
http://www.w3.org/TR/2010/WD-domcore-20101007/
Editors:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>
Aryeh Gregor (Mozilla Foundation) <ayg@aryeh.name>
Ms2ger (Mozilla Foundation) <ms2ger@gmail.com>

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

Abstract

DOM4 defines the event and document model the Web platform uses. The DOM is a language- and platform neutral interface that allows programs and scripts to dynamically access and update the content and structure of documents.

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 the 5 April 2012 W3C Working Draft of DOM4. Please send comments to www-dom@w3.org (archived) with [DOM] at the start of the subject line, or file a bug.

This document is produced by the Web Applications (WebApps) Working Group. The WebApps Working Group is part of the Rich Web Clients Activity in 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. Goals
  2. 1 Conformance
    1. 1.1 Dependencies
    2. 1.2 Extensibility
  3. 2 Terminology
    1. 2.1 Trees
    2. 2.2 Strings
    3. 2.3 Common microsyntaxes
      1. 2.3.1 Common parser idioms
      2. 2.3.2 Space-separated tokens
    4. 2.4 Namespaces
  4. 3 Errors
    1. 3.1 Exception DOMException
    2. 3.2 Interface DOMError
    3. 3.3 Error types
  5. 4 Events
    1. 4.1 Introduction to "DOM Events"
    2. 4.2 Interface Event
    3. 4.3 Interface CustomEvent
    4. 4.4 Constructing events
    5. 4.5 Interface EventTarget
    6. 4.6 Dispatching events
    7. 4.7 Firing events
  6. 5 Nodes
    1. 5.1 Introduction to "The DOM"
    2. 5.2 Node tree
      1. 5.2.1 Mutation algorithms
      2. 5.2.2 Mutation methods
      3. 5.2.3 Legacy mutation methods
      4. 5.2.4 Mutation observers
      5. 5.2.5 Interface MutationRecord
    3. 5.3 Interface Node
    4. 5.4 Interface Document
      1. 5.4.1 Interface DOMImplementation
    5. 5.5 Interface DocumentFragment
    6. 5.6 Interface DocumentType
    7. 5.7 Interface Element
      1. 5.7.1 Interface Attr
    8. 5.8 Interface CharacterData
    9. 5.9 Interface Text
    10. 5.10 Interface ProcessingInstruction
    11. 5.11 Interface Comment
  7. 6 Ranges
    1. 6.1 Interface Range
  8. 7 Traversal
    1. 7.1 Interface NodeIterator
    2. 7.2 Interface TreeWalker
    3. 7.3 Interface NodeFilter
  9. 8 Collections
    1. 8.1 Interface NodeList
    2. 8.2 Interface HTMLCollection
  10. 9 Lists
    1. 9.1 Interface DOMStringList
    2. 9.2 Interface DOMTokenList
    3. 9.3 Interface DOMSettableTokenList
  11. 10 Historical
    1. 10.1 DOM Events
    2. 10.2 DOM Core
    3. 10.3 DOM Range
    4. 10.4 DOM Traversal
  12. References
    1. Normative references
    2. Informative references
  13. Acknowledgments

Goals

This specification standardizes the DOM. It does so as follows:

  1. By consolidating DOM Level 3 Core [DOM3CORE], Element Traversal [ELEMENTTRAVERSAL], the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events [DOM3EVENTS] (specific type of events do not belong in the base specification), and DOM Level 2 Traversal and Range [DOM2TR], and:

    • Aligning them with the needs of ECMAScript where possible.
    • Aligning them with existing implementations.
    • Simplifying them as much as possible.

  2. By moving features from HTML5 that ought to be part of the DOM platform here, while preventing a dependency on HTML5. [HTML]

  3. By defining a replacement for the "Mutation Events" and "Mutation Name Event Types" chapters of DOM Level 3 Events [DOM3EVENTS] as the old model was problematic.

    The old model is expected to be removed from implementations in due course.

  4. By defining new features that simplify common DOM operations.

1 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

User agents may impose implementation-specific limits on otherwise unconstrained inputs, e.g. to prevent denial of service attacks, to guard against running out of memory, or to work around platform-specific limitations.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

1.1 Dependencies

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WEBIDL]

Some of the terms used in this specification are defined in Web IDL, XML and Namespaces in XML. [WEBIDL] [XML] [XMLNS]

1.2 Extensibility

Vendor-specific proprietary extensions to this specification are strongly discouraged. Authors must not use such extensions, as doing so reduces interoperability and fragments the user base, allowing only users of specific user agents to access the content in question.

If vendor-specific extensions are needed, the members should be prefixed by vendor-specific strings to prevent clashes with future versions of this specification. Extensions must be defined so that the use of extensions neither contradicts nor causes the non-conformance of functionality defined in the specification.

When vendor-neutral extensions to this specification are needed, either this specification can be updated accordingly, or an extension specification can be written that overrides the requirements in this specification. When someone applying this specification to their activities decides that they will recognize the requirements of such an extension specification, it becomes an applicable specification for the purposes of conformance requirements in this specification.

2 Terminology

The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.

The preferred MIME name of a character encoding is the name or alias labeled as "preferred MIME name" in the IANA Character Sets registry, if there is one, or the encoding's name, if none of the aliases are so labeled. [IANACHARSET]

2.1 Trees

Just like most programming paradigms the Web platform has finite hierarchical tree structures, simply named trees. The tree order is preorder, depth-first traversal.

An object that participates in a tree has a parent, which is either another object or null, and an ordered list of zero or more child objects.

The root of an object is itself, if it has no parent, or else it is the root of its parent.

An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.

An inclusive descendant is an object or one of its descendants.

An object A is called an ancestor of an object B if and only if B is a descendant of A.

An inclusive ancestor is an object or one of its ancestors.

An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.

An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.

An object A is following an object B if A and B are in the same tree and A comes after B in tree order.

The first child of an object is its first child or null if it has no child.

The last child of an object is its last child or null if it has no child.

The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.

The next sibling of an object is its first following sibling or null if it has no following sibling.

The index of an object is its number of preceding siblings.

2.2 Strings

Comparing two strings in a case-sensitive manner means comparing them exactly, code point for code point.

Comparing two strings in a ASCII case-insensitive manner means comparing them exactly, code point for code point, except that the characters in the range U+0041 .. U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) and the corresponding characters in the range U+0061 .. U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) are considered to also match.

Converting a string to ASCII uppercase means replacing all characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z) with the corresponding characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z).

Converting a string to ASCII lowercase means replacing all characters in the range U+0041 to U+005A (i.e. LATIN CAPITAL LETTER A to LATIN CAPITAL LETTER Z) with the corresponding characters in the range U+0061 to U+007A (i.e. LATIN SMALL LETTER A to LATIN SMALL LETTER Z).

A string pattern is a prefix match for a string s when pattern is not longer than s and truncating s to pattern's length leaves the two strings as matches of each other.

The space characters, for the purposes of this specification, are U+0020 SPACE, U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED (LF), U+000C FORM FEED (FF), and U+000D CARRIAGE RETURN (CR).

2.3 Common microsyntaxes

2.3.1 Common parser idioms

Some of the micro-parsers described below follow the pattern of having an input variable that holds the string being parsed, and having a position variable pointing at the next character to parse in input.

For parsers based on this pattern, a step that requires the user agent to collect a sequence of characters means that the following algorithm must be run, with characters being the set of characters that can be collected:

  1. Let input and position be the same variables as those of the same name in the algorithm that invoked these steps.

  2. Let result be the empty string.

  3. While position does not point past the end of input and the character at position is one of the characters, append that character to the end of result and advance position to the next character in input.

  4. Return result.

The step skip whitespace means that the user agent must collect a sequence of characters that are space characters. The collected characters are not used.

2.3.2 Space-separated tokens

A set of space-separated tokens is a string containing zero or more words (known as tokens) separated by one or more space characters, where words consist of any string of one or more characters, none of which are space characters.

A string containing a set of space-separated tokens may have leading or trailing space characters.

An unordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated.

An ordered set of unique space-separated tokens is a set of space-separated tokens where none of the tokens are duplicated but where the order of the tokens is meaningful.

Sets of space-separated tokens sometimes have a defined set of allowed values. When a set of allowed values is defined, the tokens must all be from that list of allowed values; other values are non-conforming. If no such set of allowed values is provided, then all values are conforming.

How tokens in a set of space-separated tokens are to be compared (e.g. case-sensitively or not) is defined on a per-set basis.

When a user agent has to split a string on spaces, it must use the following algorithm:

  1. Let input be the string being parsed.

  2. Let position be a pointer into input, initially pointing at the start of the string.

  3. Let tokens be a list of tokens, initially empty.

  4. Skip whitespace.

  5. While position is not past the end of input:

    1. Collect a sequence of characters that are not space characters.

    2. Add the string collected in the previous step to tokens.

    3. Skip whitespace.

  6. Return tokens.

When a user agent has to remove a token from a string, it must use the following algorithm:

  1. Let input be the string being modified.

  2. Let token be the token being removed. It will not contain any space characters.

  3. Let output be the output string, initially empty.

  4. Let position be a pointer into input, initially pointing at the start of the string.

  5. Loop: If position is beyond the end of input, terminate these steps.

  6. If the character at position is a space character:

    1. Append the character at position to the end of output.

    2. Advance position so it points at the next character in input.

    3. Return to the step labeled loop.

  7. Otherwise, the character at position is the first character of a token. Collect a sequence of characters that are not space characters, and let that be s.

  8. If s is exactly equal to token, then:

    1. Skip whitespace (in input).

    2. Remove any space characters currently at the end of output.

    3. If position is not past the end of input, and output is not the empty string, append a single U+0020 SPACE character at the end of output.

  9. Otherwise, append s to the end of output.

  10. Return to the step labeled loop.

This causes any occurrences of the token to be removed from the string, and any spaces that were surrounding the token to be collapsed to a single space, except at the start and end of the string, where such spaces are removed.

2.4 Namespaces

The HTML namespace is http://www.w3.org/1999/xhtml.

The XML namespace is http://www.w3.org/XML/1998/namespace.

The XMLNS namespace is http://www.w3.org/2000/xmlns/.

3 Errors

3.1 Exception DOMException

exception DOMException {
  const unsigned short INDEX_SIZE_ERR = 1;
  const unsigned short DOMSTRING_SIZE_ERR = 2; // historical
  const unsigned short HIERARCHY_REQUEST_ERR = 3;
  const unsigned short WRONG_DOCUMENT_ERR = 4;
  const unsigned short INVALID_CHARACTER_ERR = 5;
  const unsigned short NO_DATA_ALLOWED_ERR = 6; // historical
  const unsigned short NO_MODIFICATION_ALLOWED_ERR = 7;
  const unsigned short NOT_FOUND_ERR = 8;
  const unsigned short NOT_SUPPORTED_ERR = 9;
  const unsigned short INUSE_ATTRIBUTE_ERR = 10; // historical
  const unsigned short INVALID_STATE_ERR = 11;
  const unsigned short SYNTAX_ERR = 12;
  const unsigned short INVALID_MODIFICATION_ERR = 13;
  const unsigned short NAMESPACE_ERR = 14;
  const unsigned short INVALID_ACCESS_ERR = 15;
  const unsigned short VALIDATION_ERR = 16; // historical
  const unsigned short TYPE_MISMATCH_ERR = 17;
  const unsigned short SECURITY_ERR = 18;
  const unsigned short NETWORK_ERR = 19;
  const unsigned short ABORT_ERR = 20;
  const unsigned short URL_MISMATCH_ERR = 21;
  const unsigned short QUOTA_EXCEEDED_ERR = 22;
  const unsigned short TIMEOUT_ERR = 23;
  const unsigned short INVALID_NODE_TYPE_ERR = 24;
  const unsigned short DATA_CLONE_ERR = 25;
  unsigned short code;
};

The code exception field must return the value it was initialized to. When an exception is created it must be initialized to zero.

To throw a type exception these steps must be run:

  1. Create a new DOMException exception whose type is type.

  2. Set its message to a user agent-defined value.

  3. If its type is in the first column of the error types table and has a corresponding legacy code exception field value in the third column, set its code exception field to that value.

  4. Throw the exception.

To throw a "TimeoutError" exception, a user agent would construct a DOMException exception whose type is "TimeoutError" and code exception field value is 23, and actually throw that object as an exception. In JavaScript, this exception will have a name property whose value is "TimeoutError".

3.2 Interface DOMError

This interface is intended for other specifications that want to introduce error handling through other means than exceptions. As with exceptions, the error types table is used.

interface DOMError {
  readonly attribute DOMString name;
};

The name attribute must return the value it was initialized to.

A type DOMError means a DOMError object whose name attribute is initialized to type.

A specification could say that an error attribute must return a "SyntaxError" DOMError.

3.3 Error types

The error types table below lists all the allowed error types, a description, and legacy code exception field values (when the error type is used for throwing an exception).

If your specification requires an error type not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks!

Type | Description | Legacy code exception field value (if any)
"IndexSizeError" | The index is not in the allowed range. | INDEX_SIZE_ERR (1)
"HierarchyRequestError" | The operation would yield an incorrect node tree. | HIERARCHY_REQUEST_ERR (3)
"WrongDocumentError" | The object is in the wrong document. | WRONG_DOCUMENT_ERR (4)
"InvalidCharacterError" | The string contains invalid characters. | INVALID_CHARACTER_ERR (5)
"NoModificationAllowedError" | The object can not be modified. | NO_MODIFICATION_ALLOWED_ERR (7)
"NotFoundError" | The object can not be found here. | NOT_FOUND_ERR (8)
"NotSupportedError" | The operation is not supported. | NOT_SUPPORTED_ERR (9)
"InvalidStateError" | The object is in an invalid state. | INVALID_STATE_ERR (11)
"SyntaxError" | The string did not match the expected pattern. | SYNTAX_ERR (12)
"InvalidModificationError" | The object can not be modified in this way. | INVALID_MODIFICATION_ERR (13)
"NamespaceError" | The operation is not allowed by Namespaces in XML. [XMLNS] | NAMESPACE_ERR (14)
"InvalidAccessError" | The object does not support the operation or argument. | INVALID_ACCESS_ERR (15)
"TypeMismatchError" | The type of the object does not match the expected type. | TYPE_MISMATCH_ERR (17)
"SecurityError" | The operation is insecure. | SECURITY_ERR (18)
"NetworkError" | A network error occurred. | NETWORK_ERR (19)
"AbortError" | The operation was aborted. | ABORT_ERR (20)
"URLMismatchError" | The given URL does not match another URL. | URL_MISMATCH_ERR (21)
"QuotaExceededError" | The quota has been exceeded. | QUOTA_EXCEEDED_ERR (22)
"TimeoutError" | The operation timed out. | TIMEOUT_ERR (23)
"InvalidNodeTypeError" | The supplied node is incorrect or has an incorrect ancestor for this operation. | INVALID_NODE_TYPE_ERR (24)
"DataCloneError" | The object can not be cloned. | DATA_CLONE_ERR (25)

4 Events

4.1 Introduction to "DOM Events"

Throughout the web platform events are dispatched to objects to signal an occurrence, such as network activity or user interaction. These objects implement the EventTarget interface and can therefore add event listeners to observe events:

obj.addEventListener("load", imgFetched)

function imgFetched(ev) {
  // great success
  …
}

Event listeners can be removed by utilizing the removeEventListener() method, passing the same arguments.

Events are objects too and implement the Event interface (or a derived interface). In the example above ev is the event. It is passed as argument to event listener's callback (typically a JavaScript Function as shown above). Event listeners key off the event's type attribute value ("load" in the above example). The event's target attribute value returns the object to which the event was dispatched (obj above).

Now while typically events are dispatched by the user agent as the result of user interaction or the completion of some task, applications can dispatch events themselves, commonly known as synthetic events:

// add an appropriate event listener
obj.addEventListener("cat", function(e) { process(e.detail) })

// create and dispatch the event
var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}})
obj.dispatchEvent(event)

Apart from signaling, events are sometimes also used to let an application control what happens next in an operation. For instance as part of form submission an event whose type attribute value is "submit" is dispatched. If this event's preventDefault() method is invoked, form submission will be terminated. Applications who wish to make use of this functionality through events dispatched by the application (synthetic events) can make use of the return value of the dispatchEvent() method:

if(obj.dispatchEvent(event)) {
  // event was not canceled, time for some magic
  …
}

When an event is dispatched to an object that participates in a tree (e.g. an element), it can reach event listeners on that object's ancestors too. First all object's ancestor event listeners whose capture variable is set to true are invoked, in tree order. Second, object's own event listeners are invoked. And finally, and only if event's bubbles attribute value is true, object's ancestor event listeners are invoked again, but now in reverse tree order.

Lets look at an example on how events work in a tree:

<!doctype html>
<html>
 <head>
  <title>Boring example</title>
 </head>
 <body>
  <p>Hello <span id=x>world</span>!</p>
  <script>
   function test(e) {
     debug(e.target, e.currentTarget, e.eventPhase)
   }
   document.addEventListener("hey", test, true)
   document.body.addEventListener("hey", test)
   var ev = new Event("hey", {bubbles:true})
   document.getElementById("x").dispatchEvent(ev)
  </script>
 </body>
</html>

The debug function will be invoked twice. Each time the events's target attribute value will be the span element. The first time currentTarget attribute's value will be the document, the second time the body element. eventPhase attribute's value switches from CAPTURING_PHASE to BUBBLING_PHASE. If an event listener was registered for the span element, eventPhase attribute's value would have been AT_TARGET.

4.2 Interface Event

[Constructor(DOMString type, optional EventInit eventInitDict)]
interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? currentTarget;

  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  void stopPropagation();
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;

  readonly attribute boolean isTrusted;
  readonly attribute DOMTimeStamp timeStamp;

  void initEvent(DOMString type, boolean bubbles, boolean cancelable);
};

dictionary EventInit {
  boolean bubbles;
  boolean cancelable;
};

An event allows for signaling that something has occurred. E.g. that an image has completed downloading. It is represented by the Event interface or an interface that inherits from the Event interface.

var event = new Event(type [, eventInitDict])

Returns a new event whose type attribute value is set to type. The optional eventInitDict argument allows for setting the bubbles and cancelable attributes via object members of the same name.

event . type

Returns the type of event, e.g. "click", "hashchange", or "submit".

event . target

Returns the object event is dispatched to.

event . currentTarget

Returns the object whose event listener's callback is invoked.

event . eventPhase

Returns the event's phase, which is one of CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.

event . stopPropagation()

When dispatched in a tree, invoking this method prevents event from reaching any other objects than the current.

event . stopImmediatePropagation()

Invoking this method prevents event from reaching any event listeners registered after the current one and when dispatched in a tree also prevents event from reaching any other objects.

event . bubbles

Returns true if event's goes through its target attribute value's ancestors in reverse tree order, or false otherwise.

event . cancelable

Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.

event . preventDefault()

If invoked when the cancelable attribute value is true, signals to the operation that caused event to be dispatched that it needs to be canceled.

event . defaultPrevented

Returns true if preventDefault() was invoked while the cancelable attribute value is true, or false otherwise.

event . isTrusted

Returns true if event was dispatched by the user agent, or false otherwise.

event . timeStamp

Returns the creation time of event in the number of milliseconds that passed since 00:00:00 UTC on 1 January 1970.

The type attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the empty string.

The target and currentTarget attributes must return the values they were initialized to. When an event is created the attributes must be initialized to null.

The eventPhase attribute must return the value it was initialized to, which must be one of the following:

CAPTURING_PHASE (numeric value 1)

When an event is dispatched to an object that participates in a tree it will be in this phase before it reaches its target attribute value.

AT_TARGET (numeric value 2)

When an event is dispatched it will be in this phase on its target attribute value.

BUBBLING_PHASE (numeric value 3)

When an event is dispatched to an object that participates in a tree it will be in this phase after it reaches its target attribute value.

Initially the attribute must be initialized to AT_TARGET.

Each event has the following associated flags that are all initially unset:

  • stop propagation flag
  • stop immediate propagation flag
  • canceled flag
  • initialized flag
  • dispatch flag

When the stopPropagation() method is invoked the stop propagation flag must be set.

When the stopImmediatePropagation() method is invoked both the stop propagation flag and stop immediate propagation flag must be set.

The bubbles and cancelable attributes must return the values they were initialized to. When an event is created the attributes must be initialized to false.

When the preventDefault() method is invoked and the cancelable attribute is true, the canceled flag must be set.

The defaultPrevented attribute must return true if the canceled flag is set and false otherwise.

The isTrusted attribute must return the value it was initialized to. When an event is created the attribute must be initialized to false.

The timeStamp attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the number of milliseconds that has passed since 00:00:00 UTC on 1 January 1970.

When the initEvent(type, bubbles, cancelable) method is invoked these steps must be run:

  1. Set the initialized flag.

  2. If the dispatch flag is set, terminate these steps.

  3. Unset the stop propagation flag, stop immediate propagation flag, and canceled flag.

  4. Set the isTrusted attribute to false.

  5. Set the target attribute to null.

  6. Set the type attribute to the type argument.

  7. Set the bubbles attribute to the bubbles argument.

  8. Set the cancelable attribute to the cancelable argument.

As events have constructors initEvent() is superfluous. However, it has to be supported for legacy content.

4.3 Interface CustomEvent

[Constructor(DOMString type, optional CustomEventInit eventInitDict)]
interface CustomEvent : Event {
  readonly attribute any detail;
};

dictionary CustomEventInit : EventInit {
  any detail;
};

Events using the CustomEvent interface can be used to carry custom data.

var event = new CustomEvent(type [, eventInitDict])

Works analogously to the constructor for Event except that the optional eventInitDict argument now allows for setting the detail attribute too.

event . detail

Returns any custom data event was created with. Typically used for synthetic events.

The detail attribute must return the value it was initialized to. When an event is created the attribute must be initialized to null.

4.4 Constructing events

When a constructor of the Event interface, or of an interface that inherits from the Event interface, is invoked, these steps must be run:

  1. Create an event that uses the interface the constructor was invoked upon.

  2. Set its initialized flag.

  3. Initialize the type attribute to the type argument.

  4. If there is an eventInitDict argument then for each dictionary member defined therein find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the value of that dictionary member.

  5. Return the event.

4.5 Interface EventTarget

interface EventTarget {
  void addEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
  void removeEventListener(DOMString type, EventListener? callback, optional boolean capture = false);
  boolean dispatchEvent(Event event);
};

callback interface EventListener {
  void handleEvent(Event event);
};

EventTarget is an object to which an event is dispatched when something has occurred. Each EventTarget has an associated list of event listeners.

An event listener is a handler for a specific event. Each event listener consists of a type (of the event), callback, and capture variable.

target . addEventListener(type, callback [, capture = false])

Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched. When set to true, the capture argument ensures callback is only invoked when the event's eventPhase attribute value is CAPTURING_PHASE.

The event listener is appended to target's list of event listeners and is not appended if it is a duplicate (the event listeners in the list are unique).

target . removeEventListener(type, callback [, capture = false])

Remove the event listener in target's list of event listeners with the same type, callback, and capture.

target . dispatchEvent(event)

Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or it's preventDefault() method was not invoked, or false otherwise.

When the addEventListener(type, callback, capture) method is invoked these steps must be run:

  1. If callback is null terminate these steps.

  2. Append an event listener to the associated list of event listeners with type set to type, callback set to callback, and capture set to capture, unless there already is an event listener in that list with the same type, callback, and capture.

When the removeEventListener(type, callback, capture) method is invoked these steps must be run:

  1. Remove an event listener from the associated list of event listeners, whose type is name, callback is callback, and capture is capture.

When the dispatchEvent(event) method is invoked these steps must be run:

  1. If event's dispatch flag is set, or if its initialized flag is not set, throw an "InvalidStateError" exception and terminate these steps.

  2. Initialize event's isTrusted attribute to false.

  3. Dispatch the event and return the value that returns.

4.6 Dispatching events

To dispatch an event to a given object run these steps:

  1. Let event be the event that is dispatched.

  2. Set event's dispatch flag.

  3. Initialize event's target attribute to the object to which event is dispatched.

  4. If event's target attribute value is participating in a tree, let event path be a static ordered list of all its ancestors in tree order, or let event path be the empty list otherwise.

  5. Initialize event's eventPhase attribute to CAPTURING_PHASE.

  6. For each object in the event path invoke its event listeners with event event, as long as event's stop propagation flag is unset.

  7. Initialize event's eventPhase attribute to AT_TARGET.

  8. Invoke the event listeners of event's target attribute value with event, if event's stop propagation flag is unset.

  9. If event's bubbles attribute value is true, run these substeps:

    1. Reverse the order of event path.

    2. Initialize event's eventPhase attribute to BUBBLING_PHASE.

    3. For each object in the event path invoke its event listeners, with event event as long as event's stop propagation flag is unset.

  10. Unset event's dispatch flag.

  11. Initialize event's eventPhase attribute to AT_TARGET.

  12. Initialize event's currentTarget attribute to null.

  13. Return false if event's canceled flag is set, or true otherwise.

To invoke the event listeners for an object with an event run these steps:

  1. Let event be the event for which the event listeners are invoked.

  2. Let listeners be a static list of the event listeners associated with the object for which these steps are run.

  3. Initialize event's currentTarget attribute to the object for which these steps are run.

  4. Then run these substeps for each event listener in listeners:

    1. If event's stop immediate propagation flag is set, terminate the invoke algorithm.

    2. Let listener be the event listener.

    3. If event's type attribute value is not listener's type, terminate these substeps (and run them for the next event listener).

    4. If event's eventPhase attribute value is CAPTURING_PHASE and listener's capture is false, terminate these substeps (and run them for the next event listener).

    5. If event's eventPhase attribute value is BUBBLING_PHASE and listener's capture is true, terminate these substeps (and run them for the next event listener).

    6. If listener's callback is a Function object, its callback this value is the event's currentTarget attribute value.

    7. Call listener's callback, with the event passed to this algorithm as the first argument.

4.7 Firing events

To fire an event named e means that an event using the Event interface, with its type attribute initialized to e, and its isTrusted attribute initialized to true, is to be dispatched to the given object.

Fire is short for initializing and dispatching an event.

Fire an event is a concept to make initializing and dispatching an event easier to write down. If the event needs its bubbles or cancelable attribute initialized, one could write "fire an event named submit with its cancelable attribute initialized to true".

5 Nodes

5.1 Introduction to "The DOM"

The API to access and manipulate markup-based resources, such as HTML and XML, on the web platform is the tree of nodes, commonly referred to as "The DOM". And although typically a document ends up being the root of such a tree, it is a "document" only in the broadest sense.

To illustrate, lets see how this HTML gets represented:

<!DOCTYPE html>
<html class=e>
 <head><title>Aliens?</title></head>
 <body>Why yes.</body>
</html>
  • DOCTYPE: html
  • HTML class="e"
    • HEAD
      • TITLE
        • #text: Aliens?
    • #text:
    • BODY
      • #text: Why yes.

The root document is omitted for brevity and thanks to the magic that is HTML parsing not all space characters were turned into Text nodes, but the general concept is clear. Markup goes in, a tree of nodes comes out.

If you are interested in exploring this further, take a look at the most excellent Live DOM Viewer.

How much should be explained here? Ideas?

5.2 Node tree

Objects implementing the Document, DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, or Comment interface (simply called nodes) participate in a tree.

A tree of nodes is constrained as follows, expressed as a relationship between the type of node and its allowed children:

Document

In tree order:

  1. Zero or more nodes each of which is either ProcessingInstruction or Comment.

  2. Optionally one DocumentType node.

  3. Zero or more nodes each of which is either ProcessingInstruction or Comment.

  4. Optionally one Element node.

  5. Zero or more nodes each of which is either ProcessingInstruction or Comment.

DocumentFragment
Element

Zero or more nodes each of which is one of Element, ProcessingInstruction, Comment, or Text.

DocumentType
Text
ProcessingInstruction
Comment

None.

5.2.1 Mutation algorithms

To pre-insert a node into a parent before a child, run these steps:

  1. If parent is not a Document, DocumentFragment, or Element node, throw a "HierarchyRequestError" and terminate these steps.

  2. If node is an inclusive ancestor of parent, throw a "HierarchyRequestError" and terminate these steps.

  3. If child is not null and its parent is not parent, throw a "NotFoundError" exception and terminate these steps.

  4. If parent is a document, run these substeps:

    1. If node is not a DocumentFragment, DocumentType, Element, ProcessingInstruction, or Comment node, throw a "HierarchyRequestError" and terminate these steps.

    2. If node is a DocumentFragment node, run these inner substeps:

      1. If node has more than one element child or has a Text node child, throw a "HierarchyRequestError" and terminate these steps.

      2. If node has one element child and either parent has an element child or child is not null and a doctype is following child, throw a "HierarchyRequestError" and terminate these steps.

    3. If node is an element and either parent has an element child or child is not null and a doctype is following child, throw a "HierarchyRequestError" and terminate these steps.

    4. If node is a doctype and either parent has a doctype child, an element is preceding child, or child is null and parent has an element child, throw a "HierarchyRequestError" and terminate these steps.

  5. Otherwise if parent is a DocumentFragment or Element node and node is not a DocumentFragment, Element, Text, ProcessingInstruction, or Comment node, throw a "HierarchyRequestError" and terminate these steps.

  6. Adopt node with parent's node document.

  7. Insert node into parent before child.

  8. Return node.

To insert a node into a parent before a child, optionally with a suppress observers flag, run these steps:

  1. Let count be the number of children of node if it is a DocumentFragment node, or one otherwise.

  2. For each range whose start node is parent and start offset is greater than child's index, increase its start offset by count.

  3. For each range whose end node is parent and end offset is greater than child's index, increase its end offset by count.

  4. Let nodes be node's children if node is a DocumentFragment node, or a list containing solely node otherwise.

  5. If node is a DocumentFragment node, queue a "childList" record with target node, addedNodes null, removedNodes nodes, nextSibling null, and previousSibling null.

    This step does intentionally not pay attention to the suppress observers flag.

  6. If node is a DocumentFragment node, remove its children with the suppress observers flag set.

  7. If suppress observers flag is unset, queue a "childList" record with target parent, addedNodes nodes, removedNodes null, nextSibling child, and previousSibling child's previous sibling or parent's last child if child is null.

  8. Insert all nodes in nodes before child or at the end of parent if child is null.

To append a node to a parent, pre-insert node into parent before null.

To replace a child with node within a parent, run these steps:

  1. If child's parent is not parent, throw a "NotFoundError" exception and terminate these steps.

  2. If node is an inclusive ancestor of parent, throw a "HierarchyRequestError" and terminate these steps.

  3. If parent is not a Document, DocumentFragment, or Element node, throw a "HierarchyRequestError" and terminate these steps.

  4. If parent is a document, run these substeps:

    1. If node is not a DocumentFragment, DocumentType, Element, ProcessingInstruction, or Comment node, throw a "HierarchyRequestError" and terminate these steps.

    2. If node is a DocumentFragment node, run these inner substeps:

      1. If node has more than one element child or has a Text node child, throw a "HierarchyRequestError" and terminate these steps.

      2. If node has one element child and either parent has an element child that is not child or a doctype is following child, throw a "HierarchyRequestError" and terminate these steps.

    3. If node is an element and either parent has an element child that is not child or a doctype is following child, throw a "HierarchyRequestError" and terminate these steps.

    4. If node is a doctype and either parent has a doctype child that is not child, or an element is preceding child, throw a "HierarchyRequestError" and terminate these steps.

  5. Otherwise if parent is a DocumentFragment or Element node and node is not a DocumentFragment, Element, Text, ProcessingInstruction, or Comment node, throw a "HierarchyRequestError" and terminate these steps.

  6. Let reference child be child's next sibling.

  7. Adopt node with parent's node document.

  8. Remove child from its parent with the suppress observers flag set.

  9. Insert node into parent before reference child with the suppress observers flag set.

  10. Let nodes be node's children if node is a DocumentFragment node, or a list containing solely node otherwise.

  11. queue a "childList" record with target parent, addedNodes nodes, removedNodes a list solely containing child, nextSibling reference child, and previousSibling child's previous sibling.

  12. Return child.

To replace all with a node within a parent, run these steps:

  1. Adopt node with parent's node document.

  2. Remove all parent's children, with the suppress observers flag set.

  3. If node is not null, insert node into parent before null with the suppress observers flag set.

  4. Let nodes be null if node is null, node's children if node is a DocumentFragment node, or a list containing node otherwise.

  5. queue a "childList" record with target parent, addedNodes nodes, removedNodes parent's children, nextSibling null, and previousSibling null.

This algorithm does not make any checks with regards to the node tree. Use it wisely.

To pre-remove a child from a parent, run these steps:

  1. If child's parent is not parent, throw a "NotFoundError" exception and terminate these steps.

  2. Remove child from parent.

  3. Return child.

To remove a node from a parent, optionally with suppress observers flag set, run these steps:

  1. Let index be node's index.

  2. For each range whose start node is a descendant of node, set its start to (parent, index).

  3. For each range whose end node is a descendant of node, set its end to (parent, index).

  4. For each range whose start node is parent and start offset is greater than index, decrease its start offset by one.

  5. For each range whose end node is parent and end offset is greater than index, decrease its end offset by one.

  6. If suppress observers flag is unset, queue a "childList" record with target parent, addedNodes null, removedNodes a list solely containing node, nextSibling node's next sibling, and previousSibling node's previous sibling.

  7. For each ancestor ancestor of node, if ancestor has any registered observers whose options's subtree is true, then for each such registered observer, append a transient registered observer whose observer and options are identical to the registered observer to node's list of registered observers.

  8. Remove node from its parent.

5.2.2 Mutation methods

The mutation method macro:

  1. Let node be null.

  2. Replace each string in nodes with a Text node whose data is the string value.

  3. If nodes contains more than one node, set node to a new DocumentFragment and append each node in nodes to it. If this throws an exception, re-throw the exception and terminate these steps.

    Otherwise, set node to the single node nodes contains.

The prepend(nodes) method must run these steps:

  1. Run the mutation method macro.

  2. Pre-insert node into the context object before the context object's first child.

The append(nodes) method must run these steps:

  1. Run the mutation method macro.

  2. Append node to the context object.

The before(nodes) method must run these steps:

  1. If the context object does not have a parent, terminate these steps.

  2. Run the mutation method macro.

  3. Pre-insert node into the context object's parent before the context object.

The after(nodes) method must run these steps:

  1. If the context object does not have a parent, terminate these steps.

  2. Run the mutation method macro.

  3. Pre-insert node into the context object's parent before the context object's next sibling.

The replace(nodes) method must run these steps:

  1. If the context object does not have a parent, terminate these steps.

  2. Run the mutation method macro.

  3. Replace the context object with node within the context object's parent.

The remove() method must run these steps:

  1. If the context object does not have a parent, terminate these steps.

  2. Remove the context object from the context object's parent.

5.2.3 Legacy mutation methods

The insertBefore(node, child) method must return the result of pre-inserting node into the context object before child.

The appendChild(node) method must return the result of appending node to the context object.

The replaceChild(node, child) method must return the result of replacing child with node within the context object.

The removeChild(child) method must return the result of pre-removing child from the context object.

5.2.4 Mutation observers

Each scripting environment has an associated list of MutationObserver objects which is initially empty. To invoke MutationObserver objects, run these steps:

  1. Let notify list be a copy of scripting environment's list of MutationObserver objects whose record queue is non-empty.

  2. For each MutationObserver object mo in notify list, run these substeps:

    1. Let queue be a copy of mo's record queue.

    2. Empty mo's record queue.

    3. Remove all transient registered observers whose observer is mo.

    4. Invoke mo's callback with queue as first argument, and mo (itself) as second argument and callback this value.

  3. If any MutationObserver object in scripting environment's list of MutationObserver objects has a non-empty record queue at this point, run these steps again (indeed, all of them).

The DOM standard does not define the scripting environment nor its scope. The HTML standard defines how this concept integrates with the rest of the platform as well as when invoke is invoked. This somewhat artificial boundary is made to prevent a dependency from DOM on HTML. [HTML]

Each node has an associated list of registered observers.

A registered observer consists of an observer (a MutationObserver object) and options (a MutationObserverInit dictionary). A transient registered observer is a specific type of registered observer.

[Constructor(MutationCallback callback)]
interface MutationObserver {
  void observe(Node target, MutationObserverInit options);
  void disconnect();
};

callback MutationCallback = void (MutationRecord[] mutations, MutationObserver observer);

dictionary MutationObserverInit {
  boolean childList;
  boolean attributes;
  boolean characterData;
  boolean subtree;
  boolean attributeOldValue;
  boolean characterDataOldValue;
  DOMString[] attributeFilter;
};

A MutationObserver object can be used to observe mutations to the tree of nodes.

Each MutationObserver object has these associated concepts:

  • A callback. Set on creation.

  • A list of nodes on which it is a registered observer's observer. Initially empty.

  • A record queue (list of MutationRecord objects). Initially empty.

To queue an "attributes" record with target target, name name, namespace namespace, and oldValue oldValue, run these steps:

  1. Let record be a new MutationRecord object with its type set to "attributes", target set to target, attributeName set to name, and attributeNamespace set to namespace.

  2. Let recordWithOldValue be a copy of record with its oldValue set to oldValue.

  3. For each registered observer observer (with observer's options as options) in target's list of registered observers, run these substeps:

    1. If options's attributes is not true, terminate these substeps (and run them for the next registered observer).

    2. If options's attributeFilter is non-empty, and name is not in it, terminate these substeps (and run them for the registered observer).

    3. If options's attributeOldValue is true, append recordWithOldValue to observer's observer record queue.

    4. Otherwise, append record to observer's observer record queue.

  4. For each ancestor ancestor of target, and for each registered observer observer (with observer's options as options) in ancestor's list of registered observers, run these substeps:

    1. If options's subtree is not true, terminate these substeps (and run them for the next registered observer).

    2. If options's attributes is not true, terminate these substeps (and run them for the next registered observer).

    3. If options's attributeFilter is non-empty, and name is not in it, terminate these substeps (and run them for the next registered observer).

    4. If options's attributeOldValue is true, append recordWithOldValue to observer's observer record queue.

    5. Otherwise, append record to observer's observer record queue.

To queue a "characterData" record with target target and oldValue oldValue, run these steps:

  1. Let record be a new MutationRecord object with its type set to "characterData" and target set to target.

  2. Let recordWithOldValue be a copy of record with its oldValue set to oldValue.

  3. For each registered observer observer (with observer's options as options) in target's list of registered observers, run these substeps:

    1. If options's characterData is not true, terminate these substeps (and run them for the next registered observer).

    2. If options's characterDataOldValue is true, append recordWithOldValue to observer's observer record queue.

    3. Otherwise, append record to observer's observer record queue.

  4. For each ancestor ancestor of target, and for each registered observer observer (with options options) in ancestor's list of registered observers, run these substeps:

    1. If options's subtree is not true, terminate these substeps (and run them for the next registered observer).

    2. If options's characterData is not true, terminate these substeps (and run them for the next registered observer).

    3. If options's characterDataOldValue is true, append recordWithOldValue to observer's observer record queue.

    4. Otherwise, append record to observer's observer record queue.

To queue a "childList" record with target target, addedNodes addedNodes, removedNodes removedNodes, previousSibling previousSibling, and nextSibling nextSibling, run these steps:

  1. Let record be a new MutationRecord object with its type set to "childList", target set to target, addedNodes set to addedNodes, removedNodes set to removedNodes, previousSibling set to previousSibling, and nextSibling set to nextSibling.

  2. For each registered observer observer (with observer's options as options) in target's list of registered observers, run these substeps:

    1. If options's childList is not true, terminate these substeps (and run them for the next registered observer).

    2. Append record to observer's observer record queue.

  3. For each ancestor ancestor of target, and for each registered observer observer (with observer's options as options) in ancestor's list of registered observers, run these substeps:

    1. If options's subtree is not true, terminate these substeps (and run them for the next registered observer).

    2. If options's childList is not true, terminate these substeps (and run them for the next registered observer).

    3. Append record to observer's observer record queue.

var observer = new MutationObserver(callback)

Constructs a MutationObserver object and sets its callback to callback. The callback is invoked with a list of MutationRecord objects as first argument and the constructed MutationObserver object as second argument. It is invoked after nodes registered with the observe() method, are mutated.

observer . observe(target, options)

Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object).

The options argument allows for setting mutation observation options via object members. These are the object members that can be used:

childList

Set to true if mutations to target's children are to be observed.

attributes

Set to true if mutations to target's attributes are to be observed.

characterData

Set to true if mutations to target's data are to be observed.

subtree

Set to true if mutations to not just target, but also target's descendants are to be observed.

attributeOldValue

Set to true if attributes is set to true and target's attribute value before the mutation needs to be recorded.

characterDataOldValue

Set to true if characterData is set to true and target's data before the mutation needs to be recorded.

attributeFilter

Set to a list of attribute names if not all attribute mutations need to be observed.

observer . disconnect()

Stops the observer from observing any mutations. Until the observe() method is used again, observer's callback will not be invoked.

The MutationObserver(callback) constructor must create a new MutationObserver object with callback set to callback, return it, and append it object to the scripting environment's list of MutationObserver objects.

The observe(target, options) method must run these steps:

  1. Run these substeps, with options as the context object:

    1. If neither childList, attributes, nor characterData is true, throw a "SyntaxError" and terminate these steps.

    2. If attributeOldValue is true and attributes is not true, throw a "SyntaxError" and terminate these steps.

    3. If attributeFilter is a non-empty array and attributes is not true, throw a "SyntaxError" and terminate these steps.

    4. If characterDataOldValue is true and characterData is not true, throw a "SyntaxError" and terminate these steps.

  2. If target's list of registered observers already includes a registered observer associated with the context object, replace that registered observer's options with options.

  3. Otherwise, add a new registered observer to target's list of registered observers with the context object as the observer and options as the options, and add target to context object's list of nodes on which it is registered.

The disconnect() method must, for each node node in the context object's list of nodes, remove any registered observer on node for which the context object is the observer, and also empty context object's record queue.

5.2.5 Interface MutationRecord

interface MutationRecord {
  readonly attribute DOMString type;
  readonly attribute Node target;
  readonly attribute NodeList? addedNodes;
  readonly attribute NodeList? removedNodes;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;
  readonly attribute DOMString? attributeName;
  readonly attribute DOMString? attributeNamespace;
  readonly attribute DOMString? oldValue;
};
record . type

Returns "attributes" if it was an attribute mutation. "characterData" if it was a mutation to a CharacterData node. And "childList" if it was a mutation to the tree of nodes.

record . target

Returns the node the mutation affected, depending on the type. For "attributes", it is the element whose attribute changed. For "characterData", it is the CharacterData node. For "childList", it is the node whose children changed.

record . addedNodes
record . removedNodes

Return the nodes added and removed respectively, or null otherwise.

record . previousSibling
record . nextSibling

Return the previous and next sibling respectively of the added and/or removed nodes, or null otherwise.

record . attributeName

Returns the name of the changed attribute, or null otherwise.

record . attributeNamespace

Returns the namespace of the changed attribute, or null otherwise.

record . oldValue

The return value depends on type. For "attributes", it is the value of the changed attribute before the change. For "characterData", it is the data of the changed node before the change. For "childList", it is null.

The type and target attributes must return the values they were initialized to.

The addedNodes, removedNodes, previousSibling, nextSibling, attributeName, attributeNamespace, and oldValue attributes must return the values they were initialized to. Unless stated otherwise, when a MutationRecord object is created, they must be initialized to null.

5.3 Interface Node

interface Node : EventTarget {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2; // historical
  const unsigned short TEXT_NODE = 3;
  const unsigned short CDATA_SECTION_NODE = 4; // historical
  const unsigned short ENTITY_REFERENCE_NODE = 5; // historical
  const unsigned short ENTITY_NODE = 6; // historical
  const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short COMMENT_NODE = 8;
  const unsigned short DOCUMENT_NODE = 9;
  const unsigned short DOCUMENT_TYPE_NODE = 10;
  const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short NOTATION_NODE = 12; // historical
  readonly attribute unsigned short nodeType;
  readonly attribute DOMString nodeName;

  readonly attribute DOMString? baseURI;

  readonly attribute Document? ownerDocument;
  readonly attribute Node? parentNode;
  readonly attribute Element? parentElement;
  boolean hasChildNodes();
  readonly attribute NodeList childNodes;
  readonly attribute Node? firstChild;
  readonly attribute Node? lastChild;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;

  const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
  const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
  const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
  const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20; // historical
  unsigned short compareDocumentPosition(Node other);
  boolean contains(Node? other);

           attribute DOMString? nodeValue;
           attribute DOMString? textContent;
  Node insertBefore(Node node, Node? child);
  Node appendChild(Node node);
  Node replaceChild(Node node, Node child);
  Node removeChild(Node child);
  void normalize();

  Node cloneNode(optional boolean deep = true);
  boolean isEqualNode(Node? node);

  DOMString lookupPrefix(DOMString? namespace);
  DOMString lookupNamespaceURI(DOMString? prefix);
  boolean isDefaultNamespace(DOMString? namespace);
};

Node is an abstract interface and does not exist as node. It is used by all nodes (Document, DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, and Comment).

Each node has an associated node document, set upon creation, that is a document.

A node's node document can be changed by the "adopt" algorithm.

Each node also has an associated base URL.

Other specifications define the value of the base URL and its observable behavior. This specification solely defines the concept and the baseURI attribute.

node . nodeType

Returns the type of node, represented by a number from the following list:

Node . ELEMENT_NODE (1)
node is an element.
Node . TEXT_NODE (3)
node is a Text node.
Node . PROCESSING_INSTRUCTION_NODE (7)
node is a ProcessingInstruction node.
Node . COMMENT_NODE (8)
node is a Comment node.
Node . DOCUMENT_NODE (9)
node is a document.
Node . DOCUMENT_TYPE_NODE (10)
node is a doctype.
Node . DOCUMENT_FRAGMENT_NODE (11)
node is a DocumentFragment node.
node . nodeName

Returns a string appropriate for the type of node, as follows:

Element
Its tagName attribute value.
Text
"#text".
ProcessingInstruction
Its target.
Comment
"#comment".
Document
"#document".
DocumentType
Its name.
DocumentFragment
"#document-fragment".

The nodeType attribute must return the type of the node, which must be one of the following:

  • ELEMENT_NODE (1);
  • TEXT_NODE (3);
  • PROCESSING_INSTRUCTION_NODE (7);
  • COMMENT_NODE (8);
  • DOCUMENT_NODE (9);
  • DOCUMENT_TYPE_NODE (10);
  • DOCUMENT_FRAGMENT_NODE (11).

The nodeName attribute must return the following, depending on the context object:

Element

Its tagName attribute value.

Text

"#text".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

node . baseURI

Returns the base URL.

The baseURI attribute must return the associated base URL.

node . ownerDocument

Returns the node document.

Returns null for documents.

node . parentNode

Returns the parent.

node . parentElement

Returns the parent element.

node . hasChildNodes

Returns whether node has children.

node . childNodes

Returns the children.

node . firstChild

Returns the first child.

node . lastChild

Returns the last child.

node . previousSibling

Returns the previous sibling.

node . nextSibling

Returns the next sibling.

The ownerDocument attribute must run these steps:

  1. If the context object is a document, return null and terminate these steps.
  2. Return the node document.

The node document of a document is that document itself.

All nodes have a document at all times.

The parentNode attribute must return the parent.

The parentElement attribute must return the parent element.

The hasChildNodes() method must return true if the context object has children, or false otherwise.

The childNodes attribute must return a NodeList rooted at the context object matching only children.

The firstChild attribute must return the first child.

The lastChild attribute must return the last child.

The previousSibling attribute must return the previous sibling.

The nextSibling attribute must return the next sibling.

node . compareDocumentPosition(other)

Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:

Node . DOCUMENT_POSITION_DISCONNECTED (1)
Set when node and other are not in the same document.
Node . DOCUMENT_POSITION_PRECEDING (2)
Set when other is preceding node.
Node . DOCUMENT_POSITION_FOLLOWING (4)
Set when other is following node.
Node . DOCUMENT_POSITION_CONTAINS (8)
Set when other is an ancestor of node.
Node . DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)
Set when other is a descendant of node.
node . contains(other)

Returns true if other is an inclusive descendant of node, or false otherwise.

These are the constants compareDocumentPosition() returns as mask:

  • DOCUMENT_POSITION_DISCONNECTED (1);
  • DOCUMENT_POSITION_PRECEDING (2);
  • DOCUMENT_POSITION_FOLLOWING (4);
  • DOCUMENT_POSITION_CONTAINS (8);
  • DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal).

The compareDocumentPosition(other) method must run these steps:

  1. Let reference be the context object.

  2. If other and reference are the same object, return zero and terminate these steps.

  3. If other and reference are not in the same tree, return DOCUMENT_POSITION_DISCONNECTED and terminate these steps.

  4. If other is an ancestor of reference, return the result of adding DOCUMENT_POSITION_CONTAINS to DOCUMENT_POSITION_PRECEDING and terminate these steps.

  5. If other is a descendant of reference, return the result of adding DOCUMENT_POSITION_CONTAINED_BY to DOCUMENT_POSITION_FOLLOWING and terminate these steps.

  6. If other is preceding reference return DOCUMENT_POSITION_PRECEDING and terminate these steps.

  7. Return DOCUMENT_POSITION_FOLLOWING.

The contains(other) method must return true if other is an inclusive descendant of the context object, or false otherwise.

The nodeValue attribute must return the following, depending on the context object:

Text
Comment
ProcessingInstruction

The context object's data.

Any other node

Null.

Setting the nodeValue attribute must do as described below, depending on the context object:

Text
Comment
ProcessingInstruction

Replace data with node context object, offset 0, count length attribute value, and data new value.

Any other node

Do nothing.

The textContent attribute must return the following, depending on the context object:

DocumentFragment
Element

The concatenation of data of all the Text node descendants of the context object, in tree order.

Text
ProcessingInstruction
Comment

The context object's data.

Any other node

Null.

The textContent attribute must, on setting, if the new value is null, act as if it was the empty string instead, and then do as described below, depending on the context object:

DocumentFragment
Element

  1. Let node be null.

  2. If new value is not the empty string, set node to a new Text node whose data is new value.

  3. Replace all with node within the context object.

Text
ProcessingInstruction
Comment

Replace data with node context object, offset 0, count length attribute value, and data new value.

Any other node

Do nothing.

node . normalize()

Concatenates contiguous Text nodes into a single Text node.

The normalize() method must run these steps:

For each Text node descendant of the context object:

  1. Let node be the Text node descendant.

  2. Let length be node's length attribute value.

  3. Let data be the concatenation of the data of node's contiguous Text nodes (excluding itself), in tree order.

  4. Replace data with node node, offset length, count 0, and data data.

  5. Let current node be node's next sibling.

  6. While current node is a Text node:

    1. For each range whose start node is current node, add length to its start offset and set its start node to node.

    2. For each range whose end node is current node, add length to its end offset and set its end node to node.

    3. Add current node's length attribute value to length.

    4. Set current node to its next sibling.

  7. Remove node's contiguous Text nodes (excluding itself), in tree order.

node . cloneNode([deep])

Returns a copy of node. If deep is true or omitted, the copy also includes the node children.

node . isEqualNode(other)

Returns whether node and other have the same properties.

Specifications may define cloning steps for all or some nodes.

To clone a node, optionally with a document ownerDocument and a clone children flag, run these steps:

  1. If document is not given let ownerDocument be node's node document.

  2. Let copy be a node that implements the same interfaces as node.

  3. If copy is a document set its node document and ownerDocument to copy.

    Otherwise, set copy's node document to ownerDocument.

  4. Copy the following, depending on the type of node:

    Element

    Its namespace, namespace prefix, local name, and its attribute list.

    DocumentType

    Its name, public ID, and system ID.

    ProcessingInstruction

    Its target and data.

    Text
    Comment

    Its data.

    Any other node

    —

  5. Run any cloning steps defined for node in other applicable specifications.

  6. If the clone children flag is set, clone all the children of node and append them to copy, with ownerDocument as specified and the clone children flag being set.

  7. Return copy.

The cloneNode(deep) method must return a clone of the context object, with the clone children flag set if deep is true.

The isEqualNode(node) method must return true if all of the following conditions are true, and false otherwise:

  • node is not null.

  • node's nodeType attribute value is the same as the context object's nodeType attribute value.

  • The following are also equal, depending on node:

    DocumentType

    Its name, public ID, and system ID.

    Element

    Its namespace, namespace prefix, local name, and its number of attributes in its attribute list.

    ProcessingInstruction

    Its target and data.

    Text
    Comment

    Its data.

    Any other node

    —

  • If node is an Element, each attribute in its attribute list has an attribute with the same namespace, local name, and value in the context object's attribute list.

  • node has the same number of children as the context object.

  • Calling isEqualNode() on each child of the context object, with the child of the same index in node as argument returns true for every child.

To locate a namespace prefix for an element using namespace run these steps:

  1. If element's namespace is namespace and its namespace prefix is not null return its namespace prefix and terminate these steps.

  2. If, element has an attribute whose namespace prefix is "xmlns" and value is namespace, then return that attribute's local name and terminate these steps.

  3. If element's parent element is not null, return the result of running locate a namespace prefix on that element using namespace. Otherwise, return null.

To locate a namespace for a node using prefix depends on the node:

Element

  1. If its namespace is not null and its namespace prefix is prefix return namespace and terminate these steps.

  2. If it has an attribute whose namespace prefix is "xmlns" and local name is prefix, or whose namespace prefix is null and local name is "xmlns":

    1. Let value be its value if it is not the empty string, or null otherwise.

    2. Return value and terminate these steps.

  3. If its parent element is null, return null and terminate these steps.

  4. Return the result of running locate a namespace on its parent element using prefix.

Document

  1. If its document element is null, return null and terminate these steps.

  2. Return the result of running locate a namespace on its document element using prefix.

DocumentType
DocumentFragment

Return null.

Any other node

  1. If its parent element is null, return null and terminate these steps.

  2. Return the result of running locate a namespace on its parent element using prefix.

The lookupPrefix(namespace) method must run these steps:

  1. If namespace is null or the empty string, return null.

  2. Otherwise it depends on the context object:

    Element

    Return the result of locating a namespace prefix for the node using namespace.

    Document

    Return the result of locating a namespace prefix for its document element, if that is not null, or null otherwise.

    DocumentType
    DocumentFragment

    Return null.

    Any other node

    Return the result of locating a namespace prefix for its parent element, or if that is null, null.

The lookupNamespaceURI(prefix) method must run these steps:

  1. If prefix is the empty string, set it to null.

  2. Return the result of running locate a namespace for the context object using prefix.

The isDefaultNamespace(namespace) method must run these steps:

  1. If namespace is the empty string, set it to null.

  2. Let defaultNamespace be the result of running locate a namespace for the context object using null.

  3. Return true if defaultNamespace is the same as namespace, or false otherwise.

The list of elements with local name localName for a node root is the HTMLCollection returned by the following algorithm:

  1. If localName is "*" (U+002A), return a HTMLCollection rooted at root, whose filter matches only elements.

  2. Otherwise, if root's node document is an HTML document, return a HTMLCollection rooted at root, whose filter matches only the following elements:

    • Whose namespace is the HTML namespace and whose local name is localName converted to ASCII lowercase.
    • Whose namespace is not the HTML namespace and whose local name is localName.

  3. Otherwise, return a HTMLCollection rooted at root, whose filter matches only elements whose local name is localName.

When invoked with the same argument, the same HTMLCollection object may be returned as returned by an earlier call.

The list of elements with namespace namespace and local name localName for a node root is the HTMLCollection returned by the following algorithm:

  1. If namespace is the empty string, set it to null.

  2. If both namespace and localName are "*" (U+002A) return a HTMLCollection rooted at root, whose filter matches only elements.

  3. Otherwise, if just namespace is "*" (U+002A), return a HTMLCollection rooted at root, whose filter matches only elements whose local name is localName.

  4. Otherwise, if just localName is "*" (U+002A), return a HTMLCollection rooted at root, whose filter matches only elements whose namespace is namespace.

  5. Otherwise, return a HTMLCollection rooted at root, whose filter matches only elements whose namespace is namespace and local name is localName.

When invoked with the same arguments, the same HTMLCollection object may be returned as returned by an earlier call.

The list of elements with class names classNames for a node root is the HTMLCollection returned by the following algorithm:

  1. Let classes be the set of tokens found by splitting classNames on spaces. (Duplicates are ignored.)

  2. If classes is the empty set, return an empty HTMLCollection and terminate these steps.

  3. Return a HTMLCollection rooted at root, whose filter matches only elements that have all the classes in classes.

    If root's node document is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, or in a case-sensitive manner otherwise.

When invoked with the same argument, the same HTMLCollection object may be returned as returned by an earlier call.

5.4 Interface Document

interface Document : Node {
  readonly attribute DOMImplementation implementation;
  readonly attribute DOMString URL;
  readonly attribute DOMString documentURI;
  readonly attribute DOMString compatMode;
  readonly attribute DOMString characterSet;
  readonly attribute DOMString contentType;

  readonly attribute DocumentType? doctype;
  readonly attribute Element? documentElement;
  HTMLCollection getElementsByTagName(DOMString localName);
  HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  HTMLCollection getElementsByClassName(DOMString classNames);
  Element? getElementById(DOMString elementId);

  Element createElement(DOMString localName);
  Element createElementNS(DOMString? namespace, DOMString qualifiedName);
  DocumentFragment createDocumentFragment();
  Text createTextNode(DOMString data);
  Comment createComment(DOMString data);
  ProcessingInstruction createProcessingInstruction(DOMString target, DOMString data);

  Node importNode(Node node, optional boolean deep = true);
  Node adoptNode(Node node);

  Event createEvent(DOMString eventInterfaceName);

  Range createRange();

  NodeIterator createNodeIterator(Node root, optional unsigned long whatToShow = SHOW_ALL, optional NodeFilter? filter = null);
  TreeWalker createTreeWalker(Node root, optional unsigned long whatToShow = SHOW_ALL, optional NodeFilter? filter = null);

  // NEW
  void prepend((Node or DOMString)... nodes);
  void append((Node or DOMString)... nodes);
};

interface XMLDocument : Document {};

Document nodes are simply known as documents.

Each document has an associated encoding, content type, and URL.

Unless explicitly given when a document is created its encoding is utf-8, its content type is "application/xml", and its URL is "about:blank".

A document is assumed to be an XML document unless it is flagged as being an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.

A document is always set to one of three modes: no-quirks mode, the default; quirks mode, used typically for legacy documents; and limited-quirks mode. Unless other applicable specifications define otherwise, a document must be in no-quirks mode.

The mode is only ever changed from the default if the document is created by the HTML parser, based on the presence, absence, or value of the DOCTYPE string. [HTML]

No-quirks mode was originally known as "standards mode" and limited-quirks mode was once known as "almost standards mode". They have been renamed because their details are now defined by standards. (And because Ian Hickson vetoed their original names on the basis that they are nonsensical.)

document . implementation

Returns the associated DOMImplementation object.

document . URL
document . documentURI

Returns the URL.

document . compatMode

Returns the string "CSS1Compat" if document is in no-quirks mode or limited-quirks mode, and "BackCompat", if document is in quirks mode.

document . characterSet

Returns the encoding.

document . contentType

Returns the content type.

The implementation attribute must return the DOMImplementation object that is associated with the document.

The URL and documentURI attributes must return the URL.

The compatMode attribute must return "BackCompat" if the context object is in quirks mode, or "CSS1Compat" otherwise.

The characterSet attribute must return the preferred MIME name of the encoding.

The contentType attribute must return the content type.

document . doctype

Returns the doctype or null if there is none.

document . documentElement

Returns the document element.

collection = document . getElementsByTagName(localName)

If localName is "*" returns a HTMLCollection of all descendant elements.

Otherwise, returns a HTMLCollection of all descendant elements whose local name is localName. (Matches case-insensitively against elements in the HTML namespace within an HTML document.)

collection = document . getElementsByTagNameNS(namespace, localName)

If namespace and localName are "*" returns a HTMLCollection of all descendant elements.

If only namespace is "*" returns a HTMLCollection of all descendant elements whose local name is localName.

If only localName is "*" returns a HTMLCollection of all descendant elements whose namespace is namespace.

Otherwise, returns a HTMLCollection of all descendant elements whose namespace is namespace and local name is localName.

collection = document . getElementsByClassName(classes)
collection = element . getElementsByClassName(classes)

Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classes.

The classes argument is interpreted as a space-separated list of classes.

element = document . getElementById(elementId)

Returns the first element in document with the given ID.

The doctype attribute must return the child of the document that is a doctype, or null otherwise.

The documentElement attribute must return the document element.

The getElementsByTagName(localName) method must return the list of elements with local name localName for the context object.

Thus, in an HTML document, document.getElementsByTagName("FOO") will match FOO elements that are not in the HTML namespace, and foo elements that are in the HTML namespace, but not FOO elements that are in the HTML namespace.

The getElementsByTagNameNS(namespace, localName) method must return the list of elements with namespace namespace and local name localName for the context object.

The getElementsByClassName(classNames) method must return the list of elements with class names classNames for the context object.

Given the following XHTML fragment:

<div id="example">
  <p id="p1" class="aaa bbb"/>
  <p id="p2" class="aaa ccc"/>
  <p id="p3" class="bbb ccc"/>
</div>

A call to document.getElementById('example').getElementsByClassName('aaa') would return a HTMLCollection with the two paragraphs p1 and p2 in it.

A call to getElementsByClassName('ccc bbb') would only return one node, however, namely p3. A call to document.getElementById('example').getElementsByClassName('bbb  ccc ') would return the same thing.

A call to getElementsByClassName('aaa,bbb') would return no nodes; none of the elements above are in the aaa,bbb class.

The getElementById(elementId) method must return the first element, in tree order, within the context object's tree, whose ID is elementId, or null if there is none.

element = document . createElement(localName)

Returns an element in the HTML namespace with localName as local name. (In an HTML document localName is lowercased.)

If localName does not match the Name production an "InvalidCharacterError" exception will be thrown.

element = document . createElementNS(namespace, qualifiedName)

Returns an element with namespace namespace. Its namespace prefix will be everything before ":" (U+003E) in qualifiedName or null. Its local name will be everything after ":" (U+003E) in qualifiedName or qualifiedName.

If localName does not match the Name production an "InvalidCharacterError" exception will be thrown.

If one of the following conditions is true a "NamespaceError" exception will be thrown:

  • localName does not match the QName production.
  • Namespace prefix is not null and namespace is the empty string.
  • Namespace prefix is "xml" and namespace is not the XML namespace.
  • qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace.
  • namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns".
documentFragment = document . createDocumentFragment()

Returns a DocumentFragment node.

text = document . createTextNode(data)

Returns a Text node whose data is data.

comment = document . createComment(data)

Returns a Comment node whose data is data.

processingInstruction = document . createProcessingInstruction(target, data)

Returns a ProcessingInstruction node whose target is target and data is data.

If target does not match the Name production an "InvalidCharacterError" exception will be thrown.

If data contains "?>" an "InvalidCharacterError" exception will be thrown.

The createElement(localName) method must run the these steps:

  1. If localName does not match the Name production, throw an "InvalidCharacterError" exception and terminate these steps.

  2. If the context object is an HTML document, let localName be converted to ASCII lowercase.

  3. Return a new element with no attributes, namespace set to the HTML namespace, local name set to localName, and node document set to the context object.

The createElementNS(namespace, qualifiedName) method must run these steps:

  1. If namespace is the empty string, set it to null.

  2. If qualifiedName does not match the Name production, throw an "InvalidCharacterError" exception and terminate these steps.

  3. If qualifiedName does not match the QName production, throw a "NamespaceError" exception and terminate these steps.

  4. If qualifiedName contains a ":" (U+003E), then split the string on it and let prefix be the part before and localName the part after. Otherwise, let prefix be null and localName be qualifiedName.

  5. If prefix is not null and namespace is null, throw a "NamespaceError" exception and terminate these steps.

  6. If prefix is "xml" and namespace is not the XML namespace, throw a "NamespaceError" exception and terminate these steps.

  7. If qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, throw a "NamespaceError" exception and terminate these steps.

  8. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", throw a "NamespaceError" exception and terminate these steps.

  9. Return a new element with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, and node document set to the context object.

The createDocumentFragment() method must return a new DocumentFragment node with its node document set to the context object.

The createTextNode(data) method must return a new Text node with its data set to data and node document set to the context object.

No check is performed that data consists of characters that match the Char production.

The createComment(data) method must return a new Comment node with its data set to data and node document set to the context object.

No check is performed that data consists of characters that match the Char production or that it contains two adjacent hyphens or ends with a hyphen.

The createProcessingInstruction(target, data) method must run these steps:

  1. If target does not match the Name production, throw an "InvalidCharacterError" exception and terminate these steps.

  2. If data contains the string "?>", throw an "InvalidCharacterError" exception and terminate these steps.

  3. Return a new ProcessingInstruction node, with target set to target, data set to data, and node document set to the context object.

No check is performed that target contains "xml" or ":", or that data contains characters that match the Char production.

clone = document . importNode(node [, deep])

Returns a copy of node. If deep is true or omitted, the copy also includes the node children.

If node is a document throws a "NotSupportedError" exception.

node = document . adoptNode(node)

Moves node from another document and returns it.

If node is a document throws a "NotSupportedError" exception.

The importNode(node, deep) method must run these steps:

  1. If node is a document, throw a "NotSupportedError" exception and terminate these steps.

  2. Return a clone of node, with document context object and the clone children flag set if deep is true.

To adopt a node, with an ownerDocument, run these steps:

  1. If node is an element, it is affected by a base URL change.

  2. If node's parent is not null, remove node from its parent.

  3. Set node document for node and all its descendants to ownerDocument.

The adoptNode(node) method must run these steps:

  1. If node is a document, throw a "NotSupportedError" exception and terminate these steps.

  2. Adopt node with the context object.

  3. Return node.

POWERED BY HERONOTE
event = document . createEvent(eventInterfaceName)

Returns an event using an interface for which the interface name is a case-insensitive match for eventInterfaceName.

When the createEvent(eventInterfaceName) methed is invoked these steps must be run:

  1. If eventInterfaceName is an ASCII case-insensitive match for any of the strings in the first column in the following table, let eventInterfaceName be the string in the second column on the same row as the matching string:

    Input interface | Replacement interface
    "events" | "event"
    "htmlevents" | "event"
    "mouseevents" | "mouseevent"
    "mutationevents" | "mutationevent"
    "uievents" | "uievent"

  2. If eventInterfaceName is not an ASCII case-insensitive match for "event" or for the name of an interface that inherits from the Event interface and is supported by the user agent, throw a "NotSupportedError" and terminate these steps.

  3. Create an event implementing the interface whose name eventInterfaceName is an ASCII case-insensitive match for and return it.

This method is pretty much obsolete as events have constructors these days, but needs to be supported for legacy content. Tough.

event = document . createRange()

Returns a new range.

The createRange() method must return a new range with (context object, 0) as its start and end.

When the createNodeIterator(root, whatToShow, filter) method is invoked these steps must be run:

  1. Create a NodeIterator object.

  2. Set root and initialize the referenceNode attribute to the root argument.

  3. Set whatToShow to the whatToShow argument.

  4. Set filter to filter.

  5. Return the newly created NodeIterator object.

When the createTreeWalker(root, whatToShow, filter) method is invoked these steps must be run:

  1. Create a TreeWalker object.

  2. Set root and initialize the currentNode attribute to the root argument.

  3. Set whatToShow to the whatToShow argument.

  4. Set filter to filter.

  5. Return the newly created TreeWalker object.

5.4.1 Interface DOMImplementation

User agents must create a DOMImplementation object whenever a document is created and associate it with that document.

interface DOMImplementation {
  DocumentType createDocumentType(DOMString qualifiedName, DOMString publicId, DOMString systemId);
  XMLDocument createDocument(DOMString? namespace, DOMString qualifiedName, DocumentType? doctype);
  Document createHTMLDocument(DOMString title);

  boolean hasFeature(DOMString feature, [TreatNullAs=EmptyString] DOMString version);
};
doctype = document . implementation . createDocumentType( qualifiedName, publicId, systemId )

Returns a doctype, with the given qualifiedName, publicId, and systemId. If qualifiedName does not match the Name production, an "InvalidCharacterError" exception is thrown, and if it does not match the QName production, a "NamespaceError" exception is thrown.

doc = document . implementation . createDocument( namespace, qualifiedName, doctype )

Returns an XMLDocument, with a document element whose local name is qualifiedName and whose namespace is namespace (unless qualifiedName is the empty string), and with doctype, if it is given, as its doctype.

This method throws the same exceptions as the createElementNS method, when invoked with the same arguments.

doc = document . implementation . createHTMLDocument( title )

Returns a document, with a basic tree already constructed including a title element.

The createDocumentType(qualifiedName, publicId, systemId) method must run these steps:

  1. If qualifiedName does not match the Name production, throw an "InvalidCharacterError" exception and terminate these steps.

  2. If qualifiedName does not match the QName production in, throw a "NamespaceError" exception and terminate these steps.

  3. Return a new doctype, with qualifiedName as its name, publicId as its public ID, and systemId as its system ID, and with its node document set to the associated document of the context object.

No check is performed that the publicId matches the PublicChar or that the systemId does not contain both a '"' and "'".

The createDocument(namespace, qualifiedName, doctype) method must run these steps:

  1. Let document be a new XMLDocument.

    This method creates an XMLDocument rather than a normal document. They are identical except for the addition of the load() method deployed content relies upon. [HTML]

  2. Let element be null.

  3. If qualifiedName is not the empty string, set element to the result of invoking the createElementNS() method with the arguments namespace and qualifiedName on document. If that threw an exception, re-throw the exception and terminate these steps.

  4. If doctype is not null, append doctype to document.

  5. If element is not null, append element to document.

  6. Return document.

The createHTMLDocument(title) method must run these steps:

  1. Let doc be a newly created document.

  2. Mark doc as being an HTML document.

  3. Set doc's content type to "text/html".

  4. Create a doctype, with "html" as its name and with its node document set to doc. Append the newly created node to doc.

  5. Create an html element in the HTML namespace, and append it to doc.

  6. Create a head element in the HTML namespace, and append it to the html element created in the previous step.

  7. Create a title element in the HTML namespace, and append it to the head element created in the previous step.

  8. Create a Text node, set its data to title (which could be the empty string), and append it to the title element created in the previous step.

  9. Create a body element in the HTML namespace, and append it to the html element created in the earlier step.

  10. Return doc.

The hasFeature(feature, version) method must return true for any of (feature, version) tuples listed below where feature is an ASCII case-insensitive and version is a case-sensitive match, or false otherwise.

  • ("Core", "2.0")
  • ("HTML", "1.0")
  • ("HTML", "2.0")
  • ("XHTML", "1.0")
  • ("XHTML", "2.0")
  • ("XML", "1.0")
  • ("XML", "2.0")

Any others?

The hasFeature() is a badly designed method (features are notoriously unreliable and imprecise) that is now effectively obsolete and only needs to be supported for deployed content.

5.5 Interface DocumentFragment

interface DocumentFragment : Node {
  // NEW
  void prepend((Node or DOMString)... nodes);
  void append((Node or DOMString)... nodes);
};

5.6 Interface DocumentType

interface DocumentType : Node {
  readonly attribute DOMString name;
  readonly attribute DOMString publicId;
  readonly attribute DOMString systemId;

  // NEW
  void before((Node or DOMString)... nodes);
  void after((Node or DOMString)... nodes);
  void replace((Node or DOMString)... nodes);
  void remove();
};

DocumentType nodes are simply known as doctypes.

Doctypes have an associated name, public ID, and system ID.

When a doctype is created, its name is always given. Unless explicitly given when a doctype is created, its public ID and system ID are the empty string.

The name attribute must return the name.

The publicId attribute must return the public ID.

The systemId attribute must return the system ID.

5.7 Interface Element

interface Element : Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
  readonly attribute DOMString tagName;

           attribute DOMString id;
           attribute DOMString className;
  readonly attribute DOMTokenList classList;

  readonly attribute Attr[] attributes;
  DOMString? getAttribute(DOMString name);
  DOMString? getAttributeNS(DOMString? namespace, DOMString localName);
  void setAttribute(DOMString name, DOMString value);
  void setAttributeNS(DOMString? namespace, DOMString name, DOMString value);
  void removeAttribute(DOMString name);
  void removeAttributeNS(DOMString? namespace, DOMString localName);
  boolean hasAttribute(DOMString name);
  boolean hasAttributeNS(DOMString? namespace, DOMString localName);

  HTMLCollection getElementsByTagName(DOMString localName);
  HTMLCollection getElementsByTagNameNS(DOMString? namespace, DOMString localName);
  HTMLCollection getElementsByClassName(DOMString classNames);

  readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
  readonly attribute unsigned long childElementCount;

  // NEW
  void prepend((Node or DOMString)... nodes);
  void append((Node or DOMString)... nodes);
  void before((Node or DOMString)... nodes);
  void after((Node or DOMString)... nodes);
  void replace((Node or DOMString)... nodes);
  void remove();
};

Element nodes are simply known as elements.

Elements have an associated namespace, namespace prefix, and local name. When an element is created, its local name is always given. Unless explicitly given when an element is created, its namespace and namespace prefix are null.

Elements also have an ordered attribute list. Unless explicitly given when an element is created, its attribute list is empty. An element has an attribute A if A is in its attribute list.

Elements can have a unique identifier (ID) and classes associated with them.

Historically elements could have multiple identifiers e.g. by using the HTML id attribute and a DTD. This specification makes ID a concept of the DOM and allows for only one per element, given by an id attribute.

An element has an ID if it has an id attribute whose value is not the empty string. The ID is that attribute's value.

An element has classes if it has a class attribute, and splitting that attribute's value does not return an empty list. The classes are that attribute's value split on spaces.

While this specification defines user agent processing requirements for id and class attributes on any element, it makes no claims as to whether using them is conforming or not.

A node's parent of type Element is known as a parent element. If the node has a parent of a different type, its parent element is null.

The document element of a document is the element whose parent is that document, if it exists, and null otherwise.

As explained in the node tree section, there can only be one such element.

When an element or one of its ancestors is the document element, it is in a document.

Specifications may define base URL change steps.

When an element is affected by a base URL change, the user agent must run the base URL change steps, as defined in other applicable specifications.

namespace = element . namespaceURI

Returns the namespace.

prefix = element . prefix

Returns the namespace prefix.

localName = element . localName

Returns the local name.

qualifiedName = element . tagName

If namespace prefix is not null returns the concatenation of namespace prefix, ":", and local name. Otherwise it returns the local name. (The return value is uppercased in an HTML document.)

The namespaceURI attribute must return the context object's namespace.

The prefix attribute must return the context object's namespace prefix.

The localName attribute must return the context object's local name.

The tagName attribute must run these steps:

  1. If context object's namespace prefix is not null, let qualified name be its namespace prefix, followed by a ":" (U+003A), followed by its local name. Otherwise, let qualified name be its local name.

  2. If the context object is in the HTML namespace and its node document is an HTML document, let qualified name be converted to ASCII uppercase.

  3. Return qualified name.

Some attributes are defined to reflect a particular content attribute. This means that on getting, these steps must be run:

  1. Let value be the result of invoking getAttributeNS() with null as first argument and the name of the content attribute as second argument.
  2. If value is null, return the empty string and terminate these steps.
  3. Return value.

On setting, the setAttributeNS() must be invoked with null as first argument, the name of the content attribute as second argument, and the new value as third argument.

The id attribute must reflect the "id" content attribute.

The className attribute must reflect the "class" content attribute.

The classList attribute must return a DOMTokenList whose underlying string is the className attribute value.

The attributes attribute must return a read only array of the context object's attribute list. The returned read only array must be live. I.e. changes to the associated attributes are reflected.

The getAttribute(name) method must run these steps:

  1. If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.

  2. Return the value of the first attribute in the context object's attribute list whose name is name, or null otherwise.

The getAttributeNS(namespace, localName) method must return the following steps:

  1. If namespace is the empty string, set it to null.

  2. Return the value of the attribute in the context object's attribute list whose namespace is namespace and local name is localName, if it has one, or null otherwise.

The setAttribute(name, value) method must run these steps:

  1. If name does not match the Name production in XML, throw an "InvalidCharacterError" exception and terminate these steps.

  2. If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.

  3. If "xmlns" is a prefix match for name, throw a "NamespaceError" and terminate these steps.

  4. Let attribute be the first attribute in the context object's attribute list whose name is name, or null if there is no such attribute.

  5. If attribute is null, create an attribute whose name is name and value is value, and then append this attribute to the context object and terminate these steps.

  6. Queue an "attributes" record with target context object, name attribute's name, namespace attribute's namespace, and oldValue attribute's value.

  7. Set attribute's value to value.

The setAttributeNS(namespace, name, value) method must run these steps:

  1. If namespace is the empty string, set it to null.

  2. If name does not match the Name production in XML, throw an "InvalidCharacterError" exception and terminate these steps.

  3. If name does not match the QName production in Namespaces in XML, throw a "NamespaceError" exception and terminate these steps.

  4. If name contains a ":" (U+003E), then split the string on it and let prefix be the part before and localName the part after. Otherwise, let prefix be null and localName be name.

  5. If prefix is not null and namespace is null, throw a "NamespaceError" exception and terminate these steps.

  6. If prefix is "xml" and namespace is not the XML namespace, throw a "NamespaceError" exception and terminate these steps.

  7. If name or prefix is "xmlns" and namespace is not the XMLNS namespace, throw a "NamespaceError" exception and terminate these steps.

  8. If namespace is the XMLNS namespace and neither name nor prefix is "xmlns", throw a "NamespaceError" exception and terminate these steps.

  9. Let attribute be the first attribute in the context object's attribute list whose namespace is namespace and whose local name is localName, or null if there is no such attribute.

  10. If attribute is null, create an attribute whose name is name, namespace is namespace, namespace prefix is prefix, local name is localName, and value is value, and then append this attribute to the context object and terminate these steps.

  11. Queue an "attributes" record with target context object, name name, namespace namespace, and oldValue attribute's value.

  12. Set attribute's value to value.

The removeAttribute(name) method must run these steps:

  1. If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.

  2. Remove the first attribute from the context object whose name is name, if any.

The removeAttributeNS(namespace, localName) method must return the following steps:

  1. If namespace is the empty string, set it to null.

  2. Remove the attribute from the context object whose namespace is namespace and local name is localName, if any.

The hasAttribute(name) method must run these steps:

  1. If the context object is in the HTML namespace and its node document is an HTML document, let name be converted to ASCII lowercase.

  2. Return true if the context object has an attribute whose name is name, or false otherwise.

The hasAttributeNS(namespace, localName) method must return the following steps:

  1. If namespace is the empty string, set it to null.

  2. Return true if the context object has an attribute whose namespace is namespace and local name is localName, or false otherwise.

When the getElementsByTagName(localName) method must return the list of elements with local name localName for the context object.

When the getElementsByTagNameNS(namespace, localName) method must return the list of elements with namespace namespace and local name localName for the context object.

When the getElementsByClassName(classNames) method must return the list of elements with class names classNames for the context object.

collection = element . children

Returns the child elements.

element = element . firstElementChild

Returns the first child that is an element, or null otherwise.

element = element . lastElementChild

Returns the last child that is an element, or null otherwise.

element = element . previousElementSibling

Returns the first preceding sibling that is an element, or null otherwise.

element = element . nextElementSibling

Returns the first following sibling that is an element, or null otherwise.

The children attribute must return an HTMLCollection collection rooted at the context object matching only element children.

The firstElementChild attribute must return the first child that is an element, or null otherwise.

The lastElementChild attribute must return the last child that is an element, or null otherwise.

The previousElementSibling attribute must return the first preceding sibling that is an element, or null otherwise.

The nextElementSibling attribute must return the first following sibling that is an element, or null otherwise.

The childElementCount attribute must return the number of children of the context object that are elements.

5.7.1 Interface Attr

interface Attr {
  readonly attribute DOMString name;
           attribute DOMString value;

  readonly attribute DOMString? namespaceURI;
  readonly attribute DOMString? prefix;
  readonly attribute DOMString localName;
};

Attr objects are simply known as attributes.

Attributes have a name and value.

For legacy reasons, attributes also have an associated namespace, namespace prefix, and local name.

When an attribute is created, its name and value are always given. Unless explicitly given when an attribute is created, its local name is identical to its name, and its namespace and namespace prefix are null.

An A attribute is an attribute whose name is A and whose namespace and namespace prefix are null.

To append an attribute attribute to an element element, run these steps:

  1. Queue an "attributes" record with target element, name attribute's name, namespace attribute's namespace, and oldValue null.

  2. Append the attribute to the element's attribute list.

To remove an attribute attribute from an element element, run these steps:

  1. Queue an "attributes" record with target element, name attribute's name, namespace attribute's namespace, and oldValue attribute's value.

  2. Remove the attribute from the element's attribute list.

The name attribute must return the name.

The value attribute must return the value.

Setting the value attribute must set value to the new value.

The namespaceURI attribute must return the namespace.

The prefix attribute must return the namespace prefix.

The localName attribute must return the local name.

5.8 Interface CharacterData

interface CharacterData : Node {
  [TreatNullAs=EmptyString] attribute DOMString data;
  readonly attribute unsigned long length;
  DOMString substringData(unsigned long offset, unsigned long count);
  void appendData(DOMString data);
  void insertData(unsigned long offset, DOMString data);
  void deleteData(unsigned long offset, unsigned long count);
  void replaceData(unsigned long offset, unsigned long count, DOMString data);

  // NEW
  void before((Node or DOMString)... nodes);
  void after((Node or DOMString)... nodes);
  void replace((Node or DOMString)... nodes);
  void remove();
};

CharacterData is an abstract interface and does not exist as node. It is used by Text, Comment, and ProcessingInstruction nodes.

Each node inheriting from the CharacterData interface has an associated mutable string called data.

To replace data of node node with offset offset, count count, and data data, run these steps:

  1. Let length be the node's length attribute value.

  2. If offset is greater than length, throw an "IndexSizeError" exception and terminate these steps.

  3. If offset plus count is greater than length let count be length minus offset.

  4. Queue a "characterData" record with target node and oldValue node's data.

  5. Insert data into node's data after offset code units.

  6. Let delete offset be offset plus the number of code units in data.

  7. Starting from delete offset code units, remove count code units from node's data.

  8. For each range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.

  9. For each range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.

  10. For each range whose start node is node and start offset is greater than offset plus count, increase its start offset by the number of code units in data, then decrease it by count.

  11. For each range whose end node is node and end offset is greater than offset plus count, increase its end offset by the number of code units in data, then decrease it by count.

To substring data with node node, offset offset, and count count, run these steps:

  1. Let length be node's length attribute value.

  2. If offset is greater than length, throw an "IndexSizeError" exception and terminate these steps.

  3. If offset plus count is greater than length, return a string whose value is the code units from the offsetth code unit to the end of node's data, and then terminate these steps.

  4. Return a string whose value is the code units from the offsetth code unit to the offset+countth code unit in node's data.

The data attribute must return data, and on setting, must replace data with node context object offset 0, count length attribute value, and data new value.

The length attribute must return the number of code units in data.

The substringData(offset, count) method must substring data with node context object, offset offset, and count count.

The appendData(data) method must replace data with node context object, offset length attribute value, count 0, and data data.

The insertData(offset, data) method must replace data with node context object, offset offset, count 0, and data data.

The deleteData(offset, count) method must replace data with node context object, offset offset, count count, and data the empty string.

The replaceData(offset, count, data) method must replace data with node context object, offset offset, count count, and data data.

5.9 Interface Text

interface Text : CharacterData {
  Text splitText(unsigned long offset);
  readonly attribute DOMString wholeText;
};

To split a Text node node with offset offset, run these steps:

  1. Let length be the length attribute value.

  2. If offset is greater than length, throw an "IndexSizeError" exception and terminate these steps.

  3. Let count be length minus offset.

  4. Let new data be the result of substringing data with node node, offset offset, and count count.

  5. Let new node be a new Text node, with the same node document as node. Set new node's data to new data.

  6. Let parent be the node's parent.

  7. If parent is not null, run these substeps:

    1. Insert new node into parent before node's next sibling.

    2. For each range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.

    3. For each range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.

  8. Replace data with node node, offset offset, count count, and data the empty string.

  9. If parent is null, run these substeps:

    1. For each range whose start node is node and start offset is greater than offset, set its start offset to offset.

    2. For each range whose end node is node and end offset is greater than offset, set its end offset to offset.

  10. Return new node.

The splitText(offset) method must split the context object with offset offset.

The contiguous Text nodes of a node are the node itself, the previous sibling Text node (if any) and its contiguous Text nodes, and the next sibling Text node (if any) and its contiguous Text nodes, avoiding any duplicates.

The wholeText attribute must return a concatenation of the data of the contiguous Text nodes of the context object, in tree order.

5.10 Interface ProcessingInstruction

interface ProcessingInstruction : CharacterData {
  readonly attribute DOMString target;
};

ProcessingInstruction nodes have an associated target.

The target attribute must return the target.

5.11 Interface Comment

interface Comment : CharacterData {
};

6 Ranges

The length of a node node depends on node:

DocumentType

0.

Text
ProcessingInstruction
Comment

Its length attribute value.

Any other node

Its number of children.

6.1 Interface Range

interface Range {
  readonly attribute Node startContainer;
  readonly attribute unsigned long startOffset;
  readonly attribute Node endContainer;
  readonly attribute unsigned long endOffset;
  readonly attribute boolean collapsed;
  readonly attribute Node commonAncestorContainer;

  void setStart(Node refNode, unsigned long offset);
  void setEnd(Node refNode, unsigned long offset);
  void setStartBefore(Node refNode);
  void setStartAfter(Node refNode);
  void setEndBefore(Node refNode);
  void setEndAfter(Node refNode);
  void collapse(boolean toStart);
  void selectNode(Node refNode);
  void selectNodeContents(Node refNode);

  const unsigned short START_TO_START = 0;
  const unsigned short START_TO_END = 1;
  const unsigned short END_TO_END = 2;
  const unsigned short END_TO_START = 3;
  short compareBoundaryPoints(unsigned short how, Range sourceRange);

  void deleteContents();
  DocumentFragment extractContents();
  DocumentFragment cloneContents();
  void insertNode(Node node);
  void surroundContents(Node newParent);

  Range cloneRange();
  void detach();

  boolean isPointInRange(Node node, unsigned long offset);
  short comparePoint(Node node, unsigned long offset);

  boolean intersectsNode(Node node);

  stringifier;
};

Range objects are simply known as ranges.

Ranges can be created using the createRange() method.

A boundary point is a (node, offset) tuple, where offset is a non-negative integer.

Generally speaking, a boundary point's offset will be between zero and the boundary point's node length, inclusive. Algorithms that modify a tree (in particular the insert, remove, replace data, and split algorithms) also modify ranges associated with that tree.

If the two nodes of boundary points (node A, offset A) and (node B, offset B) have the same root, the position of the first relative to the second is either before, equal, or after, as returned by the following algorithm:

  1. If node A is the same as node B, return equal if offset A is the same as offset B, before if offset A is less than offset B, and after if offset A is greater than offset B.

  2. If node A is following node B, compute the position of (node B, offset B) relative to (node A, offset A). If it is before, return after. If it is after, return before. In either case terminate these steps.

  3. If node A is an ancestor of node B:

    1. Let child equal node B.

    2. While child is not a child of node A, set child to its parent.

    3. If the index of child is less than offset A, return after.

  4. Return before.

Each range has two associated boundary points — a start and end — an associated detached flag, which is initially unset.

For convenience, start node is start's node, start offset is start's offset, end node is end's node, and end offset is end's offset.

The root of a range is the root of its start node, or null if its detached flag is set.

A node node is contained in a range range if node's root is the same as range's root, and (node, 0) is after range's start, and (node, length of node) is before range's end.

A node is partially contained in a range if it is an inclusive ancestor of the range's start node but not its end node, or vice versa.

Some facts to better understand these definitions:

  • The content that one would think of as being within the range consists of all contained nodes, plus possibly some of the contents of the start node and end node if those are Text or Comment nodes.

  • The nodes that are contained in a range will generally not be contiguous, because the parent of a contained node will not always be contained.

  • However, the descendants of a contained node are contained, and if two siblings are contained, so are any siblings that lie between them.

  • The first contained node (if there are any) will always be after the start node, and the last contained node will always be equal to or before the end node's last descendant.

  • The start node and end node of a range are never contained within it.

  • There exists some partially contained node if and only if the start node and end node are different.

  • The commonAncestorContainer attribute value is never contained or partially contained.

  • If the start node is an ancestor of the end node, the common inclusive ancestor will be the start node. Exactly one of its children will be partially contained, and a child will be contained if and only if it precedes the partially contained child. If the end node is an ancestor of the start node, the opposite holds.

  • If the start node is not an inclusive ancestor of the end node, nor vice versa, the common inclusive ancestor will be distinct from both of them. Exactly two of its children will be partially contained, and a child will be contained if and only if it lies between those two.

node = range . startContainer

Returns range's start node.

offset = range . startOffset

Returns range's start offset.

node = range . endContainer

Returns range's end node.

offset = range . endOffset

Returns range's end offset.

collapsed = range . collapsed

Returns true if range's start and end are the same, or false otherwise.

container = range . commonAncestorContainer

Returns the node, furthest away from the document, that is an ancestor of both range's start node and end node.

The startContainer attribute must throw an "InvalidStateError" exception if the detached flag is set, or return the start node otherwise.

The startOffset attribute must throw an "InvalidStateError" exception if the detached flag is set, or return the start offset otherwise.

The endContainer attribute must throw an "InvalidStateError" exception if the detached flag is set, or return the end node otherwise.

The endOffset attribute must throw an "InvalidStateError" exception if the detached flag is set, or return the end offset otherwise.

The collapsed attribute must throw an "InvalidStateError" exception if the detached flag is set, return true if start is the same as end, or return false otherwise.

The commonAncestorContainer attribute must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let container be start node.

  3. While container is not an inclusive ancestor of end node, let container be container's parent.

  4. Return container.

To set the start or end of a range to a boundary point (node, offset), run these steps:

  1. If range's detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If node is a doctype, throw an "InvalidNodeTypeError" exception and terminate these steps.

  3. If offset is greater than node's length, throw an "IndexSizeError" exception and terminate these steps.

  4. Let bp be the boundary point (node, offset).

  5. If these steps were invoked as "set the start"

    1. If bp is after the range's end, or if the range's root is not equal to node's root, set range's end to bp.

    2. Set range's start to bp.

    If these steps were invoked as "set the end"

    1. If bp is before the range's start, or if the range's root is not equal to node's root, set range's start to bp.

    2. Set range's end to bp.

The setStart(node, offset) method must set the start of the context object to boundary point (node, offset).

The setEnd(refNode, offset) method must set the end of the context object to boundary point (node, offset).

The setStartBefore(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let parent be node's parent.

  3. If parent is null, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. Set the start of the context object to boundary point (parent, node's index).

The setStartAfter(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let parent be node's parent.

  3. If parent is null, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. Set the start of the context object to boundary point (parent, node's index plus one).

The setEndBefore(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let parent be node's parent.

  3. If parent is null, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. Set the end of the context object to boundary point (parent, node's index).

The setEndAfter(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let parent be node's parent.

  3. If parent is null, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. Set the end of the context object to boundary point (parent, node's index plus one).

The collapse(toStart) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If toStart is true, set end to start. Otherwise, set start to end.

The selectNode(refNode) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let parent be refNode's parent.

  3. If parent is null, throw an "InvalidNodeTypeError" and terminate these steps.

  4. Let index be the index of refNode.

  5. Set start to the boundary point (parent, index).

  6. Set end to the boundary point (parent, index plus one).

The selectNodeContents(refNode) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If refNode is a doctype, throw an "InvalidNodeTypeError" and terminate these steps.

  3. Let length be the length of refNode.

  4. Set start to the boundary point (refNode, 0).

  5. Set end to the boundary point (refNode, length).

The compareBoundaryPoints(how, sourceRange) method must run these steps:

  1. If context object's or sourceRange's detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If how is not one of

    • START_TO_START,
    • START_TO_END,
    • END_TO_END, and
    • END_TO_START,

    throw a "NotSupportedError" exception and terminate these steps.

  3. If context object's root is not the same as sourceRange's root, throw a "WrongDocumentError" exception and terminate these steps.

  4. If how is:

    START_TO_START:

    Let this point be the context object's start.

    Let other point be sourceRange's start.

    START_TO_END:

    Let this point be the context object's end.

    Let other point be sourceRange's start.

    END_TO_END:

    Let this point be the context object's end.

    Let other point be sourceRange's end.

    END_TO_START:

    Let this point be the context object's start.

    Let other point be sourceRange's end.

  5. If the position of this point relative to other point is

    before
    Return −1.
    equal
    Return 0.
    after
    Return 1.

The deleteContents() method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If start equals end, terminate these steps.

  3. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

  4. If original start node and original end node are the same, and they are a Text or Comment node, replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string, and then terminate these steps.

  5. Let nodes to remove be a list of all the nodes that are contained in the context object, in tree order, omitting any node whose parent is also contained in the context object.

  6. If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.

  7. Otherwise:

    1. Let reference node equal original start node.

    2. While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.

    3. Set new node to the parent of reference node, and new offset to one plus the index of reference node.

      If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we could not reach this point.

  8. If original start node is a Text or Comment node, replace data with node original start node, offset original start offset, count original start node's length minus original start offset, data the empty string.

  9. For each node in nodes to remove, in tree order, remove node from its parent.

  10. If original end node is a Text or Comment node, replace data with node original end node, offset 0, count original end offset), and data the empty string.

  11. Set start and end to (new node, new offset).

The extractContents() method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let frag be a new DocumentFragment whose node document is the same as the node document of the context object's start node.

  3. If start equals end, return frag, and terminate these steps.

  4. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

  5. If original start node equals original end node, and they are a Text or Comment node:

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.

    3. Append clone to frag.

    4. Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.

    5. Return frag and terminate these steps.

  6. Let common ancestor be original start node.

  7. While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.

  8. If original start node is an inclusive ancestor of original end node, let first partially contained child be null.

  9. Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.

  10. If original end node is an inclusive ancestor of original start node, let last partially contained child be null.

  11. Otherwise, let last partially contained child be the last child of common ancestor that is partially contained in the context object.

    These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.

  12. Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.

  13. If any member of contained children is a DocumentType, throw a "HierarchyRequestError" exception and terminate these steps.

    We do not have to worry about the first or last partially contained node, because a DocumentType can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.

  14. If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.

  15. Otherwise:

    1. Let reference node equal original start node.
    2. While reference node's parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
    3. Set new node to the parent of reference node, and new offset to one plus the index of reference node.

      If reference node's parent were null, it would be the root of the context object, so would be an inclusive ancestor of original end node, and we couldn't reach this point.

  16. If first partially contained child is a Text or Comment node:

    In this case, the first partially contained child is the original start node.

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.

    3. Append clone to frag.

    4. Replace data with node original start node, offset original start offset, count original start node's length minus original start offset, and data the empty string.

  17. Otherwise, if first partially contained child is not null:

    1. Let clone be a clone of first partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (original start node, original start offset) and whose end is (first partially contained child, length of first partially contained child).
    4. Let subfrag be the result of calling extractContents() on subrange.

      Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.

    5. For each child of subfrag, in tree order, append that child to clone.

  18. For each contained child in contained children, append contained child to frag.

  19. If last partially contained child is a Text or Comment node:

    In this case, the last partially contained child is the original end node.

    1. Let clone be a clone of original end node.

    2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.

    3. Append clone to frag.

    4. Replace data with node original end node, offset 0, count original end offset, and data the empty string.

  20. Otherwise, if last partially contained child is not null:

    1. Let clone be a clone of last partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
    4. Let subfrag be the result of calling extractContents() on subrange.

    5. For each child of subfrag, in tree order, append that child to clone.

  21. Set start and end to (new node, new offset).

  22. Return frag.

The cloneContents() method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let frag be a new DocumentFragment whose node document is the same as the node document of the context object's start node.

  3. If start equals end, return frag, and terminate these steps.

  4. Let original start node, original start offset, original end node, and original end offset be the context object's start node, start offset, end node, and end offset, respectively.

  5. If original start node equals original end node, and they are a Text or Comment node:

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.

    3. Append clone to frag.

    4. Return frag and terminate these steps.

  6. Let common ancestor be original start node.

  7. While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.

  8. If original start node is an inclusive ancestor of original end node, let first partially contained child be null.

  9. Otherwise, let first partially contained child be the first child of common ancestor that is partially contained in the context object.

  10. If original end node is an inclusive ancestor of original start node, let last partially contained child be null.

  11. Otherwise, let last partially contained child be the last child of common ancestor that is partially contained in the context object.

    These variable assignments do actually always make sense. For instance, if the original start node is not an inclusive ancestor of the original end node, the original start node is itself partially contained in the range, and so are all its ancestors up until a child of the common ancestor. The common ancestor can't be original start node, because it must be an inclusive ancestor of the original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.

  12. Let contained children be a list of all children of common ancestor that are contained in the context object, in tree order.

  13. If any member of contained children is a DocumentType, throw a "HierarchyRequestError" exception and terminate these steps.

    We don't have to worry about the first or last partially contained node, because a DocumentType can never be partially contained. It can't be a boundary point of a range, and it can't be the ancestor of anything.

  14. If first partially contained child is a Text or Comment node:

    In this case, the first partially contained child is the original start node.

    1. Let clone be a clone of original start node.

    2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node's length minus original start offset.

    3. Append clone to frag.

  15. Otherwise, if first partially contained child is not null:

    1. Let clone be a clone of first partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (original start node, original start offset) and whose end is (first partially contained child, length of first partially contained child).
    4. Let subfrag be the result of calling cloneContents() on subrange.

      Is this method of recursing black-box detectable? E.g., would it fire extra DOM mutation events or something? What we really mean is to get a list of nodes to insert, then insert them directly into frag, without an intermediate document fragment.

    5. For each child of subfrag, in tree order, append that child to clone.

  16. For each contained child in contained children:

    1. Let clone be a clone of contained child.

    2. Append clone to frag.

  17. If last partially contained child is a Text or Comment node:

    In this case, the last partially contained child is the original end node.

    1. Let clone be a clone of original end node.

    2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.

    3. Append clone to frag.

  18. Otherwise, if last partially contained child is not null:

    1. Let clone be a clone of last partially contained child.

    2. Append clone to frag.

    3. Let subrange be a new Range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
    4. Let subfrag be the result of calling cloneContents() on subrange.

    5. For each child of subfrag, in tree order, append that child to clone.

  19. Return frag.

The insertNode(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If start node is a Comment node, or a Text node whose parent is null, throw an "HierarchyRequestError" exception and terminate these steps.

  3. If start node is a Text node, split it with offset context object's start offset, and let reference node be the result.

  4. Otherwise, let reference node be the child of start node whose index is start offset, or null if there is no such child.

  5. If reference node is null, let parent be start node.

  6. Otherwise, let parent be the parent of reference node.

  7. Let new offset be the index of reference node, or parent's length if reference node is null.

  8. Add node's length to new offset, if node is a DocumentFragment. Otherwise add one to new offset.

  9. Pre-insert node into parent before reference node.

  10. If start and end are the same, set end to (parent, new offset).

The surroundContents(newParent) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If a non-Text node is partially contained in the context object, throw an "InvalidStateError" exception and terminate these steps.

  3. If newParent is a Document, DocumentType, or DocumentFragment node, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. Call extractContents() on the context object, and let fragment be the result.

  5. While newParent has children, remove its first child.

  6. Call insertNode(newParent) on the context object.
  7. Call appendChild(fragment) on newParent.
  8. Call selectNode(newParent) on the context object.

The cloneRange() method must throw an "InvalidStateError" exception if the detached flag is set. Otherwise, it must return a new range with the same start and end as the context object.

The detach() method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Set the detached flag.

position = range . comparePoint( parent, offset )

Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.

intersects = range . intersectsNode( node )

Returns whether range intersects node.

The isPointInRange(node, offset) must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If node's root is different from the context object's root, return false and terminate these steps.

  3. If node is a doctype, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. If offset is greater than node's length, throw an "IndexSizeError" exception and terminate these steps.

  5. If (node, offset) is before start or after end, return false and terminate these steps.

  6. Return true.

The comparePoint(node, offset) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If node's root is different from the context object's root, throw a "WrongDocumentError" exception and terminate these steps.

  3. If node is a doctype, throw an "InvalidNodeTypeError" exception and terminate these steps.

  4. If offset is greater than node's length, throw an "IndexSizeError" exception and terminate these steps.

  5. If (node, offset) is before start, return −1 and terminate these steps.

  6. If (node, offset) is after end, return 1 and terminate these steps.

  7. Return 0.

The intersectsNode(node) method must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. If node's root is different from the context object's root, return false and terminate these steps.

  3. Let parent be node's parent.

  4. If parent is null, throw a "NotFoundError" exception and terminate these steps.

    All implementations throw in this case, but would it make more sense to simply return true? This case can only occur when the roots are the same, so it means that node is the range's root, so the range is fully contained in node.

  5. Let offset be node's index.

  6. If (parent, offset) is before end and (parent, offset + 1) is after start, return true and terminate these steps.

  7. Return false.

The stringifier must run these steps:

  1. If the detached flag is set, throw an "InvalidStateError" exception and terminate these steps.

  2. Let s be the empty string.

  3. If start node equals end node, and it is a Text node, return the substring of that Text node's data beginning at start offset and ending at end offset, and terminate these steps.

  4. If start node is a Text node, append to s the substring of that node's data from the start offset until the end.

  5. Append to s the concatenation, in tree order, of the data of all Text nodes that are contained in the context object.

  6. If end node is a Text node, append to s the substring of that node's data from its start until the end offset.

  7. Return s.

The following extensions to the Range interface are defined in various other specifications:

  • the createContextualFragment() method; [DOMPS]
  • the getClientRects() method; and
  • the getBoundingClientRect() method. [CSSOMVIEW]

7 Traversal

NodeIterator and TreeWalker objects can be used to filter and traverse node trees.

Each NodeIterator and TreeWalker object has an associated active flag to avoid recursive invocations. It is initially unset.

Each NodeIterator and TreeWalker object also has an associated root node, whatToShow bitmask, and filter callback.

To filter node run these steps:

  1. If active flag is set throw an "InvalidStateError", terminate these steps, and terminate the steps of the algorithm that invoked this algorithm.

  2. Let n be node's nodeType attribute value minus 1.

  3. If the nth bit (where 0 is the least significant bit) of whatToShow is not set, return FILTER_SKIP and terminate these steps.

  4. If filter is null return FILTER_ACCEPT and terminate these steps.

  5. Set the active flag.

  6. Let result be the return value of invoking filter.

  7. Unset the active flag.

  8. If an exception was thrown, re-throw the exception, terminate these steps, and terminate the steps of the algorithm that invoked this algorithm.

  9. Return result.

7.1 Interface NodeIterator

interface NodeIterator {
  readonly attribute Node root;
  readonly attribute Node? referenceNode;
  readonly attribute boolean pointerBeforeReferenceNode;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;

  Node? nextNode();
  Node? previousNode();

  void detach();
};

NodeIterator objects can be created using the createNodeIterator() method.

Each NodeIterator object has an associated iterator collection, which is a collection rooted at root, whose filter matches any node.

Before a node is removed from the iterator collection, these steps must be run:

  1. If the node is not a descendant of root and is not an ancestor of the referenceNode attribute value or the referenceNode attribute value itself, terminate these steps.

  2. If the pointerBeforeReferenceNode attribute value is false, set the referenceNode attribute to the first node preceding the node that is being removed, and terminate these steps.

  3. If the pointerBeforeReferenceNode attribute value is true and there is a node following the node that is being removed, set the referenceNode attribute to the first such node, and terminate these steps.

  4. Set the referenceNode attribute to the first node preceding the node that is being removed and set the pointerBeforeReferenceNode attribute to false.

Each NodeIterator object also has an associated detached flag which is initially unset.

As mentioned earlier NodeIterator objects have an associated active flag, root node, whatToShow bitmask, and filter callback as well.

The root attribute must return root.

The referenceNode attribute must return what it was initialized to.

The pointerBeforeReferenceNode attribute must return what it was initialized to. When a NodeIterator is created it must be initialized to true.

The whatToShow attribute must return whatToShow.

The filter attribute must return filter.

To traverse in direction direction run these steps:

  1. If the detached flag is set throw an "InvalidStateError" exception and terminate these steps.

  2. Let node be the value of the referenceNode attribute.

  3. Let before node be the value of the pointerBeforeReferenceNode attribute.

  4. Run these substeps:

    1. If direction is next

      If before node is false, let node be the first node following node in the iterator collection. If there is no such node return null and terminate these steps.

      If before node is true, set it to false.

      If direction is previous

      If before node is true, let node be the first node preceding node in the iterator collection. If there is no such node return null and terminate these steps.

      If before node is false, set it to true.

    2. Filter node and let result be the return value.

    3. If the detached flag is set throw an "InvalidStateError" exception and terminate these steps.

    4. If result is FILTER_ACCEPT, go to the next step in the overall set of steps.

      Otherwise, run these substeps again.

  5. Set the referenceNode attribute to node, set the pointerBeforeReferenceNode attribute to before node, and return node.

The nextNode() method must traverse in direction next.

The previousNode() method must traverse in direction previous.

When the detach() method is invoked set the detached flag and set the referenceNode attribute to null.

7.2 Interface TreeWalker

interface TreeWalker {
  readonly attribute Node root;
  readonly attribute unsigned long whatToShow;
  readonly attribute NodeFilter? filter;
           attribute Node currentNode;

  Node? parentNode();
  Node? firstChild();
  Node? lastChild();
  Node? previousSibling();
  Node? nextSibling();
  Node? previousNode();
  Node? nextNode();
};

TreeWalker objects can be created using the createTreeWalker() method.

As mentioned earlier TreeWalker objects have an associated active flag, root node, whatToShow bitmask, and filter callback.

The root attribute must return root.

The whatToShow attribute must return whatToShow.

The filter attribute must return filter.

The currentNode attribute must return what it was initialized to.

Setting the currentNode attribute must set it to the new value.

The parentNode() method must run these steps:

  1. Let node be the value of the currentNode attribute.

  2. While node is not null and is not root, run these substeps:

    1. Let node be node's parent.

    2. If node is not null and filtering node returns FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

  3. Return null.

To traverse children of type type run these steps:

  1. Let node and current be the value of the currentNode attribute.

  2. While node is not null, run these substeps:

    1. Filter node and let result be the return value.

    2. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

    3. If result is FILTER_SKIP and node has a child, then set node as follows and run these substeps again:

      If type is first

      Set it to the first child

      If type is last

      Set it to the last child

    4. While node is not null, run these inner substeps:

      1. If type is first

        Let sibling be the next sibling of node.

        If type is last

        Let sibling be the previous sibling of node.

      2. If sibling is not null, set node to it and terminate these inner substeps.

      3. If node has a parent that is not root or current then set node to it.

        Otherwise, return null and terminate these steps.

The firstChild() method must traverse children of type first.

The lastChild() method must traverse children of type last.

To traverse siblings of type type run these steps:

  1. Let node be the value of the currentNode attribute.

  2. If node is root return null and terminate these steps.

  3. Run these substeps:

    1. If type is next

      Let sibling be the next sibling of node.

      If type is previous

      Let sibling be the previous sibling of node.

    2. While sibling is not null run these inner substeps:

      1. Set node to sibling.

      2. Filter node and let result be the return value.

      3. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

      4. If type is next

        Let sibling be the first child of node.

        If type is previous

        Let sibling be the last child of node.

      5. If result is FILTER_REJECT or sibling is null, then set sibling as follows:

        If type is next

        Let sibling be the next sibling of node.

        If type is previous

        Let sibling be the previous sibling of node.

    3. Set node to its parent.

    4. If node is null or is root return null and terminate these steps.

    5. Filter node and if the return value is FILTER_ACCEPT, then return null and terminate these steps.

    6. Run these substeps again.

The nextSibling() method must traverse children of type next.

The previousSibling() method must traverse children of type previous.

The previousNode() method must run these steps:

  1. Let node be the value of the currentNode attribute.

  2. While node is not root run these substeps:

    1. Let sibling be the previous sibling of node.

    2. While sibling is not null run these inner substeps:

      1. Set node to sibling.

      2. Filter node and let result be the return value.

      3. While result is not FILTER_REJECT and node has a child, run these innermost substeps:

        1. Set node to its last child.

        2. Filter node and set result to the return value.

      4. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

    3. If node is root or has no parent, return null and terminate these steps.

    4. Set node to its parent.

    5. Filter node and if the return value is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

The nextNode() method must run these steps:

  1. Let node be the value of the currentNode attribute.

  2. Let result be FILTER_ACCEPT.

  3. Run these substeps:

    1. While result is not FILTER_ACCEPT and node has a child, run these inner substeps:

      1. Set node to its first child

      2. Filter node and let result be the return value.

      3. If result is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

    2. If a node is following node and is not following root, set node to the first such node.

      Otherwise, run these substeps again (skipping the next step).

    3. Filter node and if the return value is FILTER_ACCEPT, then set the currentNode attribute to node, return node, and terminate these steps.

7.3 Interface NodeFilter

callback interface NodeFilter {
  // Constants for acceptNode()
  const unsigned short FILTER_ACCEPT = 1;
  const unsigned short FILTER_REJECT = 2;
  const unsigned short FILTER_SKIP = 3;

  // Constants for whatToShow
  const unsigned long SHOW_ALL = 0xFFFFFFFF;
  const unsigned long SHOW_ELEMENT = 0x1;
  const unsigned long SHOW_ATTRIBUTE = 0x2; // historical
  const unsigned long SHOW_TEXT = 0x4;
  const unsigned long SHOW_CDATA_SECTION = 0x8; // historical
  const unsigned long SHOW_ENTITY_REFERENCE = 0x10; // historical
  const unsigned long SHOW_ENTITY = 0x20; // historical
  const unsigned long SHOW_PROCESSING_INSTRUCTION = 0x40;
  const unsigned long SHOW_COMMENT = 0x80;
  const unsigned long SHOW_DOCUMENT = 0x100;
  const unsigned long SHOW_DOCUMENT_TYPE = 0x200;
  const unsigned long SHOW_DOCUMENT_FRAGMENT = 0x400;
  const unsigned long SHOW_NOTATION = 0x800; // historical

  unsigned short acceptNode(Node node);
};

NodeFilter objects can be used as filter callback and provide constants for the whatToShow bitmask.

It is typically implemented as an ECMAScript function.

These constants can be used as callback return value:

  • FILTER_ACCEPT (1);
  • FILTER_REJECT (2);
  • FILTER_SKIP (3).

These constants can be used for the whatToShow bitmask:

  • SHOW_ALL (4294967295, FFFFFFFF in hexadecimal);
  • SHOW_ELEMENT (1);
  • SHOW_TEXT (4);
  • SHOW_PROCESSING_INSTRUCTION (64, 40 in hexadecimal);
  • SHOW_COMMENT (128, 80 in hexadecimal);
  • SHOW_DOCUMENT (256, 100 in hexadecimal);
  • SHOW_DOCUMENT_TYPE (512, 200 in hexadecimal);
  • SHOW_DOCUMENT_FRAGMENT (1024, 400 in hexadecimal).

8 Collections

A collection is an object that represents a lists of DOM nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.

If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.

When a collection is created, a filter and a root are associated with it.

The collection then represents a view of the subtree rooted at the collection's root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.

An attribute that returns a live collection must return the same object every time it is retrieved.

8.1 Interface NodeList

A NodeList object is a collection of nodes.

[ArrayClass]
interface NodeList {
  getter Node? item(unsigned long index);
  readonly attribute unsigned long length;
};
collection . length

Returns the number of nodes in the collection.

element = collection . item(index)
element = collection[index]

Returns the node with index index from the collection. The nodes are sorted in tree order.

The object's supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.

The length attribute must return the number of nodes represented by the collection.

The item(index) method must return the indexth node in the collection. If there is no indexth node in the collection, then the method must return null.

8.2 Interface HTMLCollection

An HTMLCollection object is a collection of elements.

This interface is called HTMLCollection for historical reasons. The namedItem() method returns an object for interfaces that inherit from this interface, which return other objects for historical reasons.

interface HTMLCollection {
  readonly attribute unsigned long length;
  getter Element? item(unsigned long index);
  getter object? namedItem(DOMString name); // only returns Element
};
collection . length

Returns the number of elements in the collection.

element = collection . item(index)
element = collection[index]

Returns the element with index index from the collection. The elements are sorted in tree order.

element = collection . namedItem(name)
element = collection[name]

Returns the first element with ID or name name from the collection.

Only a, applet, area, embed, form, frame, frameset, iframe, img, and object element in the HTML namespace can have a name for the purpose of this method; their name is given by the value of their name attribute.

The object's supported property indices are the numbers in the range zero to one less than the number of nodes represented by the collection. If there are no such elements, then there are no supported property indices.

The length attribute must return the number of nodes represented by the collection.

The item(index) method must return the indexth element in the collection. If there is no indexth element in the collection, then the method must return null.

The supported property names consist of the values of the name attributes of each a, applet, area, embed, form, frame, frameset, iframe, img, and object element in the HTML namespace, represented by the collection with a name attribute, plus the list of IDs that the elements represented by the collection have.

The namedItem(key) method must return the first element in the collection that falls into one of the following categories:

  • It is an a, applet, area, embed, form, frame, frameset, iframe, img, or object element, in the HTML namespace, with a name attribute equal to key, or,
  • It is an element with an ID equal to key.

If no such elements are found, then the method must return null.

9 Lists

9.1 Interface DOMStringList

DOMStringList will be removed from this specification in the near future. If you are using it now, please use DOMString[] instead. Thanks!

[NoInterfaceObject]
interface DOMStringList {
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long index);
  boolean contains(DOMString string);
};

The DOMStringList interface represents an interface to an ordered list of strings.

stringlist . length

Returns the number of tokens in the string.

string = stringlist . item(index)
stringlist[index]

Returns the string with index index.

hasstring = stringlist . contains(string)

Returns true if the string is present; false otherwise.

The length attribute must return the number of strings in the list.

The object's supported property indices are the numbers in the range zero to the length attribute value minus 1, unless the length attribute value is zero, in which case there are no supported property indices.

The item(index) method must return the indexth string in the list. If index is equal to or greater than the number of strings, then the method must return null.

The contains(string) method must return true if the list of strings contains string, or false otherwise.

9.2 Interface DOMTokenList

The DOMTokenList interface represents an interface to an underlying string that consists of a set of space-separated tokens.

DOMTokenList objects are always case-sensitive, even when the underlying string might ordinarily be treated in a case-insensitive manner.

interface DOMTokenList {
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long index);
  boolean contains(DOMString token);
  void add(DOMString token);
  void remove(DOMString token);
  boolean toggle(DOMString token);
  stringifier DOMString ();
};
tokenlist . length

Returns the number of tokens in the string.

element = tokenlist . item(index)
tokenlist[index]

Returns the token with index index. The tokens are returned in the order they are found in the underlying string.

hastoken = tokenlist . contains(token)

Returns true if the token is present; false otherwise.

Throws a "SyntaxError" exception if token is empty.

Throws an "InvalidCharacterError" exception if token contains any spaces.

tokenlist . add(token)

Adds token, unless it is already present.

Throws a "SyntaxError" exception if token is empty.

Throws an "InvalidCharacterError" exception if token contains any spaces.

tokenlist . remove(token)

Removes token if it is present.

Throws a "SyntaxError" exception if token is empty.

Throws an "InvalidCharacterError" exception if token contains any spaces.

hastoken = tokenlist . toggle(token)

Adds token if it is not present, or removes it if it is. Returns true if token is now present (it was added); returns false if it is not (it was removed).

Throws a "SyntaxError" exception if token is empty.

Throws an "InvalidCharacterError" exception if token contains any spaces.

The length attribute must return the number of tokens that result from splitting the underlying string on spaces.

The object's supported property indices are the numbers in the range zero to the length attribute value minus 1, unless the length attribute value is zero, in which case there are no supported property indices.

The item(index) method must run these steps:

  1. If index is equal to or greater than the length attribute value, return null and terminate these steps.
  2. Split the underlying string on spaces, preserving the order of the tokens as found in the underlying string, to get the list of tokens.
  3. Return the indexth item in this list.

For example, if the string is "a b a c" then there are four tokens: the token with index 0 is "a", the token with index 1 is "b", the token with index 2 is "a", and the token with index 3 is "c".

The contains(token) method must run these steps:

  1. If token is the empty string, then throw a "SyntaxError" exception and terminate these steps.
  2. If token contains any space characters, then throw an "InvalidCharacterError" exception and terminate these steps.
  3. Split the underlying string on spaces to get the list of tokens.
  4. Return true if token is a case-sensitive match for one of the tokens in the list found in the previous step, or false otherwise.

The add(token) method must run these steps:

  1. If token is the empty string, then throw a "SyntaxError" exception and terminate these steps.
  2. If token contains any space characters, then throw an "InvalidCharacterError" exception and terminate these steps.
  3. Split the underlying string on spaces to get the list of tokens.
  4. If token is a case-sensitive match for one of the tokens in the list found in the previous step, then terminate these steps.
  5. If the underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to that string.
  6. Append token to the underlying string.

The remove(token) method must run these steps:

  1. If token is the empty string, then throw a "SyntaxError" exception and terminate these steps.
  2. If token contains any space characters, then throw an "InvalidCharacterError" exception and terminate these steps.
  3. Remove token from the underlying string.

The toggle(token) method must run these steps:

  1. If token is the empty string, then throw a "SyntaxError" exception and terminate these steps.
  2. If token contains any space characters, then throw an "InvalidCharacterError" exception and terminate these steps.
  3. Split the underlying string on spaces to get the list of tokens.
  4. If token is a case-sensitive match for one of the tokens in the list found in the previous step, then remove token from the underlying string, return false and terminate these steps.
  5. If the underlying string is not the empty string and the last character of that string is not a space character, then append a U+0020 SPACE character to that string.
  6. Append the value of token to the underlying string.
  7. Return true.

DOMTokenList objects must stringify to the underlying string.

9.3 Interface DOMSettableTokenList

The DOMSettableTokenList interface is the same as the DOMTokenList interface, except that it allows the underlying string to be directly changed.

interface DOMSettableTokenList : DOMTokenList {
            attribute DOMString value;
};
tokenlist . value

Returns the underlying string.

Can be set, to change the underlying string.

An object implementing the DOMSettableTokenList interface must act as defined for the DOMTokenList interface, except for the value attribute defined here.

The value attribute must return the underlying string and, on setting must replace the underlying string with the new value.

10 Historical

As explained in goals this specification is a significant revision of various DOM specifications. This section attempts to enumerate the changes.

10.1 DOM Events

These are the changes made to the features described in the "DOM Event Architecture", "Basic Event Interfaces", "Mutation Events", and "Mutation Name Event Types" chapters of DOM Level 3 Events. The other chapters are expected to move to a separate specification.

  • Events have constructors now.
  • No more restrictions on Event.type.
  • preventDefault() only changes what defaultPrevented and dispatchEvent() return if the event is cancelable.
  • Removes EventException, MutationEvent, and MutationNameEvent.
  • Fire is no longer synonymous with dispatch, but includes initializing an event.
  • The propagation and canceled flags are unset when invoking initEvent() rather than after dispatch.

10.2 DOM Core

These are the changes made to the features described in DOM Level 3 Core.

DOMString and DOMTimeStamp are now defined in Web IDL.

Node now inherits from EventTarget.

Nodes are implicitly adopted across document boundaries.

Doctypes now always have a node document and can be moved across document boundaries.

ProcessingInstruction now inherits from CharacterData.

DOMError is completely redesigned.

The remainder of interfaces and interface members listed in this section were removed to simplify the DOM platform. Implementations conforming to this specification will not support them.

Interfaces:

  • CDATASection
  • DOMConfiguration
  • DOMErrorHandler
  • DOMImplementationList
  • DOMImplementationSource
  • DOMLocator
  • DOMObject
  • DOMUserData
  • Entity
  • EntityReference
  • NamedNodeMap
  • NameList
  • Notation
  • TypeInfo
  • UserDataHandler

Interface members:

Node
  • hasAttributes()
  • attributes
  • namespaceURI
  • prefix
  • localName
  • isSupported
  • getFeature()
  • getUserData()
  • setUserData()
  • isSameNode()
Document
  • createCDATASection()
  • createAttribute()
  • createAttributeNS()
  • createEntityReference()
  • inputEncoding
  • xmlEncoding
  • xmlStandalone
  • xmlVersion
  • strictErrorChecking
  • domConfig
  • normalizeDocument()
  • renameNode()
DOMImplementation
  • getFeature()
Attr

No longer inherits from Node and therefore completely changed.

Element
  • getAttributeNode()
  • getAttributeNodeNS()
  • setAttributeNode()
  • removeAttributeNode()
  • schemaTypeInfo
  • setIdAttribute()
  • setIdAttributeNS()
  • setIdAttributeNode()
DocumentType
  • entities
  • notations
  • internalSubset
Text
  • isElementContentWhitespace
  • replaceWholeText()

10.3 DOM Range

These are the changes made to the features described in the "Document Object Model Range" chapter of DOM Level 2 Traversal and Range.

RangeException has been removed.

Range objects can now be moved between documents and used on nodes that are not in a document.

Probably incomplete.

10.4 DOM Traversal

These are the changes made to the features described in the "Document Object Model Traversal" chapter of DOM Level 2 Traversal and Range.

Differences with respect to createNodeIterator() and createTreeWalker():

  • In the previous edition of DOM Traversal both these methods accepted a fourth argument named entityReferenceExpansion that has been dropped as the DOM never actually exposed entity references in practice.

  • In the previous edition of DOM Traversal both these methods threw a "NotSupportedError" when the root was null. Now this will throw a language-binding specific exception.

  • In the previous edition of DOM Traversal both these methods did not have optional arguments. That was changed for convenience.

acceptNode() and its constants have been changed to use unsigned short, rather than just short.

The expandEntityReferences attribute has been removed from the NodeIterator and TreeWalker objects.

The referenceNode and pointerBeforeReferenceNode attributes have been added to NodeIterator objects to align with user agents.

nextNode() and previousNode() node now throw when invoked from a NodeFilter to align with user agents.

References

Normative references

[IANACHARSET]
Character Sets. IANA.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[WEBIDL]
Web IDL, Cameron McCormack. W3C.
[XML]
Extensible Markup Language, Tim Bray, Jean Paoli, C. M. Sperberg-McQueen et al.. W3C.
[XMLNS]
Namespaces in XML, Tim Bray, Dave Hollander, Andrew Layman et al.. W3C.

Informative references

[CSSOMVIEW]
CSSOM View, Glenn Adams, Shane Stephens and Anne van Kesteren. W3C.
[DOM2TR]
Document Object Model (DOM) Level 2 Traversal and Range Specification, Joe Kesselman, Jonathan Robie, Mike Champion et al.. W3C.
[DOM3CORE]
Document Object Model (DOM) Level 3 Core Specification, Arnaud Le Hors, Philippe Le Hégaret, Lauren Wood et al.. W3C.
[DOM3EVENTS]
Document Object Model (DOM) Level 3 Events Specification, Doug Schepers and Jacob Rossi. W3C.
[DOMPS]
DOM Parsing and Serialization, Ms2ger. WHATWG.
[ELEMENTTRAVERSAL]
Element Traversal Specification, Doug Schepers. W3C.
[HTML]
HTML5, Ian Hickson. W3C.

Acknowledgments

Thanks to Adam Klein, Adrian Bateman, Arun Ranganathan, Boris Zbarsky, Brandon Slade, Cameron McCormack, Dethe Elza, David Flanagan, Erik Arvidsson, Glenn Maynard, Henri Sivonen, Jacob Rossi, Jake Verbaten, James Graham, Jens Lindström, João Eiras, Jonas Sicking, 呂康豪 (Kang-Hao Lu), Kevin Sweeney, Manish Tripathi, Ojan Vafai, Olli Pettay, Ryosuke Niwa, Shiki Okasaka, Stig Halvorsen, and Travis Leithead for their useful comments.

Special thanks to Geoffrey Sneddon and Simon Pieters for first specifying the Nodes section of this specification and their useful comments.

Special thanks also to Ian Hickson for first specifying some parts of this specification in HTML and his useful comments. [HTML]

Finally, while this specification has been written from scratch, special thanks should also be extended to the editors of the various specifications that previously defined the features in this specification: Arnaud Le Hors, Björn Höhrmann, Doug Schepers, Gavin Nicol, Joe Kesselman, Jonathan Robie, Lauren Wood, Mike Champion, Peter Sharpe, Philippe Le Hégaret, Robin Berjon, Steve Byrne, Tom Pixley, and Vidur Apparao.


Check Update

DOM Specifications

Book Name: DOM

Book Title: DOM Specifications

Current Version: June 01,2012

Check Update: http://www.HeroNote.com/files/DOM.htm

e-Book Update Manager:


[File List]

 index.htm index.htm logo-WG-Note.png spec.css w3c_home.png W3C-WG-NOTE.css index.htm back.jpg forward.jpg table.gif up.jpg w3c_home.gif contributors.html copyright-notice.html cover.html def-index.html ecma-script-language-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html introduction.html java-binding.zip java-language-binding.html level-one-core.html level-one-html.html production-notes.html references.html spec.css xml-source.zip REC.gif table.gif w3c_home.gif acknowledgements.html changes.html copyright-notice.html core.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html i18n.html idl.zip idl-definitions.html introduction.html java-binding.html java-binding.zip Overview.html references.html spec.css W3C-REC.css xml-source.zip REC.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css views.html W3C-REC.css xml-source.zip REC.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html events.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css W3C-REC.css xml-source.zip REC.gif w3c_home.gif acknowledgements.html copyright-notice.html css.html def-index.html ecma-script-binding.html expanded-toc.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css stylesheets.html W3C-REC.css xml-source.zip RangeExample.gif REC.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html ranges.html references.html spec.css traversal.html W3C-REC.css xml-source.zip logo-REC.gif w3c_home.gif acknowledgements.html changes.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html html.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css W3C-REC.css xml-source.xml dom-architecture.png dom-architecture.svg REC.gif table.png table.svg w3c_home.gif wholeTextExmpl.png wholeTextExmpl.svg wholeTextExmpl2.png wholeTextExmpl2.svg wholeTextExmpl3.png wholeTextExmpl3.svg accessing-code-point-boundaries.html acknowledgements.html changes.html configuration-settings.html copyright-notice.html core.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html infoset-mapping.html introduction.html java-binding.html java-binding.zip namespaces-algorithms.html Overview.html references.html spec.css W3C-REC.css xml-source.xml REC.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip load-save.html Overview.html references.html spec.css W3C-REC.css xml-source.xml REC.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css validation.html validation-outcomes.html W3C-REC.css xml-source.xml logo-WG-Note.gif w3c_home.gif acknowledgements.html copyright-notice.html def-index.html ecma-script-binding.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip Overview.html references.html spec.css W3C-WG-NOTE.css xml-source.xml xpath.html index.htm logo-WG-Note.png spec.css w3c_home.png W3C-WG-NOTE.css index.htm index.htm index.htm index.htm index.htm index.htm index.htm index.htm eventflow.png eventflow.svg logo-WG-Note.gif w3c_home.gif acknowledgements.html changes.html copyright-notice.html def-index.html ecma-script-binding.html events.html expanded-toc.html glossary.html idl.zip idl-definitions.html java-binding.html java-binding.zip keyset.html Overview.html references.html spec.css W3C-WG-NOTE.css xml-source.xml index.htm logo-NOTE.png spec.css w3c_home.png W3C-NOTE.css index.htm index.htm index.htm index.htm index.htm index.htm index.htm index.htm index.htm B31A07C961.htm logo-WD.png w3c_home.png W3C-WD.css index.htm


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • 1. Document Object Model Views
    • 1.1. Introduction
    • 1.2. Interfaces
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
    • D.1. Production Systems
  • References
    • 1. Normative references
  • Index
previous next contents index


Document Object Model (DOM) Level 1 Specification

Version 1.0

W3C Recommendation 1 October, 1998

This version
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/DOM.ps
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/DOM.pdf
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/DOM.tgz
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/DOM.zip
http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/DOM.txt
Latest version
http://www.w3.org/TR/REC-DOM-Level-1
Previous versions
http://www.w3.org/TR/1998/PR-DOM-Level-1-19980818
http://www.w3.org/TR/1998/WD-DOM-19980720
http://www.w3.org/TR/1998/WD-DOM-19980416
http://www.w3.org/TR/WD-DOM-19980318
http://www.w3.org/TR/WD-DOM-971209
http://www.w3.org/TR/WD-DOM-971009
WG Chair
Lauren Wood, SoftQuad, Inc.
Editors
Vidur Apparao, Netscape
Steve Byrne, Sun
Mike Champion, ArborText
Scott Isaacs, Microsoft
Ian Jacobs, W3C
Arnaud Le Hors, W3C
Gavin Nicol, Inso EPS
Jonathan Robie, Texcel Research
Robert Sutor, IBM
Chris Wilson, Microsoft
Lauren Wood, SoftQuad, Inc.
Principal Contributors
Vidur Apparao, Netscape
Steve Byrne, Sun (until November 1997)
Mike Champion, ArborText, Inc.
Scott Isaacs, Microsoft (until January, 1998)
Arnaud Le Hors, W3C
Gavin Nicol, Inso EPS
Jonathan Robie, Texcel Research
Peter Sharpe, SoftQuad, Inc.
Bill Smith, Sun (after November 1997)
Jared Sorensen, Novell
Robert Sutor, IBM
Ray Whitmer, iMall
Chris Wilson, Microsoft (after January, 1998)

Status of this document

This document has been reviewed by W3C Members and other interested parties and has been endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.

The authors of this document are the DOM Working Group members, different chapters may have different editors.

Comments on this document should be sent to the public mailing list www-dom@w3.org.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Errata

The list of known errors in this document is found at http://www.w3.org/DOM/updates/REC-DOM-Level-1-19981001-errata.html.

Available Languages

The English version of this specification is the only normative version. However, for translations in other languages see http://www.w3.org/DOM/updates/REC-DOM-Level-1-translations.html.

Abstract

This specification defines the Document Object Model Level 1, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model provides a standard set of objects for representing HTML and XML documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating them. Vendors can support the DOM as an interface to their proprietary data structures and APIs, and content authors can write to the standard DOM interfaces rather than product-specific APIs, thus increasing interoperability on the Web.

The goal of the DOM specification is to define a programmatic interface for XML and HTML. The DOM Level 1 specification is separated into two parts: Core and HTML. The Core DOM Level 1 section provides a low-level set of fundamental interfaces that can represent any structured document, as well as defining extended interfaces for representing an XML document. These extended XML interfaces need not be implemented by a DOM implementation that only provides access to HTML documents; all of the fundamental interfaces in the Core section must be implemented. A compliant DOM implementation that implements the extended XML interfaces is required to also implement the fundamental Core interfaces, but not the HTML interfaces. The HTML Level 1 section provides additional, higher-level interfaces that are used with the fundamental interfaces defined in the Core Level 1 section to provide a more convenient view of an HTML document. A compliant implementation of the HTML DOM implements all of the fundamental Core interfaces as well as the HTML interfaces.

Table of contents

  • Expanded Table of Contents
  • Copyright Notice
  • What is the Document Object Model?
  • Chapter 1: Document Object Model (Core) Level 1
  • Chapter 2: Document Object Model (HTML) Level 1
  • Appendix A: Contributors
  • Appendix B: Glossary
  • Appendix C: IDL Definitions
  • Appendix D: Java Language Binding
  • Appendix E: ECMA Script Language Binding
  • References
  • Index
  • Production Notes (Non-Normative)


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • Chapter 1: Document Object Model Style Sheets
    • 1.1. Introduction
    • 1.2. Style Sheet Interfaces
    • 1.3. Document Extensions
    • 1.4. Association between a style sheet and a document.
  • Chapter 2: Document Object Model CSS
    • 2.1. Overview of the DOM Level 2 CSS Interfaces
    • 2.2. CSS Fundamental Interfaces
      • 2.2.1. Override and computed style sheet
      • 2.2.2. Style sheet creation
      • 2.2.3. Element with CSS inline style
    • 2.3. CSS2 Extended Interface
  • Appendix A: IDL Definitions
    • A.1. Document Object Model Style Sheets
    • A.2. Document Object Model CSS
  • Appendix B: Java Language Binding
    • B.1. Document Object Model Style Sheets
    • B.2. Document Object Model CSS
  • Appendix C: ECMAScript Language Binding
    • C.1. Document Object Model StyleSheets
    • C.2. Document Object Model CSS
  • Appendix D: Acknowledgements
    • D.1. Production Systems
  • References
    • 1. Normative references
    • 2. Informative references
  • Index
previous next contents index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • 1 Validation
    • 1.1 Overview
    • 1.2 Exceptions
    • 1.3 Document Editing Interfaces
  • Appendix A: Validation Outcomes
    • A.1 The nodeValidity and validateDocument methods
    • A.2 Other validation operations
  • Appendix B: IDL Definitions
  • Appendix C: Java Language Binding
  • Appendix D: ECMAScript Language Binding
  • Appendix E: Acknowledgements
    • E.1 Production Systems
  • Glossary
  • References
  • Index


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • 1. Document Object Model HTML
    • 1.1. Introduction
    • 1.2. HTML Application of Core DOM
      • 1.2.1. Naming Conventions
    • 1.3. XHTML and the HTML DOM
    • 1.4. Miscellaneous Object Definitions
    • 1.5. Objects related to HTML documents
    • 1.6. HTML Elements
      • 1.6.1. Property Attributes
      • 1.6.2. Naming Exceptions
      • 1.6.3. Exposing Element Type Names (tagName, (nodeName))
      • 1.6.4. The HTMLElement interface
      • 1.6.5. Object definitions
  • Appendix A: Changes
    • A.1. Changes between DOM Level 1 and DOM Level 2
      • A.1.1. Changes to DOM Level 1 interfaces and exceptions
      • A.1.2. New Interfaces
  • Appendix B: IDL Definitions
  • Appendix C: Java language Binding
  • Appendix D: ECMAScript Language Binding
  • Appendix E: Acknowledgements
    • E.1. Production Systems
    • E.2. DOM Level 1
  • Glossary
  • References
    • 1. Normative references
    • 2. Informative references
  • Index
previous next contents index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • 1 Document Object Model Load and Save
    • 1.1 Overview of the Interfaces
    • 1.2 Basic Types
      • 1.2.1 The LSInputStream Type
      • 1.2.2 The LSOutputStream Type
      • 1.2.3 The LSReader Type
      • 1.2.4 The LSWriter Type
    • 1.3 Fundamental Interfaces
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
    • D.1 Production Systems
  • Glossary
  • References
    • 1 Normative References
    • 2 Informative References
  • Index


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • What is the Document Object Model?
    • Introduction
    • What the Document Object Model is
    • What the Document Object Model is not
    • Where the Document Object Model came from
    • Entities and the DOM Core
    • Conformance
    • DOM Interfaces and DOM Implementations
  • 1. Document Object Model Core
    • 1.1. Overview of the DOM Core Interfaces
      • 1.1.1. The DOM Structure Model
      • 1.1.2. Memory Management
      • 1.1.3. Naming Conventions
      • 1.1.4. Inheritance vs. Flattened Views of the API
      • 1.1.5. The DOMString type
      • 1.1.6. The DOMTimeStamp type
      • 1.1.7. String comparisons in the DOM
      • 1.1.8. XML Namespaces
    • 1.2. Fundamental Interfaces
    • 1.3. Extended Interfaces
  • Appendix A: Changes
    • A.1. Changes between DOM Level 1 Core and DOM Level 2 Core
      • A.1.1. Changes to DOM Level 1 Core interfaces and exceptions
      • A.1.2. New features
  • Appendix B: Accessing code point boundaries
    • B.1. Introduction
    • B.2. Methods
  • Appendix C: IDL Definitions
  • Appendix D: Java Language Binding
  • Appendix E: ECMAScript Language Binding
  • Appendix F: Acknowledgements
    • F.1. Production Systems
  • Glossary
  • References
    • 1. Normative references
    • 2. Informative references
  • Index
previous next contents index


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • Chapter 1: Document Object Model Traversal
    • 1.1. Overview
      • 1.1.1. NodeIterators
      • 1.1.2. NodeFilters
      • 1.1.3. TreeWalker
    • 1.2. Formal Interface Definition
  • Chapter 2: Document Object Model Range
    • 2.1. Introduction
    • 2.2. Definitions and Notation
      • 2.2.1. Position
      • 2.2.2. Selection and Partial Selection
      • 2.2.3. Notation
    • 2.3. Creating a Range
    • 2.4. Changing a Range's Position
    • 2.5. Comparing Range Boundary-Points
    • 2.6. Deleting Content with a Range
    • 2.7. Extracting Content
    • 2.8. Cloning Content
    • 2.9. Inserting Content
    • 2.10. Surrounding Content
    • 2.11. Miscellaneous Members
    • 2.12. Range modification under document mutation
      • 2.12.1. Insertions
      • 2.12.2. Deletions
    • 2.13. Formal Description of the Range Interface
  • Appendix A: IDL Definitions
    • A.1. Document Object Model Traversal
    • A.2. Document Object Model Range
  • Appendix B: Java Language Binding
    • B.1. Document Object Model Traversal
    • B.2. Document Object Model Range
  • Appendix C: ECMAScript Language Binding
    • C.1. Document Object Model Traversal
    • C.2. Document Object Model Range
  • Appendix D: Acknowledgements
    • D.1. Production Systems
  • Glossary
  • References
    • 1. Normative references
  • Index
previous next contents index


Expanded Table of Contents

  • Expanded Table of Contents
  • Copyright Notice
    • W3C Document Copyright Notice and License
    • W3C Software Copyright Notice and License
  • 1. Document Object Model Events
    • 1.1. Overview of the DOM Level 2 Event Model
      • 1.1.1. Terminology
    • 1.2. Description of event flow
      • 1.2.1. Basic event flow
      • 1.2.2. Event capture
      • 1.2.3. Event bubbling
      • 1.2.4. Event cancelation
    • 1.3. Event listener registration
      • 1.3.1. Event registration interfaces
      • 1.3.2. Interaction with HTML 4.0 event listeners
    • 1.4. Event interface
    • 1.5. DocumentEvent interface
    • 1.6. Event module definitions
      • 1.6.1. User Interface event types
      • 1.6.2. Mouse event types
      • 1.6.3. Key events
      • 1.6.4. Mutation event types
      • 1.6.5. HTML event types
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
    • D.1. Production Systems
  • Glossary
  • References
    • 1. Normative references
  • Index
previous next contents index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • 1 Document Object Model XPath
    • 1.1 Introduction
    • 1.2 Mapping DOM to XPath
      • 1.2.1 Element Nodes
      • 1.2.2 Attribute Nodes
      • 1.2.3 Namespace Nodes
      • 1.2.4 Text Nodes
      • 1.2.5 Entity Reference Nodes
      • 1.2.6 Comment Nodes
      • 1.2.7 Processing Instruction Nodes
      • 1.2.8 Document order
    • 1.3 Conformance
    • 1.4 Interfaces
  • Appendix A: IDL Definitions
  • Appendix B: Java Language Binding
    • B.1 Other XPath interfaces
  • Appendix C: ECMAScript Language Binding
  • Appendix D: Acknowledgements
    • D.1 Production Systems
  • Glossary
  • References
    • 1 Normative references
    • 2 Informative references
  • Index


Expanded Table of Contents

  • Expanded Table of Contents
  • W3C Copyright Notices and Licenses
    • W3C® Document Copyright Notice and License
    • W3C® Software Copyright Notice and License
    • W3C® Short Software Notice
  • 1 Document Object Model Events
    • 1.1 Introduction
      • 1.1.1 Event flows
      • 1.1.2 Conformance
    • 1.2 DOM event flow
      • 1.2.1 Phases
      • 1.2.2 Event listeners
    • 1.3 Default actions and cancelable events
    • 1.4 Event types
      • 1.4.1 Event types and event categories
      • 1.4.2 Complete list of event types
      • 1.4.3 Compatibility with DOM Level 2 Events
    • 1.5 Event listener registration
      • 1.5.1 Using the EventTarget methods
      • 1.5.2 Using XML Events
      • 1.5.3 Using VoiceXML Events
      • 1.5.4 Using XML or HTML attributes
    • 1.6 Basic interfaces
      • 1.6.1 Event creation
    • 1.7 Event module definitions
      • 1.7.1 User Interface event types
      • 1.7.2 Text events types
      • 1.7.3 Mouse event types
      • 1.7.4 Keyboard event types
      • 1.7.5 Mutation and mutation name event types
      • 1.7.6 Basic event types
      • 1.7.7 HTML Events
  • Appendix A: Keyboard events and key identifiers
    • A.1 Introduction
      • A.1.1 Modifier keys
      • A.1.2 Dead keys
      • A.1.3 Input Method Editors
      • A.1.4 Guidelines for defining key identifiers
    • A.2 Key identifiers set
  • Appendix B: Changes
    • B.1 Changes between DOM Level 2 Events and DOM Level 3 Events
      • B.1.1 Changes to DOM Level 2 event flow
      • B.1.2 Changes to DOM Level 2 event types
      • B.1.3 Changes to DOM Level 2 Events interfaces
      • B.1.4 New Interfaces
  • Appendix C: IDL Definitions
  • Appendix D: Java Language Binding
  • Appendix E: ECMAScript Language Binding
  • Appendix F: Acknowledgements
    • F.1 Production Systems
  • Glossary
  • References
    • 1 Normative references
    • 2 Informative references
  • Index