CONTENTS

What files do I need to include to use the Classic DOM Parser?

How do I get started with the Classic DOM parser?

 

XMLDoc Object - Constructor

XMLDoc Object - createXMLNode method

XMLDoc Object - docNode property

XMLDoc Object - getUnderlyingXMLText method

XMLDoc Object - hasErrors property

XMLDoc Object - insertNodeAfter method

XMLDoc Object - insertNodeInto method

XMLDoc Object - loadXML method

XMLDoc Object - removeNodeFromTree method

XMLDoc Object - replaceNodeContents method

XMLDoc Object - source property

 

XMLDoc/XMLNode Object - selectNode method

XMLDoc/XMLNode Object - selectNodeText method

 

XMLNode Object - Constructor

XMLNode Object - addAttribute method

XMLNode Object - getAttribute method

XMLNode Object - getAttributeNames method

XMLNode Object - getElementById method

XMLNode Object - getElements method

XMLNode Object - getText method

XMLNode Object - getParent method

XMLNode Object - getUnderlyingXMLText method

XMLNode Object - nodeType property

XMLNode Object - removeAttribute method

XMLNode Object - tagName property

XMLNode Object - toString method

 

convertEscapes

convertToEscapes

trim

To use XML for <SCRIPT>'s Classic DOM Parser, you need to include xmldom.js from the jsXMLParser directory.

If you wish to use a compressed version of the parser (comments, line breaks etc removed) you may replace xmldom.js with tinyxmldom.js from the jsXMLParser/compressed directory.

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

and you want to get the text out of the TAG1 tag. Here's the code:

var objDom = new XMLDoc(<xml string>, <error function>)

} //end function xmlError

var newNode = objDom.createXMLNode(<xml string>);

createXMLNode is a convienience function to create a new node that inherits the properties of the document object

//objDom is an object of type XMLDoc
var newNode = objDom.createXMLNode("<TAG2>test</TAG2>");

See also: domManipulationTestOne in domTestSuite.js

var rootNode = objDom.docNode;

If the instantiation of the XMLDoc object is successful, the docNode property will return the root node of the XML text.

xml = ""

var objDom = new XMLDoc(xml, xmlError);
//get the root node
var objDomTree = objDom.docNode;

objDom.getUnderlyingXMLText()

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
alert(objDom.getUnderlyingXMLText());

See also: underlyingXMLFunctionsTestOne in domTestSuite.js

objDom.hasErrors;

Checking for the hasErrors property is one way of determining if an error has been reported. The recommended way of checking, however, is to catch the error in the error function passed into the XMLDoc constructor.

xml = ""
var objDom = new XMLDoc(xml, xmlError);
alert(objDom.hasErrors);

objDom = objDom.insertNodeAfter(<reference node>, <new node>)

insertNodeAfter will place a new node after the reference node at the same level. For example, inserting a new node with the text <NEW>new!</NEW> after the <REFERENCE> node in the following XML will yield:

Users of XML for <SCRIPT> should call the convertToEscapes function any time they are performing dom manipulation by adding new nodes consisting of user-generated text with the exception of CDATA type nodes. While XML for <SCRIPT> is generally rather loose with what it will allow in text, many other parsers are not and will generate an error if one of these characters is unescaped. For more information, see the information under convertToEscapes in the TOOLS section of the documentation.

<ROOTNODE>
</ROOTNODE>

<ROOTNODE>
</ROOTNODE>

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//create the new node
var newNode = objDom.createXMLNode("<TAG2>test</TAG2>");
//now add it to the tree
objDom = objDom.insertNodeAfter(referenceNode, newNode);

See also: domManipulationTestOne in domTestSuite.js

objDom = objDom.insertNodeInto(<reference node>, <new node>)

insertNodeInto will place a new node into the reference node directly after the end of the reference node's tag declaration. For example, inserting a new node with the text <NEW>new!</NEW> into the <REFNCE> node in the following XML will yield:

