CONTENTS

What files do I need to include to use the SAX Parser?

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

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

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

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) {
}; // 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) {
} // end function startElement

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

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.

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.

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

var saxParser = new SAXDriver();

function parseXML(xml) { }

saxParser.parse(<xml>);

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

function parseXML(xml) { }

saxParser.setDocumentHandler(<Handler Object>);

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

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.

function parseXML(xml) { }

saxParser.setErrorHandler(<Handler Object>);

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

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.

function parseXML(xml) { }

saxParser.setLexicalHandler(<Handler Object>);

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

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.

function parseXML(xml) { }

var eventHandler = new SAXEventHandler();

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.

function parseXML(xml) { }

characters(data, start, length)

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

characters (data, start, length) { }

comment(data, start, length)

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
comment
endElement
endDocument

comments (data, start, length) { }

endCDATA()

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
startCDATA
characters
endCDATA
endElement
endDocument

endCDATA() { }

endDocument()

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument

endDocument() { }

endElement(<Element Name>)

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument

endElement(name) { }

error(<Exception object>)

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.

error(exception) { }

fatalError(<Exception object>)

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 version="1.0"?>
<root

setDocumentLocator
startDocument
processingInstruction
fatalError

fatalError(exception) { }

processingInstructiont(<Target>, <Data>)

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 version="1.0"?>
<root>
</root>

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"

processingInstructiont(target, data) { }

setDocumentLocator(<Parser Object>)

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument

setDocumentLocator(ParserObject) { }

startCDATA()

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
startCDATA
characters
endCDATA
endElement
endDocument

startCDATA() { }

startDocument()

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument


startDocument() { }

startElement(<Name>, <Attributes Object>)

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 version="1.0"?>
<root>
</root>

setDocumentLocator
startDocument
processingInstruction
startElement
endElement
endDocument

startElement(name, atts) { }

warning(<Exception object>)

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.

warning(exception) { }

_handleCharacterData()

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

_fullCharacterDataReceived(fullCharacterData)

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.

_fullCharacterDataReceived(fullCharacterData) { }

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.