Class DOMIT_Node
A class representing a DOM Document.

This is the base class of all DOMIT_Document, DOMIT_TextNode, and DOMIT_CDATASection nodes. It cannot be instantiated directly.

isPublic? no
isAbstract? yes

Inheritance tree:

DOMIT_Node (top level class)

Known subclasses:

DOMIT_Document, DOMIT_Element, DOMIT_TextNode, DOMIT_CDATASection

Source file: xml_domit_parser.php

Includes: xml_domit_utilities.php,xml_domit_getelementsbypath.php,xml_domit_nodemaps.php




Constructor
Dies if an attempt to instantiate this class is made.

Signature: DOMIT_Node()

isPublic? no




Public Constants
ELEMENT_NODE
The nodeType for a DOMIT_Element node.

Type: int

Value: 1

TEXT_NODE
The nodeType for a DOMIT_TextNode node.

Type: int

Value: 3

CDATA_SECTION_NODE
The nodeType for a DOMIT_CDATASection node.

Type: int

Value: 4

DOCUMENT_NODE
The nodeType for a DOMIT_Document node.

Type: int

Value: 9




Private Constants



Public Fields
nodeName
The name of the current node.

For DOMIT_Document, nodeName is #document.
For DOMIT_Element, nodeName is the name of the tag.
For DOMIT_TextNode, nodeName is #text.
For DOMIT_CDATASection, nodeName is #cdata-section.

Type: String

nodeValue
The value of the current node.

For DOMIT_TextNode and DOMIT_CDATASection, this represents the text contained in the node. Otherwise, the value is null.

Type: String

nodeType
An integer representing the type of the current node.

For DOMIT_Document, nodeType is 9.
For DOMIT_Element, nodeType is 1.
For DOMIT_TextNode, nodeType is 3.
For DOMIT_CDATASection, nodeType is 4.

Type: int

parentNode
A reference to the node of which the current node is a child. For a DOMIT_Document node, this value is null.

Type: DOMIT_Node

childNodes
An array of node references of which the current node is parent. Null if the current node has no children.

Type: array

firstChild
A reference to the first node in the childNodes list. Null if the current node has no children.

Type: DOMIT_Node

lastChild
A reference to the last node in the childNodes list. Null if the current node has no children.

Type: DOMIT_Node

previousSibling
A reference to the node prior to the current node in the childNodes list. Null if the current node is the first child.

Type: DOMIT_Node

nextSibling
A reference to the node after the current node in the childNodes list. Null if the current node is the last child.

Type: DOMIT_Node

attributes
A list of key / value pairs. Only valid for a DOMIT_Element node. Null if no attributes exist.

Type: array

ownerDocument
A reference to the DOMIT_Document. Null if the node has not yet been added to the document.

Type: DOMIT_Document




Private Fields
uid
A unique id assigned to each node. Note that this id is non-persistent.

Type: int




Public Methods
insertBefore
Inserts node $newChild before $refChild in the childNodes of $this. If $refChild does not exist, $newChild is appended to the node chain.

Signature: &insertBefore(&$newChild, &$refChild)

Parameters:

DOMIT_Node newChild - The new node to be added

DOMIT_Node refChild - The existing node before which the new node will be added

Returns:

DOMIT_Node - A reference to the new node being added.

Example:

The following example inserts a "Book" node named $goodNovel before another named $okNovel in a childNodes list named $bestSellers.

$bestSellers->insertBefore($goodNovel, $okNovel);

replaceChild
Replaces node $oldChild with $newChild.

Signature: replaceChild(&$newChild, &$oldChild)

Parameters:

DOMIT_Node newChild - The new node that is to replace the old node.

DOMIT_Node oldChild - The old node that is to be replaced by the new node.

Returns:

DOMIT_Node - The new node $newChild, or false if $oldChild does not exist.

Example:

An old $userProfile node is replaced by a new node:

$userProfile->replaceChild($newProfile, $oldProfile);

removeChild
Removes the specified node from the document.

Signature: &removeChild(&$oldChild)

Parameters:

DOMIT_Node oldChild - The node that is to be removed.

Returns:

DOMIT_Node - The deleted node $oldChild, or false if $oldChild does not exist.

Example:

Node $unpopularNovel is removed from the $bestSellers parent node.

$bestSellers->removeNode($unpopularNovel);

appendChild
Appends the specified node to the childNodes list.

Signature: appendChild(&$child)

Parameters:

DOMIT_Node child - The node that is to be appended. If the parent node is of type DOMIT_Document, only a single node can be appended.

Returns:

DOMIT_Node - The appended node, or false in the case of DOMIT_TextNode and DOMIT_CDATASection subclasses.

