XML for <SCRIPT> Cross Platform XML Parsing in JavaScript - W3C DOM Parser DOMDocument Object Documentation

W3C DOM Parser DOMDocument Object Documentation

This page contains the XML for <SCRIPT> DOMDocument object documentation.

Return to W3C DOM Parser Documentation Main Page

NOTE: DOMDocument descends from DOMNode and inherits all of the properties and methods of the DOMNode object

CONTENTS

DOMDocument - object description

Native Methods:: DOMDocument - getDoctype method; DOMDocument - getImplementation method; DOMDocument - getDocumentElement method; DOMDocument - createElement method; DOMDocument - createDocumentFragment method; DOMDocument - createTextNode method; DOMDocument - createComment method; DOMDocument - createCDATASection method; DOMDocument - createProcessingInstruction method; DOMDocument - createAttribute method; DOMDocument - createAttributeNS method; DOMDocument - createElementNS method; DOMDocument - getElementById method; DOMDocument - importNode method; DOMDocument - getElementsByTagName; DOMDocument - getElementsByTagNameNS

Inherited Methods:: DOMNode - getNodeName method; DOMNode - getNodeValue method; DOMNode - setNodeValue method; DOMNode - getNodeType method; DOMNode - getParentNode method; DOMNode - getChildNodes method; DOMNode - getFirstChild method; DOMNode - getLastChild method; DOMNode - getPreviousSibling method; DOMNode - getNextSibling method; DOMNode - getAttributes method; DOMNode - getNamespaceURI method; DOMNode - getPrefix method; DOMNode - getLocalName method; DOMNode - getOwnerDocument method; DOMNode - insertBefore method; DOMNode - replaceChild method; DOMNode - removeChild method; DOMNode - appendChild method; DOMNode - hasChildNodes method; DOMNode - cloneNode method; DOMNode - getElementsByTagName method; DOMNode - getElementsByTagNameNS method; DOMNode - setPrefix method; DOMNode - normalize method; DOMNode - isSupported method; DOMNode - getXML method; DOMNode - hasAttributes method

DOMDocument - object description

The DOMDocument interface represents the entire 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 DOMDocument, the DOMDocument interface also contains the factory methods needed to create these objects. The DOMNode objects created have a getOwnerDocument method which returns the DOMDocument object within whose context they were created.

DOMDocument - getDoctype method

W3C DOM Level 1

document.getDoctype();
- or -
document.doctype;

accepts:

N/A

returns:

null (see note below)

throws:

N/A

XML for <SCRIPT> is a non-validating parser that ignores DOCTYPE declarations. XML for <SCRIPT>'s DOMDocument objects will always return null.

DOMDocument - getImplementation method

W3C DOM Level 1

document.getImplementation();
- or -
document.implementation;

accepts:

N/A

returns:

DOMImplementation - a reference to the DOMDocuments DOMImplementation object

throws:

N/A

The DOMDocument's getImplementation method returns the DOMImplementation object that is associated with the queried DOMDocument.

NOTE: It is also possible to access the DOMImplementation object of the DOMDocument by accessing the implementation property. This property should be treated as read-only and should never be set in code.

Example:

function xmljsDOMExample() {

alert("true");

}
else {

alert("false");

}

}// end function xmljsDOMExample

DOMDocument - getDocumentElement method

W3C DOM Level 1

document.getDocumentElement();
- or -
document.documentElement;

accepts:

N/A

returns:

DOMNode - a reference to the DOMDocument's root node

throws:

N/A

The DOMDocument's getDocumentElement method returns the child node that is the root element of the document.

NOTE: It is also possible to access the document elemement object of the DOMDocument by accessing the documentElement property. This property should be treated as read-only and should never be set in code.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createElement method

W3C DOM Level 1

document.createElement(<tagName>);

accepts:

String - the tagName (which will also become the nodeName) for the new Element

returns:

DOMElement - the created DOMElement object

