Home
Documentation
Case Studies
Sample Code
Test Suites
History
Tools
Download
Documentation

The documentation for XML for <SCRIPT> is broken up into five sections:

General: Documentation layout and philosophy
FAQ: Information on licensing and other general items
DOM Parser: Documents the DOM Parser and gives code examples
SAX Parser: Documents the SAX Parser and gives code examples
Miscellaneous: Documents the extra tools and capabilities of the parser

The documentation above primarily consists of code examples that document the parser's API. For a more in-depth overview of XML for <SCRIPT>, you are highly encouraged to look at the source code for the test suites and the example applications. These demonstrate "real life" useage of the parsers and give a very good overview of the capabilities of the code.

NOTE: This page is big. Please be patient while it loads. In the future, the documentation will be split up into multiple pages.

FAQ

CONTENTS
  How do I get the XML to the browser?
  What license if XML for <SCRIPT> released under?
  Help! Netscape 6 doesn't send my XML to the server!
  Does XML for <SCRIPT> work in Konqueror?
  Does XML for <SCRIPT> work in Opera?
  Is there any type of error handling?
  Are there any known bugs?
  Why does the DOM parser always return a new XMLDoc object whenever it manipulates the tree?
  The .js files are huge! Are there smaller ones available?

How do I get the XML to the browser?

There are many ways to get the XML from the server side to the client. However, depending on your targeted browser set, some ways may be better than others. In many cases, it is best to use absolute positioning to position a <textarea> off of the screen that contains your XML text. Modern browsers make this option very easy by using cascading style sheets. Older browsers may require some tweaking.

Another option is to put your XML in a hidden <input> element.

In any case, please be sure to escape out your XML when you place it in your HTML page. While some browsers may let you do something like this:

<textarea>
<?xml version="1.0"?>
<ROOTNODE>
<NODE>
value
</NODE>
</ROOTNODE>
</textarea>

the above code is invalid HTML and can cause serious problems in some browsers, noteably Mozilla.

In many cases, these browsers will change the case of the tags (or add new ones) which will break the parser. Oddly enough, not all tags get modified. An example of one that does is <TITLE>. With unescaped XML in a textarea element, mozilla will change the case of the tag leading the DOM parser to report an error of "expected /TITLE found closing /title".

The XML code sent to the browser really should be escaped to HTML, as demonstrated below:

<textarea>
&lt;?xml version="1.0"?&gt;
&lt;ROOTNODE&gt;
&lt;NODE&gt;
value
&lt;/NODE&gt;
&lt;/ROOTNODE&gt;
</textarea>

New in version 2.0 of XML for <SCRIPT> is a tool that will help you automate the changing of your XML into valid HTML. Rather than convert the XML to escaped HTML (which can be hard to read and bloated) it converts the <, >, and & characters into high ASCII characters that are unlikely to be in your XML stream. This tool can be found under the "Tools" link on the left.

What license is XML for <SCRIPT> released under?

XML for <SCRIPT> is released under the GNU Library (Lesser) General Public License. For more informaiton, please see the COPYING file included in the distribution.

Help! Netscape 6 doesn't send my XML to the server!

Netscape 6 (and all Mozilla derivitives up to Mozilla .97) have a bug that causes them not to send form data back to the server if the form element has its CSS property "display" set to "none". In this case, it is necessary to set the "display" property to something else (i.e. "block") and then submit the form.

Instead of using "display: none" consider absolute positioning. It is cross-platform with the modern browsers and avoids this problem.

The status of this bug can be found here.

Does XML for <SCRIPT> work in Konqueror?

Konqueror versions 2.2 and higher should work just fine with XML for <SCRIPT> DOM versions 1.1 and higher. Konqueror versions 3.0 are required to run the SAX parser included in XML for <SCRIPT> version 2.0

Konqueror versions prior to 2.2 seem to have problems with some of the recursive elements of XML for <SCRIPT> and some of the regular expressions used to escape illegal XML characters.

Konqueror versions prior to 3.0 had difficulties with the anonymous functions included in the SAX parser of XML for <SCRIPT> version 2.0.

Does XML for <SCRIPT> work in Opera?

Yes! Both Opera 5 and Opera 6 fully pass the XML for <SCRIPT> test suites. Please keep in mind that if you're going to use Opera, some of the HTML DOM manipulation functions are different than IE, Konqueror or Mozilla. They are actually more like Netscape 4. For more information, please see the clearTestResults() and insertOptionElement() functions included with the test suites.

Is there any type of error handling?

Yes. XML for <SCRIPT> has a number of different ways to handle errors depending on which parser you use. For the DOM parser, you may define an error function in the constructor of your XMLDoc object. This function will be called with a parameter indicating the error string. For example:

var objDom = new XMLDoc(strXML, xmlError);

In this case, "xmlError" is a "pointer" to a function that XML for <SCRIPT> will call if there is an error. xmlError should be present in your script and should accept a single parameter. This parameter will be the string of the error. For example:

function xmlError(strError) {
alert(strError);
}

The XMLDoc object also has the hasErrors property you may query to see if any errors have been reported.

