DOMIT! v 0.52 Tutorial
<<    index    >>
1    2    3    4    5    6    7    8    9    10    11    12    13    14    15    16    17   
18    19    20    21    22    23    24    25    26    27    28    29    30    31   
getElementsByPath

The getElementsByPath allows you to retrieve a single DOMIT_Element or a DOMIT_NodeList of DOMIT_Elements that match a "path"-like pattern that you provide.

NOTE: in versions of DOMIT! prior to 0.5, this method returned an array, not a DOMIT_NodeList!

The syntax is similar to an XPath query, although the range of patterns allowed by getElementsByPath is far less sophisticated than the XPath specification permits.

getElementsByPath can be called by any DOMIT_Node. There are three basic ways that you can form a pattern:

  • An absolute path search can be performed by prefixing your pattern with the / character. This type of search will start at the level of the documentElement node.

  • A relative path search can be performed by omitting the / prefix from your pattern. This type of search will start at the level of the node which called getElementsByPath.

  • An variable path search can be performed by prefixing your pattern with // characters. This type of search will find all matching elements, regardless of their position in the node hierarchy.

Given our cd collection xml string, therefore:

<cdlibrary>
	<cd id="0001">
		<name>Robbie Fulks</name>
		<title>Couples in Trouble</title>
	</cd>
	<cd id="0002">
		<name>Richard Thompson</name>
		<title>Mock Tudor</title>
	</cd>
	<cd id="0003">
		<name>Keller Williams</name>
		<title>Laugh</title>
	</cd>
</cdlibrary>

1. Calling:

$myElements =& $cdCollection->getElementsByPath("/cdlibrary/cd");

will return a DOMIT_NodeList containing the three cd elements.

2. Calling:

$myElements =& $cdCollection->getElementsByPath("//title");

will return a DOMIT_NodeList containing the three title elements.

3. Calling:

$firstCDNode =& $cdCollection->documentElement->firstChild;
$myElements =& $firstCDNode->getElementsByPath("name");

will return a DOMIT_NodeList containing the first name element.



If you would like a single node to be returned, rather than the entire node list of matching elements, you can specify the index of the requested node using the second parameter of getElementsByPath. Therefore, calling:

$firstCDElement =& $cdCollection->getElementsByPath("/cdlibrary/cd", 1);

will return the first cd element.

Note that as per the XPath convention, the index that you specify is 1-based.


Documentation generated by ClassyDoc, using the DOMIT! and SAXY parsers.
Please visit Engage Interactive to download free copies.