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

Sample table:

_near

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	7.0.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

_near($element)

Arguments

$element

HTML DOM element

element to which the other element is near

Returns

null

Details

_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

`_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.

_in

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	7.0.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

_in($element)

Arguments

$element

HTML DOM element

element in which the other element is located

Returns

null

Details

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

In the same example table as above:

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	5.0	NA	7.0.1	8.0.0	NA	NA	NA

Available for modes: Browser | Windows

_startLookInside($element)

Arguments

$element

HTML DOM element

element in which the other element is located

Returns

null

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	5.0	NA	7.0.1	8.0.0	NA	NA	NA

Available for modes: Browser | Windows

_stopLookInside()

Arguments

None

Returns

null

Details

_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

_rightOf

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	4.3	4.3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

_rightOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _rightOf relation with
$offset	pr_i_AB\|integer optional	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

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	4.3	4.3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

_leftOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _leftOf relation with
$offset	pr_i_AB\|integer optional	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

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	4.3	4.3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android

_leftOrRightOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _leftOrRightOf relation with
$offset	pr_i_AB\|integer optional	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

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

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

Arguments

$element	HTML DOM element	element to establish the _under relation with
$offset	pr_i_LR\|integer optional	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	integer optional	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

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	4.3	4.3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

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

Arguments

$element	HTML DOM element	element to establish the _above relation with
$offset	pr_i_LR\|integer optional	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	integer optional	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

Details

_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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	4.3	4.3	7.0.1	7.5.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android

_aboveOrUnder($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _aboveOrUnder relation with
$offset	pr_i_LR\|integer optional	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

Details

_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

_parentNode

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	8.0.0	7.5.0	NA	NA

Available for modes: Browser | Windows | Java | Android | iOS

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

Arguments

$element	HTML DOM element	element whose parent we wish to access
$tagName	string	Tag name of parent. eg. "TD" or "DIV"
$occurrence	integer optional	The nth parent. 1 is the immediate parent.

Returns

HTML DOM element

Parent element of the specified element

Details

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

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	NA	NA	NA	NA

Available for modes: Browser

_parentCell($element[, $occurrence])

Arguments

$element	HTML DOM element	element whose parent cell we wish to access
$occurrence	integer optional	The nth parent. 1 is the immediate parent.

Returns

HTML DOM element

Parent cell element of the specified element

Details

Eg. in

<td id="id"><a href="">aElement</a></td>

_parentCell(_link("aElement")) // points to parent cell

_parentRow

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	NA	NA	NA	NA

Available for modes: Browser

_parentRow($element[, $occurrence])

Arguments

$element	HTML DOM element	element whose parent row we wish to access
$occurrence	integer optional	The nth parent. 1 is the immediate parent row.

Returns

HTML DOM element

Parent row element of the specified element

Details

Eg. in

<tr>
  <td id="id"><a href="">aElement</a></td>
</tr>

_parentRow(_link("aElement")) // points to parent row

_parentTable

Since:	Sahi Pro	Sahi OS	Sahi Pro Starter	Desktop Add-On	Mobile Add-On	SAP Add-On	AI Assist Add-On
Since:	3.5	2	7.0.1	NA	NA	NA	NA

Available for modes: Browser

_parentTable($element[, $occurrence])

Arguments

$element	HTML DOM element	element whose parent table we wish to access
$occurrence	integer optional	The nth parent. 1 is the immediate parent table.

Returns

HTML DOM element

Parent table element of the specified element

Details

Eg. in

<table>
  <tr>
    <td id="id"><a href="">aElement</a></td>
  </tr>
</table>

_parentTable(_link("aElement")) // points to parent table