HTML::O...OM::Node(3)

📦 version 0.6.0, in alpine 3.24

🦋 `HTML::O...OM::Node(3)` — User Contributed Perl Documentation, bestie edition 🦋

okay so welcome to HTML::O...OM::Node(3) from User Contributed Perl Documentation — this is the Node manual but make it group chat 💅

🎀 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.3.0

💖 DESCRIPTION 💖

This module implements 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:

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

🦋 childNodes 🦋

Read-only, bestie 🔒

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, no cap 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected

🧚 lastChild 🧚

Read-only, periodt 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/lastChild

💜 nextSibling 💜

Read-only, lowkey important 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/nextSibling

🌈 nodeName 🌈

Read-only, iconic 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName

💀 nodeType 💀

Read-only, literally the type check 🔒

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

element node
attribute node
text node
CDATA section node
unused (formerly entity reference node)
unused (formerly entity node)
processing instruction node
comment node
document node
document type node
document fragment node
notation node
space node

See for more information: https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType

🫶 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: https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue

🎀 ownerDocument 🎀

Read-only, main character document energy 🔒

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

See for more information: https://developer.mozilla.org/en-US/docs/Web/API/Node/ownerDocument

🌸 parentNode 🌸

Read-only, your fave parent link 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/parentNode

🧚 parentElement 🧚

Read-only, but only if the parent is literally an Element 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/parentElement

🌟 previousSibling 🌟

Read-only, going backwards bestie 🔒

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: https://developer.mozilla.org/en-US/docs/Web/API/Node/previousSibling

💖 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: https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent

See also innerText in HTML::Object::DOM::Element, as_text in HTML::Object::Element and text in HTML::Object::XQuery.

💅 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: https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild

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

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/Node/cloneNode

🔥 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. 💀

okay and here's like, an actual snippet so you can see it in the wild:

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

⚠️ bestie, heads up: this method does <em>quite a bit</em> of searching among various hierarchies, so it's a lil expensive — especially on large documents. like, don't call it in a hot loop unless you're ready to feel it. 😭

See for more information <https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition> and also this blog post from John Resig <https://johnresig.com/blog/comparing-document-position/> or this one from Peter-Paul Koch <https://www.quirksmode.org/blog/archives/2006/01/contains_for_mo.html>

Also the W3C specifications <http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/core.html#Node3-compareDocumentPosition> and here <http://www.w3.org/TR/DOM-Level-3-Core/core.html#DocumentPosition>

contains 💅

Returns true or false value indicating whether or not an element is a descendant of the calling element. literally that's it, that's the whole vibe check ✨

See for more information <https://developer.mozilla.org/en-US/docs/Web/API/Node/contains>

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" — same energy, shorter name 🎀

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. (context matters, bestie — get that right and you're golden 💖)

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. yes, on this node it's literally an empty result — the Node class isn't where the actual lookup lives 🙈

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 — so like, it's giving deprecated-lite 😭

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/getRootNode>

hasChildNodes

Returns a boolean value indicating whether or not the element has any child elements. a simple lil yes/no, we stan 🫶

See for more information <https://developer.mozilla.org/en-US/docs/Web/API/Node/hasChildNodes>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/insertAfter>

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. no dupe nodes allowed, it's giving exclusivity 💅

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/insertBefore>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/isDefaultNamespace>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/isEqualNode>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/isSameNode>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/lookupNamespaceURI>

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 <https://developer.mozilla.org/en-US/docs/Web/API/Node/lookupPrefix>

new_closing

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