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

W3C DOM Parser DOMImplementation Object Documentation

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

Return to W3C DOM Parser Documentation Main Page

CONTENTS

Native Methods:: DOMImplementation - constructor; DOMImplementation - preserveWhiteSpace property; DOMImplementation - namespaceAware property; DOMImplementation - errorChecking property; DOMImplementation - hasFeature method; DOMImplementation - loadXML method; DOMImplementation - translateErrCode method; DOMImplementation - escapeString method; DOMImplementation - unescapeString method

Inherited Methods:: The DOMImplementation object has no inherited W3C methods

DOMImplementation - object description

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

DOMImplementation - constructor

W3C DOM Level 1

var parser = new DOMImplementation();

accepts:

N/A

returns:

DOMImplementation - new DOMImplementation object

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

DOMImplementation - preserveWhiteSpace property

XML for <SCRIPT> DOM Extension

DOMImplementation.preserveWhiteSpace = [true|false];

accepts:

boolean

returns:

boolean

The preserveWhiteSpace property is used to determine if the white space surrounding data inside the XML document being parsed is to be preserved or stripped during parsing.

If preserveWhiteSpace is set to true, the parser will behave in the following ways:

Multiple white space characters will be honored and be represended in the DOM object model.

By default, preserveWhiteSpace is false, meaning white space will be removed from the XML document during processing.

NOTE: Mozilla (and derivatives) seem to automatically reduce white space in JavaScript to a single white space character - even in external script files.

Example:

function xmljsDOMExample() {

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

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

//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 first "TAG1" element
var firstTag1 = docRoot.getElementsByTagName("TAG1").item(0);

//display the data
alert("|" + firstTag1.getFirstChild().getNodeValue() + "|");

} // end function xmljsDOMExample

By setting preserveWhiteSpace to true in the code above, the alert that is displayed will be shown with the XML data's leading and trailing spaces intact. If preserveWhiteSpace had been set to false (the default), these spaces would have been removed.

DOMImplementation - namespaceAware property

XML for <SCRIPT> DOM Extension

DOMImplementation.namespaceAware = [true|false];

accepts:

boolean

returns:

boolean

The namespaceAware property is used to tell the parser whether or not to process and be aware of namespaces (DOM Level 2) in the XML it is to process.

By default, namespaceAware is true, meaning the parser will process namespaces unless the programmer specifically tells it not to.

NOTE: Under normal use, there should be no reason to change the default value of namespaceAware. The namespaceAware property does not force the use of namespaces or namespace DOM methods. The only reason namespaceAware may need to be changed is in times of extremely heavy load where resource optimizing is very important.

Example:

function xmljsDOMExample() {

var xml =""

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

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

//namespaceAware is true by default
//this line is here only for demonstration purposes
parser.namespaceAware = true;

//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 ns1 "TAG1" element
var ns1 = "http://xmljs.sf.net/ns1";
var ns1Tag1 = docRoot.getElementsByTagNameNS(ns1, "TAG1").item(0);

//the following should be "ns1 Hello world"
alert(ns1Tag1.getFirstChild().getNodeValue());

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

//the following should be "ns2 Hello world"
alert(ns2Tag1.getFirstChild().getNodeValue());

} // end function xmljsDOMExample

DOMImplementation - errorChecking property

XML for <SCRIPT> DOM Extension

DOMImplementation.errorChecking = [true|false];

accepts:

boolean

returns:

boolean

By default, XML for <SCRIPT>'s W3C DOM Parser will raise exceptions as appropriate. This behavior can be turned off by setting the errorChecking property to false. Doing so, however, is not recommended as unexpected behavior can occur when errors are not trapped as designed.

NOTE: For a complete list of the exceptions thrown by XML for <SCRIPT>'s W3C DOM Parser, please view the DOMException documentation.

In addition to the DOMException documentation, each method described in the W3C DOM documentation documents the exceptions it can throw.

DOMImplementation - hasFeature method

W3C DOM Level 1 and Level 2

DOMImplementation.hasFeature(<String feature>, <String version>);

accepts:

String feature: A String of the feature to test for
String version: A String of the version of the feature to test for

returns:

boolean - true if the feature/version is supported: false otherwise

throws:

N/A

The hasFeature method is a way of testing to determine if the DOM implementation implements a specific feature. XML for <SCRIPT>'s W3C DOM Parser supports the DOM level 1 and DOM Level 2 specifications and will return true if the following information is passed to the method:

feature is "xml" and version is "1.0" or "2.0"
feature is "core" and version is "2.0"

The feature and version strings are case insensitive

DOMImplementation - loadXML method

XML for <SCRIPT> DOM Extension

DOMImplementation.loadXML(<XML>);

accepts:

String XML: The XML stream to process

returns:

DOMDocument - object representation of the XML data

throws:

DOMException.SYNTAX_ERR - If the XML is not valid

When the loadXML method of the DOMImplementation object is called, the XML stream is processed into an object representation. A DOMDocument object is returned that can be manipulated and traversed.

Example:

function xmljsDOMExample() {

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

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

//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 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

DOMImplementation - translateErrCode method

XML for <SCRIPT> DOM Extension

DOMImplementation.translateErrCode(<errCode>);

accepts:

int errCode: The error code to translate into an English error message

returns:

String - The English error string associated with the errCode

throws:

N/A

translateErrCode is a convience method that will translate a DOMException error code into an English error message.

Example:

function xmljsDOMExample() {

var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "Hello World"
+ "</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 document root
var docRoot = domDoc.getDocumentElement();

//get the TAG1 node
var tag1 = docRoot.getFirstChild();

//get the "Hello World" text
var textNode = tag1.getFirstChild();

//The following should raise a DOMException.INDEX_SIZE_ERR
try {

alert(textNode.substringData(15, 5));

}
catch (e) {

if (e.code == DOMException.INDEX_SIZE_ERR) {

var domImp = domDoc.getImplementation();
//display the error message
alert(domImp.translateErrCode(e.code));

}

else {

alert("unexpected exception");
alert(e.code);

}

}// end function xmljsDOMExample

DOMImplementation - escapeString method

XML for <SCRIPT> DOM Extension

DOMImplementation.escapeString(<string to be escaped>);

accepts:

String : The string with (possibly) invalid XML characters to be escaped into valid characters

returns:

String - The escaped version of the string

throws:

N/A

escapeString is a convenience method that will escape the following characters into their safe XML entities:

Original Character	Escaped String
&	&
<	<
>	>
"	"
'	'

Example:

function xmljsDOMExample() {

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

//The following should be &-<->-"-'
alert(parser.escapeString("&-<->-\"-'"));

}// end function xmljsDOMExample

DOMImplementation - unescapeString method

XML for <SCRIPT> DOM Extension

DOMImplementation.unescapeString(<string to be unescaped>);

accepts:

String : The string with (possibly) escaped XML characters to be returned to their original values.

returns:

String - The unescaped version of the string

throws:

N/A

unescapeString is a convenience method that will return the following entities back to their original values:

Escaped Entity Value	Original Value
&	&
<	<
>	>
"	"
'	'

Example:

function xmljsDOMExample() {

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

//The following should be &-<->-"-'
alert(parser.unescapeString("&-<->-"-'"));

}// end function xmljsDOMExample