HTML 4.01 strict HTML
Visit Sourceforge.net

This page is the W3C DOM Parser Documentation main page. It contains general documentation about XML for <SCRIPT>'s W3C DOM Parser as well as links to the documentation for all of the objects provided by the W3C DOM Parser. The general documentation is located in the CONTENTS section below.

XML for <SCRIPT>'s W3C DOM Parser Documentation is divided into multiple segments. Each segment represents the documentation for one of the objects provided by XML for <SCRIPT>'s W3C DOM implementation. You may go directly to the documentation for a particular object by clicking one of the links in the W3C DOM PARSER OBJECT DOCUMENTATION section below.

NOTE: Some information contained in the documentation was sourced from http://xml.apache.org/xerces2-j/javadocs/api/index.html. This information is Copyright 1999-2003 Apache XML Project. All Rights Reserved.

Additional inspiration and fact cross-checking from http://www.devguru.com - a site I found very useful.


CONTENTS
How do I get started with the W3C DOM Parser?
Can I use XPath expressions with the W3C DOM Parser?
What files do I need to include to use the W3C DOM Parser?
What does the DOM Object Model look like?
How does the W3C DOM Parser handle Entity characters?
How does the W3C DOM Parser handle namespaces?
What W3C Dom Objects and methods supported?

W3C DOM PARSER OBJECT DOCUMENTATION
DOMAttr Object Documentation
DOMCDATASection Object Documentation
DOMCharacterData Object Documentation
DOMComment Object Documentation
DOMDocument Object Documentation
DOMDocumentFragment Object Documentation
DOMElement Object Documentation
DOMException Object Documentation
DOMImplementation Object Documentation
DOMNamedNodeMap Object Documentation
DOMNode Object Documentation
DOMNodeList Object Documentation
DOMProcessingInstruction Object Documentation
DOMText Object Documentation
DOMDocumentType Object Documentation (not implemented)
DOMEntity Object Documentation (not implemented)
DOMEntityReference Object Documentation (not implemented)
DOMNotation Object Reference (not implemented)
How do I get started with the W3C DOM Parser?

It's very easy, really. Let's say you have the following XML:

<?xml version="1.0"?>
<ROOTNODE>
<TAG1>
Hello World
</TAG1>
</ROOTNODE>

and you want to get the text out of the TAG1 tag. After including the appropriate .js files, you would simply create code that looked like the following:

function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node (in this case, it is ROOTNODE)
var docRoot = domDoc.getDocumentElement();

//get the first "TAG1" element
var firstTag1 = docRoot.getElementsByTagName("TAG1").item(0);

//display the data
//it should be "Hello World"
alert(firstTag1.getFirstChild().getNodeValue());

} // end function xmljsDOMExample

NOTE: Since the W3C DOM uses the SAX Parser to populate its object tree, you *must* include a reference to the SAX Parser (xmlsax.js or tinyxmlsax.js) in your HTML. See the what files do I need to include to use the W3C DOM Parser section below.

Can I use XPath expressions with the W3C DOM Parser?

Yes, an XPath Contributed Add-on is available that supports many XPath expressions.


NOTE: While providing support for what should be the majority of the functionality needed for the most common uses of XPath, please keep in mind that the XPath Contributed Add-on is not fully compliant to the W3C XPath specificication and has known limitations. Please read the documentation and ensure any XPath expressions you intend to use are supported before using the XPath Contributed Add-on.
What files do I need to include to use the W3C DOM Parser?

In order to use XML for <SCRIPT>'s W3C DOM Parser, you must include the following .js files in your HTML Pages. The .js files starting with "tiny" have been compressed for faster downloads and are functionally identical to their non-compressed counterparts. The non compressed files may be found in the jsXMLParser directory. The compressed files may be found in the jsXMLParser/compressed directory.

  • xmlw3cdom.js (or tinyxmlw3cdom.js)
  • xmlsax.js (or tinyxmlsax.js)

NOTE: Since the W3C DOM uses the SAX Parser to populate its object tree, you *must* include a reference to the SAX Parser (xmlsax.js or tinyxmlsax.js) in your HTML.

What does the DOM Object Model look like?