Users of XML for <SCRIPT> should call the convertToEscapes function any time they are performing dom manipulation by adding new nodes consisting of user-generated text with the exception of CDATA type nodes. While XML for <SCRIPT> is generally rather loose with what it will allow in text, many other parsers are not and will generate an error if one of these characters is unescaped. For more information, see the information under convertToEscapes in the TOOLS section of the documentation.

<ROOT> </ROOT>

<ROOT> </ROOT>

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node to insert into, in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//create the new node
var newNode = objDom.createXMLNode("<TAG2>test</TAG2>");
//now add it to the tree
objDom = objDom.insertNodeInto(referenceNode, newNode);

See also: domManipulationTestTwo in domTestSuite.js

loadStatus = objDom.loadXML(<XML String>)

The primary purpose of the loadXML method is to reuse a pre-existing XMLDoc object and load it with new data.

NOTE: To read information out of the new XMLDoc object, you will need to get a new handle to the new XMLDoc object docNode via the docNode property. See below for an example of the correct syntax.

See also domLoadTestOne and domLoadTestTwo in domTestSuite.js

objDom = objDom.removeNodeFromTree(<reference node>)

removeNodeFromTree will remove the reference node (and all of it's children) from the XMLDoc object. For example, removing the node with the text <NEW>new!</NEW> from the following XML will yield:

<ROOT>
</ROOT>

<ROOT>
</ROOT>

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node that we want to delete in this case it is TAG2
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0].getElements("TAG2")[0];
//now remove the node
//******** REMEMBER that the return value is a new DOM object!!! ********
objDom = objDom.removeNodeFromTree(referenceNode);

See also: domManipulationTestThree in domTestSuite.js

objDom = objDom.replaceNodeContents(<reference node>, <value>)

replaceNodeContents is generally used to replace the text value of a node. <value> is commonly just the new string value you would like returned in the node's getText() method. In this case, the text of the node is replaced word for word with what is passed in by the <value> parameter. However, <value> can also be a totally new XML string, allowing for the placement of any number of new nodes inside the reference node.

Unlike the function insertNodeInto, replaceNodeContents removes all of the current contents of the reference node and replaces them with the contents of <value>. The only information retained are the attributes of the node.

For example, replacing the contents of <TAG1> with "hello" in the following XML will yield:

<ROOT>
</ROOT>

<ROOT>
</ROOT>

Replacing the contents of <REFNC> with "hello" in the following XML will yield:

<ROOT>
</ROOT>

<ROOT>
</ROOT>

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find a node to replace its contents, in this case, TAG1
var domTree = objDom.docNode;
var rfnceNode = domTree.getElements("TAG1")[0];
//now do the replace
//******** REMEMBER that the return value is a new DOM object!!! ********
objDom = objDom.replaceNodeContents(rfnceNode, "new value");

See also: domManipulationTestFour in domTestSuite.js

objDom.source;

The XMLDoc objects source property represents the *original* source XML for the object. This property is *not* updated by the dom manipulation functions.

xml = ""
var objDom = new XMLDoc(xml, xmlError)
alert(objDom.source);

objDOM.selectNode(<search string>)
objNODE.selectNode(<search string>)

XML for <SCRIPT> tagPath searching allows JavaScript developers who know the layout and structure of their XML documents easy access to the nodes in their XML Dom. The format of the search criteria is similar to that of XPath. Consider the following code:

var objDom = new XMLDoc(xml, xmlError);
//show the text of the first TAG2 node
var domTree = objDom.docNode;
alert(domTree.getElements("TAG1")[0].getElements("TAG2")[0].getText());

The code to get the node text in the example above is rather straightforward, but is large and can be cumbersome. XML for <SCRIPT> tagPath searching makes this much easier. Consider the following code, which is equivalent to the sample code above:

var objDom = new XMLDoc(xml, xmlError);
//show the text of the first TAG2 node
alert(objDom.selectNode("/TAG1/TAG2[0]").getText());