For the SAX parser, errors are reported in one of many of the SAX events. Once a SAX error has been fired parsing of the XML file stops at that point.

For more information on error handling, please look at the test suites for the parsers and inspect the error handling functions.

Are there any known bugs?

Yes. XML for <SCRIPT>'s DOM parser has two known bugs with attributes and attribute values.

1) If you place an > in the value of your attribute, XML for <SCRIPT> will appear to lock the browser. In fact, it is in a loop and will continue to call the error function until the browser is killed.

2) If you forget to close your attribute value with a quote, the same behavior as bug #1 can be observed.

XML for <SCRIPT> also has a bug where the function insertNodeInto will not produce the expected results for CDATA type nodes if the data contained within the CDATA tag contains a ">" symbol.

Why does the DOM parser always return a new XMLDoc object whenever it manipulates the tree?

At the moment, many of XML for <SCRIPT>'s dom manipulation functions are rather inefficient. An attempt was made to make all of the DOM manipulation be performed at the node level. However, JavaScript itself got in the way and prevented the code from working properly. For example, a node would be manipulated in the parser correctly, but as soon as the function returned into the application code, the node would no longer be updated correctly in either the local node object or the local XMLDoc object. It's unknown at this time whether this was a bug in the parser or a limitation of JavaScript.

Not all DOM manipulation functions had this problem. However, a consistant API was deemed more important than the performance benefits that would have been achieved with node-level manipulation. In addition, the performance of the parser is rather good even with the design employed. XML for <SCRIPT>'s dom manipulation functions have been used with success on large projects with large XML streams with adequate results.

This issue will be addressed in the future if the performance need arises. Patches are always welcome.

The .js files are huge! Are there smaller ones available?

Yes and no... There is a file called tinyxmldom.js included with the distribution. It has been run through the JavaScript Crunchinator at brainjar.com. This file is roughly 70% smaller than the standard xmldom.js file.

Currently, there is not a compressed version of xmlsax.js. This is due to me not being able to get the compressed version of it to work properly in the browsers after it had been crunched. If you would like to contribute a compressed tinyxmlsax.js file, I would appreciate it. If you do, please also include the diffs to xmlsax.js so that I can compress the files in the future as well.

DOM

CONTENTS
  How do I get started with the 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 - removeNodeFromTree method
  XMLDoc Object - replaceNodeContents method
  XMLDoc Object - source property
  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

How do I get started with the 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. Here's the code:

function displayXML() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";
//instantiate a new XMLDoc object. Send any errors to the xmlError function
var objDom = new XMLDoc(xml, xmlError)
//get the root node
var objDomTree = objDom.docNode;
//get all of the elements named "TAG1"
var tag1Elements = objDomTree.getElements("TAG1");
//get the first "TAG1" element
var element = tag1Elements[0];
//now get the text
var text = element.getText();
//show the user
alert(text);
} // end function displayXML

function xmlError(e) {
//there was an error, show the user
alert(e);
} //end function xmlError
XMLDoc Object - Constructor

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

accepts:
<xml string>: string containing XML text
<error function>: function name to call if there is an error
returns:
new XMLDoc object

Example:
function displayXML() {
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";
//instantiate a new XMLDoc object. Send any errors to the xmlError function
var objDom = new XMLDoc(xml, xmlError)
} // end function displayXML

function xmlError(e) {
//there was an error, show the user
alert(e);
} //end function xmlError
XMLDoc Object - createXMLNode method

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

accepts:
<xml string>: string containing XML text
returns:
new XMLNode object

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

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

See also: domManipulationTestOne in testSuite.js

XMLDoc Object - docNode property

var rootNode = objDom.docNode;

accepts:
N/A
returns:
new XMLNode object

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

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

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

XMLDoc Object - getUnderlyingXMLText method

objDom.getUnderlyingXMLText()

accepts:
N/A
returns:
string: The current XML representation of the XMLDoc object omitting processing instructions and DTD's. Also, this function turns any <TAG/> tags into <TAG></TAG>

Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<FOO>"
+ "<BAR>"
+ "hello"
+ "</BAR>"
+ "</FOO>";
var objDom = new XMLDoc(xml, xmlError);
alert(objDom.getUnderlyingXMLText());

See also: underlyingXMLFunctionsTestOne in testSuite.js

XMLDoc Object - hasErrors property

objDom.hasErrors;

accepts:
N/A
returns:
N/A

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.

Example:
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<>"
+ "</ROOTNODE>";
var objDom = new XMLDoc(xml, xmlError);
alert(objDom.hasErrors);
XMLDoc Object - insertNodeAfter method

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

accepts:
<reference node>: the node to insert the new node after
<new node>: the new node object to insert after the reference node object
returns:
new XMLDoc object

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 MISC section of the documentation.

Before:
<ROOTNODE>
<REFERENCE>
reference node
</REFERENCE>
</ROOTNODE>
After:
<ROOTNODE>
<REFERENCE>
reference node
</REFERENCE>
<NEW>
new!
</NEW>
</ROOTNODE>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "</TAG1>"
+ "</ROOTNODE>"
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 testSuite.js

XMLDoc Object - insertNodeInto method

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

