HTML::O...Document(3)

📦 version 0.6.0, in alpine 3.24

🦋 HTML::Object::DOM::Document(3) — User Contributed Perl Documentation 🦋

okay bestie, welcome to the manual page for HTML::Object::DOM::Document, the HTML Object DOM Document Class. this is part 1, and yes, we are keeping every detail. no cap. 💅

🌸 NAME 🌸

HTML::Object::DOM::Document — HTML Object DOM Document Class

🚀 SYNOPSIS 🚀

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

🔖 VERSION 🔖

v0.3.0

💖 DESCRIPTION 💖

This module represents an HTML document. It inherits from HTML::Object::Document and HTML::Object::DOM::Element.

It is the top object in the hierarchy, so it has no parent. It should contain only one child, the "html" element, and it has one associated element, the doctype, which can also be accessed with declaration.

🧬 INHERITANCE 🧬

here's the family tree, bestie — copy-pasted energy only for the diagram, because diagrams are sacred:

+------------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------+
| HTML::Object::Element  | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Document |
+------------------------+     +---------------------------+     +-------------------------+     +----------------------------+     +-----------------------------+
  |                                                                                                                                   ^
  |                                                                                                                                   |
  v                                                                                                                                   |
+------------------------+                                                                                                            |
| HTML::Object::Document | -----------------------------------------------------------------------------------------------------------+
+------------------------+

🎀 PROPERTIES 🎀

property time, bestie. all of these are in the original order, no skipping, no disappearing acts. ✨

activeElement

Normally this returns undef under perl, but you can set it to whatever element object you want.

Under JavaScript, this returns the element that currently has focus.

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

body

Returns the body node object of the current document.

Example:

# Given this HTML: <body id="oldBodyElement"></body>
say($doc->body->id); # "oldBodyElement"

my $aNewBodyElement = $doc->createElement("body");

$aNewBodyElement->id = "newBodyElement";
$doc->body = $aNewBodyElement;
say($doc->body->id); # "newBodyElement"

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

characterSet

This is read-only.

Returns the character set being used by the document. This is always utf-8.

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

childElementCount

This is read-only.

Returns the number of child elements of the current document. This being the top document, it typically contains only 1 element, the <html> tag.

The total number of children is not the same as the number of child nodes.

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

children

This is read-only.

Returns the child elements of the current document, as an array object.

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

compatMode

Returns undef since this is not relevant under perl.

Normally, it would indicate whether the document is rendered in quirks or strict mode.

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

contentType

This is read-only.

Returns the Content-Type from the MIME Header of the current document.

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

Set or get a semicolon-separated list of the cookies for that document or sets a single cookie.

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

currentScript

Under perl, this does not do anything special, nor return anything special, but you can set yourself an HTML::Object::DOM::Element.

Normally, under JavaScript, the currentScript property returns the <script> element whose script is currently being processed and is not a JavaScript module.

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

defaultView

This returns a reference to the window object.

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

designMode

This always returns true under perl.

Under the web, with JavaScript, this would get/set the ability to edit the whole document.

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

dir

Get or set directionality (rtl/ltr) of the document.

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

doctype

This is read-only.

Returns the Document Type Definition (DTD) object of the current document.

Example:

my $doctypeObj = $doc->doctype;

say(
    "doctype->name: " . $doctypeObj->name . "\n" +
    "doctype->internalSubset: " . $doctypeObj->internalSubset . "\n" +
    "doctype->publicId: " . $doctypeObj->publicId . "\n" +
    "doctype->systemId: " . $doctypeObj->systemId
);

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

documentElement

This is read-only.

Returns the element that is a direct child of the document. For HTML documents, this is normally the HTML Element object representing the document's <html> element.

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

documentURI

Set or get the document location as a string, if any.

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

embeds

This is read-only.

Returns a list, as an html collection object, of the embedded <embed> elements within the current document.

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

featurePolicy

Returns undef since this is not relevant under perl.

Normally, under JavaScript, this would return the FeaturePolicy interface which provides a simple API for introspecting the feature policies applied to a specific document.

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

firstElementChild

This is read-only.

Returns the first child element of the current document.

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

fonts

Returns undef since this is not relevant under perl.

Normally, it would return the FontFaceSet interface of the current document.

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

forms

This is read-only.

Returns a list, as an html collection object, of the <form> elements within the current document.

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

fullscreenElement

Returns undef since this is not relevant under perl.

Normally, it would return the element that is currently in full screen mode for this document.

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

