XMLData methods

applyXPath

7.0

Enables you to manipulate and query an XML document by using XPath expressions. The XPath language is described in the W3C document XML Path Language (XPath), which is available at http://www.w3.org/TR/xpath.

XPath expressions evaluate to one of the known four types: Boolean, Number, String, Node-set. In JavaScript, they are returned, respectively, as the following types: Boolean, Number, String, and Object.

If an object is returned, it is of type XFA object, which represents either a tree started by a single node or a tree started by a list of nodes (a tree list). The type of this object is the same as the one returned by the XMLData.parse.

Note:XFA provides a query mechanism, SOM expressions, which is similar to that of XPath. Because XPath is widely used in the XML community, the applyXPath method allows users to use XPath expressions if they choose.

Parameters

oXml

An XFAObject object representing an XML document tree.

Note:An exception is thrown if the value of this parameter is a nodeList XFA object instead of the root of an XML tree.

cXPath

A string parameter with the XPATH query to be performed on the document tree.

Returns

Boolean, Number, String, or XFAObject.

Example

This example shows each of the return types of XMLData.applyXPath (Boolean, number, string, or XFAObject). It extracts information from an XML data string, in this case, the family tree of the “Robat” family).

var cXMLDoc = "<family name = 'Robat'>\

<grandad id = 'm1' name = 'A.C.' gender='M'>\

<child> m2 </child>\

<personal>\

<income>100000</income>\

</personal>\

</grandad>\

<dad id = 'm2' name = 'Bob' gender='M'>\

<parent> m1 </parent>\

<spouse> m3 </spouse>\

<child> m4 </child>\

<child> m5 </child>\

<child> m6 </child>\

<personal>\

<income>75000</income>\

</personal>\

</dad>\

<mom id = 'm3' name = 'Mary' gender='F'>\

<spouse> m2 </spouse>\

<personal>\

<income>25000</income>\

</personal>\

</mom>\

<daughter id = 'm4' name = 'Sue' gender='F'>\

<parent> m2 </parent>\

<personal>\

<income>40000</income>\

</personal>\

</daughter>\

<son id = 'm5' name = 'Jim' gender='M'>\

<parent> m2 </parent>\

<personal>\

<income>35000</income>\

</personal>\

</son>\

<daughter id = 'm6' name = 'Megan' gender='F'>\

<parent> m2 </parent>\

<personal>\

<income>30000</income>\

</personal>\

</daughter>\

</family>";

var myXML= XMLData.parse( cXMLDoc, false);

The following line returns an XFAObject.

Get mom’s data.

var a = XMLData.applyXPath(myXML, "//family/mom")

a.saveXML('pretty');

<?xml version="1.0" encoding="UTF-8"?>

</personal>

</mom>

// get the income element value

a.personal.income.value = "20000"; // change the income

Get dad’s name, an attribute.

var b = XMLData.applyXPath(myXML, "//family/dad/@name");

b.saveXML('pretty');

<?xml version="1.0" encoding="UTF-8"?>

name="Bob"

// assign to a variable

var dadsName = b.value; // dadsName = "Bob"

Get all attributes of dad node.

var b = XMLData.applyXPath( myXML, "//family/dad/attribute::*" );

for(var i=0; i < b.length; i++)

console.println(b.item(i).saveXML('pretty'))

The loop above outputs the following to the console.

<?xml version="1.0" encoding="UTF-8"?>

id="m2"

<?xml version="1.0" encoding="UTF-8"?>

name="Bob"

<?xml version="1.0" encoding="UTF-8"?>

gender="M"

Extract particular information from this

console.println("For attribute 2, we have " + b.item(2).name + " = '"

+ b.item(2).value + "'.");

which yields an output of

For attribute 2, we have gender = 'M'.

Get dad’s second child.

var c = XMLData.applyXPath(myXML, "//family/dad/child[position()=2]");

c.saveXML('pretty')

<?xml version="1.0" encoding="UTF-8"?>

This is the id of dad’s second child. The examples below get the family data on this child.

The following returns a string.

// Calculate the value of dadsName using XPath methods.

var dadsName = XMLData.applyXPath(myXML, "string(//family/dad/@name)")

// dadsName is assigned a value of "Bob" with this one line.

Get the family information on dad’s second child. The following line assigns c = "m5". The return value of the call to applyXPath is a string, and the function normalize-space converts its argument to a string and removes any surrounding spaces.

var c = XMLData.applyXPath(myXML,

"normalize-space(//family/dad/child[2])");

var d = "//*[@id = \'" + c + "\']"; // Note: d= "//*[@id = 'm5']"

