XPath-Style Searching

While obtaining lists of child nodes enables access to the entire DOM, you can search for nodes that satisfy a set of criteria.

For example, this code can be used to log the names of all shapes within a document:

for (var i = 0; i < dom.Sections.length; i++) { 
	var section = dom.Sections[i];  

	if (section.Type == bqDashboard) { 			
	    env.log(“Dashboard “ + section.AnnotName + “ has shapes”);
	    
        var shapes = section.Shapes;  	

    	for (var j = 0; j < shapes.length; j++) 		
                   env.log(shapes[j].Name);   		
    } 
}

The DOM provides user-friendly collection names for both the Sections inside a document and the Shapes inside a dashboard. However, a complex search example that looks for all DataThreshold.DataThreshold nodes inside all ThreshFmt.ThreshFmt nodes, inside all ColColl.Item nodes, inside all table sections, results in multiple nested loops.

The Impact Management Services scripting provides an alternative approach, through XPath-style searches. For example, this is the code to use for the complex search example:

var items = dom.findNodesByPattern(“/BQY/Root.MyDocument/Rpt.DocComp”
		+ “/ColColl.Item/ThreshFmt.ThreshFmt”
		+ “/DataThreshold.Threshold”);

This single statement provides an array that contains the required nodes. Property matching requirements can be included to narrow down which nodes are to be returned.

For example, to limit the result to those nodes in the column named Drawn inside the table named Rankings.

var items = dom.findNodesByPattern(“/BQY/Root.MyDocument”
		+ “/Rpt.DocComp[AnnotName=’Rankings’]”
		+ “/ColColl.Item[Label=’Drawn’]/ThreshFmt.ThreshFmt”
		+ “/DataThreshold.Threshold”);

Searches need not begin at the root of the DOM. If a variable that contains a section node is searched, use a relative path to find other nodes beneath that section; for example:

var table = dom.findNodesByPattern(“/BQY/Root.MyDocument”
		+ “/Rpt.DocComp[AnnotName=’Rankings’]”);

var items = table.findNodesByPattern(“ColColl.Item[Label=’Drawn’]”
		+ “/ThreshFmt.ThreshFmt/DataThreshold.Threshold”);

Use getNodesByPattern() if there is a possibility that a node may not exist (that is, if documents to be processed using a script may not contain this node) or where there can be many of these nodes. In these cases, the length of the returned array is used to determine the situation.

However, if one node matching the pattern is guaranteed, use getNodeByPattern() which returns one object, rather than an array.

The search mechanism provides two wildcard facilities. An asterisk (*) in place of a node name, represents any type of node. A pair of slashes (//) represents any number of intervening nodes.

For example, to find all images in a document, in dashboards or reports (in the body, header, footer, section header, or section footer), use this example code:

var pattern = “//Box.Item[RuntimeClassName='PictField']”;
var pictures = dom.findNodesByPattern(pattern);