HTML::Object::DOM::Node - HTML Object DOM Node Class
use HTML::Object::DOM::Node; my $node = HTML::Object::DOM::Node->new || die( HTML::Object::DOM::Node->error, "\n" );
v0.2.0
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
+-----------------------+ +---------------------------+ +-------------------------+ | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | +-----------------------+ +---------------------------+ +-------------------------+
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' );
Read-only
This returns an URI object representing the base URL of the document containing the Node, if any.
The base URL is determined as follows:
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.
This returns an element representing the first direct child element of the element, or undef if the element has no child.
undef
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
This returns an element representing the last direct child element of the element, or undef if the element has no child.
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.
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
This returns an integer representing the type of the element. Possible values are:
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.
This returns the Document that this element belongs to. If the element is itself a document, returns undef.
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.
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.
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.
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.
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.
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.
child
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
HTML::Object::HierarchyRequestError
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.
Provided with some nodes, and this will add them to the list of nodes for the current node.
Returns the current node object.
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
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
Returns true or false value indicating whether or not an element is a descendant of the calling element.
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.
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.
Provided with an XPath expression and this will perform a search using the current node as the context.
Provided with an XPath expression and this will perform a search using the current node as the context and return the result 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 a list of strings.
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.
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.
Returns a list of attribute objects for this node in list context or an array object in scalar context.
Returns a list of the current child nodes in list context or an array object in scalar context.
Returns an empty list in list context and an empty array reference in scalar context.
Returns the first child node of this node, if any, or undef if there are none.
Returns the last child node of this node, if any, or undef if there are none.
Returns an undef and this method is superseded in HTML::Object::DOM::Element
This non-standard method is an alias for the property "nextSibling"
Returns the current node's parent node, if any.
This non-standard method is an alias for the property "previousSibling"
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.
Returns a boolean value indicating whether or not the element has any child elements.
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.
node
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.
new
reference
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.
insertBefore
This means that a node cannot be in two locations of the document simultaneously.
Returns the added child (unless new is a DocumentFragment, in which case the empty DocumentFragment is returned).
<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 );
Returns false by default.
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.
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.
Returns a boolean value indicating whether or not the two elements are the same (that is, they reference the same object).
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
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
http://www.w3.org/XML/1998/namespace
xml
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.
Returns a new HTML::Object::DOM::Closing object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
Returns a new HTML::Object::DOM::Comment object, passing it whatever arguments were provided and return the newly instantiated object.
Returns a new HTML::Object::DOM::Element object, passing it whatever arguments were provided and return the newly instantiated object.
Returns a new HTML::Object::DOM object, passing it whatever arguments were provided and return the newly instantiated object.
Returns a new HTML::Object::DOM::Text object, passing it whatever arguments were provided and return the newly instantiated object.
Returns the array object containing the current node's sub nodes.
Clean up all the text elements under this element (merge adjacent, remove empty).
Provided with a child node and this removes the child node from the current element, which must be a child of the current element and returns the removed node.
A HTML::Object::NotFoundError error is returned if the child is not a child of the node.
HTML::Object::NotFoundError
<div id="top"> <div id="nested"></div> </div>
To remove a specified element when knowing its parent node:
my $d = $doc->getElementById('top'); my $d_nested = $doc->getElementById('nested'); my $throwawayNode = $d->removeChild( $d_nested );
To remove a specified element without having to specify its parent node:
my $node = $doc->getElementById('nested'); if( $node->parentNode ) { $node->parentNode->removeChild( $node ); }
Removes an event listener from the node. This is inherited from HTML::Object::EventTarget
See "removeEventListener" in HTML::Object::EventTarget for more information.
Provided with a new node and and an old node and this will replace the old one by the new one. Note that if the new node is already present somewhere else in the DOM, it is first removed from that position.
old
DOM
This returns the old node removed.
For nodes that are elements, it might be easier to read and use "replaceWith" in HTML::Object::DOM::Element
It returns undef and sets an HTML::Object::HierarchyRequestError if:
the parent of old node is not a Document, DocumentFragment, or an Element.
the replacement of old node by new node would lead to a cycle, that is if new node is an ancestor of the node.
new is not a DocumentFragment, a DocumentType, an Element, or a CharacterData.
the parent of the node is a Document and new node is a DocumentFragment with more than one Element child, or that has a Text child.
the replacement of old node by new node would lead to Document with more than one Element as child.
the replacement of old node by new node would lead to the presence of an Element node before a DocumentType node.
It returns an HTML::Object::NotFoundError if the parent of old is not the current node.
<div> <span id="childSpan">foo bar</span> </div> // Build a reference to the existing node to be replaced let sp1 = document.getElementById('childSpan'); let parentDiv = sp2.parentNode; // Create an empty element node without an ID, any attributes, or any content let sp2 = document.createElement('span'); // Give it an id attribute called 'newSpan' sp2.id = "newSpan"; // Create some content for the new element. sp2.appendChild( document.createTextNode('new replacement span element.') ); // Replace existing node sp1 with the new span element sp2 parentDiv.replaceChild(sp2, sp1);
Result:
<div> <span id="newSpan">new replacement span element.</span> </div>
Provided with an even type and this will instantiate a new HTML::Object::Event object, passing it the type argument, and any other arguments provided. it returns the value returned by "dispatchEvent" in HTML::Object::EventTarget
type
If no event type is provided, it returns a HTML::Object::SyntaxError error.
HTML::Object::SyntaxError
If the event type contains illegal characters, it returns a HTML::Object::TypeError error. Accepted characters are alpha-numeric, underscore, and dash ("-").
HTML::Object::TypeError
Returns a HTML::Object::XPath object.
And also the following constants:
ELEMENT_NODE (1)
ATTRIBUTE_NODE (2)
TEXT_NODE (3)
CDATA_SECTION_NODE (4)
ENTITY_REFERENCE_NODE (5)
ENTITY_NODE (6)
PROCESSING_INSTRUCTION_NODE (7)
COMMENT_NODE (8)
DOCUMENT_NODE (9)
DOCUMENT_TYPE_NODE (10)
DOCUMENT_FRAGMENT_NODE (11)
NOTATION_NODE (12)
SPACE_NODE (13)
Jacques Deguest <jack@deguest.jp>
See Mozilla documentation
Copyright(c) 2021 DEGUEST Pte. Ltd.
All rights reserved
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install HTML::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Object
CPAN shell
perl -MCPAN -e shell install HTML::Object
For more information on module installation, please visit the detailed CPAN module installation guide.