XMLData.applyXPath(myXML, d ).saveXML('pretty'); // show what we have

</personal>

</son>

Now display information about the sixth child node of the family root. The XPath functions name and concat are used.

var e = XMLData.applyXPath(myXML,

"concat(name(//family/child::*[position()=6]), '=',

//family/child::*[position()=6]/@name)" );

console.println(e); // the output is "daughter=Megan"

Get the names of all members of the “Robat” family.

e = XMLData.applyXPath(myXML,"//family/child::*" );

for ( var i = 1; i <= e.length; i++ ) {

var str = "string(//family/child::*["+i+"]/@name)";

console.println(XMLData.applyXPath(myXML,str));

}

The output is

A.C.

Bob

Mary

Sue

Jim

Megan

The following code shows a Boolean return value.

var f = XMLData.applyXPath( myXML, "//family/dad/@id = 'm2'" );

if ( f == true ) console.println("dad's id is 'm2'");

else console.println("dad's id is not 'm2'");

The following code shows a numeric return value.

// Get dad’s income

g = XMLData.applyXPath( myXML, "number(//family/dad/personal/income)" );

// Double dad's salary, implied conversion to a number type

console.println("Dad's double salary is " +

XMLData.applyXPath( myXML, "//family/dad/personal/income * 2" ) );

Now compute the total income of the family “Robat”.

console.println("Total income of A.C. Robat's family is "

+ XMLData.applyXPath( myXML, "sum(//income)" ) + ".");

The above line writes the following to the console.

Total income of A.C. Robat's family is 305000.

List the individual incomes.

var g = XMLData.applyXPath( myXML, "//income")

for ( var i =0; i< g.length; i++) console.println(g.item(i).value);

parse

7.0

Creates an object representing an XML document tree. Its parameters are the same as those of the loadXML method in the XFA Data DOM.

This method returns an object of type XFA object that represents either a tree headed by a single node or a tree started by a list of nodes (a tree list).

Parameters

param1	A string containing the XML document.
param2	(optional) A Boolean value specifying whether the root node of the XML document should be ignored. The default value is true. If false, the root node should not be ignored.

Returns

XFAObject

Example 1

Consider the XML document as first introduced in the example following the XMLData.applyXPath method.

var x = XMLData.parse( cXMLDoc, false );

var y = x.family.name; // An XFAObject

console.println(y.value); // Output to console is "Robat"

Get information about dad.

y = x.family.dad.id; // An XFAObject

console.println(y.value); // Output to console is "m2"

y = x.family.dad.name.value; // y = "Bob"

x.family.dad.name.value = "Robert"; // Change name to "Robert"

y = x.family.dad.name.value; // y = "Robert"

y = x.family.dad.personal.income.value; // y = "75000"

x.family.dad.personal.income.value = "80000";// Give dad a raise

Example 2

Create a simple XML document and manipulate it.

x = XMLData.parse("<a> <c>A.</c><d>C.</d> </a>", false);

x.saveXML("pretty");

The output of the previous line is

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

</a>

</xfa:data>

Now create another simple document.

y = XMLData.parse("Robat", false);

y.saveXML("pretty");

The output of this line

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

Robat

</xfa:data>

Append y on to x.

x.nodes.append(y.clone(true).nodes.item(0));

x.saveXML("pretty");

The result:

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

</a>

Robat

</xfa:data>

Now execute

x.nodes.insert(y.clone(true).nodes.item(0), x.nodes.item(0));

x.saveXML("pretty")

to obtain

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

Robat

<a>

</a>

Robat

</xfa:data>

Now remove these two nodes.

x.nodes.remove( x.nodes.namedItem("b") );

Now, we are back to the original XML document.

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

</a>

</xfa:data>

Executing the following line

x.a.nodes.insert( y.clone(true).nodes.item(0), x.a.nodes.item(0));

x.saveXML("pretty");

yields the following output:

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

Robat

</a>

</xfa:data>

Now remove that node just inserted.

x.a.nodes.remove( x.a.nodes.namedItem("b"));

Now insert y (actually a clone of y) between the first and second children of the element a.

x.a.nodes.insert( y.clone(true).nodes.item(0), x.a.nodes.item(1));

This produces the following

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

Robat

</a>

</xfa:data>

Remove that node just inserted:

x.a.nodes.remove( x.a.nodes.namedItem("b"));

Finally, append y onto a.

x.a.nodes.append( y.clone(true).nodes.item(0));

yielding

<?xml version="1.0" encoding="UTF-8"?>

<xfa:data xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">

<a>

Robat

</a>

</xfa:data>