NAME

HTML::Object::TokenList - HTML Object Token List Class

SYNOPSIS

    use HTML::Object::TokenList;
    # standalone, i.e. without connection to an element
    my $list = HTML::Object::TokenList->new( 'some class to edit' ) || 
        die( HTML::Object::TokenList->error, "\n" );

Or

    use HTML::Object::Element;
    my $e = HTML::Object::Element->new( tag => 'div' );
    my $list = $e->classList;

    $list->add( 'another-class' );
    $list->remove( 'edit' );
    $list->length;
    $list->value;
    $list->as_string;
    $list->contains( 'some' );
    $list->forEach(sub
    {
        my $c = shift( @_ ); # also available as $_
        # do something
    });
    $list->item(3); # 'edit'
    $list->replace( 'to' = 'other' );
    $list->toggle( 'visible' ); # activate it
    $list->toggle( 'visible' ); # now remove it

VERSION

    v0.2.0

DESCRIPTION

The TokenList interface represents a set of space-separated tokens. Such a set is returned by "classList" in HTML::Object::DOM::Element or "relList" in HTML::Object::DOM::AnchorElement.

A TokenList is indexed beginning with 0 as with perl array. TokenList is always case-sensitive.

This module can be used independently or be instantiated by an element, and in which case, any modification made will be reflected in the associated element's attribute.

PROPERTIES

length

Read-only. This returns an integer representing the number of objects stored in the object.

value

A stringifier property that returns the value of the list as a string. See also "as_string"

METHODS

add

Adds the specified tokens to the list. Returns the current object for chaining.

The tokens can be provided either as a list of string, an array reference of strings, or a space-delimited string of tokens.

as_string

A stringifier property that returns the value of the list as a string. See also "value"

attribute

Set or get the element attribute to which TokenList is bound. For example a class attribute or a rel attribute

This is optional if you want to use this class independently from any element, or if you want to set the element later.

contains

Returns true if the list contains the given token, otherwise false.

element

Set or get the element

This is optional if you want to use this class independently from any element, or if you want to set the element later.

entries

This does nothing.

Normally, under JavaScript, this would return an iterator, allowing you to go through all key/value pairs contained in this object.

forEach

Executes a provided callback function once for each DOMTokenList element.

item

Returns the item in the list by its index, or undefined if the index is greater than or equal to the list's length.

items

Sets or gets the list of token items. It returns the array object containing all the tokens.

keys

This does nothing.

Normally, under JavaScript, this would return an iterator, allowing you to go through all keys of the key/value pairs contained in this object.

remove

Removes the specified tokens from the list.

replace

Replaces the token with another one.

It returns a boolean value, which is true if the old entry was successfully replaced, or false if not.

See the Mozilla documentation for more information.

reset

Reset the tokens list to an empty list and, of course, propagate that change to the associated element's attribute, if any was set.

Returns the current object.

supports

Returns true if the given token is in the associated attribute's supported tokens.

For the purpose of the perl environment, this actually always returns true.

toggle

Removes the token from the list if it exists, or adds it to the list if it does not. Returns a boolean indicating whether the token is in the list after the operation.

tokens

Sets or get the array object of tokens.

update

This method is called by an internal callback in HTML::Object::Element when the value of an registered attribute has been changed. It does not propagate the change back to the element since it is triggered by the element itself.

If undef is provided as its sole argument, this will empty the tokens list, otherwise it will set the new tokens list with a space-delimited string of tokens, a list or array reference of tokens.

Returns the current object.

values

This does nothing.

Normally, under JavaScript, this would return an iterator, allowing you to go through all values of the key/value pairs contained in this object.

EXAMPLES

In the following simple example, we retrieve the list of classes set on a <p> element as a HTML::Object::TokenList using "classList" in HTML::Object::Element, add a class using "add" in HTML::Object::TokenList, and then update the textContent of the <p> to equal the HTML::Object::TokenList.

    <p class="a b c"></p>

    my $para = $doc->querySelector("p");
    my $classes = $para->classList;
    $para->classList->add("d");
    $para->textContent = qq{paragraph classList is "${classes}"};

would yield:

    paragraph classList is "a b c d"

WHITESPACE AND DUPLICATES

Methods that modify the TokenList (such as "add" in HTML::Object::TokenList) automatically trim any excess whitespace and remove duplicate values from the list. For example:

    <span class="    d   d e f"></span>

    my $span = $doc->querySelector("span");
    my $classes = $span->classList;
    $span->classList->add("x");
    $span->textContent = qq{span classList is "${classes}"};

would yield:

    span classList is "d e f x"

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

HTML::Object::Element

Mozilla 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.

cpanm HTML::Object

perl -MCPAN -e shell
install HTML::Object