tagPath searching allows JavaScript developers to specify which node they wish to select by passing in a well-formed search string. This search string is formatted according to the following rules:

Only one search attribute is allowed in any attribute ([@<attribute>=",<value>"]) search. However, multiple attribute searches are allowed for a single node (/node[@<attribute1>=",<value>"][@<attribute2>=",<value>"]).

For more information on XML for <SCRIPT>s tagPath capabilities, you are encouraged to inspect the DOM test suite and the DOM tagPath sample application source code.

You can view an interactive demo of the tagPath capabilities by viewing the DOM tagPath sample application. This sample application is located in the "Sample Code (Parsers)" section of the website.

objDOM.selectNodeText(<search string>)
objNODE.selectNodeText(<search string>)

The return string of this function is the exact same string that would be returned if the NODE object method getText() was invoked on a NODE returned from a selectNode call.

var objNode = new XMLNode(<node type>, <doc>,<str>)

It is uncommon for anyone but the parser itself to create new XMLNode objects. When creating new node objects in code for dom manipulation, it is recommended that you use the createXMLNode method of the XMLDoc object. However, it is possible to create your own nodes should the need arise.

The available node types are TEXT, COMMENT, ELEMENT and CDATA. These should be passed as text in upper-case to the constructor.

var xml;
xml = ""
//instantiate a new XMLDoc object.
var objDom = new XMLDoc(xml, xmlError)
var objNode = new XMLNode("TEXT", objDom, "<TAG1>value</TAG1>")

objNode.addAttribute(<attribute name>, <attribute value>)

addAttribute will add an attribute to the node object. This addition will also be reflected in the node's XMLDoc object as well.

If the attribute name passed in already exists for the node, the old value will be removed and replaced with the new value.

For example, adding an attribute of name "name" and value "value" to <TAG1> in the following XML will yield:

<ROOT>
</ROOT>

<ROOT>
</ROOT>

var xml = ""
var objDom = new XMLDoc(, xmlError);
//first find the node to add the attribute to, in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now add the attribute
referenceNode.addAttribute("attribute", "attributeValue");

See also: domManipulationTestFive in domTestSuite.js

objNode.getAttribute(<attribute name>)

getAttribute's <attribute name> parameter is case sensitive.

For example, getting the "id" attribute from <TAG1> in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(, xmlError);
//first find the node to get an attribute from, in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now get the attribute
var attributeValue = referenceNode.getAttribute("id");

See also: domManipulationTestNine in domTestSuite.js

objNode.getAttributeNames()

getAttributeNames will return an empty array if there are no attributes for the node.

For example, getting the attribute names from <TAG1> in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node to get attributes from, in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now get the attributes
var attributes = referenceNode.getAttributes();

See also: domManipulationTestEight in domTestSuite.js

