Skip to content
Get Free Trial

Relation Functions

Relation functions let Sahi relate one element to another.

There are 2 kinds of relation functions: DOM Relation functions and Positional Relation functions

Sample table:

Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_near($element)

Arguments

NameTypeDescription
$elementHTML DOM elementelement to which the other element is near

Returns

null

_near is a DOM relation marker which specifies that the element should be searched near another element.

Example:

<table style="width:300px">
<tr>
<td>Name</td>
<td>Action</td>
<td>ID</td>
</tr>
<tr>
<td>User One</td>
<td id="del1"><a href="/deleteUser?id=1" onclick="return false">delete</a></td>
<td>ID 1</td>
</tr>
<tr>
<td>User Two</td>
<td id="del2"><a href="/deleteUser?id=2" onclick="return false">delete</a></td>
<td>ID 2</td>
</tr>
</table>
Name Action ID
User One delete ID 1
User Two delete ID 2
Accessor Description
_link(0, _near(_cell("User Two"))) points to the 0th link near cell with text “User Two”.
Note that the index is 0 here since it is the nearest link.
_link("delete", _near(_cell("User Two"))) points to the nearest link with text “delete” near cell with text “User Two”.
Note that we do not need to specify “delete[1]” since it is the delete link nearest to User Two.
Since
Sahi Pro 3.5
Desktop Engine 7.0.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_in($element)

Arguments

NameTypeDescription
$elementHTML DOM elementelement in which the other element is located

Returns

null

_in is a DOM relation marker which specifies that the element should be searched within another element.

In the same example table as above:

Accessor Description
_link(0, _in(_cell(“del2”))) points to the 0th link in cell with id “del2”
_link(“delete”, _in(_cell(“del2”))) points to the link with text “delete” within cell with id “del2”
Since
Sahi Pro 5.0
Desktop Engine 8.0.0

Modes BrowserWindows

_startLookInside($element)

Arguments

NameTypeDescription
$elementHTML DOM elementelement in which the other element is located

Returns

null

_startLookInside is a DOM relation marker setter which specifies that the element should be searched within another element.

Example:

_startLookInside(_cell("del2"));
_link(0); //points to the 0th link in cell with id "del2"
_link("delete"); //points to the link with text "delete" within cell with id "del2"
_stopLookInside();
Since
Sahi Pro 5.0
Desktop Engine 8.0.0

Modes BrowserWindows

_stopLookInside()

Arguments

NameTypeDescription
None

Returns

null

_stopLookInside is a DOM relation marker re-setter which re-sets the _startLookInside relation marker.

Example:

_startLookInside(_cell("del2"));
_link(0);
_link("delete");
_stopLookInside(); //reset the _startLookInside relation marker.
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_rightOf($element[, $offset])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _rightOf relation with
$offsetpr_i_AB|integeroptionaloffset specifies the above and below extension to element boundary within which to look for the other element.
If offset is a single integer, both above and below offsets are set to this integer.

By default, Sahi matches only elements whose top and bottom match. If element1 is to the right of element2 but slightly above or below element2, use the offset.

Returns

null

_rightOf specifies that the other element should be searched to the right of this element.

Example

_link(0, _rightOf(_cell("User Two")))
_link("delete", _rightOf(_cell("User Two")))
_link("delete", _rightOf(_cell("User Two"), 25))
_link("delete", _rightOf(_cell("User Two"), [25,25]))
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_leftOf($element[, $offset])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _leftOf relation with
$offsetpr_i_AB|integeroptionaloffset specifies the above and below extension to element boundary within which to look for the other element.
If offset is a single integer, both above and below offsets are set to this integer.

By default, Sahi matches only elements whose top and bottom match. If element1 is to the left of element2 but slightly above or below element2, use the offset.

Returns

null

_leftOf specifies that the other element should be searched to the left of this element.

Example

_link(0, _leftOf(_cell("ID 2")))
_link("delete", _leftOf(_cell("ID 2")))
_link("delete", _leftOf(_cell("ID 2"), 25))
_link("delete", _leftOf(_cell("ID 2"), [25,25]))
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroid

_leftOrRightOf($element[, $offset])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _leftOrRightOf relation with
$offsetpr_i_AB|integeroptionaloffset specifies the above and below extension to element boundary within which to look for the other element.
If offset is a single integer, both above and below offsets are set to this integer.

By default, Sahi matches only elements whose top and bottom match. If element1 is to the left or right of element2 but slightly above or below element2, use the offset.

Returns

null

_leftOrRightOf specifies that the other element should be searched to the left or right of this element.

Example

_link(0, _leftOrRightOf(_cell("ID 2")))
_link("delete", _leftOrRightOf(_cell("ID 2")))
_link("delete", _leftOrRightOf(_cell("ID 2"), 25))
_link("delete", _leftOrRightOf(_cell("ID 2"), [25,25]))
Since
Sahi Pro 3.5
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_under($element[, $offset[, $limitUnder]])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _under relation with
$offsetpr_i_LR|integeroptionaloffset specifies the left and right extension to element boundary within which to look for the other element.
If offset is a single integer, both left and right offsets are set to this integer.