This is read-only.

Returns the <head element|HTML::Object::DOM::Head> of the current document, or undef if there is none.

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

hidden

Returns undef since this is not relevant under perl.

Normally, it would return a boolean value indicating if the page is considered hidden or not.

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

images

This is read-only.

Returns a list, as an html collection object, of the images in the current document.

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

implementation

This returns the DOM implementation object associated with the current document.

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

lastElementChild

This is read-only.

Returns the last child element of the current document, which is the root <html> element, the only child of the document.

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

lastModified

This is read-only.

Returns the date on which the document was last modified, if any, as a DateTime object.

This value exists if the document was read from a file, and it would contain the file last modification time.

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

This is read-only.

Returns a list, as an html collection object, of all the hyperlinks in the document.

Example:

my $links = $doc->$links;
for( my $i = 0; $i < $links->length; $i++ )
{
    my $linkHref = $doc->createTextNode( $links->[$i]->href );
    my $lineBreak = $doc->createElement("br");
    $doc->body->appendChild( $linkHref );
    $doc->body->appendChild( $lineBreak );
}

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

location

Set or get the URI of the current document. This is the same as documentURI.

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

mozSyntheticDocument

Normally this returns undef under perl, but you can set whatever boolean value you want.

Under JavaScript, this returns a boolean that is true only if this document is synthetic, such as a standalone image, video, audio file, or the like.

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

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 returns the objct value.

More info from Mozilla: https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue

ownerDocument

Read-only, bestie — and it always hands you back undef, because this is the top element, there's literally nothing above it. It's inherited from HTML::Object::DOM::Node. Main character at the tippy top of the tree 💅

pictureInPictureElement

Under perl this normally returns undef, but like… you can set it to whatever element object you want, no judgment.

Under JavaScript it returns undef since it's not relevant under perl.

Normally, under JavaScript, this would return the Element currently being presented in picture-in-picture mode in this document.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/pictureInPictureElement ✨

pictureInPictureEnabled

Normally returns undef under perl, but you can set whatever boolean value you want, go off queen.

Under JavaScript, this would return true if the picture-in-picture feature is enabled, and false otherwise.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/pictureInPictureEnabled 🎀

plugins

Always returns an empty collection object, since this is not relevant under perl. Empty. Like my inbox on a Sunday. 🫶

Normally, under JavaScript, this would return a list, as a collection, of the available plugins.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/plugins

pointerLockElement

Normally returns undef under perl, but you can set whatever element object you want.

Under JavaScript, this would return the element set as the target for mouse events while the pointer is locked. It's null if lock is pending, pointer is unlocked, or if the target is in another document.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/pointerLockElement

readyState

This one's read-only, so hands off the wheel.

Returns loading status of the document, and it always returns a true value.

The readyState of a document can be one of the following:

  • loading — the document is still loading.
  • interactive — the document has finished loading and the document has been parsed.

There is actually no distinction with the following complete state.

  • complete — the document and all its resources have finished loading. The state indicates that the load event is about to fire.

This is actually the same state as interactive.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState ⭐

referrer

Set or get the URI of the page that linked to this page. It's giving "how did you get here" energy.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/referrer

scripts

This is read-only.

Returns all the <script> elements on the document — that's HTML::Object::DOM::Element::Script for the pod-link girlies — as a collection object.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/scripts 🦋

scrollingElement

Lowkey meaningless under perl, but you can set or get an element object that scrolls the document. Vibes only.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/scrollingElement

styleSheets

This is read-only.

Returns a list, as an array object, of CSS StyleSheet element objects for stylesheets explicitly linked into, or embedded in, a document.

Contrary to the original JavaScript equivalent, this does not return CSSStyleSheet objects, because it would be potentially heavy to parse each css in link and style tags. You could do this yourself by using CSS::Object and looping through each element object returned. For example:

$doc->styleSheets->foreach(sub
{
    my $e = shift( @_ );
    if( $e->tag eq 'link' )
    {
        my $resp = $ua->get( $e->attr( 'href' ) );
        die( $resp->message ) if( $resp->is_error );
        my $style = $resp->decoded_content;
        my $css = CSS::Object->new;
        $css->read_string( $style );
        $css->rules->foreach(sub
        {
            my $rule = shift( @_ );
            # more processing
        });
    }
    elsif( $e->tag eq 'style' )
    {
        my $css = CSS::Object->new;
        $css->read_string( $e->text );
        $css->rules->foreach(sub
        {
            my $rule = shift( @_ );
            # more processing
        });
    }
});

