XML for <SCRIPT> Cross Platform XML Parsing in JavaScript

Documentation - Tools

CONTENTS: What tools are available in XML for <SCRIPT>?; What files do I need to include to use XML for <SCRIPT>'s tools; What browsers does the xmlIO API work with?; What browsers does the xmlEscape API work with?
xmlIO API: How can I save XML to the client's hard drive?; xmlIODeleteData; xmlIOGetData; xmlIOSaveData; xmlIOListSavedDataNames; How can I load XML data from my local web server?; How can I load XML files from the client's file system?; What format must the server-side XML files be in?; xmlIOLoadLocalData; xmlIOLoadLocalGetLastLoadStatus; How can I load XML data from any domain?
xmlEscape API: How can I make my escaped XML easy to read and smaller?; xmlEscapeXMLToHTML; xmlUnescapeHTMLToXML

What tools are available in XML for <SCRIPT>?

XML for <SCRIPT> includes a number of tools that make development easier. These tools make it both possible and easy to extract, save and manipulate XML from a variety of data sources.

XML for <SCRIPT>'s tools have been catategorized into the following JavaScript files, which can be found in the jsTools directory. Three categories exist: one that requires both xmlIO.js and xmlEscape.js, one that requires xmlIO.js exclusively and one that requires xmlEscape.js exclusively.

Both xmlIO.js and xmlEscape.js

Load XML from any web server
Load XML from the local web server

xmlIO.js only

Load XML from client's stored cookies
Save XML to client via cookies
Retrieve list of saved XML data streams
Delete a saved XML data stream

xmlEscape.js only

Escape XML into valid and readable HTML
Unescape escaped XML back to true XML

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

What browsers does the xmlIO API work with?

Please be aware of some browser compatibility issues when using the xmlIO API. The xmlIO API has two sections: one for retreiving data via the local webserver, the client's filesystem, or via a server-side proxy and another for saving and retreiving XML data to the local client's hard drive via cookies. Each section has different browser compatibility issues.

Loading Local and Remote Data:

