domObj.getObjectsByName

(As of 3.1.002.06)

Find all objects in the current DOM which match a specified name (or names). Find objects that match a Name.

Syntax

domObj.getObjectsByName(name[, name ...] [callback])

Parameters

name is either a simple Object Name, or an array of object names to search for.

callback is an optional JavaScript function that will be called for each successful match.

Object names must match exactly in case. If the last character in a name parameter is * it is treated as a wildcard. So a search for Address* will match objects called 'Address', 'Address1', 'Address2', 'AddressCity' etc.

Note that a simple parameter of '*' will return a list of all objects below the current object.

var p=getObjectsByName('*'); //returns all subobjects

Returned Value 

If a callback function is specified, this function returns TRUE. Otherwise, it returns a JavaScript array of pointers to DocOrigin DOM objects. That array is empty if no matches are found.

Background 

This routine searches only the current object (typically the object containing this script) as well as all objects within (under) this object. When using the callback function, you can cause the search of the DOM to terminate prematurely by having the callback function return TRUE. Otherwise, the callback is called for every match in the DOM. This can be useful (for example) if you're only interested in the first match, or already know that there is in fact only one object that will match. This might improve the program's speed.

Example

var p=getObjectsByName('UnitPrice', 'Amount');

for(i=0; i<p.length; i++) {
	_logf("%d. name='%s' value='%s'", i, p[i]._name, p[i]._value);
}

The above script will generate a listing of all objects called UnitPrice or Amount. If this script is put on a top-level object (Form, Page, Container for instance) then all instances are found. If it occurs on a lower-level Pane it will only find the instances within that Pane.

function myfun(p) {
	_logf("%d. name='%s' value='%s'", i, p._name, p._value);
	if (p._value == 0) return true;		// quit when a value of zero is encountered
}

getObjectsByName('UnitPrice', 'Amount', myfun);

This second example does the same thing as the first, but via a callback routine. It also terminates the search if an object with a value of zero is encountered.

See Also

domObj.getObjectsByType
domObj.getObjectsByTag
domObj.getObjectsByTagValue