or you can use find in HTML::Object::XQuery with a xpath selector, such as:

use HTML::Object::XQuery; # Load jQuery style query functions
# $doc is the HTML::Object::Document returned by HTML::Object->parse
my $collection = $doc->findNode( 'link[rel="https://example.org/css/main.css"]' ) ||
    die( $doc->error );
$collection->children->foreach(sub
{
    # more processing
});

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/styleSheets 💖

timeline

Returns undef since this is not relevant under perl.

Normally, under JavaScript, this would return timeline as a special instance of DocumentTimeline that is automatically created on page load.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/timeline

title

Set or get the title of the current document. Short, sweet, iconic.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/title

URL

Set or get the document location as a string. Fr fr.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/URL

visibilityState

Normally returns undef under perl, but you can set whatever string value you want. This returns a scalar object.

Under JavaScript, this would return a string denoting the visibility state of the document. Possible values are visible, hidden, prerender, and unloaded.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState 🌸

✨ METHODS ✨

adoptNode

adoptNode transfers a node from another document into the method's document. The adopted node and its subtree is removed from its original document (if any), and its ownerDocument is changed to the current document. The node can then be inserted into the current document. It's giving "you're one of us now" 🫶

Before they can be inserted into the current document, nodes from external documents should either be:

  • cloned using importNode; or
  • adopted using adoptNode.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/adoptNode

append

Inserts a set of Node objects or string objects after the last child of the document.

This is inherited from HTML::Object::DOM::Element.

Example:

my $html = $doc->createElement( 'html' );
$doc->append( $html );
# HierarchyRequestError: The operation would yield an incorrect node tree.

Also

my $doc = HTML::Object::DOM::Document->new;
my $html = $doc->createElement( 'html');
$doc->append( $html );

$doc->children; # HTMLCollection [<html>]

appendChild

Provided with one or more nodes and this will add them to the list of this document's children. Simple as that, queen 👑

as_string

Returns a string representation of this document and all its hierarchy. The whole tree, rendered. Obsessed.

captureEvents

See captureEvents in HTML::Object::DOM::Window.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/captureEvents

caretRangeFromPoint

Always returns undef under perl. That's it, that's the whole method 💀

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/caretRangeFromPoint

caretPositionFromPoint

Returns undef since this is not relevant under perl.

Normally, under JavaScript, this would return a CaretPosition object containing the DOM node containing the caret, and caret's character offset within that node.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/caretPositionFromPoint

childNodes

Returns an array object of the document child nodes.

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

close

The close() method finishes writing to a document, opened with open.

Example:

# Open a document to write to it
$doc->open();

# Write the content of the document
$doc->write("<p>The one and only content.</p>");

# Close the document
$doc->close();

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/close 🎀

contentType

Ngl, the original page lists this one with literally no description attached. It's just here, existing, serving c*nt. 🙈

createAttribute

Provided with an argument and this creates a new attribute object and returns it.

The attribute name is converted to lowercase. That's just the rule, bestie.

Example:

my $node = $doc->getElementById( 'div1' );
my $a = $doc->createAttribute( 'my_attrib' );
$a->value = 'newVal';
$node->setAttributeNode( $a );
say( $node->getAttribute( 'my_attrib' ) ); # "newVal"

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createAttribute

createAttributeNS

Returns undef since this is not relevant under perl.

Normally, under JavaScript, this would create a new attribute node in a given namespace and returns it.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createAttributeNS

createCDATASection

Returns undef since this is not relevant under perl.

Normally, under JavaScript, this would create a new CDATA node and returns it.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createCDATASection

createComment

Creates a new comment node and returns it. Sneaky little thing, love that for you 🦋

Example:

my $comment = $doc->createComment( 'This is a not-so-secret comment in your document' );
$doc->getElementsByTagName( 'div' )->[0]->appendChild( $comment );
say( $doc->as_string );
# <div><!--This is a not-so-secret $comment in your document--></div>

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createComment

createDocumentFragment

This create a new HTML::Object::DOM::DocumentFragment object, passing its new() constructor whatever argument was provided.

It returns the newly instantiated object.

Document fragments are DOM Node objects which are never part of the main DOM tree. The usual use case is to create the document fragment, append elements to the document fragment and then append the document fragment to the DOM tree. In the DOM tree, the document fragment is replaced by all its children.

Since the document fragment is not part of the main DOM tree, appending children to it does not affect the main tree.