By default, Sahi matches only elements whose left and right match. If element1 is under element2 but slightly to the left or right of element2, use the offset.
$limitUnderintegeroptionalFor a large page, you may want to limit how far you look under. This value limits the search to limitUnder pixels below this element.

Returns

null

_under specifies that the other element should be searched under this element.

Example

_link(0, _under(_cell("Action")))
_link("delete", _under(_cell("Action")))
_link("delete", _under(_cell("Action")), _rightOf(_cell("User Two")))
_link("delete", _under(_cell("Action"), 10))
_link("delete", _under(_cell("Action"), [10, 50]))
_link("delete", _under(_cell("Action"), 10, 100))
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_above($element[, $offset[, $limitTop]])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _above relation with
$offsetpr_i_LR|integeroptionaloffset specifies the left and right extension to element boundary within which to look for the other element.
If offset is a single integer, both left and right offsets are set to this integer.

By default, Sahi matches only elements whose left and right match. If element1 is above element2 but slightly to the left or right of element2, use the offset.
$limitTopintegeroptionalFor a large page, you may want to limit how far you look above. This value limits the search to limitTop pixels above this element.

Returns

null

_above specifies that the other element should be searched above this element.

Example

_cell(0, _above(_cell("User Two"))) // gives User One
_link("delete", _above(_cell("Action")))
_link("delete", _above(_cell("Action")), _rightOf(_cell("User Two")))
_link("delete", _above(_cell("Action"), 10))
_link("delete", _above(_cell("Action"), [10, 50]))
_link("delete", _above(_cell("Action"), 10, 100))
Since
Sahi Pro 4.3
Desktop Engine 7.5.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroid

_aboveOrUnder($element[, $offset])

Arguments

NameTypeDescription
$elementHTML DOM elementelement to establish the _aboveOrUnder relation with
$offsetpr_i_LR|integeroptionaloffset specifies the left and right extension to element boundary within which to look for the other element.
If offset is a single integer, both left and right offsets are set to this integer.

By default, Sahi matches only elements whose left and right match. If element1 is under or above element2 but slightly to the left or right of element2, use the offset.

Returns

null

_aboveOrUnder specifies that the other element should be searched above or below this element.

Example

_cell(0, _aboveOrUnder(_cell("User Two"))) // gives User One
_link(0, _aboveOrUnder(_cell("ID 2")))
_link("delete", _aboveOrUnder(_cell("ID 2")))
_link("delete", _aboveOrUnder(_cell("ID 2"), 25))
_link("delete", _aboveOrUnder(_cell("ID 2"), [25,25]))
Since
Sahi Pro 3.5
Desktop Engine 8.0.0
Mobile Engine 7.5.0

Modes BrowserWindowsJavaAndroidiOS

_parentNode($element, $tagName[, $occurrence])

Arguments

NameTypeDescription
$elementHTML DOM elementelement whose parent we wish to access
$tagNamestringTag name of parent. eg. "TD" or "DIV"
$occurrenceintegeroptionalThe nth parent. 1 is the immediate parent.

Returns

HTML DOM elementParent element of the specified element

Eg. in

<div id="div2">
<span><div id="div1">
<a href="">aLink</a>
</div></span>
</div>
_parentNode(_link("aLink"), "DIV", 1) // points to div1
_parentNode(_link("aLink"), "DIV", 2) // points to div2
Since
Sahi Pro 3.5

Modes Browser

_parentCell($element[, $occurrence])

Arguments

NameTypeDescription
$elementHTML DOM elementelement whose parent cell we wish to access
$occurrenceintegeroptionalThe nth parent. 1 is the immediate parent.

Returns

HTML DOM elementParent cell element of the specified element

Eg. in

<td id="id"><a href="">aElement</a></td>
_parentCell(_link("aElement")) // points to parent cell
Since
Sahi Pro 3.5

Modes Browser

_parentRow($element[, $occurrence])

Arguments

NameTypeDescription
$elementHTML DOM elementelement whose parent row we wish to access
$occurrenceintegeroptionalThe nth parent. 1 is the immediate parent row.

Returns

HTML DOM elementParent row element of the specified element

Eg. in

<tr>
<td id="id"><a href="">aElement</a></td>
</tr>
_parentRow(_link("aElement")) // points to parent row
Since
Sahi Pro 3.5

Modes Browser

_parentTable($element[, $occurrence])

Arguments

NameTypeDescription
$elementHTML DOM elementelement whose parent table we wish to access
$occurrenceintegeroptionalThe nth parent. 1 is the immediate parent table.

Returns

HTML DOM elementParent table element of the specified element

Eg. in

<table>
<tr>
<td id="id"><a href="">aElement</a></td>
</tr>
</table>
_parentTable(_link("aElement")) // points to parent table