NAME

HTML::Object::DOM::Node - HTML Object DOM Node Class

SYNOPSIS

use HTML::Object::DOM::Node;
my $node = HTML::Object::DOM::Node->new || 
    die( HTML::Object::DOM::Node->error, "\n" );

VERSION

v0.2.3

DESCRIPTION

This module implement the properties and methods for HTML DOM nodes. It inherits from HTML::Object::EventTarget and is used by HTML::Object::DOM::Element

INHERITANCE

+-----------------------+     +---------------------------+     +-------------------------+
| HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node |
+-----------------------+     +---------------------------+     +-------------------------+

PROPERTIES

All the following properties can be used as lvalue method as well as regular method. For example with "baseURI"

# Get the base uri, if any
my $uri = $e->baseURI;
$e->baseURI = 'https://example.org/some/where';
# or
$e->baseURI( 'https://example.org/some/where' );

baseURI

Normally this is read-only, but in this api, you can set an URI.

This returns an URI object representing the base URL of the document containing the Node, if any.

The base URL is determined as follows:

1. By default, the base URL is the location of the document (as set by "parse_url" in HTML::Object).
2. If it is an HTML Document and there is a <base|https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base> element in the document, the hrefvalue of the first Base element with such an attribute is used instead.
3. By specifying an uri with "documentURI" in HTML::Object::DOM::Document or "URL" in HTML::Object::DOM::Document

childNodes

Read-only

This returns an array object containing all the children of this node (including elements, text and comments). This list being live means that if the children of the Node change, the list object is automatically updated.

firstChild

Read-only

This returns an element representing the first direct child element of the element, or undef if the element has no child.

isConnected

Returns a boolean indicating whether or not the element is connected (directly or indirectly) to the context object, i.e. the Document object in the case of the normal DOM.

See for more information

lastChild

Read-only

This returns an element representing the last direct child element of the element, or undef if the element has no child.

See for more information

nextSibling

Read-only

This returns an element representing the next element in the tree, or undef if there is not such element.

The next node could also be a whitespace or a text. If you want to get the next element and not just any node, use nextElementSibling instead.

See for more information

nodeName

Read-only

This returns a string containing the name of the element. The structure of the name will differ with the element type. E.g. An HTML Element will contain the name of the corresponding tag, like 'audio' for an HTML audio element, a Text element will have the '#text' string, or a Document element will have the '#document' string.

For HTML element, contrary to the standard specifications, is not the uppercase value of the tag name, but the lowercase value. However, if you really wanted the uppercase value, you could get it quite easily like so:

$e->nodeName->uc;

This is because "tag" in HTML::Object::Element returns a scalar object

Example:

This is some html:
<div id="d1">Hello world</div>
<!-- Example of comment -->
Text <span>Text</span>
Text<br/>
<svg height="20" width="20">
  <circle cx="10" cy="10" r="5" stroke="black" stroke-width="1" fill="red" />
<hr>
<output id="result">Not calculated yet.</output>

then, with the script:

let node = document.getElementsByTagName("body")[0].firstChild;
let result = "Node names are:<br/>";
while (node) {
  result += node.nodeName + "<br/>";
  node = node.nextSibling
}

const output = document.getElementById("result");
output.innerHTML = result;

would produce:

Node names are:
#text
div
#text
#comment
#text
span
#text
br
#text
svg
hr
#text
output
#text
script

See for more information

nodeType

Read-only

This returns an integer representing the type of the element. Possible values are:

1. element node
2. attribute node
3. text node
4. CDATA section node
5. unused (formerly entity reference node)
6. unused (formerly entity node)
7. processing instruction node
8. comment node
9. document node
10. document type node
11. document fragment node
12. notation node
13. space node

See for more information

nodeValue

This returns or sets the value of the current node.

For document, element or collection, this returns undef and for attribute, text or comment, this sets or returns the objct value.

See for more information

ownerDocument

Read-only

This returns the Document that this element belongs to. If the element is itself a document, returns undef.

See for more information

parentNode

Read-only

This returns an element that is the parent of this element. If there is no such element, like if this element is the top of the tree or if does not participate in a tree, this property returns undef.

See for more information

parentElement

Read-only

This returns an element that is the parent of this element. If the element has no parent, or if that parent is not an Element, this property returns undef.

See for more information

previousSibling

Read-only

This returns a element representing the previous element in the tree, or undef if there is not such element.