throws:

DOMException.INVALID_CHARACTER_ERR - Thrown if the string contains an illegal character

The createElement method allows DOMElement objects to be created which can then be added to the document programatically.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createDocumentFragment method

W3C DOM Level 1

document.createDocumentFragment();;

accepts:

N/A

returns:

DOMDocumentFragment object - the created DOMDocumentFragment object

throws:

N/A

The createDocumentFragment method allows DOMDocumentFragment objects to be created which can then be added to the document programatically.

A DOMDocumentFragment 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 DOMNode (DOMDocumentFragment descends from DOMNode) for this purpose. While it is true that a Document object could fulfill this role, a Document object can potentially be a heavyweight object. What is really needed for this is a very lightweight object. DOMDocumentFragment is such an object.

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, but is nonetheless legal inside a DOMDocumentFragment object.

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.

Example:

function xmljsDOMExample() {

var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "Hello"
+ "</TAG1>"
+ "</ROOT>";

//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.documentElement;

//create the DOMDocumentFragment
var newDocFrag;
newDocFrag = domDoc.createDocumentFragment();

//create a new DOMElement and DOMText
//that will be added to the DOMDocumentFragment
//NOTE: These elements are *NOT* actually in the
//DOMDocument yet.
var newElem = domDoc.createElement("NEWELEMENT");
var newText = domDoc.createTextNode("new text");

//append the new objects to each other
newElem.appendChild(newText);
newDocFrag.appendChild(newElem);

//append the DOMDocumentFragment
//to the ROOT node. At this point
//the new nodes become visible in the
//DOMDocument.
docRoot.appendChild(newDocFrag);

//the following should be
//"<?xml version="1.0"?>
//<ROOT>
// <TAG1>
// Hello
// </TAG1>
// <NEWELEMENT>
// new text
// </NEWELEMENT>
//</ROOT>"
alert(domDoc.getXML());

//get the NEWELEMENT Node from the document
//I can do this now that I've appended the
//DOMDocumentFragment to the tree
var newElem = docRoot.getElementsByTagName("NEWELEMENT").item(0);

//the following should be "new text"
alert(newElem.getFirstChild().getNodeValue());

}// end function xmljsDOMExample

DOMDocument - createTextNode method

W3C DOM Level 1

document.createTextNode(<New Node Data>);

accepts:

String - the data for new DOMText node

returns:

DOMText object - the created DOMText object

throws:

N/A

DOMText objects represent the textual content (termed character data in XML) of a DOMElement or DOMAttr. Creating a new DOMText object allows developers to insert textual data into the document. The createTextNode method allows DOMText objects to be created which can then be added to the document programatically.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createComment method

W3C DOM Level 1

document.createComment(<New Node Data>);

accepts:

String - the data (comment string) for the new DOMComment node

returns:

DOMComment object - the created DOMComment object

throws:

N/A

DOMComment objects represent the content of an XML comment, i.e., all the characters between the starting ' '. Creating a new DOMComment object allows developers to insert comments into the document. The createComment method allows DOMComment objects to be created which can then be added to the document programatically.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createCDATASection method

W3C DOM Level 1

document.createCDATASection(<New Node Data>);

accepts:

String - the data (CDATA content) for the new DOMCDATASection node

returns:

DOMCDATASection object - the created DOMCDATASection object

throws:

N/A

DOMCDATASection objects are used to escape blocks of text containing characters that would otherwise be regarded as markup. Their primary purpose is for including material such as XML fragments, without needing to escape all the delimiters. The createCDATASection method allows DOMCDATASection objects to be created which can then be added to the document programatically.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createProcessingInstruction method

W3C DOM Level 1

document.createProcessingInstruction(<target>, <data>);

accepts:

String - The target for the processing instruction
String - The data for the processing instruction

returns:

DOMProcessingInstruction object - the created DOMProcessingInstruction object

throws:

