XMLUtilJS - Global

  • Release version: Washingtondc
  • Updated February 1, 2024
  • 3 minutes to read

    • Provides XML utilities for JavaScript to be used with Discovery scripts.

    The XMLUtilJS API 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.

    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.

    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.

    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.

    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;