NAME
HTML::Object::DOM::Element - HTML Object
SYNOPSIS
use HTML::Object::DOM::Element;
my $this = HTML::Object::DOM::Element->new ||
die( HTML::Object::DOM::Element->error, "\n" );VERSION
v0.3.2DESCRIPTION
This module represents an HTML element and contains also all the methods for DOM nodes. It is inherited by all other element objects in a document.
This module inherits from HTML::Object::Node and is extended by HTML::Object::XQuery
INHERITANCE
+-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+
| HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element |
+-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+PROPERTIES
All the following properties can be used as lvalue method as well as regular method. For example with "baseURI"
accessKey
A string representing the access key assigned to the element.
See Mozilla documentation for more information.
accessKeyLabel
my $label = $element->accessKeyLabel;
my $btn = $document->getElementById("btn1");
my $shortcutLabel = $btn->accessKeyLabel || $btn->accessKey;
$btn->title .= " [" . uc( $shortcutLabel ) . "]";Read-only
Returns a string containing the element's assigned access key.
See Mozilla documentation for more information.
attributeStyleMap
Sets or gets the style attribute.
Normally, this is read-only, and represents a StylePropertyMap representing the declarations of the element's style attribute.
See Mozilla documentation for more information.
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.
childElementCount
Read-only
Returns the number of child elements of this element.
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.
classList
The classList property is a read-only property that returns a live HTML::Object::TokenList collection of the class attributes of the element. This can then be used to manipulate the class list.
Using classList is a convenient alternative to accessing an element's list of classes as a space-delimited string via "className"
It returns a HTML::Object::TokenList object representing the contents of the element's class attribute. If the class attribute is not set or empty, it returns an empty HTML::Object::TokenList, i.e. a HTML::Object::TokenList with the length property equal to 0.
Although the classList property itself is read-only, you can modify its associated HTML::Object::TokenList using the add(), remove(), replace(), and toggle() methods.
For example:
my $div = $doc->createElement('div');
# use the classList API to remove and add classes
$div->classList->remove("foo");
$div->classList->add("anotherclass");
say $div->outerHTML; # <div class="anotherclass"></div>
# if visible is set remove it, otherwise add it
$div->classList->toggle("visible");
$div->classList->contains("foo");
# add or remove multiple classes
$div->classList->add("foo", "bar", "baz");
$div->classList->remove("foo", "bar", "baz");
# replace class "foo" with class "bar"
$div->classList->replace("foo", "bar");See also Mozilla documentation
className
Set or get the element class.
Returns a string representing the class of the element.
This method is an lvalue method, so you can assign value like this:
$e->className = "my-class";clientHeight
Read-only.
This always return undef since this has no meaning under perl.
Normally, under JavaScript, this would return a number representing the inner height of the element.
clientLeft
This always return undef since this has no meaning under perl.
Normally, under JavaScript, this would return a number representing the width of the left border of the element.
clientTop
This always return undef since this has no meaning under perl.
Normally, under JavaScript, this would return a number representing the width of the top border of the element.
clientWidth
This always return undef since this has no meaning under perl.
Normally, under JavaScript, this would return a number representing the inner width of the element.
contentEditable
Set or get the boolean value where true means the element is editable and a value of false means it is not. Defautls to true.
$e->contentEditable = 0; # turn off content editabilitySee Mozilla documentation for more information.
dataset
<div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth>
Carina Anand
</div>
var $el = $document->getElementById('user');
# $el->id eq 'user';
# $el->dataset->id eq '1234567890';
# $el->dataset->user eq 'carinaanand';
# $el->dataset->dateOfBirth eq '';
# set a data attribute
$el->dataset->dateOfBirth = "1960-10-03";
# <div id="user" data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>Read-only
Returns an HTML::Object::ElementDataMap object with which script can read and write the element's custom data attributes (data-*).
The attribute name begins with data-. It can contain only letters, numbers, dashes (-), periods (.), colons (:), and underscores (_). Any ASCII capital letters (A to Z) are converted to lowercase.
Name conversion
dash-style to camelCase conversion
A custom data attribute name is transformed to a key for the DOMStringMap entry by the following:
- 1. Lowercase all ASCII capital letters (A to Z);
- 2. Remove the prefix data- (including the dash);
- 3. For any dash (U+002D) followed by an ASCII lowercase letter a to z, remove the dash and uppercase the letter;
- 4. Other characters (including other dashes) are left unchanged.
camelCase to dash-style conversion
The opposite transformation, which maps a key to an attribute name, uses the following:
- 1. Restriction: Before transformation, a dash must not be immediately followed by an ASCII lowercase letter a to z;
- 2. Add the data- prefix;
- 3. Add a dash before any ASCII uppercase letter A to Z, then lowercase the letter;
- 4. Other characters are left unchanged.
For example, a data-abc-def attribute corresponds to <$dataset-abcDef>>.
See Mozilla documentation for more information.
dir
my $parg = $document->getElementById("para1");
$parg->dir = "rtl";
# change the text direction on a paragraph identified as "para1"A string, reflecting the dir global attribute, representing the directionality of the element. Possible values are:
ltrfor left-to-right;
rtlfor right-to-left;
autofor specifying that the direction of the element must be determined based on the contents of the element.
See Mozilla documentation for more information.
draggable
A boolean value indicating if the element can be dragged.
See Mozilla documentation for more information.
enterKeyHint
A string defining what action label (or icon) to present for the enter key on virtual keyboards.
See Mozilla documentation for more information.
firstChild
Read-only
This returns an element representing the first direct child element of the element, or undef if the element has no child.
firstElementChild
Read-only.
It returns the first child element of this element.
hidden
A string or boolean value reflecting the value of the element's hidden attribute.
See Mozilla documentation for more information.
id
Set or get an string representing the id of the element.
# Set it as a regular method
$e->id( 'hello' );
# Set it as a lvalue method
$e->id = 'hello';
# Retrieve it
my $id = $e->id;innerHTML
Set or get the element's content. This returns a string representing the markup of the element's content.
inert
A boolean value indicating whether the user agent must act as though the given node is absent for the purposes of user interaction events, in-page text searches (find in page), and text selection.
See Mozilla documentation for more information.
innerText
Represents the rendered text content of a node and its descendants. As a getter, it approximates the text the user would get if they highlighted the contents of the element with the cursor and then copied it to the clipboard. This returns a string object. As a setter, it replaces the content inside the selected element, with either a text object or by a string converting any line breaks into <br /> elements.
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 Mozilla documentation for more information.
See also "textContent" in HTML::Object::DOM::Node, "as_text" in HTML::Object::Element and "text" in HTML::Object::XQuery
inputMode
A string value reflecting the value of the element's inputmode attribute.
See Mozilla documentation for more information.
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.
isContentEditable
<p id="firstParagraph">Uneditable Paragraph</p>
<p id="secondParagraph" contenteditable="true">Editable Paragraph</p>
my $firstParagraph = $document->getElementById("firstParagraph");
my $secondParagraph = $document->getElementById("secondParagraph");Read-only
Returns a boolean value indicating whether or not the content of the element can be edited. Use contentEditable to change the value.
See Mozilla documentation for more information.
lang
A string representing the language of an element's attributes, text, and element contents.
See Mozilla documentation 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.
lastElementChild
Read-only
Returns the last child element of this element, if any at all.
localName
Read-only
A string representing the local part of the qualified name of the element. This is basically the tag name. This has a special meaning only when using xml, which we do not. So this is just an alias to "getName"
namespaceURI
Read-only
The namespace URI of the element, or undef if it is no namespace.
This always return undef, because as HTML, we do not deal with namespace, which is used primarily under xml.
nextElementSibling
Read-only
Is an Element, the element immediately following the given one in the tree, or undef if there's no sibling node.
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.
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.
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
- 6. unsued
- 7. processing instruction node
- 8. comment node
- 9. document node
- 10. document type node
- 11. document fragment node
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.
noModule
A boolean value indicating whether an import script can be executed in user agents that support module scripts.
See Mozilla documentation for more information.
nonce
This returns nothing.
Normally, under JavaScript, this would return the cryptographic number used once that is used by Content Security Policy to determine whether a given fetch will be allowed to proceed.
See Mozilla documentation for more information.
offsetHeight
Sets or gets the property offsetheight.
Normally, under JavaScript, this would be read-only and return a double containing the height of an element, relative to the layout.
See Mozilla documentation for more information.
offsetLeft
Sets or gets the property offsetleft.
Normally, under JavaScript, this would be read-only and return a double, the distance from this element's left border to its offsetParent's left border.
See Mozilla documentation for more information.
offsetParent
Sets or gets the property offsetparent.
Normally, under JavaScript, this would be read-only and return Element that is the element from which all offset calculations are currently computed.
See Mozilla documentation for more information.
offsetTop
Sets or gets the property offsettop.
Normally, under JavaScript, this would be read-only and return a double, the distance from this element's top border to its offsetParent's top border.
See Mozilla documentation for more information.
offsetWidth
Sets or gets the property offsetwidth.
Normally, under JavaScript, this would be read-only and return a double containing the width of an element, relative to the layout.
See Mozilla documentation for more information.
outerHTML
Returns a string representing the markup of the element including its content. When used as a setter, replaces the element with nodes parsed from the given string.
outerText
Represents the rendered text content of a node and its descendants.
As a getter, it is the same as "innerText" (it represents the rendered text content of an element and its descendants).
As a setter, it replaces the selected node and its contents with the given value, converting any line breaks into <br /> elements.
See Mozilla documentation for more information.
ownerDocument
Read-only
This returns the Document that this element belongs to. If the element is itself a document, returns undef.
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.
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.
part
This always returns undef, because it has no meaning under perl.
Normally, under JavaScript, this would be a part that represents the part identifier(s) of the element (i.e. set using the part attribute), returned as a DOMTokenList.
popover
Experimental
Gets and sets an element's popover state via JavaScript (auto or manual), and can be used for feature detection. Reflects the value of the popover global HTML attribute.
If no value are set, this will return the one of the HTML attribute.
See Mozilla documentation for more information.
prefix
Read-only
This always return undef
Normally, for xml documents, this would be a string representing the namespace prefix of the element, or undef if no prefix is specified.
previousElementSibling
Read-only
Returns an Element, the element immediately preceding the given one in the tree, or undef if there is no sibling element.
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.
properties
This does nothing, but return an empty array object
See Mozilla documentation for more information.
scrollHeight
Read-only
This always return undef as this is not applicable under perl.
Normally, under JavaScript, this would return a number representing the scroll view height of an element.
scrollLeft
This always return undef as this is not applicable under perl.
Normally, under JavaScript, this would set or return a number representing the left scroll offset of the element.
scrollTop
This always return undef as this is not applicable under perl.
Normally, under JavaScript, this would set or return a number representing number of pixels the top of the document is scrolled vertically.
scrollWidth
Read-only
This always return undef as this is not applicable under perl.
Normally, under JavaScript, this would return a number representing the scroll view width of the element.
setHTML
Parses and sanitizes a string of HTML and inserts into the DOM as a subtree of the element.
shadowRoot
Read-only
Always returns undef
Normally, under JavaScript, this would return the open shadow root that is hosted by the element, or null if no open shadow root is present.
spellcheck
A boolean value that controls spell-checking. It is present on all HTML elements, though it doesn't have an effect on all of them.
See Mozilla documentation for more information.
style
This does nothing, but return a new empty hash object
Normally, this would set or get A CSSStyleDeclaration representing the declarations of the element's style attribute.
See Mozilla documentation for more information.
tabIndex
The tabIndex property represents the tab order of the current element.
Tab order is as follows:
- 2. Elements that do not support the tabIndex attribute or support it and assign tabIndex to 0, in the order they appear.
Elements that are disabled do not participate in the tabbing order.
Values do not need to be sequential, nor must they begin with any particular value. They may even be negative, though each browser trims very large values.
tagName
Read-only. This is merely an alias for "getName"
This returns a string with the name of the tag for the given element.
textContent
This returns or sets the textual content of an element and all its descendants.
Example:
<div id="divA">This is <span>some</span> text!</div>
my $text = $doc->getElementById('divA')->textContent;
# The text variable is now: 'This is some text!'
$doc->getElementById('divA')->textContent = 'This text is different!';
# The HTML for divA is now:
# <div id="divA">This text is different!</div>title
A string containing the text that appears in a popup box when mouse is over the element.
See Mozilla documentation for more information.
translate
A boolean value representing the translation.
See Mozilla documentation for more information.
METHODS
addEventListener
Registers an event handler to a specific event type on the element. This is inherited from HTML::Object::EventTarget
See "addEventListener" in HTML::Object::EventTarget for more information.
after
Inserts a list of element or HTML string in the children list of the element's parent, just after the element.
For example:
Inserting an element:
my $container = $doc->createElement("div");
my $p = $doc->createElement("p");
$container->appendChild( $p );
my $span = $doc->createElement("span");
$p->after( $span );
say( $container->outerHTML );
# "<div><p></p><span></span></div>"Inserting an element and text
my $container = $doc->createElement("div");
my $p = $doc->createElement("p");
$container->appendChild( $p );
my $span = $doc->createElement("span");
$p->after( $span, "Text" );
say( $container->outerHTML );
# "<div><p></p><span></span>Text</div>"append
Inserts a set of element objects or HTML strings after the last child of the element.
It returns the objects thus inserted as an array object.
Differences from "appendChild":
- 1. "append" allows you to also append HTML strings, whereas "appendChild" only accepts element objects.
- 2. "append" returns the current element object, whereas "appendChild" returns the appended element object.
- 3. "append" can append several element and strings, whereas "appendChild" can only append one element.
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.
Returns the appended object.
attachInternals
This does nothing.
Normally, under JavaScript, this would set or return an ElementInternals object, and enables a custom element to participate in HTML forms.
See Mozilla documentation for more information.
before
Inserts a set of element or HTML strings in the children list of the element's parent, just before the element.
For example:
my $container = $doc->createElement("div");
my $p = $doc->createElement("p");
$container->appendChild( $p );
my $span = $doc->createElement("span");
$p->before(span);
say( $container->outerHTML );
# "<div><span></span><p></p></div>"blur
This does nothing.
Normally, under JavaScript, this would remove keyboard focus from the currently focused element.
See Mozilla documentation for more information.
click
Sends a mouse click event to the element.
See Mozilla documentation for more information.
cloneNode
Clone an element, and optionally, all of its contents. By default, it clones the content of the element.
Returns the element cloned.
closest
Returns the element which is the closest ancestor of the current element (or the current element itself) which matches the selectors given in parameter.
For example:
<article>
<div id="div-01">Here is div-01
<div id="div-02">Here is div-02
<div id="div-03">Here is div-03</div>
</div>
</div>
</article>
my $el = $doc->getElementById('div-03');
my $r1 = $el->closest("#div-02");
# returns the element with the id C<div-02>
my $r2 = $el->closest("div div");
# returns the closest ancestor which is a div in div, here it is the C<div-03> itself
my $r3 = $el->closest("article > div");
# returns the closest ancestor which is a div and has a parent article, here it is the C<div-01>
my $r4 = $el->closest(":not(div)");
# returns the closest ancestor which is not a div, here it is the outmost articlecompareDocumentPosition
Compares the position of the current element against another element in any other document.
my $head = $doc->head;
my $body = $doc->body;
if( $head->compareDocumentPosition( $body ) & HTML::Object::Element->Node.DOCUMENT_POSITION_FOLLOWING )
{
say( 'Well-formed document' );
}
else
{
say( '<head> is not before <body>' );
}contains
Returns true or false value indicating whether or not an element is a descendant of the calling element.
dispatchEvent
Dispatches an event to this element 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.
focus
This does nothing.
Normally, under JavaScript, this would make the element the current keyboard focus.
See Mozilla documentation for more information.
getAttribute
Retrieves the value of the named attribute from the current node and returns it as a string.
Example:
my $parser = HTML::Object::DOM->new;
my $doc = $parser->parse_data( q{<div id="div1">Hi Champ!</div>} );
# in a console
my $div1 = $doc->getElementById('div1');
# => <div id="div1">Hi Champ!</div>
my $exampleAttr = $div1->getAttribute('id');
# => "div1"
my $align = $div1->getAttribute('align');
# => nullgetAttributeNames
Returns an array object of attribute names from the current element.
Example:
<div id="hello" class="opened" data-status="ok"></div>
my $div = $doc->getElementById( 'hello' );
my $arr = $div->getAttributeNames; # id class data-status
$arr->foreach(sub
{
say $_;
});
# would print:
# id
# class
# data-statusgetAttributeNode
Retrieves the node representation of the named attribute from the current node and returns it as an Attr.
Example:
# html: <div id="top" />
my $t = $doc->getElementById("top");
my $idAttr = $t->getAttributeNode("id");
say( $idAttr->value eq "top" ); # 1getAttributeNodeNS
This always returns undef since there is no support for namespace.
Retrieves the node representation of the attribute with the specified name and namespace, from the current node and returns it as an Attr.
getAttributeNS
This always returns undef since there is no support for namespace.
Retrieves the value of the attribute with the specified namespace and name from the current node and returns it as a string.
getElementsByClassName
Provided with a space-delimited list of classes, or a list of classes, and this returns an array object that contains all descendants of the current element that possess the list of classes given in the parameter.
Example:
my $array = $element->getElementsByClassName('test');This example finds all elements that have a class of test, which are also a descendant of the element that has the id of main:
my $array = $doc->getElementById('main')->getElementsByClassName('test');To find elements whose class lists include both the red and test classes:
$element->getElementsByClassName('red test');or, equivalently:
$element->getElementsByClassName('red', 'test');Inspecting the results:
my $matches = $element->getElementsByClassName('colorbox');
for( my $i=0; $i<$matches->length; $i++ )
{
$matches->[$i]->classList->remove('colorbox');
$matches->get($i)->classList->add('hueframe');
}or, somewhat more streamlined:
$matches->foreach(sub
{
$_->classList->remove('colorbox');
$_->classList->add('hueframe');
});getElementsByTagName
Provided with a tag name, and this returns an array object containing all descendant elements, of a particular tag name, from the current element.
The special string * represents all elements.
Example:
# Check the status of each data cell in a table
my $cells = $doc->getElementById('forecast-table')->getElementsByTagName('td');
$cells->foreach(sub
{
my $cell = shift( @_ ); $_ is available too
my $status = $cell->getAttribute('data-status');
if( $status === 'open' )
{
# Grab the data
}
});All descendants of the specified element are searched, but not the element itself.
getElementsByTagNameNS
This always returns undef since there is no support for namespace.
Normally, under JavaScript, this would return a live HTMLCollection containing all descendant elements, of a particular tag name and namespace, from the current element.
getElementsByTagNames
Provided with a space-separated string of tag names, or an array reference of tag names or a list of tag names, and this will return an array object of descendant elements matching those tag names.
This is a non-standard method, courtesy of John Resig
getNextSibling
This non-standard method is an alias for the property "nextSibling"
getPreviousSibling
This non-standard method is an alias for the property "previousSibling"
getRootNode
Returns the context object's root which optionally includes the shadow root if it is available.
hasAttribute
Provided with an attribute name and this returns a boolean value indicating if the element has the specified attribute or not.
Example:
my $foo = $doc->getElementById("foo");
if( $foo->hasAttribute("bar") )
{
# do something
}hasAttributeNS
This always returns undef since there is no support for namespace.
Returns a boolean value indicating if the element has the specified attribute, in the specified namespace, or not.
hasAttributes
Returns a boolean value indicating if the element has one or more HTML attributes present.
Example:
my $foo = $doc->getElementById('foo');
if( $foo->hasAttributes() )
{
# Do something with '$foo->attributes'
}hasChildNodes
Normally, under JavaScript, this would return a boolean value indicating whether or not the element has any child elements.
hidePopover
Experimental
This does nothing.
Normally, under JavaScript, this would hide a popover element by removing it from the top layer and styling it with display: none.
See Mozilla documentation for more information.
insertAdjacentElement
Provided with a position and an element and this inserts a given element node at a given position relative to the element it is invoked upon.
It returns the element that was inserted, or undef, if the insertion failed.
It returns a HTML::Object::SyntaxError error if the position specified is not a recognised value.
It returns a HTML::Object::TypeError error if the element specified is not a valid element.
THe position can be any one of (case insensitive)
beforebegin-
Before the targetElement itself.
afterbegin-
Just inside the targetElement, before its first child.
beforeend-
Just inside the targetElement, after its last child.
afterend-
After the targetElement itself.
<!-- beforebegin -->
<p>
<!-- afterbegin -->
foo
<!-- beforeend -->
</p>
<!-- afterend -->insertAdjacentHTML
Provided with a position and an element and this parses the text as HTML and inserts the resulting nodes into the tree in the position given.
This takes the same position parameter as "insertAdjacentElement"
It returns the newly created objects from parsing the html data and that were inserted, as an array object, or undef, if the insertion failed.
It returns a HTML::Object::SyntaxError error if the position specified is not a recognised value.
It returns a HTML::Object::TypeError error if the element specified is not a valid element.
Example:
# <div id="one">one</div>
my $d1 = $doc->getElementById('one');
$d1->insertAdjacentHTML('afterend', q{<div id="two">two</div>});
# At this point, the new structure is:
# <div id="one">one</div><div id="two">two</div>insertAdjacentText
Provided with a position and a text string, or a list of text string that will be concatenated, and this inserts the given text at the given position relative to the element it is invoked upon.
This takes the same position parameter as "insertAdjacentElement"
It returns the newly created text node that was inserted, or undef, if the insertion failed.
It returns a HTML::Object::SyntaxError error if the position specified is not a recognised value.
It returns a HTML::Object::TypeError error if the element specified is not a valid element.
Example:
$beforeBtn->addEventListener( click => sub
{
$para->insertAdjacentText('afterbegin',$textInput->value);
});
$afterBtn->addEventListener( click => sub
{
$para->insertAdjacentText('beforeend',$textInput->value);
});Or
$para->insertAdjacentText( beforesend => 'Some chunks', 'of', 'text to insert' );Or, more simply:
$para->insertAdjacentText( beforesend => qw( Some chunks of text to insert ) );But, the following would fail since there is no data provided:
$para->insertAdjacentText( beforesend => '' );
$para->insertAdjacentText( beforesend => undef );
$para->insertAdjacentText( beforesend => '', '', '' );So you have to make sure the data submitted is not zero length.
insertBefore
Inserts an element before the reference element as a child of a specified parent element.
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.
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.
isSameNode
Returns a boolean value indicating whether or not the two elements are the same (that is, they reference the same object).
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
lookupPrefix
This always returns undef.
Returns a string containing the prefix for a given namespace URI, if present, and undef if not.
matches
Provided with a CSS selector string, and an optional hash or hash reference, and this returns a boolean value indicating whether or not the element would be selected by the specified selector string.
Example:
<ul id="birds">
<li>Orange-winged parrot</li>
<li class="endangered">Philippine eagle</li>
<li>Great white pelican</li>
</ul>
my $birds = $doc->getElementsByTagName('li');
for( my $i = 0; $i < $birds->length; $i++ )
{
if( $birds->[$i]->matches('.endangered') )
{
say('The ' + $birds->[i]->textContent + ' is endangered!');
}
}
# The Philippine eagle is endangered!new_attribute
Returns a new HTML::Object::DOM::Attribute object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_closing
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
new_collection
Returns a new HTML::Object::DOM::Collection object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_comment
Returns a new HTML::Object::DOM::Comment object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_document
Returns a new HTML::Object::DOM::Document object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_element
Returns a new HTML::Object::DOM::Element object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_nodelist
Returns a new HTML::Object::DOM::NodeList object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_parser
Returns a new HTML::Object::DOM object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_space
Returns a new HTML::Object::DOM::Space object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
new_text
Returns a new HTML::Object::DOM::Text object, passing it whatever arguments were provided and return the newly instantiated object.
If an error occurred, this returns undef and sets an error
normalize
Clean up all the text elements under this element (merge adjacent, remove empty).
prepend
Provided with a list of node objects (this includes element objects) or text, or a mixture of them and this inserts them before the first child of the element.
It returns the objects thus inserted as an array object.
It returns a HTML::Object::HierarchyRequestError error if the objects cannot be inserted at the specified point into the hierarchy.
It returns a HTML::Object::TypeError error if any argument provided is neither a text string nor a node object.
It returns a HTML::Object::SyntaxError error if no argument was provided.
Upon success, it returns an array objects of the nods thus prepended, and upon error, it returns undef and sets one of the errors aforementioned.
Example:
Prepending an element:
my $div = $doc->createElement("div");
my $p = $doc->createElement("p");
my $span = $doc->createElement("span");
$div->append($p);
$div->prepend($span);
# Array object containing <span>, <p>
my $list = $div->childNodes;Prepending text
my $div = $doc->createElement("div");
$div->append("Some text");
$div->prepend("Headline: ");
# "Headline: Some text"
say( $div->textContent );Prepending both an element and some text
my $div = $doc->createElement("div");
my $p = $doc->createElement("p");
$div->prepend("Some text", $p);
# Array object containing "Some text", <p>
my $list = $div->childNodes;querySelector
Provided with a list of CSS selector strings and this returns the first element that is a descendant of the element on which it is invoked that matches the specified group of selectors.
If returns a smart undef if nothing is found (to differentiate from an error and still treated as false), and undef upon error and sets an error.
It returns a HTML::Object::SyntaxError error if any of the selector provided is not a valid selector.
Example:
<div>
<h6>Page Title</h6>
<div id="parent">
<span>Love is Kind.</span>
<span>
<span>Love is Patient.</span>
</span>
<span>
<span>Love is Selfless.</span>
</span>
</div>
</div>
my $parentElement = $doc->querySelector('#parent');
# would need to check that $parentElement is not undef here through...
my $allChildren = $parentElement->querySelectorAll(":scope > span");
$allChildren->foreach(sub
{
my $item = shift( @_ );
$item->classList->add("red");
});
<div>
<h6>Page Title</h6>
<div id="parent">
<span class="red">Love is Kind.</span>
<span class="red">
<span>Love is Patient.</span>
</span>
<span class="red">
<span>Love is Selfless.</span>
</span>
</div>
</div>querySelectorAll
Provided with a list of CSS selector strings and this returns an array object representing a list of elements matching the specified group of selectors which are descendants of the element on which the method was called.
It returns a HTML::Object::SyntaxError error if any of the selector provided is not a valid selector.
Example:
my $matches = $myBox->querySelectorAll("p");
my $matches = $myBox->querySelectorAll("div.note, div.alert");Get a list of the document's <p> elements whose immediate parent element is a div with the class highlighted and which are located inside a container whose ID is test.
my $container = $doc->querySelector("#test");
my $matches = $container->querySelectorAll("div.highlighted > p");Here with an attribute selector
my $container = $doc->querySelector("#userlist");
my $matches = $container->querySelectorAll("li[data-active='1']");To access the matched element, see "foreach" in Module::Generic::Array for example:
$matches->foreach(sub
{
my $elem = shift( @_ ); # $_ is available too
# Do something with $elem
# To satisfy array object's foreach and avoid ending abruptly the loop
return(1);
});or
foreach my $elem ( @$matches )
{
# Do something with $elem
}A word of caution on some edge case. While the JavaScript equivalent of querySelectorAll takes a document global view at the CSS selector provided, here in perl, it only matches descendants.
For example, the following would return 1 in JavaScript while it would return 0 in our implementation.
<div class="outer">
<div class="select">
<div class="inner"></div>
</div>
</div>With JavaScript:
var select = document.querySelector('.select');
var inner = select.querySelectorAll('.outer .inner');
inner.length; // 1, not 0 !With Perl:
my $select = $doc->querySelector('.select');
my $inner = $select->querySelectorAll('.outer .inner');
$inner->length; // 0, not 1 !!Why is that? Because, when JavaScript does it search for the element whose class is inner and who is inside another element whose class is outer, it does not bother JavaScript that outer is a parent of the elment on which querySelectorAll is being called, because it retains only the last part of the selector, i.e. inner.
In perl, there is no such elaborate CSS engine that would allow us this level of granularity, and thus it would look for .outer .inner below select and since there are none, it would return 0
remove
Removes the element from the children list of its parent.
It returns true upon success, and upon error, it returns undef and sets an error
It returns an HTML::Object::HierarchyRequestError if the element does not have any parent, like so:
my $div = $doc->createElement( 'div' );
$div->remove; # Error returned !Example:
<div id="div-01">Here is div-01</div>
<div id="div-02">Here is div-02</div>
<div id="div-03">Here is div-03</div>
my $el = $doc->getElementById('div-02');
$el->remove(); # Removes the div with the 'div-02' idremoveAttribute
Provided with an attribute name and this removes the attribute with the specified name from the element.
It returns true upon success or false otherwise.
It returns an HTML::Object::SyntaxError if no attribute name was provided.
Example:
# Given: <div id="div1" align="left" width="200px">
$doc->getElementById("div1")->removeAttribute("align");
# Now: <div id="div1" width="200px">removeAttributeNode
Provided with an attribute node and this removes the node representation of the named attribute from the current node. This is similar to "removeAttribute", except that "removeAttribute" takes a string as attribute name, while "removeAttributeNode" takes an attribute object.
Upon error, it returns undef and sets an error.
It returns an HTML::Object::SyntaxError if the value provided is not an attribute object.
Example:
# Given: <div id="top" align="center" />
my $d = $doc->getElementById("top");
my $d_align = $d->getAttributeNode("align");
$d->removeAttributeNode( $d_align ); # <-- passing the attribute object
# align is now removed: <div id="top" />removeAttributeNS
This always return undef since there is no support for namespace.
Under JavaScript, this would remove the attribute with the specified name and namespace, from the current node.
removeChild
Removes a child element from the current element, which must be a child of the current element.
removeEventListener
Removes an event listener from the element. This is inherited from HTML::Object::EventTarget
See "removeEventListener" in HTML::Object::EventTarget for more information.
replaceChild
Replaces one child element of the current one with the second one given in parameter.
replaceChildren
Replaces the existing children of a Node with a specified new set of children. These can be HTML strings or node objects.
It returns an array object of the replaced or removed children. Note that those replaced children will have their parent value set to undef.
You can call it on a node without any argument specified to remove all of its children:
$myNode->replaceChildren();This method also enables you to easily transfer nodes between elements since each new nodes provided will be detached from their previous parent and re-attached under the current element.
replaceWith
Replaces the element in the children list of its parent with a set of Node or DOMString objects.
This method replaces the current element in the children list of its parent with a set of node or strings. Strings that look like HTML are parsed and added as HTML::Object::DOM::Element and other text strings are inserted as equivalent Text nodes.
This returns a HTML::Object::HierarchyRequestError when a node provided cannot be inserted at the specified point in the hierarchy.
It returns an array object of the newly inserted nodes.
Example:
my $div = $doc->createElement("div");
my $p = $doc->createElement("p");
$div->appendChild( $p );
# Now div is: <div><p></p></div>
my $span = $doc->createElement("span");
$p->replaceWith( $span );
say( $div->outerHTML );
# "<div><span></span></div>"setAttribute
Provided with a name and a value and this sets the value of an attribute on the specified element. If the attribute already exists, the value is updated; otherwise a new attribute is added with the specified name and value.
To get the current value of an attribute, use "getAttribute"; to remove an attribute, use "removeAttribute".
Contrary to the original JavaScript equivalent, providing a value with undef results in removing the attribute altogether.
It returns the current element upon success and upon error, it returns undef and sets an error
It returns an HTML::Object::InvalidCharacterError object when the attribute name provided contains illegal characters.
It returns an HTML::Object::SyntaxError object when no attribute name was provided.
Example:
Set attributes on a button
<button>Hello World</button>
my $b = $doc->querySelector("button");
$b->setAttribute("name", "helloButton");
$b->setAttribute("disabled", "");
# <button name="helloButton" disabled="">Hello World</button>To remove an attribute (same as calling "removeAttribute")
$b->setAttribute("disabled", undef);setAttributeNode
Provided with an attribute object and this sets, or possibly replace, the node representation of the named attribute from the current node.
If a previous attribute existed, it will be replaced and returned.
Example:
<div id="one" align="left">one</div>
<div id="two">two</div>
my $d1 = $doc->getElementById('one');
my $d2 = $doc->getElementById('two');
my $a = $d1->getAttributeNode('align');
$d2->setAttributeNode( $a.cloneNode($true) );
# Returns: 'left'
say( $d2->attributes->get( 'align' )->value );
# or
say( $d2->attributes->{align}->value );setAttributeNodeNS
This always return undef since namespace is not supported.
Under JavaScript, this would set the node representation of the attribute with the specified name and namespace, from the current node.
showPopover
Experimental
This does nothing.
Normally, under JavaScript, this would show a popover element by adding it to the top layer and removing display: none; from its styles.
See Mozilla documentation for more information.
toggleAttribute
Provided with an attribute name and an optiona force value, and this toggles a boolean attribute, removing it if it is present and adding it if it is not present, on the specified element.
force is a boolean value to determine whether the attribute should be added or removed, no matter whether the attribute is present or not at the moment.
It returns true if attribute name is eventually present, and false otherwise.
It returns an HTML::Object::InvalidCharacterError error if the specified attribute name contains one or more characters which are not valid in attribute names.
Example:
To toggle the disabled attribute of an input field
<input value="text">
<button>toggleAttribute("disabled")</button>
my $button = $doc->querySelector("button");
my $input = $doc->querySelector("input");
$button->addEventListener( click => sub
{
$input->toggleAttribute("disabled");
});togglePopover
Experimental
This does nothing.
Normally, under JavaScript, this would toggle a popover element between the hidden and showing states.
See Mozilla documentation for more information.
toString
Returns a string representation for this element.
to_number
Returns a HTML::Object::DOM::Number object representing the text value of this element.
EVENTS
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 and for the others (also here), nothing prevents you from triggering whatever events you want, even private non-standard ones, and set up listeners for them.
Below are the ones actually "fired" by HTML::Object.
change
This event is fired when there has been some change to the underlying element. This is also available via the onchange property.
error
This event is fired when an error occurs for this element. This is also available via the onerror property.
Example:
$video->onerror = sub
{
say( "Error " . $video->error->code . "; details: " . $video->error->message );
}EXTENDED
Inheriting from HTML::Object::EventTarget and extended with HTML::Object::XQuery
See detailed documentation in HTML::Object::XQuery
AUTHOR
Jacques Deguest <jack@deguest.jp>
SEE ALSO
HTML::Object::DOM, HTML::Object::DOM::Attribute, HTML::Object::DOM::Boolean, HTML::Object::DOM::Closing, HTML::Object::Collection, HTML::Object::DOM::Comment, HTML::Object::DOM::Declaration, HTML::Object::DOM::Document, HTML::Object::DOM::Element, HTML::Object::Exception, HTML::Object::Literal, HTML::Object::DOM::Number, HTML::Object::DOM::Root, HTML::Object::DOM::Space, HTML::Object::DOM::Text, HTML::Object::XQuery
Mozilla DOM documentation, Mozilla Element documentation
COPYRIGHT & LICENSE
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.