Finds elements by the specified Location Rules interpreted against
the specified context element and returns the first of the found elements.
If no elements found, the function returns null
.
This function does the same as the following calls:
However, it will work faster.findElementsByLRules ( ... // the same parameters ).next().toElement()
See also "What are Location Rules?" section below for more information.
Parameters:
element
The initial context element against which the Location Rules are interpreted.If this parameter is not specified, the generator context element is used by default, which is the same as the call:
contextElement.findElementByLRules(...)
See Also:
GOMContext.contextElement
locationRules
Specifies the array of Location Rules to be interpreted.Each Location Rule is represented by an object created using
LocationRule()
function. See description of that function for more detail.Note: You can use the Location Rule Builder (found at the left panel's tree) to quickly construct Location Rules needed for this parameter.
elementTypeSpec
Specify the list of target Element Types (see "Specifying Matching Element Types" below).The returned element will comply with at least one of the specified target Element Types.
filterQuery
Specify an additional condition on the returned element.This should be a boolean subquery created with
BooleanQuery()
function. The subquery will be processed against each initially selected element. It must returntrue
if the element may be returned as the function result andfalse
otherwise. The tested element is passed as the generator context element.
See Also:
LocationRule(), BooleanQuery(), findElementsByLRules(), findElementByLPath()
${include ../../../refs/lrules.htm}
${include ../../../refs/matching_ets_spec.htm}