XML for <SCRIPT>'s DOM object model follows the W3C's object model standards. The three primary objects are DOMNode, DOMImplementation and DOMNodeList. All other objects descend from one of these primary objects as described below.

  • DOMImplementation
  • DOMException
  • DOMNode
    • DOMCharacterData
      • DOMComment
      • DOMText
        • DOMCDATASection
    • DOMAttr
    • DOMProcessingInstruction
    • DOMElement
    • DOMDocument
    • DOMDocumentFragment
  • DOMNodeList
    • DOMNamedNodeMap

The following image displays XML for <SCRIPT>'s object hierarchy graphically.
Click on the image to display the model in a browser view suitable for printing.

W3C DOM Object Model


How does the W3C DOM Parser handle Entity characters?

Entities are character strings that represent other strings in XML. For example, the entity string &amp; represents the "&" character. Even though XML for <SCRIPT>'s W3C DOM parser does not support the DOMEntity object, it does recognise the following "native" XML entities:

  • &amp; which represents the "&" character
  • &lt; which represents the "<" character
  • &apos; which represents the "'" (apostrophe) character
  • &quot; which represents the quote (") character

The entity characters above must be used in XML strings and attributes rather than the characters they represent in order for the XML string to be well formed. When read into the DOM, XML for <SCRIPT>'s W3C parser follows the W3C convention for converting the entity characters into their true form.

NOTE: The W3C convention states that entity characters are only converted into their true representation for DOMText and DOMAttr objects. All other objects pass their character data unmodified into the DOM.

When a DOMAttr or DOMText object is queried for it's nodeValue, the character the entity characters represent will be return. For example, consider the following XML string:

<NODE attr="&lt;hello&gt;">
&pos;text node&pos;
</NODE>

When the attribute's value is queried, the returned string will be "<hello>".
when the text node's value is queried, the returned string will be "'text node'".

When an XML for <SCRIPT> object has its getXML() method called, the method will convert all characters that require entity representation before returning from the function. In the example above:

getXML() on the attribute will return "&lt;hello&gt;"
getXML() on the text node will return "&pos;text node&pos;"

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 foo=\"&lt;&apos;goo&apos;&gt;\">"
+ "&amp;Hello&quot;World"
+ "<!--com\">&lt;ment-->"
+ "<![CDATA[nodeType <<<&amp;> CDATA]]>"
+ "<?foo h<el&gt;lo ?>"
+ "</TAG1>" + "</ROOTNODE>";

//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//get the "TAG1" element
var tag1 = docRoot.getElementsByTagName("TAG1").item(0);

//the following should be "<'goo'>"
alert(tag1.getAttributes().item(0).getNodeValue());

//the following should be 'foo="&lt;&apos;goo&apos;&gt;"'
alert(tag1.getAttributes().item(0).getXML());


//the following should be '&Hello"World'
alert(tag1.childNodes.item(0).getNodeValue());

//the following should be "&amp;Hello&quot;World"
alert(tag1.childNodes.item(0).getXML());


//the following should be 'com">&lt;ment'
alert(tag1.childNodes.item(1).getNodeValue());

//the following should be '<!--com">&lt;ment-->
alert(tag1.childNodes.item(1).getXML());


//the following should be "nodeType <<<&amp;> CDATA"
alert(tag1.childNodes.item(2).getNodeValue());

//the following should be "<![CDATA[nodeType <<<&amp;> CDATA]]>"
alert(tag1.childNodes.item(2).getXML());


//the following should be "h<el&gt;lo"
alert(tag1.childNodes.item(3).getNodeValue());

//the following should be "<?foo h<el&gt;lo ?>"
alert(tag1.childNodes.item(3).getXML());

}// end function xmljsDOMExample

How does the W3C DOM Parser handle namespaces?
Namespaces, as defined by the W3C...

...are a collection of names, identified by a URI reference [RFC2396], which are used in XML documents as element types and attribute names.

URI references which identify namespaces are considered identical when they are exactly the same character-for-character. Note that URI references which are not identical in this sense may in fact be functionally equivalent. Examples include URI references which differ only in case, or which are in external entities which have different effective base URIs.

Names from XML namespaces may appear as qualified names, which contain a single colon, separating the name into a namespace prefix and a local part. The prefix, which is mapped to a URI reference, selects a namespace. The combination of the universally managed URI namespace and the document's own namespace produces identifiers that are universally unique.