N/A

A DOMProcessingInstruction represents a "processing instruction", used in XML as a way to keep processor-specific information in the text of the document. The createProcessingInstruction method allows DOMProcessingInstruction objects to be created which can then be added to the document programatically.

NOTE: XML for <SCRIPT> does not process processing instructions at this time. However, it does properly handle the DOMProcessingInstruction object so that processing instructions can be passed correctly to other parsers.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createAttribute method

W3C DOM Level 1

document.createAttribute(<attribute name>);

accepts:

String - The name of the attribute

returns:

DOMAttr object - the created DOMAttr object

throws:

DOMException.INVALID_CHARACTER_ERR - Thrown if the string contains an illegal character

A DOMAttr object represents an attribute of an element. The createAttribute method allows DOMAttr objects to be created which can then be added to the document programatically.

NOTE: creating a DOMAttr only creates the attribute object. To assign the attribute object a value, the DOMAttr's setNodeValue method must be called.

To add the new attribute to a DOMElement, the DOMElement's setAttribute method can be called.

NOTE: please see the documentation for DOMElement - setAttribute for another method of adding and editing attributes in elements.

Example:

function xmljsDOMExample() {

}// end function xmljsDOMExample

DOMDocument - createAttributeNS method

W3C DOM Level 2

document.createAttributeNS(<namespaceURI>, <qualified attribute name>);

accepts:

String - The URI associated with the prefix in the attribute name
String - the fully qualified attribute name (including prefix)

returns:

DOMAttr object - the created DOMAttr object

throws:

DOMException.NAMESPACE_ERR - Thrown if the namespace is invalid
DOMException.INVALID_CHARACTER_ERR - Thrown if the string contains an illegal character

A DOMAttr object represents an attribute of an element. The createAttributeNS method allows DOMAttr objects with namespace information to be created which can then be added to the document programatically.

NOTE: creating a DOMAttr only creates the attribute object. To assign the attribute object a value, the DOMAttr's setNodeValue method must be called.

To add the new attribute to a DOMElement, the DOMElement's setAttribute method can be called.

NOTE: please see the documentation for DOMElement - setAttribute for another method of adding and editing attributes in elements.

NOTE: The name of the attribute must be fully qualified (i.e. include <prefix>:<attributeName>) or unexpected behavior may result.

Example:

function xmljsDOMExample() {

var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOT xmlns:ns1=\"http://xmljs.sf.net/ns1\" >"
+ "<ns1:TAG1>"
+ "Hello"
+ "</ns1:TAG1>"
+ "</ns1:ROOT>";

//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/ns1";
var tag1 = docRoot.getElementsByTagNameNS(ns1, "TAG1").item(0);

//create a new DOMAttr node with
//the ns1 namespace
var ns1="http://xmljs.sf.net/ns1";
var newAttribute = domDoc.createAttributeNS(ns1, "ns1:attribute");

newAttribute.setNodeValue("value");

//Add the new attribute to TAG1
tag1.setAttributeNode(newAttribute);

//the following should be
//<?xml version=\"1.0\"?>
//<ns1:ROOT xmlns:ns1="http://xmljs.sf.net/ns1" >
//<ns1:TAG1 ns1:attribute="value">
//Hello
//</ns1:TAG1>
//</ns1:ROOT>"
alert(domDoc.getXML());

}// end function xmljsDOMExample

DOMDocument - createElementNS method

W3C DOM Level 2

document.createElementNS(<namespaceURI>, <qualified element name>);

accepts:

String - The URI associated with the prefix in the element name
String - the fully qualified element name (including prefix)

returns:

DOMElement object - the created DOMElement object

throws:

DOMException.NAMESPACE_ERR - Thrown if the namespace is invalid
DOMException.INVALID_CHARACTER_ERR - Thrown if the string contains an illegal character

The createElement method allows DOMElement objects associated with namespaces to be created which can then be added to the document programatically.

