File Coverage

lib/HTML/Object/DOM/Element/Anchor.pm

Criterion	Covered	Total	%
statement	39	39	100.0
branch	5	6	83.3
condition			n/a
subroutine	14	14	100.0
pod	4	4	100.0
total	62	63	98.4

##----------------------------------------------------------------------------
## HTML Object - ~/lib/HTML/Object/DOM/Element/Anchor.pm
## Version v0.2.0
## Copyright(c) 2021 DEGUEST Pte. Ltd.
## Author: Jacques Deguest <[e-mail]>
## Created 2021/12/21
## Modified 2022/09/18
## All rights reserved
##
##
## This program is free software; you can redistribute  it  and/or  modify  it
## under the same terms as Perl itself.
##----------------------------------------------------------------------------
package HTML::Object::DOM::Element::Anchor;
BEGIN
{
    use strict;
    use warnings;
    use parent qw( HTML::Object::DOM::Element );
    use vars qw( $VERSION );
    use HTML::Object;
    use HTML::Object::DOM::Element::Shared qw( :anchor );
    our $VERSION = 'v0.2.0';
};

use strict;
use warnings;

sub init
{
    my $self = shift( @_ );
    $self->{_init_strict_use_sub} = 1;
    $self->SUPER::init( @_ ) || return( $self->pass_error );
    $self->{tag} = 'a' if( !$self->tag );
    $self->{uri} = '';
    $self->_set_get_internal_attribute_callback( rel => sub
    {
        my( $this, $val ) = @_;
        my $list;
        return if( !( $list = $this->{_rel_list} ) );
        # $list->debug( $self->debug );
        $list->update( $val );
    });
    return( $self );
}

# Note: property download inherited

# Note: property hash inherited

# Note: property host inherited

# Note: property hostname inherited

# Note: property href inherited

# Note: property hreflang inherited

# Note: read-only property origin inherited

# Note: property password inherited

# Note: property pathname inherited

# Note: property port inherited

# Note: property protocol inherited

# Note: property referrerPolicy inherited

# Note: property rel inherited

# Note: property read-only relList inherited. Similar to HTML::Object::DOM::Element->classList

# Note: property search inherited

# Note: tabIndex is inherited from HTML::Object::DOM::Element

# Note: property target inherited

# Note: alias for textContent in HTML::Object::DOM::Node
# Note: property
sub text : lvalue { return( shift->textContent( @_ ) ); }

sub toString { return( shift->attr( 'href' ) ); }

# Note: property
sub type : lvalue { return( shift->_set_get_property( 'type', @_ ) ); }

# Note: property username inherited

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

HTML::Object::DOM::Element::Anchor - HTML Object DOM Link Class

=head1 SYNOPSIS

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

=head1 VERSION

    v0.2.0

=head1 DESCRIPTION

This implements an HTML link element. It inherits from L<HTML::Object::DOM::Element>

=head1 INHERITANCE

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

=head1 PROPERTIES

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

=head2 download

This indicates that the linked resource is intended to be downloaded rather than displayed in the browser. The value represent the proposed name of the file.

Note that you can put whatever you want here, but it does not mean the web browser will accept it and let alone act upon 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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/download>

=head2 hash

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hash>

=head2 host

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/host>

=head2 hostname

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hostname>

=head2 href

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href>

=head2 hreflang

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hreflang>

=head2 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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/origin>

=head2 password

Is a string containing the password specified before the domain name.

Example:

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

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

=head2 pathname

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/pathname>

=head2 port

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/port>

=head2 protocol

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/protocol>

=head2 referrerPolicy

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

A proper value is one of the following:

=over 4

=item no-referrer

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

=item 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).

=item origin

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

=item 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.

=item same-origin

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

=item 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).

=item 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).

=item 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.

=back

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 L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/referrerPolicy>

=head2 rel

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:

=over 4

=item L<alternate|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-alternate>

=item L<author|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-author>

=item L<bookmark|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-bookmark>

=item L<help|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-help>

=item L<license|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-license>

=item L<manifest|https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/manifest>

=item L<next|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-next>

=item L<prev|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-prev>

=item L<search|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-search>

=item L<tag|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-tag>

=back

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 C<noopener> value prevents the newly opened page from controlling the page that delivered the traffic. This is because, in the case of C<target> attribute set to C<_blank>, for example, the newly opened page can access the current window object with the C<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 C<noreferrer> value prevents the web browser from sending the referrer information to the target site. C<noreferrer> attribute has the same effect as C<noopener> and is well supported, but often both are used for when C<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 ) );
        }
    });

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/rel>, L<Mozilla documentation on rel|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel>, L<StackOverflow discussion|https://stackoverflow.com/questions/57628890/why-people-use-rel-noopener-noreferrer-instead-of-just-rel-noreferrer>

L<W3C specification|https://html.spec.whatwg.org/multipage/links.html#link-type-noreferrer>

=head2 relList

Read-only.

Returns a L<TokenList|HTML::Object::TokenList> that reflects the rel HTML attribute, as a list of link types indicating the relationship between the resource represented by the <a> element and the current document.

The property itself is read-only, meaning you can not substitute the L<TokenList|HTML::Object::TokenList> with another one, but its contents can still be changed.

Example:

    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] );
        }
    }

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/relList>

=head2 search

Is a string representing the search element, including leading question mark ('?'), if any, of the referenced URL.

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'

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/search>

=head2 tabIndex

Is a long containing the position of the element in the tabbing navigation order for the current document.

See L<HTML::Object::DOM::Element/tabIndex>

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/tabIndex>

=head2 target

Is a string that reflects the target HTML attribute, indicating where to display the linked resource.

Example:

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

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/target>

=head2 text

Is a string being a synonym for the L<HTML::Object::DOM::Node/textContent> property.

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/text>

=head2 type

Is a string that reflects the type HTML attribute, indicating the MIME type of the linked resource.

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/type>

=head2 username

Is a string containing the username specified before the domain name.

Example:

    # An <a id="myAnchor" href="https://anonymous:[e-mail]/some/where"> element is in the document
    my $anchor = $doc->getElementByID("myAnchor");
    $anchor->username; # returns 'anonymous'

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/username>

=head1 METHODS

Inherits methods from its parent L<HTML::Object::DOM::Element>

=head2 toString

Returns a string containing the whole URL. It is a synonym for HTMLAnchorElement.href, though it can't be used to modify the value.

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'

See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/toString>

=head1 AUTHOR

Jacques Deguest E<lt>F<[e-mail]>E<gt>

=head1 SEE ALSO

L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement>, L<Mozilla documentation on anchor element|https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a>

=head1 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.

=cut