accepts:
<reference node>: the node to insert the new node into
<new node>: the new node object to insert into the reference node object
returns:
new XMLDoc object

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 MISC section of the documentation.

Before:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
<NEW>
new!
</NEW>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<TAG3>"
+ "value"
+ "</TAG3>"
+ "</TAG1>"
+ "</ROOT>";
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 testSuite.js

XMLDoc Object - removeNodeFromTree method

objDom = objDom.removeNodeFromTree(<reference node>)

accepts:
<reference node>: the node to remove from the tree
returns:
new XMLDoc object

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:

Before:
<ROOT>
<REFNC>
<NEW>
<TAG1>
value
</TAG1>
</NEW>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
</REFNC>
</ROOT>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<TAG2>"
+ "hello"
+ "</TAG2>"
+ "</TAG1>"
+ "</ROOT>";
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 testSuite.js

XMLDoc Object - replaceNodeContents method

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

accepts:
<reference node>: the node to have it's contents replaced
<value>: the new value of the node
returns:
new XMLDoc object

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:

Before:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
<TAG1>
hello
</TAG1>
</REFNC>
</ROOT>

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

Before:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
hello
</REFNC>
</ROOT>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 attribute=\"keepme\">"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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 testSuite.js

XMLDoc Object - source property

objDom.source;

accepts:
N/A
returns:
N/A

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

Example:
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "value"
+ "</TAG1>"
+ "</ROOT>";
var objDom = new XMLDoc(xml, xmlError)
alert(objDom.source);
Node Object - Constructor

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

accepts:
<nodeType>: indicates the node type of the node
<doc>: contains a reference to the XMLDoc object describing the document
<str>: contains the text for the tag or text entity
returns:
new XMLNode object

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.

Example:
var xml;
xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "Hello World"
+ "</TAG1>"
+ "</ROOTNODE>";
//instantiate a new XMLDoc object.
var objDom = new XMLDoc(xml, xmlError)
var objNode = new XMLNode("TEXT", objDom, "<TAG1>value</TAG1>")
Node Object - addAttribute method

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

accepts:
<attribute name>: the name of the new attribute
<attribute value>: the value of the new attribute
returns:
N/A

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:

Before:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
<TAG1 name="value">
value
</TAG1>
</REFNC>
</ROOT>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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 testSuite.js

Node Object - getAttribute method

objNode.getAttribute(<attribute name>)

accepts:
<attribute name>: the name of the new attribute
returns:
attribute value: if name is found
null: if name is not found

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

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

XML:
<ROOT>
<REFNC>
<TAG1 id="value">
hello
</TAG1>
</REFNC>
</ROOT>
Result:
"value"
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1 id="hello" >"
+ "</TAG1>"
+ "</ROOT>";
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 testSuite.js

Node Object - getAttributeNames method

objNode.getAttributeNames()

accepts:
N/A
returns:
Array of attribute Names for the node

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:

XML:
<ROOT>
<REFNC>
<TAG1 id="value" hxy="2" >
</TAG1>
</REFNC>
</ROOT>
Result:
Array[0] = "id"
Array[1] = "hxy"
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1 id="hello" >"
+ "</TAG1>"
+ "</ROOT>";
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 testSuite.js

Node Object - getElementById method

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

accepts:
<element's id attribute value>: the id attribute value of a node to search for
returns:
XMLNode object: if id is found
null: if id is not found

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:

XML:
<ROOT>
<REFNC>
<TAG1 id="4">
value
</TAG1>
</REFNC>
</ROOT>
Result:
The node object representing <TAG1 id="4">value</TAG1>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<REFNC>"
+ "<TAG1 id="4">"
+ "value"
+ "</TAG1>"
+ "</REFNC>"
+ "</ROOT>";
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 testSuite.js

Node Object - getElements method

objNode.getElements(|tag name|)

accepts:
|tag name|: optional element name to filter on.
returns:
Array of XMLNode objects: if any are found matching the filter criteria

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:

XML:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
<TAG2>
value
</TAG2>
</REFNC>
</ROOT>
Result:
Array[0]: node object representing <TAG1>value</TAG1>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1 id="hello" >"
+ "</TAG1>"
+ "</ROOT>";
var objDom = new XMLDoc(xml, xmlError);
//find the first TAG1 node
var domTree = objDom.docNode;
var firstTag1Node = domTree.getElements("TAG1")[0];
Node Object - getText method

objNode.getText()

accepts:
N/A
returns:
The text value of the node with the escape values converted to their real value for TEXT and COMMENT nodes.

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:

XML:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
<TAG2>
value
</TAG2>
</REFNC>
</ROOT>
Result:
"value"
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1 id=\"hello\" >"
+ "</TAG1>"
+ "</ROOT>";
var objDom = new XMLDoc(xml, xmlError);
//find the first TAG1 node
var domTree = objDom.docNode;
var firstTag1Node = domTree.getElements("TAG1")[0];
alert(firstTag1Node.getText());
Node Object - getParent method

objNode.getParent()

accepts:
N/A
returns:
The parent XMLNode object to the node

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