objNode.getElementById(<element's id attribute value>)

If there is more than one node in the XML with the same ID, the parser will return the first node found, searching top to bottom beginning at the node calling getElementById.

For example, getting the element of id 4 from in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(, xmlError);
//get the root node and then search for the node with id=4
var domTree = objDom.docNode;
var searchNode = domTree.getElementById("4");

See also: getElementByIdTestOne in domTestSuite.js

objNode.getElements(|tag name|)

If no tag name filter is passed to the method, getElements will return all of the elements under the node. If a tag name filter is specified, only those tags whos tag name matches that filter will be returned. An empty array will be returned if there are no tags under the node or if no tag names under the node match the tag name filter passed in.

For example, calling getElements("TAG1") from the <REFNC> node in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//find the first TAG1 node
var domTree = objDom.docNode;
var firstTag1Node = domTree.getElements("TAG1")[0];

objNode.getText()

Generally, getText is called on a node at the bottom of the tree to get the text value out of it. Calling getText on a node with node elements under it will return the text value of those nodes as well.

Sometimes putting your XML in HTML can cause extra spaces to be inserted into your text. Since XML for <SCRIPT> tries to retain these spaces, you may want to trim the retults of getText() to your liking.

For example, calling getText() from the <TAG1> node in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//find the first TAG1 node
var domTree = objDom.docNode;
var firstTag1Node = domTree.getElements("TAG1")[0];
alert(firstTag1Node.getText());

objNode.getParent()

For example, calling getParent() from the <TAG1> node in the following XML will yield:

<ROOT>
</ROOT>

The XMLNode object representing
<REFNC>
</REFNC>

var xml = ""
var objDom = new XMLDoc(, xmlError);
//first find the node to find the parent of, in this case TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
var elementParent = referenceNode.getParent();

See also: domManipulationTestEleven in domTestSuite.js

objNode.getUnderlyingXMLText()

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
var domTree = objDom.docNode;
var node = domTree.getElements("FOO")[0];
alert(node.getUnderlyingXMLText());

See also: underlyingXMLFunctionsTestTwo in domTestSuite.js

objNode.nodeType

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
var domTree = objDom.docNode;
var node = domTree.getElements("FOO")[0];
alert(node.nodeType);

See also: nodeTypeTestOne, nodeTypeTestTwo, nodeTypeTestThree and nodeTypeTestFour in domTestSuite.js

objNode.removeAttribute(<attribute name>)

removeAttribute will remove an attribute to the node object. This subtraction will also be reflected in the node's XMLDoc object as well.

For example, remove an attribute of name "name" from <TAG1> in the following XML will yield:

<ROOT>
</ROOT>

<ROOT>
</ROOT>

var xml = ""
var objDom = new XMLDoc(, xmlError);
//first find a node to remove an attribute from, in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now remove the attribute
referenceNode.removeAttribute("id");

See also: domManipulationTestSeven in domTestSuite.js

objNode.tagName

The tagName property returns the tag name (without any attributes) of the node.

For example, calling tagName from the <TAG1> node in the following XML will yield:

<ROOT>
</ROOT>


var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node for to get a tag name from , in this case, TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now get the tag name
alert(referenceNode.tagName);

See also: domManipulationTestEleven, domManipulationTestTen and getElementByIdTestOne in domTestSuite.js

objNode.toString()

The toString method produces a diagnostic string description of a the node.

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node for which we want to call toString, in this case it is TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//now get the tag name
alert(referenceNode.toString());

convertEscapes(<string>)

Characters such as less-than signs, greater-than signs and ampersands are illegal in XML syntax and must be escaped before being inserted into the DOM. This function is a convience function to take those escaped characters and return them to their original values for processing outside the parser.

XML for <SCRIPT> will automagically convert the content of the XML elements to their non-escaped values when xmlNode.getText() is called for every element except CDATA.

convertToEscapes(<string>)

Characters such as less-than signs, greater-than signs and ampersands are illegal in XML syntax. This function is a convience function to escape those characters out to there legal values.

Users of XML for <SCRIPT> should call this function any time they are performing dom manipulation by adding new nodes consisting of user-generated text with the exception of CDATA type nodes. While XML for <SCRIPT>'s Classic DOM Parser is generally rather loose with what it will allow in text, many other parsers are not (including XML for <SCRIPT>'s W3C DOM Parser) and will generate an error if one of these characters is unescaped.

var xml = ""
var objDom = new XMLDoc(xml, xmlError);
//first find the node that we want to insert into, in this case it is TAG1
var domTree = objDom.docNode;
var referenceNode = domTree.getElements("TAG1")[0];
//get a value input by the user in an HTML form
var userValue = document.getElementById("inputDescription").value;
//convert to escapes to make sure all XML is valid
userValue = convertToEscapes(userValue);
//create the new node
var newNode = objDom.createXMLNode("<DESC>" + userValue + "</DESC>");
//now add it to the tree
objDom = objDom.insertNodeInto(referenceNode, newNode);

See also: cmdSaveClicked in formFunctions.js

trim(<string>, |trim left true|false |, |trim right |true|false |)

In the trim function, trim left and trim right default to "true" if not passed in.