Example:

A new node, $brocolli, is appended to the $myGroceryList parent node.

$myGroceryList->appendChild($brocolli);

hasChildNodes
Determines whether a node has any children.

Signature: hasChildNodes()

Returns:

boolean - True if the node has children, false if not.

Example:

The following example checks the $cookieJar node to see if it has any children (cookies!).

$isCookieJarEmpty = $cookieJar->hasChildNodes();

cloneNode
Returns a copy of the specified node, and if $deep is set to true, all nodes below it in the hierarchy.

Signature: &cloneNode($deep)

Parameters:

boolean deep - True if the children below the cloned node are also to be cloned.

Returns:

DOMIT_Node - The cloned node, with a clone of all subnodes if $deep is set to true.

Example:

In the following example, a node named $styleTemplate is cloned, presumably so the user can create a new style based on the characteristics of the original node.

$newStyle =& styleTemplate->cloneNode(false);

selectNodes
Applies the specified XPath expression. NOT YET IMPLEMENTED, BUT WILL BE SOON!

Signature: &selectNodes($pattern)

Parameters:

String pattern - The XPath expression to be parsed.

Returns:

DOMIT_NodeList - An list of DOMIT_Nodes described by the XPath expression.

Example:

The first "param" element found with a parent named "params" is returned:

$myNodeList =& $someNode->selectNodes("//params/param[1

getElementsByPath
Retrieves an element or DOMIT_NodeList of elements corresponding to the specified "path"-like expression. Relative paths (which do not start with "/"), absolute paths (which start with "/") , and variable paths (which start with "//") are allowed. For more information, please see the DOMIT! Tutorial. For more complex patterns, please see the selectNodes method.

Signature: &getElementsByPath($pattern, $nodeIndex = 0)

Parameters:

String pattern - The path-like pattern specifying the elements(s) to be returned.

int nodeIndex - If more than one element matches the specified pattern, setting nodeIndex will return a single node from these possibilities. This is a one-based index.

Returns:

Domit_Node - A DOMIT_NodeList of DOMIT_Nodes, or a single DOMIT_Node, described by the expression.

Example:

The first "param" element found with a parent named "params" is returned:

$myNode =& $xmlDoc->getElementsByPath("//params/param", 1);

getText
Returns the text contained in all DOMIT_TextNodes and DOMIT_CDataSections that are children of the specified starting node

Signature: getText()

Example:

All text and cdata nodes in the document will be concatenated and returned.

$allDocmentText = $xmldoc->getText();

toNormalizedString
Returns a readable representation of the xml document. Note that the class DOMIT_Utilities is required for this function.

Signature: toNormalizedString()

Returns:

String - A readable representation of the xml document.

Example:

A normalized representation of the xml document is returned:

echo (htmlentities("<pre>" . $myDoc->toNormalizedString(). "</pre>"));




Private Methods
_constructor
Called by subclasses of DOMIT_Node to initialize fields in the superclass.

Signature: _constructor()

getChildNodeIndex
Searches for and returns the position of the specified child node in the childNodes list.

Signature: getChildNodeIndex(&$arr, &$child)

Parameters:

array arr - A reference to the childNodes list.

DOMIT_Node child - The node to search for in the childNodes list.

Returns:

int - The index of $child in the childNodes array, or -1 if it is not found.

Example:

In the following example, the index of node $myAlbum in parent node $albums is returned:

$index = $albums->getChildNodeIndex($albums->childNodes, $myAlbum);

getNamedElements
A recursive method called by getElementsByTagsName to traverse the document and construct a DOMIT_NodeList of elements of name $tagName that are present.

Signature: getNamedElements(&$nodeList, $tagName)

Parameters:

DOMIT_NodeList nodeList - The DOMIT_NodeList in which the DOMIT_Element references are placed.

String tagName - The tag name of the DOMIT_Elements to be searched for, or "*" if all child elements are to be returned.

Example:

All elements in the document tree named "title" are placed in the $nodeList variable.

require_once("xml_domit_nodemaps.php");
$nodeList =& new DOMIT_NodeList();
$this->documentElement->getNamedElements($nodeList, "title");

nvl
Tests whether a reference is null. The specified default value is returned if the reference is null. The reference is returned if it is not null.

Signature: &nvl(&$value,$default)

Parameters:

Object value - The reference to be tested for a null value.

Object default - The default value to be returned if the reference is null.

Returns:

Object - Either $value if it is not null, or $default it $value is null.

Example:

A custom menu node is returned if one exists; otherwise the default menu is returned:

$myMenu =& nvl($myCustomMenu, $defaultMenu);


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