Example:

<ul id="ul"></ul>
use Module::Generic::Array;
my $element  = $doc->getElementById('ul'); # assuming ul exists
my $fragment = $doc->createDocumentFragment();
my $browsers = Module::Generic::Array->new( ['Firefox', 'Chrome', 'Opera',
    'Safari', 'Internet Explorer'] );

$browsers->foreach(sub
{
    my $browser = shift( @_ );
    my $li = $doc->createElement('li');
    $li->textContent = $browser;
    $fragment->appendChild( $li );
});

$element->appendChild( $fragment );

would yield:

  • Firefox
  • Chrome
  • Opera
  • Safari
  • Internet Explorer

See Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createDocumentFragment 🦋

🎀 createElement

Hand it a tag name and it hands you back a brand new HTML::Object::Element object. Slay.

If something goes sideways, this method sets an error and returns undef. So like, always check your return value, bestie. 💅

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement

🌸 createElementNS

Returns undef, because this whole namespace-URI thing is just not the vibe under perl. 🙈

Normally, under JavaScript, this would create a new element with the given tag name and namespace URI.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS

🧚 createEntityReference

Returns undef since this is not relevant for an HTML document. That one's for XML.

This was used to create a new entity reference object and returns it.

Example:

$doc->createEntityReference( '&amp' ); # &

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createEntityReference

✨ createEvent

Creates an event object, passing it whatever arguments were provided, and returns it. Honestly? Chef's kiss. 👑

Example:

my $event = $doc->createEvent( $type );

# Create the $event.
my $event = $doc->createEvent( 'click' );

# Define that the event name is 'build'.
$event->initEvent( build => { bubbles => 1 });

# Listen for the $event.
$elem->addEventListener( build => sub
{
    # e->target matches elem
}, { capture => 0 });

# Target can be any Element or other EventTarget.
$elem->dispatchEvent( $event );

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createEvent

🦋 createExpression

Compiles an HTML::Object::XPath::Expr which can then be used for (repeated) evaluations. It returns a HTML::Object::DOM::XPathResult object. Reusable, efficient, main character energy fr fr. 💜

Example:

my $xpathExpr = $doc->createExpression( $xpathText );
my $result = $xpathExpr->evaluate( $contextNode );

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createExpression

🌈 createNSResolver

This always returns undef as XML is not used in HTML::Object

Normally, under JavaScript, this creates an XPathNSResolver object.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createNSResolver

🎀 createNodeIterator

Creates a HTML::Object::DOM::NodeIterator object. Look at her go. 😭

Example:

use Module::Generic::Array;
my $nodeIterator = $doc->createNodeIterator(
    $doc->body,
    NodeFilter->SHOW_ELEMENT,
    {
        sub acceptNode
        {
            my $node = shift( @_ );
            return( $node->nodeName->toLowerCase() == 'p' ? NodeFilter->FILTER_ACCEPT : NodeFilter->FILTER_REJECT;
        }
    }
);
my $pars = Module::Generic::Array->new;
my $currentNode;

while( $currentNode = $nodeIterator->nextNode() )
{
    $pars->push( $currentNode );
}

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createNodeIterator

🍓 createProcessingInstruction

Creates a new ProcessingInstruction object. Yes bestie, we're doing XML-flavoured things now. 💀

Example:

my $doc = HTML::Object::DOM->new->parseFromString('<foo />', 'application/xml');
my $pi = $doc->createProcessingInstruction('xml-stylesheet', 'href="mycss->css" type="text/css"');

$doc->insertBefore($pi, $doc->firstChild);

say( $doc->as_string );
# Displays: <?xml-stylesheet href="mycss->css" type="text/css"?><foo/>

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createProcessingInstruction

🌟 createRange

This always returns undef under perl.

Normally, under JavaScript, this creates a Range object.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createRange

💖 createTextNode

Provided with a text, either as a string, or as a list of strings, and this creates a text node. Simple, clean, does exactly what it says on the tin. 🫶

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createTextNode

🔥 createTouch

This always returns undef under perl.

Normally, under JavaScript, this creates a Touch object.

Also, this feature is deprecated. So like, don't get attached. ⚠️

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createTouch

💫 createTouchList

This always returns undef under perl.

Normally, under JavaScript, this creates a TouchList object.

Also, this feature is deprecated. Same warning, different method, iykyk. 🙈

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createTouchList

🌸 createTreeWalker

Creates a TreeWalker object. We love a tree traversal moment. 🧚

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);

