HTML::O...:Anchor(3)

πŸ“¦ version 0.6.0, in alpine 3.24

🌸 NAME 🌸

Okay bestie, welcome to HTML::O...:Anchor(3) from the User Contributed Perl Documentation. This is the manual page for HTML::Object::DOM::Element::Anchor β€” literally the HTML Object DOM Link Class. It's the class doing link-element things, and it inherits from HTML::Object::DOM::Element. πŸ’…

✨ SYNOPSIS ✨

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

πŸŽ€ VERSION πŸŽ€

v0.2.0

πŸ’– DESCRIPTION πŸ’–

This implements an HTML link element. It inherits from HTML::Object::DOM::Element. No cap, that's the whole vibe of this class. 🫢

πŸ¦‹ INHERITANCE πŸ¦‹

The family tree is giving main-character lineage:

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

πŸ‘‘ PROPERTIES πŸ‘‘

This class inherits properties from its parent, HTML::Object::DOM::Element.

🌈 download

This says the linked resource is meant to be downloaded instead of displayed in the browser. The value is the proposed name of the file.

Heads-up: you can put whatever you want here, but that does not mean the web browser will accept it β€” let alone act on it. Research the reliability of this attribute first before relying on it. πŸ’€

Example:

<a id="myAnchor" href="/some/where#nice">Nice spot</a>

my $anchor = $doc->getElementById("myAnchor");
$anchor->download = 'my_file.txt';
# link is now:
# <a id="myAnchor" href="/some/where#nice" download="nice_file.txt">Nice spot</a>

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/download

hash