NOTE: The name of the element must be fully qualified (i.e. include <prefix>:<elementName>) or unexpected behavior may result.

Example:

function xmljsDOMExample() {

var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ns1:ROOT xmlns:ns1=\"http://xmljs.sf.net/ns1\" >"
+ "<ns1:TAG1>"
+ "Hello"
+ "</ns1:TAG1>"
+ "</ns1:ROOT>";

//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/ns1";
var tag1 = docRoot.getElementsByTagNameNS(ns1, "TAG1").item(0);

//create a new DOMElement node with
//the ns1 namespace
var ns1="http://xmljs.sf.net/ns1";
var newElement = domDoc.createElementNS(ns1, "ns1:NewElement");

//create and append a DOMText to the new node
var newText = domDoc.createTextNode("new text");
newElement.appendChild(newText);

//Add the new DOMElement to the document
docRoot.appendChild(newElement);

//the following should be
//<?xml version=\"1.0\"?>
//<ns1:ROOT xmlns:ns1="http://xmljs.sf.net/ns1" >
//<ns1:TAG1>
//Hello
//</ns1:TAG1>
//<ns1:NewElement>
//new text
//</ns1:NewElement>
//</ns1:ROOT>"
alert(domDoc.getXML());

}// end function xmljsDOMExample

DOMDocument - getElementById method

W3C DOM Level 2

document.getElementById(<element id>);

accepts:

String - The element id to search on

returns:

DOMElement object - the DOMElement object with the id attribute who's value matches the element id passed in.

throws:

N/A

The getElementById method returns the DOMElement whose id attribute value is matched by the element id passed into the method. If no such DOMElement exists, getELementById will return null.

NOTE: XML for <SCRIPT> classifies id attributes as any attribute who's name is a case insensitive match to "id".

NOTE: Having more than one DOMElement in a document with the same id value can cause unpredictable behavior. Take care to ensure the id values of the document are unique.

Example:

function xmljsDOMExample() {

var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1 id=\"foo\">"
+ "Hello"
+ "</TAG1>"
+ "</ROOT>";

//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();

//find tag1 by searching by its id
var tag1 = domDoc.getElementById("foo");

//the following should be
//<TAG1 id="foo">
//Hello
//</TAG1>
alert(tag1.getXML());

//now add a new DOMElement to the document
var newElem = domDoc.createElement("NEWELEM");
docRoot.appendChild(newElem);

//add an id element to the new element so it
//can be found later using getElementById
var newAttr = domDoc.createAttribute("id");
newAttr.setNodeValue("newid");
newElem.setAttributeNode(newAttr);

//add a text node to the new element
var newText = domDoc.createTextNode("new text");
newElem.appendChild(newText);

//get the element I just added by searching
//on its ID
var newElem = domDoc.getElementById("newid");

//the following should be
//<NEWELEM id="newid">
//new text
//</NEWELEM>
alert(newElem.getXML());

//now remove tag1
docRoot.removeChild(tag1);

//try to search for tag1
//it should not be found
var noTag1Found = domDoc.getElementById("foo");

//the following should show the alert
if (noTag1Found == null) {

alert("no tag1 element found!");

}

}// end function xmljsDOMExample

DOMDocument - importNode method

W3C DOM Level 2

document.importNode(<node to import>, <recurse children>);

accepts:

DOMNode node to import - the DOMNode to be imported
boolean - recursively import children

returns:

DOMNode - a node suitable for addition into the document.

throws:

N/A

Under normal circumstances, nodes from one document cannot be added to another. This avoids situations where nodes of the same document have different implementation objects and different parents. However, there are times where adding nodes from one document into another would be convenient. For cases such as this, the importNode method can be used.

The importNode method prepares a DOMNode from another document to be added to the document that importNode was called from. The returned node has no parent (e.g. parentNode is null). The source node is not altered or removed from the original document; importNode creates a new copy of the source node.