The xmlIO functions associated with loading remote data (via a server-side proxy) or loading local data (from the local web server or the client's filesystem) are compatible with the following browsers:

Netscape 6.0+
Mozilla (and Mozilla derivitives) 1.0+
Internet Explorer (Win32) 5.5+
Internet Explorer (MacOS) 5.2+
Opera 7+
Konqueror 3.01+
Safari 1.0+

The xmlIO functions associated with loading remote data (via a server-side proxy) or loading local data (from the local web server or the client's filesystem) are known to be incompatible with the following browsers:

Internet Explorer 5.0
Konqueror 2.x
Opera 6.x

The following functions are affected by this limitation:

xmlIOProxyLoadData
xmlIOProxyGetLastLoadStatus
xmlIOLoadLocalData
xmlIOLoadLocalGetLastLoadStatus

Loading/Saving XML Data via Cookies:

The xmlIO functions associated with loading, saving and manipulating XML data on the client's hard drive via cookies are compatible with the following browsers:

Netscape 6.0+
Mozilla (and Mozilla derivitives) 1.0+
Internet Explorer (all platforms) 5.0+
Opera 7+
Konqueror 3.03+

The xmlIO functions associated with loading, saving and manipulating XML data on the client's hard drive via cookies are known to be incompatible with the following browsers:

Konqueror 2.x
Opera 6.x

The following functions are affected by this limitation:

xmlIODeleteData
xmlIOGetData
xmlIOListSavedDataNames
xmlIOSaveData

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.

NOTE: On Mac OSX, the browsers do not delete the cookie name from the cookie collection when xmlIODeleteData is called. The cookie value is reset to a blank string, but the name is retained. This issue can be seen in Safari, IE and Mozilla/Netscape. This issue does not seem to be present on other operating systems.

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 load XML data from my local web server?

XML for <SCRIPT>'s server-side proxies allow JavaScript developers to load XML data from any domain on the Internet. However, for instances when the XML data that needs to be loaded resides on the same domain as the web page and its JavaScript (i.e. the local web server), the extra complexity involved with the server-side proxies may not be desired. In situations such as these, XML for <SCRIPT> provides an API that allows for XML data to be loaded from the local web server without the need to use the server-side proxies.

XML for <SCRIPT> attempts to make loading files from your local server both possible and simple. It does this by abstracting the many different methods for browser-server communications in a simple-to-use API. This API (xmlIOLoadLocalData) loads the local XML on behalf of the JavaScript and returns it to the browser in such a manner that reading and manipulation is possible.

NOTE: Please be aware of the browser limitations and the required server-side XML file format before using this feature.

How can I load XML files from the client's file system?

If your application runs from the client's local file system (such as a web application that runs off of a CD), you may use the xmlIOLoadLocalData API in the same manner as you would if you were loading the data from your local web server.

Since xmlIOLoadLocalData does not rely on any server-side software to be present when loading XML, it is fully capable of loading data from a filesystem without the need for a client to install any extra software.

NOTE: xmlIOLoadLocalData will only be able to load XML data from the local file system if the web page it is being called from originated on the local file system as well.

NOTE: Please be aware of the browser limitations and the required XML file format before using this feature.

What format must the server-side XML files be in?

XML for <SCRIPT>'s xmlIOLoadLocalData API has two very important requirements for the server-side XML files that it loads. These requirements are outlined below.

Requirement 1:

In order to avoid XML applications (such as XML Spy or kate) launching when you request the XML data from your web server, the file containing the XML data must have a mime type associated by the browsers as an HTML file. The easiest way to do this is to name your XML file with an HTMl extension (*.html, *.htm etc) and have your web server serve the file as a normal HTML file and *NOT* as an XML file.

NOTE: If you are loading XML data from the client's file system and do not have a web server, you must ensure that the browser recognizes the file as an HTML file that it is capable of opening.

For example, if your XML file was called data.xml, you could change the name to data.xml.html and properly load the XML data into your JavaScript using the xmlIOLoadLocalData API.

There are other ways of accomplishing this requirement as well. The core requirement being that the browser and operating system must think that it is getting a document back that should be handled by the browser and not another application.

Requirement 2:

The XML in the document must be returned to the browser with all "<" and ">" characters escaped to "«" (ascii char 171) and "»" (ascii char 187). This requirement ensures that all browsers will have access to the returned data. Without escaping the opening and closing tags, many browsers will not return all of the XML data back to the calling JavaScript.

For example, you might have a file called data.xml.html that looks like the following:

<xml>
  <tag>
    value
  </tag>
</xml>

In order to use the xmlIOLoadLocalData API, you would represent this data in the following way:

«xml»
  «tag»
    value
  «/tag»
«/xml»

xmlIOLoadLocalData

xmlIOLoadLocalData(<dataURL>, <callbackFunction>)

accepts:

dataURL - the URL of the data file to load
callbackFunction - a string with the name of the callback function that will be called when the data has been loaded.

returns:

N/A

The xmlIOLoadLocalData API allows JavaScript developers to load XML data either from the local web server or from the client's file system without the need for a server-side proxy or any other software.

The local web server is defined as the web server in which the web page running the JavaScript calling xmlIOLoadLocalData was served from.

NOTE: xmlIOLoadLocalData will *only* load data from the same domain that the JavaScript calling it originated from. It is not possible to load data from the client's file system if the web page originated from a web server.

xmlIOLoadLocalData works by creating an IFrame in the background with its src attribute being dataURL. xmlIOLoadLocalData then abstracts the various ways that browsers handle loading and reading data from IFrames and returns the data retrieved by calling the callback function.

The callback function used can have any name, but it must have the following method signature:

<methodName>(<xmlData>);

xmlData will be the fully unescaped XML data in String form.

To aid in debugging development issues, xmlIOLoadLocalData includes a logging variable that records the last action it took. If the callback function is never called, additional debugging information may be available by calling the xmlIOLoadLocalGetLastLoadStatus method.

NOTE: Please be aware of the browser limitations. the required XML file format and the required JavaScript files that must be included in your web page before using this API.

Example:

function loadLocalXML() {

/*
the XMLIO API handles all of the data retrieval.
all we need to do is tell it which file to load and what
function to call when it is finished
*/
xmlIOLoadLocalData("xmlData.xml.html", "callbackFunction");

} //end function loadLocalXML

function callbackFunction(strXML) {

//display the returned XML data
alert(strXML);

} // end method callbackFunction

xmlIOLoadLocalGetLastLoadStatus

xmlIOLoadLocalGetLastLoadStatus()

accepts:

N/A

returns:

String with the last result of the xmlIOLoadLocalData function

If for some reason the JavaScript programmer's callback function never gets called after an invocation of xmlIOLoadLocalData, more information about why may be available by calling the xmlIOLoadLocalGetLastLoadStatus method.

After a successful call to the callback function, the xmlIOLoadLocalGetLastLoadStatus will always return the string "__loadLocalIFrameXML successfully called callback function".

The most common reason for the callback function not being called is a misspelled callback function name in the call to xmlIOLoadLocalData function. In this case, JavaScript cannot call the callback function. In cases such as these, the error message detailing what went wrong will be returned by calling xmlIOLoadLocalGetLastLoadStatus.

Example:

//get local data
var dataURL = "xml.xml.html";
var cbFunction = "myCallbackFunc";

//set the callbackCalled variable to false;
callbackCalled = false;

//make the call to the API to load the local data
xmlIOLoadLocalData(dataUrl, cbFunction);

//If something goes really wrong, let the user know
window.setTimeout("getError()", 5000);

}

function myCallbackFunc(xmlData){

//set the callback called to true. This ensures
//our window.setTimeout error function knows everything is OK
callbackCalled = true;

//we have valid data. Show it to the user
alert("The XML returned was:\n" + xmlData);

}

function getError(){

//display the alert message if the callback
//function has not been called
if (callbackCalled == false) {
alert(xmlIOProxyGetLastLoadStatus());
}

}

</script>

How can I load XML data from any domain?

Please see the server-side proxy documentation in the "Documentation" -> "Server-Side Proxies" section of the web site.

xmlIOListSavedDataNames

xmlIOListSavedDataNames()

accepts:

N/A

returns:

An array containing all of the names of the saved data streams.

This function is useful for building dialogs that allow users to choose which data stream that they would like to open. It also can can be used by developers to ensure that a data stream name is not already in use before saving.

XML for <SCRIPT> does not compensate for this as it is possible to use the xmlIO functions to save an empty string whos name should show up in a call to xmlIOListSavedDataNames. If you are targeting Mac OSX and are using this feature, please be aware of this issue and code accordingly.

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:

your escaped HTML would look like this:

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:

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)

What browsers does the xmlEscape API work with?

The xmlEscape API is known to work with all browsers supported by XML for <SCRIPT>.

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:

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:

After: