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


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/Element/Anchor.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/21
7             ## Modified 2022/09/18
8             ## All rights reserved
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTML::Object::DOM::Element::Anchor;
15             BEGIN
16             {
17 7     7   3147 use strict;
  7         19  
  7         207  
18 7     7   34 use warnings;
  7         17  
  7         194  
19 7     7   35 use parent qw( HTML::Object::DOM::Element );
  7         14  
  7         36  
20 7     7   466 use vars qw( $VERSION );
  7         21  
  7         331  
21 7     7   52 use HTML::Object;
  7         11  
  7         52  
22 7     7   937 use HTML::Object::DOM::Element::Shared qw( :anchor );
  7         25  
  7         1638  
23 7     7   167 our $VERSION = 'v0.2.0';
24             };
25              
26 7     7   44 use strict;
  7         15  
  7         176  
27 7     7   46 use warnings;
  7         15  
  7         1953  
28              
29             sub init
30             {
31 6     6 1 1328 my $self = shift( @_ );
32 6         349 $self->{_init_strict_use_sub} = 1;
33 6 50       48 $self->SUPER::init( @_ ) || return( $self->pass_error );
34 6 100       28 $self->{tag} = 'a' if( !$self->tag );
35 6         4078 $self->{uri} = '';
36             $self->_set_get_internal_attribute_callback( rel => sub
37             {
38 3     3   19 my( $this, $val ) = @_;
39 3         5 my $list;
40 3 100       12 return if( !( $list = $this->{_rel_list} ) );
41             # $list->debug( $self->debug );
42 2         11 $list->update( $val );
43 6         99 });
44 6         19 return( $self );
45             }
46              
47             # Note: property download inherited
48              
49             # Note: property hash inherited
50              
51             # Note: property host inherited
52              
53             # Note: property hostname inherited
54              
55             # Note: property href inherited
56              
57             # Note: property hreflang inherited
58              
59             # Note: read-only property origin inherited
60              
61             # Note: property password inherited
62              
63             # Note: property pathname inherited
64              
65             # Note: property port inherited
66              
67             # Note: property protocol inherited
68              
69             # Note: property referrerPolicy inherited
70              
71             # Note: property rel inherited
72              
73             # Note: property read-only relList inherited. Similar to HTML::Object::DOM::Element->classList
74              
75             # Note: property search inherited
76              
77             # Note: tabIndex is inherited from HTML::Object::DOM::Element
78              
79             # Note: property target inherited
80              
81             # Note: alias for textContent in HTML::Object::DOM::Node
82             # Note: property
83 2     2 1 852 sub text : lvalue { return( shift->textContent( @_ ) ); }
84              
85 1     1 1 1188 sub toString { return( shift->attr( 'href' ) ); }
86              
87             # Note: property
88 2     2 1 1508 sub type : lvalue { return( shift->_set_get_property( 'type', @_ ) ); }
89              
90             # Note: property username inherited
91              
92             1;
93             # NOTE: POD
94             __END__
95              
96             =encoding utf-8
97              
98             =head1 NAME
99              
100             HTML::Object::DOM::Element::Anchor - HTML Object DOM Link Class
101              
102             =head1 SYNOPSIS
103              
104             use HTML::Object::DOM::Element::Anchor;
105             my $link = HTML::Object::DOM::Element::Anchor->new ||
106             die( HTML::Object::DOM::Element::Anchor->error, "\n" );
107              
108             =head1 VERSION
109              
110             v0.2.0
111              
112             =head1 DESCRIPTION
113              
114             This implements an HTML link element. It inherits from L<HTML::Object::DOM::Element>
115              
116             =head1 INHERITANCE
117              
118             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +------------------------------------+
119             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Anchor |
120             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +------------------------------------+
121              
122             =head1 PROPERTIES
123              
124             This class inherits properties from its parent, L<HTML::Object::DOM::Element>.
125              
126             =head2 download
127              
128             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.
129              
130             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.
131              
132             Example:
133              
134             <a id="myAnchor" href="/some/where#nice">Nice spot</a>
135              
136             my $anchor = $doc->getElementById("myAnchor");
137             $anchor->download = 'my_file.txt';
138             # link is now:
139             # <a id="myAnchor" href="/some/where#nice" download="nice_file.txt">Nice spot</a>
140              
141             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/download>
142              
143             =head2 hash
144              
145             Is a string representing the fragment identifier, including the leading hash mark ('#'), if any, in the referenced URL.
146              
147             Example:
148              
149             <a id="myAnchor" href="/some/where#nice">Examples</a>
150              
151             my $anchor = $doc->getElementById("myAnchor");
152             $anchor->hash; # returns '#nice'
153              
154             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hash>
155              
156             =head2 host
157              
158             Is a string representing the hostname and port (if it's not the default port) in the referenced URL.
159              
160             Example:
161              
162             my $anchor = $document->createElement("a");
163              
164             $anchor->href = "https://example.org/some/where"
165             $anchor->host = "example.org"
166              
167             $anchor->href = "https://example.org:443/some/where"
168             $anchor->host = "example.org"
169             # The port number is not included because 443 is the scheme's default port
170              
171             $anchor->href = "https://example.org:4097/some/where"
172             $anchor->host = "example.org:4097"
173              
174             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/host>
175              
176             =head2 hostname
177              
178             Is a string representing the hostname in the referenced URL.
179              
180             Example:
181              
182             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
183             my $anchor = $doc->getElementById("myAnchor");
184             $anchor->hostname; # returns 'example.org'
185              
186             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hostname>
187              
188             =head2 href
189              
190             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.
191              
192             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
193             my $anchor = $doc->getElementById("myAnchor");
194             $anchor->href; # returns 'https://example.org/some/where'
195              
196             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/href>
197              
198             =head2 hreflang
199              
200             Is a string that reflects the hreflang HTML attribute, indicating the language of the linked resource.
201              
202             Example:
203              
204             <a href="https://example.org/ja-jp/some/where" hreflang="ja">マニュアル</a>
205             var lang = document.getElementById("myAnchor").hreflang; # ja
206              
207             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hreflang>
208              
209             =head2 origin
210              
211             Read-only.
212              
213             Returns a string containing the origin of the URL, that is its scheme, its domain and its port.
214              
215             Example:
216              
217             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
218             my $anchor = $doc->getElementById("myAnchor");
219             $anchor->origin; # returns 'https://example.org'
220              
221             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/origin>
222              
223             =head2 password
224              
225             Is a string containing the password specified before the domain name.
226              
227             Example:
228              
229             # An <a id="myAnchor" href="https://anonymous:flabada@example.org/some/where"> is in the document
230             my $anchor = $doc->getElementByID("myAnchor");
231             $anchor->password; # returns 'flabada'
232              
233             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/password>
234              
235             =head2 pathname
236              
237             Is a string containing an initial '/' followed by the path of the URL, not including the query string or fragment.
238              
239             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
240             my $anchor = $doc->getElementById("myAnchor");
241             $anchor->pathname; # returns '/some/where'
242              
243             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/pathname>
244              
245             =head2 port
246              
247             Is a string representing the port component, if any, of the referenced URL.
248              
249             # An <a id="myAnchor" href="https://example.org:443/some/where"> element is in the document
250             my $anchor = $doc->getElementByID("myAnchor");
251             $anchor->port; # returns '443'
252              
253             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/port>
254              
255             =head2 protocol
256              
257             Is a string representing the protocol component, including trailing colon (':'), of the referenced URL.
258              
259             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
260             my $anchor = $doc->getElementById("myAnchor");
261             $anchor->protocol; # returns 'https:'
262              
263             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/protocol>
264              
265             =head2 referrerPolicy
266              
267             Is a string that reflects the referrerpolicy HTML attribute indicating which referrer to use.
268              
269             A proper value is one of the following:
270              
271             =over 4
272              
273             =item no-referrer
274              
275             The Referer header will be omitted entirely. No referrer information is sent along with requests.
276              
277             =item no-referrer-when-downgrade
278              
279             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).
280              
281             =item origin
282              
283             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/>.
284              
285             =item origin-when-cross-origin
286              
287             Send a full URL when performing a same-origin request, but only send the origin of the document for other cases.
288              
289             =item same-origin
290              
291             A referrer will be sent for same-site origins, but cross-origin requests will contain no referrer information.
292              
293             =item strict-origin
294              
295             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).
296              
297             =item strict-origin-when-cross-origin (default)
298              
299             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).
300              
301             =item unsafe-url
302              
303             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.
304              
305             =back
306              
307             Example:
308              
309             my $elt = $doc->createElement("a");
310             my $linkText = $doc->createTextNode("My link");
311             $elt->appendChild( $linkText );
312             $elt->href = "https://example.org/ja-jp/";
313             $elt->referrerPolicy = "no-referrer";
314              
315             my $div = $doc->getElementById("divAround");
316             $div->appendChild( $elt ); # When clicked, the link will not send a referrer header.
317              
318             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/referrerPolicy>
319              
320             =head2 rel
321              
322             Is a string that reflects the rel HTML attribute, specifying the relationship of the target object to the linked object.
323              
324             You can set whatever value you want, but standard values are:
325              
326             =over 4
327              
328             =item L<alternate|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-alternate>
329              
330             =item L<author|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-author>
331              
332             =item L<bookmark|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-bookmark>
333              
334             =item L<help|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-help>
335              
336             =item L<license|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-license>
337              
338             =item L<manifest|https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/manifest>
339              
340             =item L<next|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-next>
341              
342             =item L<prev|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-prev>
343              
344             =item L<search|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-search>
345              
346             =item L<tag|https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel#attr-tag>
347              
348             =back
349              
350             Example:
351              
352             my $anchors = $doc->getElementsByTagName("a");
353             my $length = $anchors->length;
354             for( my $i = 0; $i < $length; $i++ )
355             {
356             say( "Rel: " + anchors->[$i]->rel );
357             }
358              
359             could print:
360              
361             Re;: noopener noreferrer
362              
363             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.
364              
365             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.
366              
367             To mitigate this issue, you could do:
368              
369             # Replace 'example.org' by whatever your safe domain name is
370             $doc->getElementsByTagName( 'a' )->foreach(sub
371             {
372             if( $_->href->host ne 'example.org' &&
373             $_->hasAttribute( 'target' ) &&
374             $_->getAttribute( 'target' ) eq '_blank' )
375             {
376             $_->relList->add( qw( noopener noreferrer ) );
377             }
378             });
379              
380             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>
381              
382             L<W3C specification|https://html.spec.whatwg.org/multipage/links.html#link-type-noreferrer>
383              
384             =head2 relList
385              
386             Read-only.
387              
388             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.
389              
390             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.
391              
392             Example:
393              
394             my $anchors = $doc->getElementsByTagName("a");
395             my $length = $anchors->length;
396             for( my $i = 0; $i < $length; $i++ )
397             {
398             my $list = $anchors->[$i]->relList;
399             my $listLength = $list->length;
400             say( "New anchor node found with", $listLength, "link types in relList." );
401             for( my $j = 0; $j < $listLength; $j++ )
402             {
403             say( $list->[$j] );
404             }
405             }
406              
407             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/relList>
408              
409             =head2 search
410              
411             Is a string representing the search element, including leading question mark ('?'), if any, of the referenced URL.
412              
413             Example:
414              
415             # An <a id="myAnchor" href="/some/where?q=123"> element is in the document
416             my $anchor = $doc->getElementById("myAnchor");
417             $anchor->search; # returns '?q=123'
418              
419             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/search>
420              
421             =head2 tabIndex
422              
423             Is a long containing the position of the element in the tabbing navigation order for the current document.
424              
425             See L<HTML::Object::DOM::Element/tabIndex>
426              
427             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/tabIndex>
428              
429             =head2 target
430              
431             Is a string that reflects the target HTML attribute, indicating where to display the linked resource.
432              
433             Example:
434              
435             $doc->getElementById("myAnchor")->target = "_blank";
436              
437             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/target>
438              
439             =head2 text
440              
441             Is a string being a synonym for the L<HTML::Object::DOM::Node/textContent> property.
442              
443             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/text>
444              
445             =head2 type
446              
447             Is a string that reflects the type HTML attribute, indicating the MIME type of the linked resource.
448              
449             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/type>
450              
451             =head2 username
452              
453             Is a string containing the username specified before the domain name.
454              
455             Example:
456              
457             # An <a id="myAnchor" href="https://anonymous:flabada@example.org/some/where"> element is in the document
458             my $anchor = $doc->getElementByID("myAnchor");
459             $anchor->username; # returns 'anonymous'
460              
461             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/username>
462              
463             =head1 METHODS
464              
465             Inherits methods from its parent L<HTML::Object::DOM::Element>
466              
467             =head2 toString
468              
469             Returns a string containing the whole URL. It is a synonym for HTMLAnchorElement.href, though it can't be used to modify the value.
470              
471             Example:
472              
473             # An <a id="myAnchor" href="https://example.org/some/where"> element is in the document
474             my $anchor = $doc->getElementById("myAnchor");
475             $anchor->toString(); # returns 'https://example.org/some/where'
476              
477             See L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/toString>
478              
479             =head1 AUTHOR
480              
481             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
482              
483             =head1 SEE ALSO
484              
485             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>
486              
487             =head1 COPYRIGHT & LICENSE
488              
489             Copyright(c) 2021 DEGUEST Pte. Ltd.
490              
491             All rights reserved
492              
493             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
494              
495             =cut