XML:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
<TAG2>
value
</TAG2>
</REFNC>
</ROOT>
Result:
The XMLNode object representing
<REFNC>
<TAG1>
value
</TAG1>
<TAG2>
value
</TAG2>
</REFNC>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1>"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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 testSuite.js

Node Object - getUnderlyingXMLText method

objNode.getUnderlyingXMLText()

accepts:
N/A
returns:
string: The current XML representation of the XMLNode object omitting processing instructions and DTD's. Also, this function turns any <TAG/> tags into <TAG></TAG>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<FOO>"
+ "<BAR>"
+ "hello"
+ "</BAR>"
+ "</FOO>";
var objDom = new XMLDoc(xml, xmlError);
var domTree = objDom.docNode;
var node = domTree.getElements("FOO")[0];
alert(node.getUnderlyingXMLText());

See also: underlyingXMLFunctionsTestTwo in testSuite.js

Node Object - nodeType property

objNode.nodeType

accepts:
N/A
returns:
string: The node type of the node.
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<FOO>"
+ "<BAR>"
+ "hello"
+ "</BAR>"
+ "</FOO>";
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 testSuite.js

Node Object - removeAttribute method

objNode.removeAttribute(<attribute name>)

accepts:
<attribute name>: the name of the attribute to remove
returns:
N/A

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:

Before:
<ROOT>
<REFNC>
<TAG1 name="value">
hello
</TAG1>
</REFNC>
</ROOT>
After:
<ROOT>
<REFNC>
<TAG1>
value
</TAG1>
</REFNC>
</ROOT>
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 id=\"3\">"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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 testSuite.js

Node Object - tagName property

objNode.tagName

accepts:
N/A
returns:
N/A

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:

XML:
<ROOT>
<REFNC>
<TAG1 name="value">
hello
</TAG1>
</REFNC>
</ROOT>
Result:
"TAG1"
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 id=\"3\">"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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 testSuite.js

Node Object - toString method

objNode.toString()

accepts:
N/A
returns:
N/A

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

Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOTNODE>"
+ "<TAG1 id=\"3\">"
+ "foo"
+ "</TAG1>"
+ "</ROOTNODE>";
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());
Convenience Functions - convertEscapes function

convertEscapes(<string>)

accepts:
<string>: string with escaped characters (i.e. "&lt;")
returns:
string with unescaped characters (i.e. "<")

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.

Examples:
&amp; == &
&lt; == <
&gt; == >
Convenience Functions - convertToEscapes function

convertToEscapes(<string>)

accepts:
<string>: string with unescaped characters (i.e. "<")
returns:
string with escaped characters (i.e. "&lt;")

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

Examples:
< == &lt;
> == &gt;
& == &amp;
Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<TAG3>"
+ "value"
+ "</TAG3>"
+ "</TAG1>"
+ "</ROOT>";
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

Convenience Functions - trim function

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

accepts:
<string>: string to be trimmed
|trim left|: (optional) trim the left side of the string
|trim right|: (optional) trim the right side of the string
returns:
string trimmed as desired.

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

SAX

CONTENTS
  How do I get started with the SAX Parser?
  What SAX Events and Interfaces are supported?
  Is there a pre-built event handler object available?
  Do I need to catch every event fired by the SAX Parser?
  What's this handleCharacterData function for?
  SAXDriver Object - Constructor
  SAXDriver Object - parse method
  SAXDriver Object - setDocumentHandler method
  SAXDriver Object - setErrorHandler method
  SAXDriver Object - setLexicalHandler method
  SAXEventHandler Object - Constructor
  SAXEventHandler Object - characters event
  SAXEventHandler Object - comment event
  SAXEventHandler Object - endCDATA event
  SAXEventHandler Object - endDocument event
  SAXEventHandler Object - endElement event
  SAXEventHandler Object - error event
  SAXEventHandler Object - fatalError event
  SAXEventHandler Object - processingInstruction event
  SAXEventHandler Object - setDocumentLocator event
  SAXEventHandler Object - startCDATA event
  SAXEventHandler Object - startDocument event
  SAXEventHandler Object - startElement event
  SAXEventHandler Object - warning event
  SAXEventHandler Object - _handleCharacterData method
  SAXEventHandler Object - _fullCharacterDataReceived
  trim

How do I get started with the SAX Parser?

It's actually very easy. XML for <SCRIPT> ships with a pre-built SAXEventHandler object that is ready to accept events from the SAXDriver object. Simply copy the code in preMadeSaxEventHandler.js (located in the jsXMLParser directory) into your code (or link to the file) and write code to handle events as you see fit.

For example, if you wanted to show the user an alert box with the name of each element as it was parsed, you would write the following code:

function startParser(xml) {
var parser = new SAXDriver();
var eventHandler = new SAXEventHandler();
parser.setDocumentHandler(eventHandler);
parser.setLexicalHandler(eventHandler);
parser.setErrorHandler(eventHandler);
parser.parse(xml);
}; // end function startParser

The code to show the alert box at the start of each element would reside in the startElement event sink and would look like the following:

SAXEventHandler.prototype.startElement = function(name, atts) {
alert(name);
} // end function startElement
What SAX Events and Interfaces are supported?

