Technical Reports . Technical Materials
Test Suites . FAQ . Mailing List
Member-restricted resource: DOM Working Group
About DOM .
DOM Activity statement
Technical Reports .
Technical Materials
Test Suites . FAQ
. Mailing List
Member-restricted resource: DOM Working Group
This document contains the most frequently asked questions about the Document Object Model. It is not intended to replace any specifications or other documents. Please send suggestions or comments about this FAQ to the address above.
(Note: We maintain this document's source as faq.xml, using the markup language defined by faq.dtd. This XHTML version is generated from that source using faq.xsl.)
The Document Object Model. This means that we are developing a model in which the document or Web page contains objects (elements, links, etc.) that can be manipulated. So you will be able to delete, add, or change an element (as long as the document is still valid, of course!), change its content or add, delete or change an attribute. You will be able to get a list of all the H1 elements in the document, or all the elements with an attribute CLASS="foo".
The DOM API provides a standardized, versatile view of a document's contents. By supporting the DOM API, a program not only allows its data to be manipulated by other routines, but does so in a way that allows those manipulations to be reused with other DOMs, or to take advantage of solutions already written for those DOMs. This interoperability also allows programmers who invest in learning to use the DOM calls to apply those skills to other DOMs.
The intent is that -- if you stick with the standardized APIs -- any DOM implementation can be plugged together with any DOM-based application. The original example of this was dynamic-HTML scripts; by agreeing on the DOM as their standard representation of the document, scripts can be be written that will work properly on all browsers. But this applies to larger-scale programming as well; for example, a server-side solution might be built out of the following reusable components, which may or may not all share a single DOM implementation:
If a better implementation of one of these modules becomes available (a faster XML parser, for example) or if an additional/different processing stage is required, you should be able to unplug the existing connections and plug in the new component with minimal recoding.
(The goal is "no recoding", and that is already the case for many applications, but at this writing the DOM Level 2 APIs are not yet complete enough to promise this for all applications. In particular, some of the tools needed to construct a DOM "from scratch" are not yet exposed in the published APIs, and the DOM has not yet defined a representation for the DTD/Schema information.)
Similarly, while all DOM implementations should be interoperable, they may vary considerably in code size, memory demand, and performance of individual operations. So the ability to unplug and replace the DOM itself may also be very useful. For example, since some parsers can write into a user-provided DOM, you may be able to parse a document directly into the above-mentioned database.
There is one potential downside to using the DOM: As with any generalized set of interfaces, the DOM calls can be used to solve a very wide range of problems, but may not be the optimal solution for any specific problem. The advantages of interoperability and familiarity to users will more than compensate for this in many applications, but you will find that some tasks may call for other interfaces in addition to, or instead of, the DOM. For example, your application may wish to use custom interfaces internally for performance reasons, yet be able to import/export/expose its data via the DOM for convenient access from outside.
The DOM Level 1 and Level 2 specifications are W3C Recommendations. This means that the specification is final and can be implemented without fear of things changing. Level 1 allows navigation around an HTML or XML document, and manipulation of the content in that document. Level 2 extends Level 1 with a number of features: XML Namespace support, filtered views, ranges, events, etc. Level 3 is currently a Working Draft, which means that it is under active development and subject to change as we continue to refine it.
A DOM implementation (also called a host implementation) is that piece of software which takes the parsed XML or HTML document and makes it available for processing via the DOM interfaces. A browser contains a hosting implementation, for example.
A DOM application (also called a client application) is that piece of software which takes the document made available by the implementation, and does something to it. A script which runs in a browser is an example of an application.
This will depend on what hosting implementation you want to use it with. Your favorite browser might implement a JavaScript or VBScript interface, so you can use those scripting languages within the page itself to manipulate the page or change the CSS style sheet. Your favorite editor might implement a Scheme or Java interface so you can write an executable in those languages that talks to your editor to manipulate the page. You might be able to write an application in C++ that uses the DOM interface to transfer information from the page in your browser to a database via an ODBC driver. We are writing a set of interfaces; different companies will be able to implement these interfaces in different ways. It is unlikely that any one company will give you a choice of C++ and Java and Scheme and Perl and Python and ..., but interfaces in all these languages will be possible, since the DOM itself is language-neutral.
The Object Management Group Interface Definition Language (OMG IDL) was chosen as it was designed for specifying language and implementation-neutral interfaces. Various other IDLs could be used; the use of OMG IDL does not imply a requirement to use a specific object binding runtime.
We expect that the DOM can be implemented using CORBA, COM, or Java Virtual Machine runtime bindings. We expect that many implementations of the DOM will use bindings to various programming languages. The DOM specifies bindings for Java and ECMAScript (the standardization of JavaScript/JScript by the European Computer Manufacturer's Association (ECMA) defined by ECMA-262) as appendices to the specification; other language bindings (for example, ANSI C++, Perl, or VBScript) may be supplied by other interested parties. Obviously it would be good if different implementations in other languages are consistent with each other.
Although questions about the DOM may be posted in other forums, it would be best to post them to the public mailing list at www-dom@w3.org. To subscribe, send mail to www-dom-request@w3.org with the subject "subscribe". Please read this FAQ before posting any questions.
Read the specifications up on the Web site, and send email to www-dom@w3.org. We will update the specifications as often as we can.
See the Activity statement for a description of what the DOM WG is currently working on.
Yes. W3C and the member organizations that make up W3C are concerned with accessibility. The DOM will make it much easier for accessibility tools to access documents, since they will be able to take a document and feed it into an accessibility-enabled application, such as a screen reader.
The DOM will not change other standards, or redefine standards. The DOM will have clean interfaces to other relevant specifications. The DOM WG works together with other groups, as far as possible, to make sure various specifications are consistent.
The Document Object Model, despite its name, is not an object model in the same way as the Component Object Model (COM). The COM, like CORBA, is a language-independent way to specify interfaces and objects; the Document Object Model 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 that we define.
There will be two ways of using the HTML module of the DOM. You might write JavaScript or VBScript in your page. Or, you might use an external application such as a plug-in, ActiveX control, or Java applet, that accesses the document through your browser (support depends on the browser).
Dynamic HTML (DHTML) is a term used by some vendors to describe the combination of HTML, style sheets and scripts that allows documents to be animated. The scripting interfaces provided in DHTML have a significant overlap with the DOM, particularly with the HTML module. Compatibility with DHTML was a motivating factor in the development of the DOM. The DOM, however, is more than DHTML. It is a platform- and language-neutral interface that will allow programs and scripts to dynamically access and update the content, structure and style of documents, both HTML and XML.
In general your pages should not be broken, if you want to be able to use the DOM to get consistent results. It's the same right now - if you mix JavaScript or VBScript with a broken HTML page, you can get some odd results.
A DOM-compliant document model is one that responds to all the
DOM API calls with the results documented in a specific Level of
the DOM Recommendation. You are not required to implement the
optional modules (XML, HTML, Stylesheet, CSS, Traversal, Ranges,
Events or the specific event sets) in order to claim compliance,
but if your DOM does not completely implement these it should
respond "false" to the relevant
hasFeature queries. For example, a DOM which implements
just the Level 1 APIs plus the
importNode method would be compliant only with Level 1,
since it does not have complete support for Level 2.
In many situations, it is possible and desirable to add features to a DOM without breaking compliance. The simplest and safest way to do so is to define a new set of APIs which the objects in your customized DOM could support, so the behavior of the standard DOM API can be left unchanged. The HTML DOM is a good example of this approach; it defined a set of custom subclasses of standard DOM objects, each of which continues to respect the core DOM behaviors but also supports additional behaviors.
Some developers are starting to reuse portions of the DOM API without promising 100% DOM compliance. For example, some people have written DOM subsets (read-only DOMs, for example), or have used portions of the DOM API to build other kinds of node trees, or even mixed their own custom nodetypes with those defined by the DOM. If designed and written well, these solutions may allow _limited_ interchange of code with standard DOMs -- for example, all reasonable programs that work on a read-only DOM should run just as well on a "real" DOM, though the reverse is obviously not true. However, since the DOM's greatest value is that it promotes interoperability, such changes to the DOM's behavior should be avoided if at all possible, and will not be recognized as fully compliant implementations of the DOM.
The DOM Level 2 specifies a way to manipulate and change CSS stylesheets. There is also core functionality for linking style sheets in any stylesheet language to an XML or HTML file. A similar interface to XSL stylesheets may be specified later on, perhaps not by the DOM WG.
The object model in the DOM is a programming object model that comes from object-oriented design. It refers to the fact that the interfaces are defined in terms of objects. In the DOM work, we call the object model that groves specify an abstract data model. There is an implicit data model in the DOM, but implementors do not have to use this to implement the interfaces. The data model in the DOM is specified in the Information Set specification.
A future Level of the DOM is expected to include a query interface, so that you will be able to interface to whatever query language your DOM implementation supports. W3C is working on a query language, so the DOM WG does not need to specify this.
Other groups are designing DOM modules that work with the DOM specification and give extra functionality for particular markup languages. Examples are the MathML DOM for use with MathML, the SVG DOM for use with SVG, and the SMIL DOM. These DOM modules are being designed by the groups responsible for designing those languages.
DOM and SAX are currently the two most popular APIs for manipulating XML documents. They differ significantly in provenance, in scope, and in programming style. They are not in direct competition with each other; each has strengths and weaknesses.
Provenance:Unlike the DOM, SAX ("Simple API for XML") is not being developed by the World Wide Web Consortium. Instead, it was developed by an informal group of participants of the XML-DEV mailing list. SAX 1 has been fairly widely supported by providers of XML processing software. SAX 2, now being developed, is not yet widely supported, and at this writing diverges significantly from SAX 1, though it includes the SAX 1 APIs for backward-compatibility purposes.
Scope:SAX was originally designed specifically as an API for XML parsers. As such, it includes functions which won't be supported in the DOM until DOM Level 3's Load/Save module is released. On the other hand, SAX 1 discarded some information (such as comments) that the DOM retains. As with the DOM, later versions of SAX are working to improve their coverage of the XML Information Set.
Style:The most important difference between SAX and DOM is that SAX presents the document as a serialized "event stream" (a sequence of calls to a handler function as each chunk of XML syntax is recognized) rather than the DOM's tree. A major disadvantage of this approach is that SAX does not support random-access manipulation of the document -- you see the tokens once, in document order, and that's it. If you might want to refer back to anything you saw earlier, it's your code's responsibility to store that information so you can retrieve it. But this requirement that you invent your own document model means you can decide to discard information that will not be needed, which can result in reduced memory overhead versus retaining a complete model such as the DOM.
However, depending on the task you're trying to perform, SAX may not always have a storage-size advantage. And one should remember that DOM implementations vary in their memory requirements, just as they do in code size and performance. Some are more compact than others, and some do not keep the whole document in main memory at once.
So how should you decide between SAX events and DOM trees? If you intend to allow other code, such as utility routines, middleware, applications, and scripts within the document, to explore and possibly alter the document's contents, the DOM is almost certainly the way to go; it provides a W3C-standardized, complete, and editable view of the document's contents. Conversely, if your task processes the document on a straight-line flow-through basis, without permitting users to write "scripts" against it and without needing much contextual information at each stage -- for example, if you're parsing the XML document directly into a database for storage -- SAX may provide a more direct interface to the parser. Between these extremes, it's a judgement call; you have to think about how much trouble it will be to implement your own document model versus using the DOM, and about how you expect your application to grow in the future.
In fact, it is possible to combine SAX and DOM within a single system. Many parsers can produce both SAX and DOM output, and some have borrowed SAX's parser-control calls as a stopgap while they wait for the DOM 3 Load/Save API to be defined. Despite the slight "impedance mismatch" between them, it is not uncommon to use a SAX stream as input to a DOM builder, or to use a DOM's contents to generate SAX events; code for both these operations is widely available. There are also some new APIs being developed which combine SAX and DOM in interesting ways, for example returning DOM nodes from SAX operations.
Full details are in the DOM specification. A brief summary follows:
If you are implementing the interfaces defined by DOM, then you must use the official package name of those interfaces, which, by definition, is "org.w3c.dom". If you add any additional interfaces or change the interfaces in any way, they may not start with "org.w3c.dom" - they have to be in a different package.
You will need a DOM implementation which supports the Java bindings. Check the documentation for the implementation you're interested in to make sure this is the case. The documentation should also include information as to how to use the Java bindings.
The DOM specification does not define any methods related to memory management (such as to release an object). This is because while the DOM is a programming language independent API, the way one deals with memory is very language specific. Therefore any method related to memory management that is required by a particular language, needs to be specified in that language binding. Due to the way memory is managed in Java and ECMAScript, none of the bindings included in the DOM specification have such methods.
NodeList, although it resembles an array or vector (it
has a length attribute, and you can access the members of the list
via an integer index), is _not_ an array. Think of it instead as
another way of looking at the DOM's document tree. If that tree
changes -- if something inserts or appends or removes
Nodes -- the
NodeList will be automatically adjusted at the same
time. The result is that a
NodeList is always an accurate representation of the
getChildNodes or
getElementsByTagName results as if you had just issued
that call, so there is no need to refresh the
NodeList to pick up changes to the underlying
document.
In MVC terminology, the underlying document tree is the "Model",
the DOM API that allows the tree to be modified is the
"Controller", and each
NodeList is a "View" of Model. In other words, the
NodeList is not something separate from the document
tree that needs to be kept in synch with the tree, but a view of
the actual tree with array-like semantics that may be more
convenient for some tasks than the tree-like semantics of the DOM
Node hierarchy.
This means there is no need to refresh the nodes of a
NodeList as a document changes. The fact that the
indexed nodes of a
NodeList returned by
getChildNodes or
getElementsByTagName are automatically updated so that
they are always correct as descendants are inserted or removed can
be convenient, but it can also cause the index and count of nodes
in the list to shift unexpectedly. Some DOM implementations may
perform the automatic updating poorly.
For example, a loop that removes a node from the hierarchy causes the next node to slide to the current index and the length to shrink. This could cause the next node to be skipped and the end of the list to be overshot. This can be avoided by decrementing the index from length - 1 to 0 instead of incrementing from 0. Decrementing processes each node before it can shift. To properly use a loop that starts at 0, whenever a removal occurs, the index must not be incremented, but the maximum index must be decremented instead.
Different DOM implementations will process
NodeLists differently, so getting nodes in
non-sequential order, getting the list length, or intermixing
document modification could affect the performance of the
application. Some DOM implementations might force the list to be
completely recomputed every time a change occurs to the document.
These problems can be avoided. For example, random access is seldom
required and the length is not really needed if a loop terminates
when the returned item is null. Constructing a loop to avoid
accessing shifted nodes makes the implementation less likely to
have to do a fix up. In some cases, copying nodes of a
NodeList to a static list before modifying the document
may be the best way to avoid index shifts and recomputations.
DOMException (WRONG_DOCUMENT_ERR) when you attempt to
do so. Exposing ownerDocument introduced no additional
constraints... and added significant value, e.g. by allowing you to
write
myNode.appendChild(myNode.getOwnerDocument().createTextNode("new
child")); even when myNode is not currently part of the
Document's main tree.parent.appendChild(newchild.clonenode(true)) do if
parent and newchild have different
ownerDocument values?DOMException (WRONG_DOCUMENT_ERR) if an attempt is made
to insert a node from one ownerDocument into a tree with a
different ownerDocument. Some DOM implementations may allow this
code fragment to work in specific circumstances, when they know
that the underlying representation of the nodes is compatable, but
that is considered non-compliant behavior.Yes. The elements will always be in document order.
The DOM Level 3 API specifies an interoperable way to parse and save documents.
In Level 1, you must use vendor-specific solutions, since the Level 1 DOM did not define how to create a Document. Level 2 does define how to create a new Document.
Attr is a Node because its value is actually carried by
its children, which may be a mixture of
Text and
EntityReference nodes, and because making it a
Node allows us to store it in a
NamedNodeMap for easy retrieval.
The
getAttribute method hides this detail by returning a
string representing the concatenation of all these children, and
similarly
setAttribute replaces the
Attr's contents with a single
Text node holding the new string. To create or
manipulate other children of an
Attr, you have to access the
Attrnode directly via the
getAttributeNode and
setAttributeNode methods, or by retrieving it from the
element's "attributes"
NamedNodeMap.
Section 1.1.1 of the Level 1 DOM Recommendation gives a list of
which nodes can be parents and children of which other nodes.
Attr is not a legal child of any node, so attempts to
insert it as one will throw a
DOMException (HIERARCHY_REQUEST_ERR).
There is, but it's called
removeAttributeNode.
We needed both
setAttributeNode and
setAttributeNodeNS, because those functions use
different rules to select which (if any) existing
Attr the new one will replace.
setAttributeNode bases this decision on the
nodeName, while
setAttributeNodeNS looks at the combination of
namespaceURI and localname. However, when you remove a specific
AttrNode, its
nodeName,
localname, and
namespaceURI are ignored, and there's no need for a
second method to support this.
In XML, all whitespace has to be passed through to the application. This means that if you have whitespace, such as carriage returns, between tags in your source file, these have to be passed through, even if they're just there for pretty-printing. The DOM implementation has to put this whitespace somewhere, and the only possibility is a text node. Thus you will get text nodes which look empty, but in fact have a carriage return or other whitespace in them.
Note that some DOM implementations, which do not consider whitespace in element content to be meaningful for the XML languages they support, discard these whitespace nodes before exposing the DOM to their users.
See also the parameter "element-content-whitespace" in the
DOMConfiguration interface provided by DOM Level 3.
The DOM structure model that is created by whatever it is that
creates it has one Text node per block of text when it starts. The
only way you can have adjacent Text nodes is as a result of user
operations; it is not an option for the DOM implementation when it
first presents its structure model to the user. The
normalize method (on the
Element interface in level 1, but moved to
Node for Level 2) will merge all the adjacent Text
nodes into one again, so they will have the same form as if you
wrote out the XML or HTML and then read it in again. Note that this
will have no effect on CDATA Sections.
A filtered view of a document, such as that obtained through use of TreeWalker, may have adjacent Text nodes because the intervening Nodes are not seen in that view.
To change a CDATA section into a Text node, you have to copy the
content of the CDATA section node into a string (using the
data attribute that is inherited from the
CharacterData interface). Create a Text node with that
content (using the
createTextNode method on the
Documentinterface). Find the parent of the
CDATASection node. Then replace the CDATA Section node with the
Text node (either by inserting the Text node and deleting the CDATA
Section node, or using the
replaceChild method on the
Node interface). You may then wish to call the
normalize method (on
Element in Level 1, but on
Node in Level 2), to merge any adjacent Text nodes.
See also the parameter "cdata-sections" in the
DOMConfiguration interface provided by DOM Level 3.
Interfaces are widely used in many object-oriented languages, for example Java, and have several advantages when designing an API. They are similar to abstract classes, but all the methods are abstract. Variables in an interface must be constants. The key point with interfaces is that they do not constrain implementations. The methods defined in an interface must give the correct results, but the implementation is free to do anything it needs to. Thus, for example, even if one interface inherits from another, this does not mean that the implementation must share any code.
Interfaces are implemented by classes. Any given class is free to implement more than one interface (e.g., an interface specified by the DOM and some extensions). When a class implements more than one interface, it must provide an implementation for all the abstract methods in each interface, but again, need not share code or any other implementation details.
In Level 2 we needed to add some more functionality to, for example, the Node interface. There are several choices for how to add new functionality to an existing interface. One is to define a new interface, say Node2, and have it inherit from Node, adding the new methods. Another possibility is to have the Node2 interface copy all the existing methods from Node, rather than inheriting them. Another method is to extend the interfaces.
All three of these methods have advantages and disadvantages, which vary according to the language binding you are using. One big disadvantage of the inheritance method is the diamond inheritance you get when, for example, Document2 is created, which inherits both from Document (which inherits from Node) and from Node2. But Node2 also inherits from Node. The problem will only get worse as we design Level 3, Level 4, etc of the DOM. This inheritance also necessitates a lot of casting, and the user has to know which precise interface a method was defined on, to know what to cast the result to.
Copying all the methods leads to bloated interfaces, since many methods will be present many times (again, this problem gets worse as we design more Levels of the DOM).
Adding new methods to existing interfaces where appropriate does not work in all languages, but those languages which need a different way of doing things are expressly allowed to do so by the DOM specification. It avoids the problems of diamond inheritance and excessive casting, and cuts down on interface bloat.
That may work in some implementations of the DOM, but it isn't portable and should be avoided. Not all languages support this kind of runtime type identification. Even in languages which do, the results will depend on exactly how the DOM was implemented.
The specification does not guarantee that there is a one-to-one mapping from DOM interface to actual object type. It is entirely possible that a single class might have been written to implement more than one of the DOM interfaces. In such an implementation, the language features can't tell which of those interfaces is actually in use by a given instance of the class. For example, if the DOM developer decided to implement Text and Comment nodes using a single class, an instance of this class would be recognized as being a legitimate instance of both interfaces.
To reliably tell which kind of Node you're looking at, you should look at its nodeType value. To distinguish HTMLElements, look at their nodeName.
Visitor was considered for inclusion in the Traversal module of the Level 2 DOM. There are negative as well as positive consequences to implementing the Visitor pattern. One of Visitor's advantages over Iterator is that Visitor can handle structures where the objects don't share a common ancestor class, which is not an issue when everything you're looking at is derived from Node. Since most of the things a Visitor could do can be emulated with a switch statement driven by an iterator, we decided to defer this issue.
Neither Level 1 nor Level 2 allow you to move a Node from one
document to another, although Level 2 has an
importNode method which allows you to copy a Node from
one document to another. So, using Level 2, you copy the Node from
the source to the target document and then delete the Node from the
source document. If you want to do this in Level 1, you will need
to write your own function that creates a new Node in the target
document and then copies the data.
DOM Level 3 has
adoptNode() that will let you move a
Node from one
Document to another.
When elements or attributes which have namespace prefixes are moved, it's possible that the prefix no longer matches the same namespace URI. The DOM is always internally consistent, since each node carries its own namespace URI. It may or may not contain all the namespace declaration attributes in the right places, or have the prefixes matched up properly if those declarations do exist. The DOM is departing from canonical form, just a bit, in part because the DOM WG was concerned that continuously enforcing those restrictions could impose a significant amount of overhead. But it should contain all the data needed to allow reconciliation of those departures.
If you think about this as a
namespace_normalize() operation, it may make more
sense. In Level 2, that normalization task is left as an exercise
for the reader, but Level 3 is expected to provide a standardized
version.
The DOM assumes that an XML document which is read in is well-formed, since otherwise the XML processor which builds the DOM structure model has to stop with a fatal error, as per the XML specification. However, it is possible to carry out some editing operations using the DOM which would result in a non-WF XML document if the document were to be naively serialized. Examples are allowing "--" in comments, or not fixing up namespace URI / prefix bindings, or allowing the insertion of a character which isn't legal XML. If the document is serialized, the serializer is expected to fix the problem, e.g. by modifying the comment appropriately, or choosing an appropriate character encoding to make the character legal XML. This issue is expected to be resolved in Level 3.
DOM Level 3 provides the attributes
Document.xmlVersion,
Document.xmlStandalone and
Document.xmlEncoding for that effect.
DOM Level 3 provides the method
renameNode(). Some DOM implementations may have given
it special handling based on that information (like the subclasses
of HTMLElement), so the
Node being renamed might get destroyed and a new
Node is be returned.
The child node should be removed from its parent, then
reinserted in the same place, as if the call had actually been
parent.insertBefore(child,child.getNextSibling()).
Note that this is not considered a usage error; no
DOMexception is thrown. Nor is it necessarily a "no-op"
even though the document is left unchanged, since the removal and
reinsertion may have side effects -- for example,
MutationEvents may be fired, and
NodeIterator and
Range fixups may occur.
No! As explained in
section
1.1.8 XML Namespaces, they're different and not
really interoperable. DOM Level 1 methods solely identify attribute
nodes by their
nodeName while DOM Level 2 methods related to
namespaces, identify attribute nodes by their
namespaceURI and
localName. Unless you are writing a pure DOM 1.0
application, don't use the non-namespace-aware version of these
calls.
As mentioned in DOM Level 3, "DOM operations only raise
exceptions in "exceptional" circumstances, [...]
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.", therefore if an
attribute is declared unsigned, using a
negative should generate an error. Note that the error
itself is not defined and is therefore implementation and
binding dependent.