my $nodeList = Module::Generic::Array->new;
my $currentNode = $treeWalker->currentNode;

while( $currentNode )
{
    $nodeList->push( $currentNode );
    $currentNode = $treeWalker->nextNode();
}

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/createTreeWalker

💅 elementFromPoint

This always returns undef under perl.

Normally, under JavaScript, this returns the topmost element at the specified coordinates.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/elementFromPoint

🌈 elementsFromPoint

This always returns undef under perl.

Normally, under JavaScript, this returns an array of all elements at the specified coordinates.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/elementsFromPoint

🎀 enableStyleSheetsForSet

This always returns undef under perl.

Normally, under JavaScript, this enables the style sheets for the specified style sheet set.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/enableStyleSheetsForSet

⭐ evaluate

Evaluates an XPath expression. This is the one, bestie. 🫶

Example:

my $xpathResult = $doc->evaluate(
    $xpathExpression,
    $contextNode
);

my $headings = $doc->evaluate( "/html/body//h2", $document );
# Search the document for all h2 elements.
# The result will likely be an unordered node iterator.
my $thisHeading = $headings->iterateNext();
my $alertText = "Level 2 $headings in this document are:\n";
while( $thisHeading )
{
    $alertText .= $thisHeading->textContent . "\n";
    $thisHeading = $headings->iterateNext();
}
say( $alertText ); # print the text of all h2 elements

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate

💀 execCommand

This does absolutely nothing and always returns undef. Literally nothing. A void. An empty group chat. 😭

This is actually a deprecated feature of the web API. 👑

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/execCommand

🌟 exitPictureInPicture

This always returns undef under perl.

Normally, under JavaScript, this removes the video from the floating picture-in-picture window back to its original container.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/exitPictureInPicture

🦋 exitPointerLock

This always returns undef under perl.

Normally, under JavaScript, this releases the pointer lock.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/exitPointerLock

💜 firstChild

Returns the first child from the document list of nodes. First in line, obviously. ✨

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

🎀 firstElementChild

That's it. That's the whole entry. No description. She said "my presence is the description" and honestly? Iconic. 👑

🔥 getElementById

Provided with an element id, and this method returns the corresponding element object.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById

🌈 getAnimations

This always returns undef under perl.

Normally, under JavaScript, this returns an array of all Animation objects currently in effect, whose target elements are descendants of the document.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/getAnimations

🍓 getBoxQuads

This always returns undef under perl.

Normally, under JavaScript, this returns a list of DOMQuad objects representing the CSS fragments of the node.

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/getBoxQuads

💖 getElementById

Yes bestie, she's back. Same name, slightly different wording — provided with a string and this returns an element object whose id attribute matches the string specified. Not a typo, it's literally in there twice. 🙈

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/Document/getElementById

🌸 getElementsByClassName

Returns a list of elements with the given class name. Class-based searching, we stan. 💅

Example:

<span class="orange fruit">Orange Fruit</span>
<span class="orange juice">Orange Juice</span>
<span class="apple juice">Apple Juice</span>
<span class="foo bar">Something Random</span>
<textarea id="resultArea" style="width:98%;height:7em"></textarea>

Another example:

# getElementsByClassName only selects elements that have both given classes
my $allOrangeJuiceByClass = $doc->getElementsByClassName('orange juice');
my $result = "$doc->getElementsByClassName('orange juice')";
for( my $i=0; $i < $allOrangeJuiceByClass->length; $i++ )
{
    $result .= "\n    " . $allOrangeJuiceByClass->[$i]->textContent;
}
# querySelector only selects full complete matches
my $allOrangeJuiceQuery = $doc->querySelectorAll('.orange->juice');
$result += "\n\ndocument->querySelectorAll('.orange->juice')";
for( my $i=0; $i < $allOrangeJuiceQuery->length; $i++ )
{
    $result .= "\n    " . $allOrangeJuiceQuery->[$i]->textContent;
}

$doc->getElementById( 'resultArea' )->value = $result;

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

getElementsByName 🌸

Returns a NodeList Collection of elements with a given name attribute in the document.

Example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Example: using getElementsByName</title>
    </head>
    <body>
        <input type="hidden" name="up" />
        <input type="hidden" name="down" />
    </body>
</html>

my $up_names = $doc->getElementsByName( 'up' );
say( $up_names->[0]->tagName ); # displays "input"

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

getElementsByTagName 💅