URI references can contain characters not allowed in names, so cannot be used directly as namespace prefixes.

In translation, Nodes with namespaces have three components, a URI, a localname and a prefix. The combination of the local name and the prefix is called the qualified name, or QName.

For example, consider the following XML:

<ns1:tag xmlns:ns1="http://www.foo.com">

The namespace URI for the element is "http://www.foo.com" while the prefix is "ns1" and the localname is "tag". When an element or an attribute is created with namespace information included, the two parameters passed in are:

  • The namespace URI
  • The prefix and the local name separated by a colon.

Namespace URIs are associated with prefixes by using the attribute "xmlns". This association can happen in any element in the XML document. The "xmlns" attribute associates URIs with prefixes in the following way:

xmlns:<prefix>="<namespace URI"

A default namespace for an XML document can be assigned by using the "xmlns" attribute as well. If the prefix is left off of the "xmlns" attribute, the namespace URI specified becomes the default namespace URI for all elements in the XML document.

NOTE: Default namespaces for DOMElements are inherited. If one DOMElement node defines a default namespace, the DOMElement children of that DOMElement will be in that default namespace unless specified otherwise.

NOTE: DOMAttr nodes do not inherit any namespaces - including the default namespace. In order to associate an attribute with a namespace, that attribute name must include a prefix that is associated with a namespace URI.

Example:
function xmljsDOMExample() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOTNODE xmlns=\"http://xmljs.sf.net/nsdefault\" xmlns:ns1=\"http://xmljs.sf.net/ns1\" >"
+ "<TAG1>"
+ "<ns1:TAG2 att1=\"foo\" ns1:att2=\"nsfoo\" xmlns=\"newDefault\">"
+ "<TAG3>"
+ "Hello World"
+ "</TAG3>"
+ "</ns1:TAG2>"
+ "<TAG4>"
+ "Hello World"
+ "</TAG4>"
+ "</TAG1>"
+ "</ns1:ROOTNODE>";
//instantiate the W3C DOM Parser
var parser = new DOMImplementation();

//load the XML into the parser and get the DOMDocument
var domDoc = parser.loadXML(xml);

//get the root node
var docRoot = domDoc.getDocumentElement();

//get the "TAG1" element
var ns1="http://xmljs.sf.net/nsdefault"
var tag1 = docRoot.getElementsByTagNameNS(ns1, "TAG1").item(0);

//the TAG1 element has a namespace URI of
//http://xmljs.sf.net/nsdefault because it exists in the
//default namespace of the XML (as defined in the ROOTNODE's
//xmlns="http://xmljs.sf.net/nsdefault" attribtue) and it
//does not have a namespace declaration of its own.

//The following should be "http://xmljs.sf.net/nsdefault"
alert(tag1.getNamespaceURI());

//The following should be "TAG1"
alert(tag1.getLocalName());

//The following should be "" (blank) because TAG1 is in
//the default namespace (which does not have a prefix)
alert(tag1.getPrefix());

//The following should be "TAG1" since there is no prefix
//to append to the localName
alert(tag1.getNodeName());


//get the TAG2 element
var tag2 = tag1.getFirstChild();

//the TAG2 element has a namespace URI of
//http://xmljs.sf.net/ns1 because it uses the "ns1" prefix which
//was defined to exist in the http://xmljs.sf.net/ns1 namespace
//in the xmlns:ns1="http://xmlns="http://xmljs.sf.net/ns1" attribtue
//of the ROOTNODE.

//The following should be "http://xmljs.sf.net/ns1"
alert(tag2.getNamespaceURI());

//the following should be "TAG2"
alert(tag2.getLocalName());

//the following should be "ns1"
alert(tag2.getPrefix());

//the following should be "ns1:TAG2"
alert(tag2.getNodeName());


//get the "att1" attribute
var att1 = tag2.getAttributes().item(0);

//The att1 attribute does not reside in any namespace
//because attribute nodes do not inherit any namespace
//information

//the following should be "" (blank)
alert(att1.getNamespaceURI());

//the following should be "att1"
alert(att1.getLocalName());

//the following should be "" (blank)
alert(att1.getPrefix());

//the following should be "att1"
alert(att1.getNodeName());


//get the "att2" attribute
var att2 = tag2.getAttributes().item(1);

