Relation APIs
Relation APIs let Sahi relate one element to another.
There are 2 kinds of relation APIs: DOM Relation APIs and Positional Relation APIs
DOM Relation APIs
Section titled “DOM Relation APIs”Sample table:
- Since
- Sahi Pro 3.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_near($element)Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element 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
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element 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” |
_startLookInside
Section titled “_startLookInside”- Since
- Sahi Pro 5.0
- Desktop Engine 8.0.0
Modes BrowserWindows
_startLookInside($element)Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element 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();_stopLookInside
Section titled “_stopLookInside”- Since
- Sahi Pro 5.0
- Desktop Engine 8.0.0
Modes BrowserWindows
_stopLookInside()Arguments
| Name | Type | Description |
|---|---|---|
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.Positional Relation APIs
Section titled “Positional Relation APIs”_rightOf
Section titled “_rightOf”- Since
- Sahi Pro 4.3
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_rightOf($element[, $offset])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _rightOf relation with |
$offset | pr_i_AB|integeroptional | offset 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]))_leftOf
Section titled “_leftOf”- Since
- Sahi Pro 4.3
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_leftOf($element[, $offset])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _leftOf relation with |
$offset | pr_i_AB|integeroptional | offset 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]))_leftOrRightOf
Section titled “_leftOrRightOf”- Since
- Sahi Pro 4.3
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroid
_leftOrRightOf($element[, $offset])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _leftOrRightOf relation with |
$offset | pr_i_AB|integeroptional | offset 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]))_under
Section titled “_under”- Since
- Sahi Pro 3.5
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_under($element[, $offset[, $limitUnder]])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _under relation with |
$offset | pr_i_LR|integeroptional | offset 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. |
$limitUnder | integeroptional | For 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))_above
Section titled “_above”- Since
- Sahi Pro 4.3
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_above($element[, $offset[, $limitTop]])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _above relation with |
$offset | pr_i_LR|integeroptional | offset 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. |
$limitTop | integeroptional | For 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))_aboveOrUnder
Section titled “_aboveOrUnder”- Since
- Sahi Pro 4.3
- Desktop Engine 7.5.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroid
_aboveOrUnder($element[, $offset])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element to establish the _aboveOrUnder relation with |
$offset | pr_i_LR|integeroptional | offset 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]))Parent APIs
Section titled “Parent APIs”_parentNode
Section titled “_parentNode”- Since
- Sahi Pro 3.5
- Desktop Engine 8.0.0
- Mobile Engine 7.5.0
Modes BrowserWindowsJavaAndroidiOS
_parentNode($element, $tagName[, $occurrence])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element whose parent we wish to access |
$tagName | string | Tag name of parent. eg. "TD" or "DIV" |
$occurrence | integeroptional | The nth parent. 1 is the immediate parent. |
Returns
HTML DOM element | Parent 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_parentCell
Section titled “_parentCell”- Since
- Sahi Pro 3.5
Modes Browser
_parentCell($element[, $occurrence])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element whose parent cell we wish to access |
$occurrence | integeroptional | The nth parent. 1 is the immediate parent. |
Returns
HTML DOM element | Parent cell element of the specified element |
Eg. in
<td id="id"><a href="">aElement</a></td>_parentCell(_link("aElement")) // points to parent cell_parentRow
Section titled “_parentRow”- Since
- Sahi Pro 3.5
Modes Browser
_parentRow($element[, $occurrence])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element whose parent row we wish to access |
$occurrence | integeroptional | The nth parent. 1 is the immediate parent row. |
Returns
HTML DOM element | Parent 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_parentTable
Section titled “_parentTable”- Since
- Sahi Pro 3.5
Modes Browser
_parentTable($element[, $occurrence])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM element | element whose parent table we wish to access |
$occurrence | integeroptional | The nth parent. 1 is the immediate parent table. |
Returns
HTML DOM element | Parent 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