Returns a list of elements with the given tag name.

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

getElementsByTagNameNS 🦋

This is merely an alias to getElementsByTagName since there is no support for namespace.

Normally, under JavaScript, this returns a list of elements with the given tag name and namespace.

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

getRootNode 👑

Returns the current object.

getSelection ✨

This always returns undef under perl.

Normally, under JavaScript, this returns a Selection object representing the range of text selected by the user, or the current position of the caret.

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

hasChildNodes 🎀

Returns true if the document list of nodes is not empty, false otherwise.

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

hasFocus 🔥

Under perl, this always returns true.

Normally, under JavaScript, this returns a boolean value indicating whether the document or any element inside the document has focus. This method can be used to determine whether the active element in a document has focus.

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

hasStorageAccess 💜

This always returns undef under perl.

Normally, under JavaScript, this returns a Promise that resolves with a boolean value indicating whether the document has access to its first-party storage.

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

importNode 🌈

Returns a clone of a node from an external document.

Example:

my $iframe  = $doc->querySelector( 'iframe' );
my $oldNode = $iframe->contentWindow->document->getElementById( 'myNode' );
my $newNode = $doc->importNode( $oldNode, $true );
$doc->getElementById( 'container' )->appendChild( $newNode );

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

insertAfter 🌟

Provided with a node and a reference node and this will insert the node after the reference node.

It returns the current object upon success, or undef upon error

Surprisingly enough there is no insertAfter method in the web API, only insertBefore

insertBefore 💫

Provided with a node and a reference node and this will insert the node before the reference node.

It returns the current object upon success, or undef upon error

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

lastChild 🍓

Returns the last child node from the document list of nodes.

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

mozSetImageElement 🧚

This always returns undef under perl.

Normally, under JavaScript, this allows you to change the element being used as the background image for a specified element ID.

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

nextSibling 🫶

Returns a smart undef. This means the return value will depend on what the caller expects. In scalar context it will return undef and an empty list in list context, but if this method is chained, it will return a dummy object to avoid the perl error "method called on an undefined value"

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

normalizeDocument 🌸

Replaces entities, normalizes text nodes, etc.

This is actually an alias to normalize in HTML::Object::DOM::Node

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

open 🔓

The open() method opens a document for writing and returns the current document object.

This does come with some side effects. For example:

  • All event listeners currently registered on the document, nodes inside the document, or the document's window are removed.
  • All existing nodes are removed from the document.

Example:

The following simple code opens the document and replaces its content with a number of different HTML fragments, before closing it again.

my $doc = $parser->parse_data( $html );
$doc->open();
$doc->write("<p>Hello world!</p>");
$doc->write("<p>I am a fish</p>");
$doc->write("<p>The number is 42</p>");
$doc->close();

An automatic open call happens when write is called after the document has loaded.

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

parentElement 💖

This interface returns the DOM node's parent Element, or undef if the node either has no parent, or its parent isn't a DOM Element.

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

parentNode 🌷

This returns the parent of the specified node in the DOM tree.

Document and DocumentFragment nodes can never have a parent, so parentNode will always return undef.

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

prepend 🎀

Inserts a set of Node objects or string objects before the first child of the document.

Example:

my $html = $doc->createElement( 'html' );
$doc->prepend( $html );
# HierarchyRequestError: The operation would yield an incorrect node tree.

Another example:

my $doc = HTML::Object::DOM::Document->new;
my $html = $doc->createElement( 'html' );
$doc->prepend( $html );

$doc->children; # HTMLCollection [<$html>]

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

previousSibling 🦋

This returns the node immediately preceding the specified one in its parent's childNodes list, or undef if the specified node is the first in that list.

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

queryCommandEnabled 💀

This always returns false under perl.

Normally, under JavaScript, this reports whether or not the specified editor command is enabled by the browser.

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

queryCommandIndeterm 🙈

This always returns true under perl.

Normally, under JavaScript, this returns true if the formatting command is in an indeterminate state on the current range.

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

queryCommandState 💅

This always returns false under perl.

Normally, under JavaScript, this returns true if the formatting command has been executed on the current range.

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

queryCommandSupported ⭐

This always returns false under perl.

Normally, under JavaScript, this returns true if the formatting command is supported on the current range.

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

queryCommandValue 💜

This always returns undef under perl.

Normally, under JavaScript, this returns the current value of the current range for a formatting command.

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

querySelector 🔍

Returns the first Element node within the document, in document order, that matches the specified selectors.