//The att2 attribute resides in the ns1 namespace
//because it's prefix was specified

//the following should be "http://xmljs.sf.net/ns1"
alert(att2.getNamespaceURI());

//the following should be "att2"
alert(att2.getLocalName());

//the following should be "ns1"
alert(att2.getPrefix());

//the following should be "ns1:att2"
alert(att2.getNodeName());


//get TAG3
var tag3 = tag2.getFirstChild();

//tag 3 had its default namespace specified by the
//"xmlns" attribute of tag2.

//the following should be "newDefault"
alert(tag3.getNamespaceURI());

//the following should be "TAG3"
alert(tag3.getLocalName());

//the following should be "" (blank) because the
//node is part of a default namespace that does
//not have a prefix
alert(tag3.getPrefix());

//the following should be "TAG3"
alert(tag3.getNodeName());


//get TAG4
//tag 4 is not a child of TAG2 and thus did not inherit
//its new default namespace URI. TAG4 uses the default
//namespace URI specified in ROOTNODE
var tag4 = docRoot.getElementsByTagNameNS(ns1, "TAG4").item(0);

//The following should be "http://xmljs.sf.net/nsdefault"
alert(tag4.getNamespaceURI());

}// end function xmljsDOMExample

What W3C Dom Objects and methods supported?

XML for <SCRIPT> supports the following W3C DOM objects and methods:

DOMException: Supported
code Supported
DOMImplementation: Supported
hasFeature() Supported
createDocumentType() Not Supported
createDocument() Not Supported
DOMDocumentFragment: Supported
DOMDocument: Supported
getDocType() Partially Supported
getImplementation() Supported
createElement() Supported
createDocumentFragment() Supported
createTextNode() Supported
createComment() Supported
createCDATASection() Supported
createProcessingInstruction() Supported
createAttribute() Supported
createEntityReference() Not Supported
getElementsByTagName() Supported
importNode() Supported
createElementNS() Supported
createAttributeNS() Supported
getElementsByTagNameNS() Supported
GetElementById() Supported
DOMNode: Supported
getNodeName() Supported
getNodeValue() Supported
setNodeValue() Supported
getNodeType() Supported
getParentNode() Supported
getChildNodes() Supported
getFirstChild() Supported
getLastChild() Supported
getPreviousSibling() Supported
getNextSibling() Supported
getAttributes() Supported
getOwnerDocument() Supported
insertBefore() Supported
replaceChild() Supported
removeChild() Supported
appendChild() Supported
hasChildNodes() Supported
cloneNode() Supported
normalize() Supported
isSupported() Supported
getNamespaceURI() Supported
getPrefix() Supported
setPrefix() Supported
getLocalName() Supported
hasAttributes() Supported
DOMNodeList: Supported
getLength() Supported
DOMNamedNodeMap: Supported
getNamedItem() Supported
setNamedItem() Supported
removeNamedItem() Supported
item() Supported
getLength() Supported
getNamedItemNS() Supported
setNamedItemNS() Supported
removeNamedItemNS() Supported
DOMCharacterData: Supported
getData() Supported
setData() Supported
getLength() Supported
substringData() Supported
appendData() Supported
insertData() Supported
deleteData() Supported
replaceData() Supported
DOMAttr: Supported
getName() Supported
getSpecified() Partially Supported
getValue() Supported
setValue() Supported
getOwnerElement() Supported
DOMElement: Supported
getTagName() Supported>
getAttribute() Supported
setAttribute() Supported
removeAttribute() Supported
getAttributeNode() Supported
setAttributeNode() Supported
removeAttributeNode() Supported
getElementsByTagName() Supported
getAttributeNS() Supported
setAttributeNS() Supported
removeAttributeNS() Supported
getAttributeNodeNS() Supported
setAttributeNodeNS() Supported
getElementsByTagNameNS() Supported
hasAttribute() Supported
hasAttributeNS() Supported
DOMText: Supported
splitText() Supported
DOMComment: Supported
DOMCDATASection: Supported
DOMProcessingInstruction: Supported
getTarget() Supported
getData() Supported
setData() Supported
DOMDocumentType: Not Supported
DOMNotation: Not Supported
DOMEntity: Not Supported
DOMEntityReference: Not Supported