The SAX "standard" defines the following interfaces. See below for the support offerred by XML for <SCRIPT>

Implemented Interfaces:
//Document Interface
SAXDocumentHandler.startDocument ()
SAXDocumentHandler.endDocument ()
SAXDocumentHandler.startElement (name, atts)
SAXDocumentHandler.endElement (name)
SAXDocumentHandler.characters (data, start, length)
SAXDocumentHandler.processingInstruction (target, data)
SAXDocumentHandler.setDocumentLocator (locator)
//Lexical Interface
SAXLexicalHandler.startCDATA ()
SAXLexicalHandler.endCDATA ()
SAXLexicalHandler.comment (data, start, length)
//Error Interface
SAXErrorHandler.warning (exception)
SAXErrorHandler.error (exception)
SAXErrorHandler.fatalError (exception)
Unimplemented Interfaces:
SAXDocumentHandler.ignorableWhitespace (data, start, length)
SAXLexicalHandler.startDTD (name, publicId, systemId)
SAXLexicalHandler.endDTD ()
SAXLexicalHandler.startEntity (name)
SAXLexicalHandler.endEntity (name)
Is there a pre-built event handler object available?

Yes! Please see the file preMadeSaxEventHandler.js in the jsXMLParser directory. This pre-built object supports all three event handling interfaces (Document, Lexical and Error) as well as provides built in methods for correctly handling character data.

Please keep in mind that you don't *have* to use this pre-built object if you don't want to. You may certainly roll your own if it suits you needs better.

Do I need to catch every event fired by the SAX Parser?

No. XML for <SCRIPT>'s SAX Driver object is capable of detecting whether or not an event handler exists for the event it wants to fire. If no event handler exists, the event will not fire and the parsing will continue.

What's this handleCharacterData function for?

During the parsing of an XML document, it is possible that the characters event may fire multiple times for a single element. If you place your characters event handling code in this event, you may not get all of the character data you expect.

To compensate for this behavior, XML for <SCRIPT>'s pre-built event handler includes a function called _handleCharacterData. This function is designed to capture all of the character data reported to the event handler and report it to the user all at once in the _fullCharacterDataReceived function. This reporting is done only when the function is sure there is no more character data expected for that element.

For more information on the _handleCharacterData function, click here

For more information on the _fullCharacterDataReceived function, click here

SAXDriver Object - Constructor

var saxParser = new SAXDriver();

Accepts:
N/A
Returns:
new SAXDriver object
Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXDriver Object - parse method

saxParser.parse(<xml>);

Accepts:
<xml> - String containing the XML to parse
Returns:
N/A

The parse method begins the process of parsing the XML data. The processing will complete before the next line of code is called.

Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXDriver Object - setDocumentHandler method

saxParser.setDocumentHandler(<Handler Object>);

Accepts:
<Handler Object> - An object that supports the Document Event Interface
Returns:
N/A

setDocumentHandler tells the SAX parser what code to call for the following events:

startDocument ()
endDocument ()
startElement (name, atts)
endElement (name)
characters (data, start, length)
processingInstruction (target, data)
setDocumentLocator (locator)

Your handler object does not need to support all of these events. Events that do not interest you can be left out with no ill-effect. However, for the events that you do wish to trap, your handler object must implement the above functions exactly as shown.

For your convenience, XML for <SCRIPT> provides a pre-built event handler in the file preMadeSaxEventHandler.js under the jsXMLParser directory. This handler implements all three SAX interfacs for you so you do not have to code them yourself.

Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXDriver Object - setErrorHandler method

saxParser.setErrorHandler(<Handler Object>);

Accepts:
<Handler Object> - An object that supports the Error Event Interface
Returns:
N/A

setErrorHandler tells the SAX parser what code to call for the following events:

SAXErrorHandler.warning (exception)
SAXErrorHandler.error (exception)
SAXErrorHandler.fatalError (exception)

Your handler object does not need to support all of these events. Events that do not interest you can be left out with no ill-effect. However, for the events that you do wish to trap, your handler object must implement the above functions exactly as shown.

For your convenience, XML for <SCRIPT> provides a pre-built event handler in the file preMadeSaxEventHandler.js under the jsXMLParser directory. This handler implements all three SAX interfacs for you so you do not have to code them yourself.

Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXDriver Object - setLexicalHandler method

saxParser.setLexicalHandler(<Handler Object>);

Accepts:
<Handler Object> - An object that supports the Lexical Event Interface
Returns:
N/A

setLexicalHandler tells the SAX parser what code to call for the following events:

SAXLexicalHandler.startCDATA ()
SAXLexicalHandler.endCDATA ()
SAXLexicalHandler.comment (data, start, length)

Your handler object does not need to support all of these events. Events that do not interest you can be left out with no ill-effect. However, for the events that you do wish to trap, your handler object must implement the above functions exactly as shown.

For your convenience, XML for <SCRIPT> provides a pre-built event handler in the file preMadeSaxEventHandler.js under the jsXMLParser directory. This handler implements all three SAX interfacs for you so you do not have to code them yourself.

Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXEventHandler Object - Constructor