Example:

<div id="foo\bar"></div>
<div id="foo:bar"></div>

$doc->querySelector( '#foo\\bar' ); # Match the first div
$doc->querySelector( '#foo\:bar' ); # Match the second div

my $el = $doc->querySelector(".myclass");

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

querySelectorAll 🌈

Returns a list of all the Element nodes within the document that match the specified selectors.

Example:

<div class="outer">
    <div class="select">
        <div class="inner">
        </div>
    </div>
</div>

my $inner = $select->querySelectorAll( '.outer .inner' );
$inner->length; # 1, not 0

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

releaseCapture 🖱️

Releases the current mouse capture if it's on an element in this document.

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

releaseEvents 🎈

See releaseEvents in HTML::Object::DOM::Window.

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

removeChild 🧹

Provided with a node and this removes a child node from the DOM and returns the removed node.

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

replaceChild 🔁

Provided with a "new" node 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.

This returns the "old" node removed.

For the full tea on replaceChild, the HTML::Object::DOM::Node docs have you covered — that’s where the deets live. 👀 Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Node/replaceChild

🧸 replaceChildren

Replaces the existing children of a document with a specified new set of children. Literally swaps out the whole kid lineup. 💅

Example:

$doc->replaceChildren();
$doc->children; # HTMLCollection []

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/replaceChildren

🔐 requestStorageAccess

This always returns undef under perl. 😭

Normally, under JavaScript, this returns a Promise that resolves if the access to first-party storage was granted, and rejects if access was denied. No cap — under perl it’s just undef.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/requestStorageAccess

🫠 string_value

This always returns undef. That’s it. That’s the whole vibe.

✍️ write

Provided with a list of nodes, and this will write them to the body of this document. If the document is already closed, such as when it has already loaded, this will call open, which will cause the document to be emptied. 😳

⚠️ Warning: that open call can empty the document, so don’t come for me if your content vanishes.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/write

📝 writeln

Same as write, except this will add a new line. Periodt. ✨

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/writeln

✨ EVENTS ✨

There is only limited support for events under perl, but you can trigger yourself any event. Yes, really — you’re the main character. 💅

Event listeners for those events can also be found by prepending on before the event type:

So click event listeners can be set also with the onclick method:

$e->onclick(sub{ # do something });
# or as an lvalue method
$e->onclick = sub{ # do something };

Below are some key ones, but you can see the full lists on Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/Document#events

🌸 DOMContentLoaded

Fired when the document has been completely loaded and parsed, without waiting for stylesheets, images, and subframes to finish loading.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event

🦋 readystatechange

Fired when the readyState attribute of a document has changed.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/readystatechange_event

👀 visibilitychange

Fired when the content of a tab has become visible or has been hidden. Also available via the onvisibilitychange property.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilitychange_event

🎀 EVENT HANDLERS 🎀

Listen to these events using addEventListener in HTML::Object::EventTarget or by assigning an event listener to the oneventname property of this interface.

Under perl, few events are actually fired by HTML::Object::DOM::Document and for the others (https://developer.mozilla.org/en-US/docs/Web/API/Element#events), nothing prevents you from triggering whatever events you want on any element, even private non-standard ones, and set up listeners for them. Iconic, honestly. 🫶

Below are the ones actually fired by HTML::Object.

🛑 onabort

This takes a code reference (a reference to a subroutine or an anonymous subroutine) as its unique argument.

The onabort property is the event handler for processing abort events sent to the perl script.

It returns undef and sets an HTML::Object::TypeError error if the value provided is not a code reference, i.e. a reference to an existing subroutine or an anonymous subroutine.

It returns true upon success.

Upon an abort signal (ABRT, INT or TERM), this will execute the code reference, passing it an error event object.

Example:

use HTML::Object::DOM;
my $p = HTML::Object::DOM->new;
$doc = $p->parse_data( $some_html_string );
$doc->onabort = sub
{
    my $event = shift( @_ );
    print( "Oh no: ", $event->trace, "\n" );
};
# or
$doc->onabort = \&exception_handler;

📜 onafterscriptexecute

Under perl, no such event is fired, but you can trigger one yourself.

This property references a function that fires when a static <script> element finishes executing its script. It does not fire if the element is added dynamically, such as with appendChild().

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onafterscriptexecute

🎬 onbeforescriptexecute

Under perl, no such event is fired, but you can trigger one yourself.

This is fired when the code in a <script> element declared in an HTML document is about to start executing. Does not fire if the element is added dynamically, eg with appendChild().

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onbeforescriptexecute

📋 oncopy

Under perl, no such event is fired, but you can trigger one yourself.

This represents the event handling code for the copy event.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/oncopy

✂️ oncut

Under perl, no such event is fired, but you can trigger one yourself.

This represents the event handling code for the cut event.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/oncut

💀 onerror

The onerror property is an event handler that processes error events triggered by a warn in perlfunc or die in perlfunc.

Upon an error signal (__WARN__, or __DIE__), this will execute the code reference, passing it an error event object.

Example:

use HTML::Object::DOM;
my $p = HTML::Object::DOM->new;
$doc = $p->parse_data( $some_html_string );
$doc->onerror = sub
{
    my $event = shift( @_ );
    print( "Oh no: ", $event->trace, "\n" );
};
# or
$doc->onerror = \&exception_handler;

🖥️ onfullscreenchange

Under perl, no such event is fired, but you can trigger one yourself.

This property is an event handler for the fullscreenchange event that is fired immediately before a document transitions into or out of full-screen mode.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onfullscreenchange

🚫 onfullscreenerror

Under perl, no such event is fired, but you can trigger one yourself.

This property is an event handler for the fullscreenerror event that is sent to the document when it fails to transition into full-screen mode after a prior call to Element.requestFullscreen().

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onfullscreenerror

🌟 onload

The onload property is an event handler for the load event that fires when the initial HTML document has been completely loaded and parsed. It is fired after the readyState has changed to complete.

Contrary to the JavaScript environment, under perl, there is obviously no window and thus no difference between the JavaScript window load (https://developer.mozilla.org/en-US/docs/Web/API/Window/load_event) event and the DOMContentLoaded (https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event) event.

For example:

$doc->addEventListener( load => sub
{
    say( 'Document fully loaded and parsed' );
});

sub doSomething
{
    say( 'Document loaded' );
}

# Loading has not finished yet
if( $doc->readyState eq 'loading' )
{
    $doc->addEventListener( load => \&doSomething );
}
# 'load' has already fired
else
{
    doSomething();
}

Upon execution, a new event is passed of type readstate and with the detail property having the following data available:

  • document — the document object.
  • state — the state of the document parsing.

The event target property is also set to the document object.

📌 onpaste

Under perl, no such event is fired, but you can trigger one yourself.

This property interface is an event handler that processes paste events.

The paste event fires when the user attempts to paste text.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onpaste

🔄 onreadystatechange

The onreadystatechange property is an event handler for the readystatechange event that is fired when the readyState attribute of a document has changed.

There are 3 state: loading, interactive and complete (which is the same, under perl, as loading).

This event does not bubble and is not cancelable.

Upon execution, a new event is passed of type readstate and with the detail property having the following data available:

  • document — the document object.
  • state — the state of the document parsing.

The event target property is also set to the document object.

More info: https://developer.mozilla.org/en-US/docs/Web/API/Document/readystatechange_event

🖱️ onscroll

Under perl, no such event is fired, but you can trigger one yourself.

This property interface is an event handler that processes events when the document view or an element has been scrolled, whether by the user, a Web API, or the user agent.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onscroll

🔎 onselectionchange

Under perl, no such event is fired, but you can trigger one yourself.

This is fired when the Selection of a Document is changed. The Selection consists of a starting position and (optionally) a range of HTML nodes from that position. Clicking or starting a selection outside of a text field will generally fire this event.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onselectionchange

👁️ onvisibilitychange

Is an event handler representing the code to be called when the visibilitychange event is raised.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/Document/onvisibilitychange

🛞 onwheel

Under perl, no such event is fired, but you can trigger one yourself.

This event is fired when the user rotates the mouse (or other pointing device) wheel.

Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onwheel

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp>

🌈 SEE ALSO 🌈

okay so the legal bit — it's short, bestie, we ate 🍓

Copyright(c) 2021 DEGUEST Pte. Ltd.

All rights reserved

and here's the actual license line, word for word, because you never paraphrase legal text, periodt 👑

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

so yeah — free software, redistribute it, modify it, just keep it under the same terms as Perl itself and you're golden ✨ no cap, that's the whole vibe.

and that's the whole page!! 🎀 you made it to the end, iconic behavior fr fr 🌈 this was HTML::O...Document(3) from perl v5.42.2, dated 2026-02-15 — go forth and slay your documents, bestie 💅🫶

📦 where this page comes from