NOTE: calling a DOMDocument's importNode method does *not* modify the DOMDocument in any way. In order to modify the DOMDocument, the node returned from the importNode method must be added via a DOM manipulation method such as appendChild.

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. The following list describes the specific behavior of importNode for each type of node.

Node Type	importNode Behavior
ATTRIBUTE_NODE	The ownerElement attribute is set to null and the specified flag is set to true on the generated DOMAttr. The descendants of the source DOMAttr are recursively imported and the resulting nodes reassembled to form a subtree identical to the original. Note that the deep parameter has no effect on DOMAttr nodes; they always carry their children with them when imported.
DOCUMENT_FRAGMENT_NODE	If the deep option is set to true, the descendants of the source element are recursively imported and the resulting nodes reassembled to form a subtree identical to the original. Otherwise, importNode simply generates an empty DOMDocumentFragment.
DOCUMENT_NODE	DOMDocument nodes cannot be imported. importNode will return null.
ELEMENT_NODE	Specified attribute nodes of the source element are imported, and the generated DOMAttr nodes are attached to the generated Element. 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 a subtree identical to the original.
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 DOMCharacterData copy their data and length attributes from those of the source node.

Example:

function xmljsDOMExample() {

var xml1;
xml1 = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<DEEPNODE>"
+ "Hello 1"
+ "</DEEPNODE>"
+ "</TAG1>"
+ "</ROOT>";

var xml2;
xml2 = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT2>"
+ "<TAG2>"
+ "Hello 2"
+ "</TAG2>"
+ "</ROOT2>";

//instantiate the W3C DOM Parsers
var parser1 = new DOMImplementation();
var parser2 = new DOMImplementation();

//load the XML into the parsers and get the DOMDocuments
var domDoc1 = parser1.loadXML(xml1);
var domDoc2 = parser2.loadXML(xml2);

//get the root nodes
var docRoot1 = domDoc1.getDocumentElement();
var docRoot2 = domDoc2.getDocumentElement();

//get tag1 of the first XML
var tag1 = docRoot1.getElementsByTagName("TAG1").item(0);

//try to append tag1 to the second xml
//this should fail because the tag1 is
//not part of the second XML document
try {

docRoot2.appendChild(tag1);

}
catch(e) {

//I should have failed with a
//failure code of
//DOMException.WRONG_DOCUMENT_ERROR
//check to make sure
if (e.code == DOMException.WRONG_DOCUMENT_ERR) {

//this is expected. do nothing and continue

}
else {

alert("unexpected error");

}

}

//to add nodes that originate from different
//documents, use the importNode method
//Also, send true to the deep argument

//so that all the child nodes are imported
//as well.

var nodeToImport = domDoc2.importNode(tag1, true);

//nodeToImport can now be added to the second document

docRoot2.appendChild(nodeToImport);

//the following should be
//<?xml version="1.0"?>
//<ROOT2>
//<TAG2>
//Hello 2
//</TAG2>
//<TAG1>
//<DEEPNODE>
//Hello 1
//</DEEPNODE>
//</TAG1>
//</ROOT2>
alert(domDoc2.getXML());

}// end function xmljsDOMExample

DOMDocument - getElementsByTagName

W3C DOM Level 1

NOTE: The W3C specification includes getElementsByTagName only for DOMElements and DOMDocuments. XML for <SCRIPT> implements getElementsByTagName for all DOMNodes.

You may find documentation on the getElementsByTagName by viewing the DOMNode getElementsByTagName documentation.

DOMDocument - getElememtnsByTagNameNS

W3C DOM Level 2

NOTE: The W3C specification includes getElementsByTagNameNS only for DOMElements and DOMDocuments. XML for <SCRIPT> implements getElementsByTagNameNS for all DOMNodes.

You may find documentation on the getElementByTagNameNS by viewing the DOMNode getElementsByTagNameNS documentation.