var eventHandler = new SAXEventHandler();

Accepts:
N/A
Returns:
New SAXEvent handler object

The SAXEventHandler object is XML for <SCRIPT>'s pre-built event handler. It exists for your convenience. If you choose to roll your own event handler, you may ignore the information contained in the constructor section of the documentation. If you do roll your own event handler, it will need to have the same function signatures as the pre-built event handler for the events you will be trapping.

Example:
function parseXML(xml) {
//instantiate the SAX Driver object
var saxParser = new SAXDriver();
//instantiate the pre-built event handler object
var eventHandler = new SAXEventHandler();
//tell the SAX driver object where to send events
saxParser.setDocumentHandler(eventHandler);
saxParser.setLexicalHandler(eventHandler);
saxParser.setErrorHandler(eventHandler);
//start the parsing process
saxParser.parse(xml);
}
SAXEventHandler Object - characters event

characters(data, start, length)

Provides:
data - the raw xml data provided to the parser
start - position to start getting characters
length - number of characters to get

During the parsing of an XML document, it is possible that the characters event may fire multiple times for a single element. If you place your characters event handling code in this event, you may not get all of the character data you expect.

To compensate for this behavior, XML for <SCRIPT>'s pre-built event handler includes a function called _handleCharacterData. This function is designed to capture all of the character data reported to the event handler and report it to the user all at once in the _fullCharacterDataReceived function. This reporting is done only when the function is sure there is no more character data expected for that element.

The characters event traps the character data being reported by the parser, and appends the new data to an internal variable that keeps track of all the previous character data that had been reported for the current element.

For more information on the _handleCharacterData function, click here

For more information on the _fullCharacterDataReceived function, click here

Example:
characters (data, start, length) {
this.characterData += data.substr(start, length);
}
SAXEventHandler Object - comment event

comment(data, start, length)

Provides:
data - the raw xml data provided to the parser
start - position to start getting characters
length - number of characters to get

The comment event is fired whenever comment data is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsComment1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
<!--Comment Text-->
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
comment
endElement
endDocument
Example:
comments (data, start, length) {
var commentData = data.substr(start, length);
}
SAXEventHandler Object - endCDATA event

endCDATA()

Provides:
N/A

The endCDATA event is fired whenever the end of a CDATA section is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsCDATA1() in saxTestSuite.js.

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
<![CDATA[CDATA Text]]>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
startCDATA
characters
endCDATA
endElement
endDocument
Example:
endCDATA() {
//make note that we have reached end of CDATA tag
}
SAXEventHandler Object - endDocument event

endDocument()

Provides:
N/A

The endDocument event is fired whenever the end of the document is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElement1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument
Example:
endDocument() {
//make note that we have reached end of the document
}
SAXEventHandler Object - endElement event

endElement(<Element Name>)

Provides:
<Element Name> - the name of the element that is ending

The endElement event is fired whenever the end of an element is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElement1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument
Example:
endElement(name) {
alert("I have reached the end of the element " + name);
}
SAXEventHandler Object - error event

error(<Exception object>)

Provides:
<Exception object> - Object containing information about the exception

The exception object has these methods:

exception.getMessage() - returns an error string
exception.getLineNumber() - returns the line number of the error
exception.getColumnNumber() - returns the column number of the error

At this time, XML for <SCRIPT>'s SAX parser does not throw this event. All error reporting is provided via the fatalError event. For more information on that event, please click here In the future, this event may be utilized so it is highly recommended that you place error trapping code in your handler for this event.

Example:
error(exception) {
//tell the user there is a problem
alert(exception.getMessage());
}
SAXEventHandler Object - fatalError event

fatalError(<Exception object>)

Provides:
<Exception object> - Object containing information about the exception

The exception object has these methods:

exception.getMessage() - returns an error string
exception.getLineNumber() - returns the line number of the error
exception.getColumnNumber() - returns the column number of the error

The fatalError event is fired whenever an error is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElementError1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root
Events:
setDocumentLocator
startDocument
processingInstruction
fatalError
Example:
fatalError(exception) {
//tell the user there is a problem
alert(exception.getMessage());
}
SAXEventHandler Object - processingInstruction event

processingInstructiont(<Target>, <Data>)

Provides:
<Target> - the target of the processing instruction
<Data> - the data of the processing instruction

The processingInstruction event is fired whenever a processing instruction is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsPI1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument

In the above example, the Target variable passed in would be set to xml while the data variable would be set to version="1.0"

Example:
processingInstructiont(target, data) {
alert("Processing instruction target:" + target);
alert("Processing instruction data:" + data);
}
SAXEventHandler Object - setDocumentLocator event

setDocumentLocator(<Parser Object>)

Provides:
<Parser Object> - A handle to the low level XML Parser

The setDocumentLocator event is always the first event fired when parsing an XML stream. The object provided is a handle to the actuall object behind the scenes responsible for the parsing of the XML. In most cases, you will not need to do anything with this object and this event can safely be ignored. However, if you do need raw access to the underlying parser, it is provided to you here. If you do need to add functionality to this underlying parser, the object that is being returned is defined in xmlsax.js as XMLP.