The previous node could also be a whitespace or a text. If you want to get the previous element and not just any node, use previousElementSibling instead.

See for more information

textContent

Returns / Sets the textual content of an element and all its descendants.

If this is called on a text node or a comment node, it will, instead, set the object value to the textual content provided.

When setting some values, this method will ensure that HTML characters are escaped, namely: <, > and new lines are preceded by the <br /> tag.

When the value is retrieved, this is reversed.

See for more information

METHODS

addEventListener

Registers an event handler to a specific event type on the node. This is inherited from HTML::Object::EventTarget

See "addEventListener" in HTML::Object::EventTarget for more information.

appendChild

Adds the specified child element argument as the last child to the current element. If the argument referenced an existing element on the DOM tree, the element will be detached from its current position and attached at the new position.

If the given child is a DocumentFragment, the entire contents of the DocumentFragment are moved into the child list of the specified parent node.

It returns the element added, except when the child is a DocumentFragment, in which case the empty DocumentFragment is returned.

It returns undef and sets an HTML::Object::HierarchyRequestError error

the parent of child is not a Document, DocumentFragment, or an Element.
the insertion of child would lead to a cycle, that is If child is an ancestor of the node.
child is not a DocumentFragment, a DocumentType, an Element, or a CharacterData.
the current node is a Text, and its parent is a Document.
the current node is a DocumentType and its parent is not a Document, as a doctype should always be a direct descendant of a document.
the parent of the node is a Document and child is a DocumentFragment with more than one Element child, or that has a Text child.
the insertion of child would lead to Document with more than one Element as child.
the insertion of child would lead to the presence of an Element node before a DocumentType node.

See for more information

appendNodes

Provided with some nodes, and this will add them to the list of nodes for the current node.

Returns the current node object.

cloneNode

Clone an element, and optionally, all of its contents. By default, it clones the content of the element.

To clone a node to insert into a different document, use "importNode" in HTML::Object::DOM::Document instead.

Returns the element cloned. The cloned node has no parent and is not part of the document, until it is added to another node that is part of the document, using "appendChild" or a similar method.

compareDocumentPosition

Compares the position of the current element against another element in any other document and returns a bitwise value comprised of one or more of the following constants (that are automatically exported):

DOCUMENT_POSITION_IDENTICAL (0 or in bits: 000000)

Elements are identical.
DOCUMENT_POSITION_DISCONNECTED (1 or in bits: 000001)

No relationship, both nodes are in different documents or different trees in the same document.
DOCUMENT_POSITION_PRECEDING (2 or in bits: 000010)

The specified node precedes the current node.
DOCUMENT_POSITION_FOLLOWING (4 or in bits: 000100)

The specified node follows the current node.
DOCUMENT_POSITION_CONTAINS (8 or in bits: 001000)

The otherNode is an ancestor of / contains the current node.
DOCUMENT_POSITION_CONTAINED_BY (16 or in bits: 010000)

The otherNode is a descendant of / contained by the node.
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32 or in bits: 100000)

The specified node and the current node have no common container node or the two nodes are different attributes of the same node.

use HTML::Object::DOM::Node;
my $head = $doc->head;
my $body = $doc->body;

if( $head->compareDocumentPosition( $body ) & DOCUMENT_POSITION_FOLLOWING )
{
    say( 'Well-formed document' );
} 
else
{
    say( '<head> is not before <body>' );
}

For example:

<div id="writeroot">
    <form>
        <input id="test" />
    </form>
</div>

my $x = $doc->getElementById('writeroot');
my $y = $doc->getElementById('test');
say( $x->compareDocumentPosition( $y ) ); # 20, i.e. 16 | 4
say( $y->compareDocumentPosition( $x ) ); # 10, i.e. 8 | 2

Be careful that, since this method does quite a bit of searching among various hierarchies, this method is a bit expensive, especially on large documents.

See for more information and also this blog post from John Resig or this one from Peter-Paul Koch

Also the W3C specifications and here

contains

Returns true or false value indicating whether or not an element is a descendant of the calling element.

See for more information

dispatchEvent

Dispatches an event to this node in the DOM and returns a boolean value that indicates whether no handler canceled the event. This is inherited from HTML::Object::EventTarget

See "dispatchEvent" in HTML::Object::EventTarget for more information.

find

This is an alias for "findNode"

find_xpath

Provided with an XPath expression and this will perform a search using the current node as the context.

findNode

Provided with an node object or a selector and this will search throughout the current node hierarchy using the XPath expression provided.