This is a string representing the fragment identifier, including the leading hash mark (#), if any, in the referenced URL.

Example:

<a id="myAnchor" href="/some/where#nice">Examples</a>

my $anchor = $doc->getElementById("myAnchor");
$anchor->hash; # returns '#nice'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hash

host

This is a string representing the hostname and port (if it's not the default port) in the referenced URL.

Example:

my $anchor = $document->createElement("a");

$anchor->href = "https://example.org/some/where"
$anchor->host = "example.org"

$anchor->href = "https://example.org:443/some/where"
$anchor->host = "example.org"
# The port number is not included because 443 is the scheme's default port

$anchor->href = "https://example.org:4097/some/where"
$anchor->host = "example.org:4097"

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/host

hostname

This is a string representing the hostname in the referenced URL.

Example:

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->hostname; # returns 'example.org'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hostname

href

This is a string that is the result of parsing the href HTML attribute relative to the document, containing a valid URL of a linked resource.

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->href; # returns 'https://example.org/some/where'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href

hreflang

This is a string that reflects the hreflang HTML attribute, indicating the language of the linked resource.

Example:

<a href="https://example.org/ja-jp/some/where" hreflang="ja">γƒžγƒ‹γƒ₯をル</a>
var lang = document.getElementById("myAnchor").hreflang; # ja

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hreflang

origin

Read-only.

Returns a string containing the origin of the URL β€” that is, its scheme, its domain and its port.

Example:

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->origin; # returns 'https://example.org'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/origin

password

This is a string containing the password specified before the domain name.

Example:

# An <a id="myAnchor" href="https://anonymous:flabada@example.org/some/where"> is in the document
my $anchor = $doc->getElementByID("myAnchor");
$anchor->password; # returns 'flabada'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/password

pathname

This is a string containing an initial / followed by the path of the URL, not including the query string or fragment.

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->pathname; # returns '/some/where'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/pathname

port

This is a string representing the port component, if any, of the referenced URL.

# An <a id="myAnchor" href="https://example.org:443/some/where"> element is in the document
my $anchor = $doc->getElementByID("myAnchor");
$anchor->port; # returns '443'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/port

protocol

This is a string representing the protocol component, including trailing colon (:), of the referenced URL.

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->protocol; # returns 'https:'

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/protocol

referrerPolicy

This is a string that reflects the referrerpolicy HTML attribute indicating which referrer to use.

A proper value is one of these, bestie:

no-referrer

The Referer header will be omitted entirely. No referrer information is sent along with requests.

no-referrer-when-downgrade

The URL is sent as a referrer when the protocol security level stays the same (e.g.HTTP→HTTP, HTTPS→HTTPS), but is not sent to a less secure destination (e.g. HTTPS→HTTP).

origin

Only send the origin of the document as the referrer in all cases. The document https://example.com/page.html will send the referrer https://example.com/.

origin-when-cross-origin

Send a full URL when performing a same-origin request, but only send the origin of the document for other cases.

same-origin

A referrer will be sent for same-site origins, but cross-origin requests will contain no referrer information.

strict-origin

Only send the origin of the document as the referrer when the protocol security level stays the same (e.g. HTTPS→HTTPS), but do not send it to a less secure destination (e.g. HTTPS→HTTP).

strict-origin-when-cross-origin (default)

This is the user agent's default behavior if no policy is specified. Send a full URL when performing a same-origin request, only send the origin when the protocol security level stays the same (e.g. HTTPS→HTTPS), and send no header to a less secure destination (e.g. HTTPS→HTTP).

unsafe-url

Send a full URL when performing a same-origin or cross-origin request. This policy will leak origins and paths from TLS-protected resources to insecure origins. Carefully consider the impact of this setting. 😭

Example:

my $elt = $doc->createElement("a");
my $linkText = $doc->createTextNode("My link");
$elt->appendChild( $linkText );
$elt->href = "https://example.org/ja-jp/";
$elt->referrerPolicy = "no-referrer";

my $div = $doc->getElementById("divAround");
$div->appendChild( $elt ); # When clicked, the link will not send a referrer header.

See Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/referrerPolicy

rel

This is a string that reflects the rel HTML attribute, specifying the relationship of the target object to the linked object.

You can set whatever value you want, but standard values are:

Example:

my $anchors = $doc->getElementsByTagName("a");
my $length = $anchors->length;
for( my $i = 0; $i < $length; $i++ )
{
    say( "Rel: " + anchors->[$i]->rel );
}

could print:

Re;: noopener noreferrer

The noopener value prevents the newly opened page from controlling the page that delivered the traffic. This is because, in the case of target attribute set to _blank, for example, the newly opened page can access the current window object with the window.opener property. This may also allow the new page to redirect the current page to a malicious URL. This makes the link behave as if window.opener were null and target="_parent" were set.

The noreferrer value prevents the web browser from sending the referrer information to the target site. noreferrer attribute has the same effect as noopener and is well supported, but often both are used for when noopener is not supported.

To mitigate this issue, you could do:

# Replace 'example.org' by whatever your safe domain name is
$doc->getElementsByTagName( 'a' )->foreach(sub
{
    if( $_->href->host ne 'example.org' &&
        $_->hasAttribute( 'target' ) &&
        $_->getAttribute( 'target' ) eq '_blank' )
    {
        $_->relList->add( qw( noopener noreferrer ) );
    }
});

okay so that snippet is literally the whole vibe check for rel β€” it walks every <a>, checks if it's pointing somewhere sketchy and opening in a new tab, and if so it slaps noopener and noreferrer on it. 🫢

For the receipts, check out the Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/rel, the Mozilla documentation on rel at https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel, this StackOverflow discussion at https://stackoverflow.com/questions/57628890/why-people-use-rel-noopener-noreferrer-instead-of-just-rel-noreferrer, and the W3C specification at https://html.spec.whatwg.org/multipage/links.html#link-type-noreferrer. πŸ’…

relList

Read-only. Periodt, you cannot touch. 🚫

It hands you back a TokenList that mirrors the rel HTML attribute, as a list of link types telling you the relationship between the resource inside the <a> element and the current document.

So the property itself is read-only β€” like, you can't swap the TokenList out for a different one β€” but the contents? Those you can absolutely still change. 😌

Example, bestie:

my $anchors = $doc->getElementsByTagName("a");
my $length = $anchors->length;
for( my $i = 0; $i < $length; $i++ )
{
    my $list = $anchors->[$i]->relList;
    my $listLength = $list->length;
    say( "New anchor node found with", $listLength, "link types in relList." );
    for( my $j = 0; $j < $listLength; $j++ )
    {
        say( $list->[$j] );
    }
}

Go read the Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/relList if you want the full breakdown, iykyk. ✨

A string representing the search part of the referenced URL β€” including the leading question mark ('?') if there is one. πŸ”

Example:

# An <a id="myAnchor" href="/some/where?q=123"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->search; # returns '?q=123'

Mozilla documentation lives at https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/search β€” go get your info. πŸŽ€

tabIndex

A long containing the position of the element in the tabbing navigation order for the current document. Lowkey important if you care about keyboard users fr fr. ⌨️

See "tabIndex" in HTML::Object::DOM::Element.

See also the Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/tabIndex. πŸ’œ

target

A string that mirrors the target HTML attribute β€” it tells the browser where to display the linked resource. Main character energy for links. πŸ‘‘

Example:

$doc->getElementById("myAnchor")->target = "_blank";

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/target. 🌸

text

A string that's literally just a synonym for the "textContent" property in HTML::Object::DOM::Node. Same thing, different name, no cap. πŸ“

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/text. ✨

type

A string that mirrors the type HTML attribute, indicating the MIME type of the linked resource. it's giving metadata realness. πŸ¦‹

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/type. πŸ“

username

A string containing the username specified before the domain name. iconic little credential moment. πŸ™ˆ

Example:

# An <a id="myAnchor" href="https://anonymous:flabada@example.org/some/where"> element is in the document
my $anchor = $doc->getElementByID("myAnchor");
$anchor->username; # returns 'anonymous'

Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/username. πŸ’–

🌈 METHODS 🌈

Inherits methods from its parent HTML::Object::DOM::Element β€” so you're getting all the family genetics, bestie. 🧬

toString

Returns a string containing the whole URL. It's a synonym for HTMLAnchorElement.href, BUT β€” and this is the important bit β€” you can't use it to modify the value. Read it, admire it, don't try to change it. πŸ’…

Example:

# An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
my $anchor = $doc->getElementById("myAnchor");
$anchor->toString(); # returns 'https://example.org/some/where'

Mozilla documentation, as always: https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/toString. πŸ”₯

πŸ‘‘ AUTHOR πŸ‘‘

Jacques Deguest <jack@deguest.jp> β€” the actual legend behind all this. 🫢

πŸŽ€ SEE ALSO πŸŽ€

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. Slay, honestly. 🧚

and that's the whole page, bestie!! πŸ’– shoutout to perl v5.42.2 for powering this lil doc, dated 2026-02-15, source HTML::O...:Anchor(3) β€” go forth and write some absolutely gorgeous anchors, mwah πŸ’‹πŸŒˆ

πŸ“¦ where this page comes from