The XMLUtilJS script include provides XML utility methods for JavaScript to be used with Discovery scripts.

This script include is provided with the Discovery plugin. Use this script include in any server-side Discovery script in which you need XML utilities.

Access these methods using the static variable XMLUtilJS.

XMLUtilJS - escapeForXMLText(String text)

Provides escape text for a given string.

Table 1. Parameters
Name Type Description
text String The text to format.
Table 2. Returns
Type Description
String The formatted text.

Example

The following example shows how to list escaped XML data in a document. See also stringToValue().

// Create an XML document to work with
var doc = new XMLDocument2();

// Add an element called catalog
var catalog = doc.createElement('catalog');

// Set current element to the one previously made to add more elements
doc.setCurrentElement(catalog);

// Add an element called catalog
var bookAttribute = doc.createElement('book');

// Add an attribute to the element created
bookAttribute.setAttribute('id', 'bk101');

// Create multiple elements with a defined value
doc.createElementWithTextValue('author', 'Gambardella, Matthew');
doc.createElementWithTextValue('title', 'XML Developer');
doc.createElementWithTextValue('genre', 'Computer');
doc.createElementWithTextValue('price', '44.95');

// Pass the created XML document as a string to the XMLUtilJS API function
var escapedXML = XMLUtilJS.escapeForXMLText(doc.toString());

// Print the escapedXML. If an invalid XML is created, the original value will be returned
gs.print(escapedXML);

Output:

<?xml version="1.0" encoding="UTF-8"?><catalog><book id="bk101"/><author>Gambardella, Matthew</author><title>XML Developer</title><genre>Computer</genre><price>44.95</price></catalog>

XMLUtilJS - stringToValue(String str)

Converts a string to an XML value.

Table 3. Parameters
Name Type Description
str String The string to convert.
Table 4. Returns
Type Description
String The specified string converted to XML.

Example

The following example shows how to transform a string of escaped XML to tagged XML output. See also escapeForXMLText().

//Example of an escaped XML string, previously generated by XMLUtilJS.escapeForXMLText()
var escapedXML = '<catalog><book id="bk101"><author>Gambardella, Matthew</author><title>XML Developer\'s Guide</title><genre>Computer</genre><price>44.95</price><publish_date>2000-10-01</publish_date><description>An in-depth look at creating applications with XML.</description></book></catalog>';

//Pass in escaped XML text and store output in a variable
var output = XMLUtilJS.stringToValue(escapedXML);

// If the input value is a string value of NULL, the output will be null, otherwise an unescaped XML string value.
gs.print(output);

Output:

<catalog><book id="bk101"><author>Gambardella, Matthew</author><title>XML Developer's Guide</title><genre>Computer</genre><price>44.95</price><publish_date>2000-10-01</publish_date><description>An in-depth look at creating applications with XML.</description></book></catalog>

XMLUtilJS - unescapeForXMLText(String text)

Provides un-escaped XML for a given string.

Table 5. Parameters
Name Type Description
text String The XML text to clean up.
Table 6. Returns
Type Description
String The cleaned up XML string.

Example

The following example shows how to convert an escaped XML string to tagged XML output. See also escapeForXMLText().

//Example of an escaped XML string, previously generated by XMLUtilJS.escapeForXMLText()
var escapedXML = '&lt;catalog&gt;&lt;book id="bk101"&gt;&lt;author&gt;Gambardella, Matthew&lt;/author&gt;&lt;title&gt;XML Developer\'s Guide&lt;/title&gt;&lt;genre&gt;Computer&lt;/genre&gt;&lt;price&gt;44.95&lt;/price&gt;&lt;publish_date&gt;2000-10-01&lt;/publish_date&gt;&lt;description&gt;An in-depth look at creating applications with XML.&lt;/description&gt;&lt;/book&gt;&lt;/catalog&gt;';

//Pass in escaped XML text and store output in a variable
var output = XMLUtilJS.unescapeForXMLText(escapedXML);


//Print the escapedXML. If the XML is invalid, the original value will be returned
gs.print(output);

Output:

<catalog><book id="bk101"><author>Gambardella, Matthew</author><title>XML Developer's Guide</title><genre>Computer</genre><price>44.95</price><publish_date>2000-10-01</publish_date><description>An in-depth look at creating applications with XML.</description></book></catalog>

XMLUtilJS - valueToString(String XMLvalue)

Converts an XML value to a string.

Table 7. Parameters
Name Type Description
XMLvalue String The XML to convert
Table 8. Returns
Type Description
String The XML value converted to a string.

Example

The following example shows how to convert an XML document to a string.

//Create an XML document to work with
var doc = new XMLDocument2();

//Add an element called catalog
var catalog = doc.createElement("catalog");

//Set our current element to the one previously made to add further elements
doc.setCurrentElement(catalog);

//Add an element called catalog
var bookAttribute = doc.createElement("book");

//Add an attribute to the element created
bookAttribute.setAttribute("id" , "bk101");

//create multiple elements with a defined value
doc.createElementWithTextValue("author" , "Gambardella, Matthew");
doc.createElementWithTextValue("title" , "XML Developer");
doc.createElementWithTextValue("genre" , "Computer");
doc.createElementWithTextValue("price" , "44.95");

//Pass the created XML document as a string to the XMLUtilJS API function.
var escapedXML = XMLUtilJS.valueToString(doc.toString());

// Print the results
// Returns NULL if XML is invalid
gs.print(escapedXML);

Output:

&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;catalog&gt;&lt;book id="bk101"/&gt;&lt;author&gt;Gambardella, Matthew&lt;/author&gt;&lt;title&gt;XML Developer&lt;/title&gt;&lt;genre&gt;Computer&lt;/genre&gt;&lt;price&gt;44.95&lt;/price&gt;&lt;/catalog&gt;