JavaScript method: XML.setContent()

This method creates an XML object from a string or the contents of an external file. It always creates a valid XML document with a document element. The method removes any values outside the document element.

Syntax

XML.setContent( String ); setContent( "FilePath", IsFile );

Arguments

The following arguments are valid for this method:

Argument	Data type	Description
String	String	This argument specifies the text string you want the script to parse as on XML object. The string argument must contain a valid XML document with a document element.
FilePath	String	This argument specifies the path to the XML document you want the script to parse an XML object. You must enclose the FilePath argument in quotation marks and use the true argument to indicate that the first argument is a file path and not a string value.
IsFile	Boolean	This argument specifies whether the first argument is a string or a file path. A true value indicates the first argument is a file path. Any other value, including omitting the second argument, indicates that the first argument is a string.

Return values

An XML object or null.

The method returns an XML object if it parses the XML input and returns null if it cannot parse the input.

Arguments

Use the toXMLString method to convert an XML object to an XML string.

Example

This example attempts to create an XML object from five different sources.

This example requires the following sample data:

• A valid XML string (for example, <document><parent1><child1 attribute1=\"1\" /></parent1><parent2 /></document>)
• An XML string with more than one document element (for example, <document1><parent1 /></document1><document2><parent2 /></document2>)
• A local XML file (for example, C:\test.xml which contains <document><parent1><child1 attribute1="a" /><child2 /></parent1><parent2><child3 /><child4 /></parent2></document>)
• An existing XML object (for example, the list of currently logged on users stored in system.users)
• An XML object converted to a string (for example, the list of currently logged on users stored in system.users)

/* Create a function to execute the setContent method.
*  The function creates a new XML object xmlObj.
*  It sets the content of the XML object to the source argument.
*  The isFile argument determines if the source is an XML string or file path.
*  If setContent returns true, it prints an XML string and returns the XML object.
*  If setContent returns false, it prints the source and returns null. */
function setXML( source, isFile )
{
 var xmlObj = new XML();

 if ( xmlObj.setContent( source, isFile ) )
 {
  var xmlDoc = xmlObj.toXMLString();
  print( "setContent succeeded! \n The XML document is: \n" + xmlDoc );
  return xmlObj
 }
 else
 {
  print( "setContent failed. \n Could not parse the following input as XML: \n" + source );
  return null
 }
}

/* Create variables to store your XML source objects.
*  Use xmlObject to test setting content to an XML object.
*  xmlObjectConverted converts xmlObject to an XML string.
*  Note: The toXMLstring method removes the object header information.
*  Use xmlString to test setting content to an XML string.
*  Note: You must use the backslash character to escape out quotation marks in your XML string.
*  Use xmlFile to test setting content to an XML file. */
var xmlString = "<document><parent1><child1 attribute1=\"1\" /></parent1><parent2 /></document>";
var xmlBad = "<document1><parent1 /></document1><document2><parent2 /></document2>"
var xmlFile = "C:\\test.xml";
var xmlObject = system.users
var xmlObjectConverted = xmlObject.toXMLString();

/* Note: You can omit the isFile argument when the content source is an XML string.
*  See the xmlString example below. */
print( "Testing setting content to a valid XML string...\n" );
setXML( xmlString );
print( "Testing setting content to an XML string with more than one document element...\n" );
print( "The non-compliant XML string before conversion is: \n" +  xmlBad );
setXML( xmlBad );
print( "Testing setting content to an XML file...\n" );
setXML( xmlFile, true );
print( "Testing setting content to an existing XML object...\n" );
setXML( xmlObject, false );
print( "Testing setting content to an existing XML object converted to an XML string...\n" );
setXML( xmlObjectConverted, false );