It returns an array object of the nodes found.

findnodes

Provided with an XPath expression and this will perform a search using the current node as the context.

findnodes_as_string

Provided with an XPath expression and this will perform a search using the current node as the context and return the result as string.

findnodes_as_strings

Provided with an XPath expression and this will perform a search using the current node as the context and return the result as a list of strings.

findvalue

Provided with an XPath expression and this will perform a search using the current node as the context and return the result as the node value.

findvalues

Provided with an XPath expression and this will perform a search using the current node as the context and return the result as a list of node values.

getAttributes

Returns a list of attribute objects for this node in list context or an array object in scalar context.

getChildNodes

Returns a list of the current child nodes in list context or an array object in scalar context.

getElementById

Returns an empty list in list context and an empty array reference in scalar context.

getFirstChild

Returns the first child node of this node, if any, or undef if there are none.

getLastChild

Returns the last child node of this node, if any, or undef if there are none.

getName

Returns an undef and this method is superseded in HTML::Object::DOM::Element

getNextSibling

This non-standard method is an alias for the property "nextSibling"

getParentNode

Returns the current node's parent node, if any.

getPreviousSibling

This non-standard method is an alias for the property "previousSibling"

getRootNode

Returns the context object's root.

Under JavaScript, this optionally includes the shadow root if it is available. However a shadow root has no meaning under this perl interface.

See for more information

hasChildNodes

Returns a boolean value indicating whether or not the element has any child elements.

See for more information

insertAfter

This is a non-standard method since it does not exist in the web API, surprisingly enough.

This is exactly the same as "insertBefore" below except it inserts the node after.

See for more information

insertBefore

Provided with a new node and an optional reference node and this inserts an element before the reference element as a child of a specified parent element. If the reference node is undef, then new node is inserted at the end of current node's child nodes.

If the given node already exists in the document, insertBefore moves it from its current position to the new position. This means it will automatically be removed from its existing parent before appending it to the specified new parent.

This means that a node cannot be in two locations of the document simultaneously.

If the given child is a DocumentFragment, the entire contents of the DocumentFragment are moved into the child list of the specified parent node.

Returns the added child (unless new is a DocumentFragment, in which case the empty DocumentFragment is returned).

Example:

<div id="parentElement">
    <span id="childElement">foo bar</span>
</div>

# Create a new, plain <span> element
my $sp1 = $doc->createElement( 'span' );

# Get the reference element
my $sp2 = $doc->getElementById( 'childElement' );
# Get the parent element
my $parentDiv = $sp2->parentNode

# Insert the new element into before sp2
$parentDiv->insertBefore( $sp1, $sp2 );

See for more information

isAttributeNode

Returns false by default.

isCommentNode

Returns false by default.

isDefaultNamespace

Accepts a namespace URI as an argument and returns a boolean value with a value of true if the namespace is the default namespace on the given element or false if not.

See for more information

isElementNode

Returns false by default.

isEqualNode

Returns a boolean value which indicates whether or not two elements are of the same type and all their defining data points match.

Two elements are equal when they have the same type, defining characteristics (this would be their ID, number of children, and so forth), its attributes match, and so on. The specific set of data points that must match varies depending on the types of the elements.

See for more information

isNamespaceNode

Returns false by default.

isPINode

Returns false by default.

isProcessingInstructionNode

Returns false by default.

isSameNode

Returns a boolean value indicating whether or not the two elements are the same (that is, they reference the same object).

Example:

my $div1 = $doc->createElement('div');
$div1->appendChild( $doc->createTextNode('This is an element.') );
my $div2 = $div1->cloneNode;
say $div1->isSameNode( $div2 ); # false
say $div1->isSameNode( $div1 ); # true

We can also use with the equality operator:

say $div1 == $div2; # false
say $div1 eq $div2; # same; false
say $div1 == $div1; # true

See for more information

isTextNode

Returns false by default.

lookupNamespaceURI

Accepts a prefix and returns the namespace URI associated with it on the given element if found (and undef if not). Supplying undef for the prefix will return the default namespace.

This always return an empty string and http://www.w3.org/XML/1998/namespace if the prefix is xml

See for more information

lookupPrefix

This always returns undef, because this is for XML, which is not supported.

Returns a string containing the prefix for a given namespace URI, if present, and undef if not.

See for more information

new_closing

Returns a new HTML::Object::DOM::Closing object, passing it whatever arguments were provided and return the newly instantiated object.