The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

HTML::Object::DOM::Element::Select - HTML Object DOM Select Class

SYNOPSIS

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

VERSION

    v0.2.0

DESCRIPTION

This interface represents a <select> HTML Element. These elements also share all of the properties and methods of other HTML elements via the HTML::Object::DOM::Element interface.

INHERITANCE

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

PROPERTIES

Inherits properties from its parent HTML::Object::DOM::Element

autofocus

A boolean value reflecting the autofocus HTML attribute, which indicates whether the control should have input focus when the page loads, unless the user overrides it, for example by typing in a different control. Only one form-associated element in a document can have this attribute specified.

Example:

    <select id="mySelect" autofocus>
        <option>Option 1</option>
        <option>Option 2</option>
    </select>

    # Check if the autofocus attribute on the <select>
    my $hasAutofocus = $doc->getElementById('mySelect')->autofocus;

See also Mozilla documentation

disabled

A boolean value reflecting the disabled HTML attribute, which indicates whether the control is disabled. If it is disabled, it does not accept clicks.

Example:

    <label>
        Allow drinks?
        <input id="allow-drinks" type="checkbox" />
    </label>

    <label for="drink-select">Drink selection:</label>
    <select id="drink-select" disabled>
        <option value="1">Water</option>
        <option value="2">Beer</option>
        <option value="3">Pepsi</option>
        <option value="4">Whisky</option>
    </select>

    my $allowDrinksCheckbox = $doc->getElementById( 'allow-drinks' );
    my $drinkSelect = $doc->getElementById( 'drink-select' );

    $allowDrinksCheckbox->addEventListener( change => sub
    {
        if( $event->target->checked )
        {
            $drinkSelect->disabled = 0; # false
        }
        else
        {
            $drinkSelect->disabled = 1; # true
        }
    }, { capture => 0});

See also Mozilla documentation

form

Read-only.

An HTML::Object::DOM::Element::Form referencing the form that this element is associated with. If the element is not associated with of a <form> element, then it returns undef.

Example:

    <form id="pet-form">
        <label for="pet-select">Choose a pet</label>
        <select name="pets" id="pet-select">
            <option value="dog">Dog</option>
            <option value="cat">Cat</option>
            <option value="parrot">Parrot</option>
        </select>

        <button type="submit">Submit</button>
    </form>

    <label for="lunch-select">Choose your lunch</label>
    <select name="lunch" id="lunch-select">
            <option value="salad">Salad</option>
            <option value="sandwich">Sandwich</option>
    </select>

    my $petSelect = $doc->getElementById( 'pet-select' );
    my $petForm = $petSelect->form; # <form id="pet-form">

    my $lunchSelect = $doc->getElementById( 'lunch-select' );
    my $lunchForm = $lunchSelect->form; # undef

See also Mozilla documentation

labels

Read-only.

A HTML::Object::DOM::NodeList of label elements associated with the element.

Example:

    <label id="label1" for="test">Label 1</label>
    <select id="test">
        <option value="1">Option 1</option>
        <option value="2">Option 2</option>
    </select>
    <label id="label2" for="test">Label 2</label>

    window->addEventListener( DOMContentLoaded => sub
    {
        my $select = $doc->getElementById( 'test' );
        for( my $i = 0; $i < $select->labels->length; $i++ )
        {
            say( $select->labels->[$i]->textContent ); # "Label 1" and "Label 2"
        }
    });

See also Mozilla documentation

length

An unsigned long that reflects the number of option elements in this select element.

See also Mozilla documentation

multiple

A boolean value reflecting the multiple HTML attribute, which indicates whether multiple items can be selected.

See also Mozilla documentation

name

A string reflecting the name HTML attribute, containing the name of this control used by servers and DOM search functions.

See also Mozilla documentation

options

Read-only.

An OptionsCollection representing the set of option elements contained by this element.

Example:

    <label for="test">Label</label>
    <select id="test">
        <option value="1">Option 1</option>
        <option value="2">Option 2</option>
    </select>

    window->addEventListener( DOMContentLoaded => sub
    {
        my $select = $doc->getElementById( 'test' );
        for( my $i = 0; $i < $select->options->length; $i++ )
        {
            say( $select->options->[$i]->label ); # "Option 1" and "Option 2"
        }
    });

See also Mozilla documentation

required

A boolean value reflecting the required HTML attribute, which indicates whether the user is required to select a value before submitting the form.

See also Mozilla documentation

selectedIndex

A long reflecting the index of the first selected option element. The value undef indicates no element is selected.

Example:

    <p id="p">selectedIndex: 0</p>
    <select id="select">
        <option selected>Option A</option>
        <option>Option B</option>
        <option>Option C</option>
        <option>Option D</option>
        <option>Option E</option>
    </select>

    my $selectElem = $doc->getElementById('select');
    my $pElem = $doc->getElementById('p');

    # When a new <option> is selected
    $selectElem->addEventListener( change => sub
    {
        my $index = $selectElem->selectedIndex;
        # Add that data to the <p>
        $pElem->innerHTML = 'selectedIndex: ' . $index;
    })

See also Mozilla documentation

selectedOptions

Read-only.

An Collection representing the set of option elements that are selected.

See also Mozilla documentation

size

A long reflecting the size HTML attribute, which contains the number of visible items in the control. The default is 1, unless multiple is true, in which case it is 4.

See also Mozilla documentation

type

Read-only.

A string represeting the form control's type. When multiple is true, it returns select-multiple; otherwise, it returns select-one.

See also Mozilla documentation

validationMessage

Read-only.

A string representing a localized message that describes the validation constraints that the control does not satisfy (if any). This attribute is the empty string if the control is not a candidate for constraint validation (willValidate is false), or it satisfies its constraints.

See also Mozilla documentation

validity

Read-only.

A ValidityState object reflecting the validity state that this control is in.

See also Mozilla documentation

value

A string reflecting the value of the form control. Returns the value property of the first selected option element if there is one, otherwise the empty string.

See also Mozilla documentation

willValidate

Read-only.

A boolean value that indicates whether the button is a candidate for constraint validation. It is false if any conditions bar it from constraint validation.

See also Mozilla documentation

METHODS

Inherits methods from its parent HTML::Object::DOM::Element

add

Provided with an item and optionally an position offset before which to insert the item and this adds an element to the collection of option elements for this select element.

item is an Option element or OptGroup element
before is optional and an element of the collection, or an index of type long, representing the item should be inserted before. If this parameter is undef (or the index does not exist), the new element is appended to the end of the collection.

Example:

    my $sel = $doc->createElement( 'select' );
    my $opt1 = $doc->createElement( 'option' );
    my $opt2 = $doc->createElement( 'option' );

    $opt1->value = 1;
    $opt1->text = "Option: Value 1";

    $opt2->value = 2;
    $opt2->text = "Option: Value 2";

    # No second argument; no 'before' argument
    $sel->add( $opt1, undef );
    # Equivalent to above
    $sel->add( $opt2 );

Produces the following, conceptually:

    <select>
        <option value="1">Option: Value 1</option>
        <option value="2">Option: Value 2</option>
    </select>

See also Mozilla documentation

blur

Under perl, of course, this does nothing.

Under JavaScript, this removes the input focus from this element. This method is now implemented on HTML::Object::DOM::Element.

See also Mozilla documentation

checkValidity

Checks whether the element has any constraints and whether it satisfies them. If the element fails its constraints, the browser fires a cancelable invalid event at the element (and returns false).

See also Mozilla documentation

focus

Under perl, of course, this does nothing.

Under JavaScript, this gives input focus to this element. This method is now implemented on HTML::Object::DOM::Element.

See also Mozilla documentation

item

Gets an item from the options collection for this select element by providing a zero-based index position.

Example:

    <select id="myFormControl">
        <option id="o1">Opt 1</option>
        <option id="o2">Opt 2</option>
    </select>

    # Returns the OptionElement representing #o2
    my $sel = $doc->getElementById( 'myFormControl' );
    my $elem1 = $sel->item(1); # Opt 2

See also Mozilla documentation

namedItem

Gets the item in the options collection with the specified name. The name string can match either the id or the name attribute of an option node.

Example:

    <select id="myFormControl">
        <option id="o1">Opt 1</option>
        <option id="o2">Opt 2</option>
    </select>

    my $elem1 = $doc->getElementById( 'myFormControl' )->namedItem( 'o1' ); # Returns the OptionElement representing #o1

This is, in effect, a shortcut for $select-options->namedItem>

See also Mozilla documentation

remove

Removes the element at the specified index (zero-based) from the options collection for this select element and return it.

Example:

    <select id="existingList" name="existingList">
        <option value="1">Option: Value 1</option>
        <option value="2">Option: Value 2</option>
        <option value="3">Option: Value 3</option>
    </select>

    my $sel = $doc->getElementById( 'existingList' );
    my $removed = $sel->remove(1);

HTML is now:

    <select id="existingList" name="existingList">
        <option value="1">Option: Value 1</option>
        <option value="3">Option: Value 3</option>
    </select>

See also Mozilla documentation

reportValidity

This method reports the problems with the constraints on the element, if any, to the user. If there are problems, it fires a cancelable invalid event at the element, and returns false; if there are no problems, it returns true.

See also Mozilla documentation

setCustomValidity

Sets the custom validity message for the selection element to the specified message. Use the empty string to indicate that the element does not have a custom validity error.

See also Mozilla documentation

EVENTS

Event listeners for those events can also be found by prepending on before the event type:

click event listeners can be set also with onclick method:

    $e->onclick(sub{ # do something });
    # or as an lvalue method
    $e->onclick = sub{ # do something };

Note that, under perl, almost no event are fired, but you can trigger them yourself.

change

Fires when the user selects an option, but since there is no user interaction, this event is fired when the selectedIndex value changes, which you can change yourself.

Example:

    <label>Choose an ice cream flavor:
        <select class="ice-cream" name="ice-cream">
            <option value="">Select One …</option>
            <option value="chocolate">Chocolate</option>
            <option value="sardine">Sardine</option>
            <option value="vanilla">Vanilla</option>
        </select>
    </label>

    <div class="result"></div>

    my $selectElement = $doc->querySelector('.ice-cream');

    $selectElement->addEventListener( change => sub
    {
        my $result = $doc->querySelector( '.$result' );
        $result->textContent = "You like " . $event->target->value;
    });

See also Mozilla documentation

input

Fires when the value of an <input>, <select>, or <textarea> element has been changed.

See also Mozilla documentation

reset

Reset the cache flag so that some data will be recomputed. The cache is design to avoid doing useless computing repeatedly when there is no change of data.

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

Mozilla documentation, Mozilla documentation on select element

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.