For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElement1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument
Example:
setDocumentLocator(ParserObject) {
//ignore this event
}
SAXEventHandler Object - startCDATA event

startCDATA()

Provides:
N/A

The startCDATA event is fired whenever the start of a CDATA section is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsCDATA1() in saxTestSuite.js.

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
<![CDATA[CDATA Text]]>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
startCDATA
characters
endCDATA
endElement
endDocument
Example:
startCDATA() {
//make note that we have found the start of a CDATA tag
}
SAXEventHandler Object - startDocument event

startDocument()

Provides:
N/A

The startDocument event is fired when the start of a the document is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElement1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument
Example:
Example:
startDocument() {
//make note that we have found the start of the document
}
SAXEventHandler Object - startElement event

startElement(<Name>, <Attributes Object>)

Provides:
<Name> - The name of the element that is starting
<Attribute Object> - An object representing the element's attributes

The Attributes Object (atts) has these methods:

atts.getName(<ordinal>) - gets the name of the attribute specified
atts.getValue(<ordinal>) - gets the value of the attribute specified
atts.getLength() -- gets the number of attributes for the element
atts.getValueByName(<name>) -- gets the value for the attribute specified

The value expected for the methods getName and getValue is a zero based ordinal based on the position of the attribute you're looking for in the attribute list.

The startElement event is fired when the start of an element is found in the XML stream. For example, the following XML will yield the events listed below if XML for <SCRIPT>'s pre-built event handler is used.

NOTE: Only the event name is reported here. For a full description of the events fired with this XML, please see testsElement1() in saxTestSuite.js

NOTE: If the "characters" event is listed below, it is assumed to come from the function _fullCharacterDataReceived.

XML:
<?xml version="1.0"?>
<root>
<tag att1="val1" att2="val2">
</tag>
</root>
Events:
setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument
Example:
startElement(name, atts) {
//get element name
var elm = "Element Name: " + name + "\n");
//now loop through attributes
var intCount = atts.getLength();
if (intCount > 0) {
elm += "Has element data of:\n";
}
for (intLoop=0;intLoop<intCount;intLoop++) {
elm += atts.getName(intLoop) + ": ";
elm += atts.getValue(intLoop) + "\n"
}
//display element info
alert(elm);
}
SAXEventHandler Object - warning event

warning(<Exception object>)

Provides:
<Exception object> - Object containing information about the exception

The exception object has these methods:

exception.getMessage() - returns an error string
exception.getLineNumber() - returns the line number of the error
exception.getColumnNumber() - returns the column number of the error

At this time, XML for <SCRIPT>'s SAX parser does not throw this event. All error reporting is provided via the fatalError event. For more information on that event, please click here In the future, this event may be utilized so it is highly recommended that you place error trapping code in your handler for this event.

Example:
warning(exception) {
//tell the user there is a problem
alert(exception.getMessage());
}
SAXEventHandler Object - _handleCharacterData method

_handleCharacterData()

Provides:
N/A

During the parsing of an XML document, it is possible that the characters event may fire multiple times for a single element. If you place your characters event handling code in this event, you may not get all of the character data you expect.

To compensate for this behavior, XML for <SCRIPT>'s pre-built event handler includes a function called _handleCharacterData. Since the characters event can be fired multiple times for an element, the only way to be sure you have received all of the characters for an element is to wait until an event other than characters is fired while at the same time storing all of the data reported by the multiple characters events. Once this non-character event is fired, then you can be assured you have the complete character data for the element.

_handleCharacterData is the internal function that serves the purpose of checking for non-characters events. It is called at the beginning every event which can signify that all of the characters data has been received. When _handleCharacterEvents is called, it checks the internal variable that holds the collection of characters data. If that varable is non-blank, then the function calls the interal event _fullCharacterDataReceived and resets the internal variable. _fullCharacterDataReceived is where you should put your character handling code.

Generally, it will not be necessary for you to modify this function.

For more information on the _fullCharacterDataReceived function, click here

SAXEventHandler Object - _fullCharacterDataReceived

_fullCharacterDataReceived(fullCharacterData)

Provides:
fullCharacterData - all of the character data for the element

During the parsing of an XML document, it is possible that the characters event may fire multiple times for a single element. If you place your characters event handling code in this event, you may not get all of the character data you expect.

XML for <SCRIPT>'s pre-built event handler compensates for this behavior for you. Once it is sure that all of the character data has been received for an element, it fires _fullCharacterDataReceived. This event is where you should put your characters event handling code.

Example:
_fullCharacterDataReceived(fullCharacterData) {
//show the user all of the character data
alert("characters for this element: " + fullCharacterData);
}
Convenience Functions - trim function

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

accepts:
<string>: string to be trimmed
|trim left|: (optional) trim the left side of the string
|trim right|: (optional) trim the right side of the string
returns:
string trimmed as desired.

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

MISC

CONTENTS
  How can I save XML to the client's hard drive?
  xmlIODeleteData
  xmlIOGetData
  xmlIOSaveData
  How can I make my escaped XML easy to read and smaller?
  xmlEscapeXMLToHTML
  xmlUnescapeHTMLToXML

