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.0DESCRIPTION
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; # undefSee 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.
itemis an Option element or OptGroup elementbeforeis optional and an element of the collection, or an index of type long, representing the item should be inserted before. If this parameter isundef(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 2See 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 #o1This 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.