Sahi Pro Documentation - Relation APIs

Sahi Pro - 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

_near($element)

Arguments

$element

HTML DOM element

element to which the other element is near

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

_in($element)

Arguments

$element

HTML DOM element

element in which the other element is located

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

_startLookInside($element)

Arguments

$element

HTML DOM element

element in which the other element is located

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

_stopLookInside()

Arguments

None

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

_rightOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _rightOf relation with
$offset	integer array\|integer optional	offset above and below within which to look for elements boundry within which to look for the other element. If offset is an integer, both above and below offsets are set to this offset element1 may be to the right but slightly above or below element2. Sahi normally matches only elements whose bases match. To force it to look a little above or below while looking to the right, use the offset.

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

_leftOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _leftOf relation with
$offset	integer array\|integer optional	offset above and below within which to look for elements boundry If offset is an integer, both above and below offsets are set to this offset. element1 may be to the left but slightly above or below element2. Sahi normally matches only elements whose bases match. To force it to look a little above or below while looking to the left, use the offset.

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

_leftOrRightOf($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _leftOrRightOf relation with
$offset	integer array\|integer optional	offset above and below within which to look for elements boundry If offset is an integer, both above and below offsets are set to this offset. element1 may be to the left but slightly above or below element2. Sahi normally matches only elements whose bases match. To force it to look a little above or below while looking to the left or right, use the offset.

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

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

Arguments

$element	HTML DOM element	element to establish the _under relation with
$offset	integer array\|integer optional	offset specifies the left and right extension to element boundary within which to look for the other element. If offset is an integer, both left and right offsets are set to this 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.

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")))

_above

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

Arguments

$element	HTML DOM element	element to establish the _above relation with
$offset	integer array\|integer optional	offset specifies the left and right extension to element boundary within which to look for the other element. If offset is an integer, both left and right offsets are set to this 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.

Details

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

Example

_cell(0, _above(_cell("User Two"))) // gives User One

_aboveOrUnder

_aboveOrUnder($element[, $offset])

Arguments

$element	HTML DOM element	element to establish the _aboveOrUnder relation with
$offset	integer array\|integer optional	offset specifies the left and right extension to element boundary within which to look for the other element. If offset is an integer, both left and right offsets are set to this offset

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

Parent APIs

_parentNode

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

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

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

Details

Eg. in

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

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

_parentRow

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

Details

Eg. in

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

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

_parentTable

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

Details

Eg. in

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

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