How can I save XML to the clients hard drive?

In many instances, it is nice to be able to save an XML stream onto a client's hard drive. Sadly (or thankfully, depending on your perspective) this is made difficult if not impossible to do by the browsers. Each browser does have methods allowing this type of activity, but these methods are not cross platform and can raise serious security concerns with users.

XML for <SCRIPT> attempts to resolve this information by providing an interface for saving and retrieving XML streams using cookies. This interface allows programmers to save data for a specified period of time and retrieve that data when needed. It is not a requirement to save XML, any string data is supported by the interface.

NOTE: This API is only functional in Netscape, Mozilla and Internet Explorer. Konqueror and Opera don't support JavaScript manipulation of cookies.
xmlIODeleteData

xmlIODeleteData(<Stream Name>)

accepts:
<Stream Name>: name of the saved data stream to delete
returns:
N/A

On browsers that support JavaScript manipulation of cookies, xmlIODelete will remove a named data stream from the cookie on the client's machine by setting that cookie's expiration date to a time in the past.

Example:
//delete the XML Stream named savedXML
xmlIODeleteData("savedXML");
xmlIOGetData

xmlIOGetData(<Stream Name>)

accepts:
<Stream Name>: name of the saved data stream to retrieve
returns:
string containing the data stream requested

On browsers that support JavaScript manipulation of cookies, xmlIOGetData will return the saved data from the cookie on the client's machine.

Example:
//get the saved XML named savedXML from the cookie
var myXML = xmlIOGetData("savedXML");
xmlIOSaveData

xmlIOSaveData(<Stream Name>, <Data> [,expiration date])

accepts:
<Stream Name>: name of data stream to save
<Data>: The data to save
[expiration date]: JavaScript date object reflecting the time the saved data will be automatically deleted
returns:
N/A

On browsers that support JavaScript manipulation of cookies, xmlIOSaveData will save the data passed in to the cookie on the client's machine. This data will remain until either the user deletes it manually, the programmer deletes it via xmlIODeleteData, or the expiration date has passed.

If the expiration date parameter is not passed in, xmlIOSaveData will set the cookie to automatically expire on January 1st, 10 years in the future.

Example:
var xml = ""
+ "<?xml version=\"1.0\"?>"
+ "<ROOT>"
+ "<TAG1>"
+ "<TAG3>"
+ "value"
+ "</TAG3>"
+ "</TAG1>"
+ "</ROOT>";
//save the xml to the client's hard drive until Jan 1, 2003
var expDate = new Date("January 1, 2003");
xmlIOSaveData("savedXML", xml, expDate);
How can I make my escaped XML easy to read and smaller?

Escaping XML into valid HTML can be an error prone and expensive process. The escaped HTML is very difficult to read with the human eye and is much larger than the original XML source. For example, if you had some original XML such as the following:

<root>
<node></node>
</root>

your escaped HTML would look like this:

&lt;root&gt;
&lt;node&gt;&lt;/node&gt;
&lt;/root&gt;

This escaped HTML is hard to read and can be much larger than the original XML text.

XML for <SCRIPT> attempts to resolve this situation by converting your XML into valid HTML not by escaping the XML, but by replacing the XML markup tags with high ascii characters which are not likely to be found in your XML data. Consider the same example as before:

<root>
<node></node>
</root>

After running that XML through the XML for <SCRIPT> xmlEscape functions, your XML would look like this:

«root»
«node»«/node»
«/root»

This data is valid HTML and can be placed anywhere in your HTML form safely. It is also much easier to read and no larger than the original XML.

If you need to convert your XML on the server side before sending the XML to the client, XML for <SCRIPT> performs the following conversions in its xmlEscape functions.

< == « == String.fromCharCode(171)
> == » == String.fromCharCode(187)
& == § == String.fromCharCode(167)

xmlEscapeXMLToHTML

xmlEscapeXMLToHTML(<XML Data>)

accepts:
<XML Data>: XML Data to be escaped
returns:
String containing a representation of the XML data in valid HTML

xmlEscapeXMLToHTML is a useful function to help you escape out your XML to valid HTML. The valid HTML that is returned is smaller than standard escaped HTML and is still human readable. xmlEscapeXMLToHTML converts the following characters:

< == « == String.fromCharCode(171)
> == » == String.fromCharCode(187)
& == § == String.fromCharCode(167)

For example, calling xmlEscapeXMLToHTML on the following XML:

Before:
<root>
<node></node>
</root>

will yield the following text:

After:
«root»
«node»«/node»
«/root»
xmlUnescapeHTMLToXML

xmlUnescapeHTMLToXML(<HTML Data>)

accepts:
<HTML Data>: Escaped HTML data
returns:
String containing the original XML data before it was escaped

xmlUnescapeHTMLToXML is the companion function to xmlEscapeXMLToHTML. This function will take a string that has been run through xmlEscapeXMLToHTML and return it to its original form.

For example, calling xmlUnescapeHTMLToXML on the following escaped HTML:

Before:
«root»
«node»«/node»
«/root»

will yield the following text:

Before:
<root>
<node></node>
</root>