File Coverage

lib/HTML/Object/DOM/Element/Form.pm
Criterion Covered Total %
statement 29 47 61.7
branch 2 4 50.0
condition n/a
subroutine 9 20 45.0
pod 11 11 100.0
total 51 82 62.2


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/Element/Form.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/23
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::Form;
15             BEGIN
16             {
17 3     3   2807 use strict;
  3         7  
  3         110  
18 3     3   25 use warnings;
  3         6  
  3         162  
19 3     3   26 use parent qw( HTML::Object::DOM::Element );
  3         6  
  3         26  
20 3     3   268 use vars qw( $VERSION );
  3         7  
  3         193  
21 3     3   583 use HTML::Object::DOM::Element::Shared qw( :form );
  3         17  
  3         689  
22 3     3   112 our $VERSION = 'v0.2.0';
23             };
24              
25 3     3   22 use strict;
  3         7  
  3         73  
26 3     3   50 use warnings;
  3         11  
  3         1641  
27              
28             sub init
29             {
30 2     2 1 166 my $self = shift( @_ );
31 2         265 $self->{checkValidity} = 1;
32 2         5 $self->{reportValidity} = 1;
33 2         4 $self->{_init_strict_use_sub} = 1;
34 2 50       20 $self->SUPER::init( @_ ) || return( $self->pass_error );
35 2 50       11 $self->{tag} = 'form' if( !CORE::length( "$self->{tag}" ) );
36 2         20 return( $self );
37             }
38              
39             # Note: property attribute
40 0     0 1   sub acceptCharset : lvalue { return( shift->_set_get_property( 'accept-charset', @_ ) ); }
41              
42             # Note: property attribute
43 0     0 1   sub action : lvalue { return( shift->_set_get_property( 'action', @_ ) ); }
44              
45             # Note: property accept inherited
46              
47             # Note: property autocapitalize inherited
48              
49             # Note: method checkValidity inherited
50              
51             # Note: property read-only
52             # Same as in HTML::Object::DOM::FieldSet
53             sub elements
54             {
55 0     0 1   my $self = shift( @_ );
56 0           my $children = $self->children;
57             # my $form_elements = $self->new_array( [qw( button datalist fieldset input label legend meter optgroup option output progress select textarea )] );
58             # <https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements#value>
59 0           my $form_elements = $self->new_array( [qw( button fieldset input object output select textarea )] );
60 0           my $list = $form_elements->as_hash;
61 0     0     my $results = $children->grep(sub{ exists( $form_elements->{ $_->tag } ) });
  0            
62 0           my $col = $self->new_collection;
63 0           $col->push( $results->list );
64 0           return( $col );
65             }
66              
67             # Note: property
68 0     0 1   sub encoding : lvalue { return( shift->_set_get_property( 'encoding', @_ ) ); }
69              
70             # Note: property
71 0     0 1   sub length : lvalue { return( shift->_set_get_property( 'length', @_ ) ); }
72              
73             # Note: property
74 0     0 1   sub method : lvalue { return( shift->_set_get_property( 'method', @_ ) ); }
75              
76             # Note: property name inherited
77              
78             # Note: property
79 0     0 1   sub noValidate : lvalue { return( shift->_set_get_property( { attribute => 'novalidate', is_boolean => 1 }, @_ ) ); }
80              
81 0     0 1   sub requestSubmit { return( shift->_set_get_object_without_init( 'requestSubmit', 'HTML::Object::DOM::Element', @_ ) ); }
82              
83             # Note: method reportValidity inherited
84              
85 0     0 1   sub submit { return; }
86              
87             # Note: property target
88 0     0 1   sub target : lvalue { return( shift->_set_get_property( { attribute => 'target', is_uri => 1 }, @_ ) ); }
89              
90             1;
91             # NOTE: POD
92             __END__
93              
94             =encoding utf-8
95              
96             =head1 NAME
97              
98             HTML::Object::DOM::Element::Form - HTML Object DOM Form Class
99              
100             =head1 SYNOPSIS
101              
102             use HTML::Object::DOM::Element::Form;
103             my $form = HTML::Object::DOM::Element::Form->new ||
104             die( HTML::Object::DOM::Element::Form->error, "\n" );
105              
106             =head1 VERSION
107              
108             v0.2.0
109              
110             =head1 DESCRIPTION
111              
112             This interface represents a <form> element in the DOM. It allows access to—and, in some cases, modification of—aspects of the form, as well as access to its component elements.
113              
114             =head1 INHERITANCE
115              
116             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +----------------------------------+
117             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Form |
118             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +----------------------------------+
119              
120             =head1 PROPERTIES
121              
122             Inherits properties from its parent L<HTML::Object::DOM::Element>
123              
124             =head2 acceptCharset
125              
126             A string reflecting the value of the form's accept-charset HTML attribute, representing the character encoding that the server accepts.
127              
128             Example:
129              
130             <form action="/some/where" accept-charset="utf-8">
131             <button>Ok</button>
132             </form>
133              
134             my $inputs = $doc->forms->[0]->acceptCharset; # utf-8
135              
136             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/acceptCharset>
137              
138             =head2 action
139              
140             A string reflecting the value of the form's action HTML attribute, containing the URI of a program that processes the information submitted by the form.
141              
142             Example:
143              
144             var $form = $doc->forms->[0];
145             $form->action = '/cgi-bin/publish';
146              
147             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/action>
148              
149             =head2 autocomplete
150              
151             A string (C<on> or C<off>) reflecting the value of the form's autocomplete HTML attribute, indicating whether the controls in this form can have their values automatically populated by the browser.
152              
153             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/autocomplete>
154              
155             =head2 elements
156              
157             Read-only.
158              
159             A L<collection object|HTML::Object::DOM::Collection> holding all L<form controls|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements> belonging to this form element.
160              
161             Example:
162              
163             <form id="my-form">
164             <input type="text" name="username">
165             <input type="text" name="full-name">
166             <input type="password" name="password">
167             </form>
168              
169             my $inputs = $doc->getElementById("my-form")->elements;
170             my $inputByIndex = $inputs->[0];
171             my $inputByName = $inputs->username;
172              
173             Another example:
174              
175             my $inputs = $doc->getElementById("my-form")->elements;
176              
177             # Iterate over the form controls
178             for( my $i = 0; $i < $inputs->length; $i++ )
179             {
180             if( $inputs->[i]->nodeName == "INPUT" && $inputs->[i]->type == "text" )
181             {
182             # Update text input
183             $inputs->[i]->value->toLocaleUpperCase();
184             }
185             }
186              
187             Another example:
188              
189             my $inputs = $doc->getElementById("my-form")->elements;
190              
191             # Iterate over the form controls
192             for( my $i = 0; $i < $inputs->length; $i++ )
193             {
194             # Disable all form controls
195             $inputs->[$i]->setAttribute( "disabled", "" );
196             }
197              
198             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements>, L<StackOverflow question|https://stackoverflow.com/questions/34785743/javascript-about-form-elements>
199              
200             =head2 encoding
201              
202             A string reflecting the value of the form's enctype HTML attribute, indicating the type of content that is used to transmit the form to the server. Only specified values can be set. The two properties are synonyms.
203              
204             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/encoding>
205              
206             =head2 length
207              
208             Read-only.
209              
210             A long reflecting the number of controls in the form.
211              
212             Example:
213              
214             if( $doc->getElementById('form1')->length > 1 )
215             {
216             # more than one form control here
217             }
218              
219             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/length>
220              
221             =head2 method
222              
223             A string reflecting the value of the form's method HTML attribute, indicating the HTTP method used to submit the form. Only specified values can be set.
224              
225             Example:
226              
227             $doc->forms->myform->method = 'post';
228              
229             my $formElement = $doc->createElement("form"); # Create a form
230             $doc->body->appendChild( $formElement );
231             say( $formElement->method ); # 'get'
232              
233             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/method>
234              
235             =head2 name
236              
237             A string reflecting the value of the form's name HTML attribute, containing the name of the form.
238              
239             Example:
240              
241             my $string = form->name;
242             form->name = $string;
243              
244             my $form1name = $doc->getElementById('form1').name;
245              
246             if ($form1name != $doc->form->form1) {
247             # Browser does not support this form of reference
248             }
249              
250             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/name>
251              
252             =head2 noValidate
253              
254             A boolean value reflecting the value of the form's novalidate HTML attribute, indicating whether the form should not be validated.
255              
256             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/noValidate>
257              
258             =head2 target
259              
260             A URL reflecting the value of the form's target HTML attribute, indicating where to display the results received from submitting the form.
261              
262             Example:
263              
264             $myForm->target = $doc->frames->[1]->name;
265              
266             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/target>
267              
268             =head1 METHODS
269              
270             Inherits methods from its parent L<HTML::Object::DOM::Element>
271              
272             =head2 checkValidity
273              
274             In perl, this always returns true, or whatever value you would have set.
275              
276             In JavaScript environment, this returns true if the element's child controls are subject to constraint validation and satisfy those constraints; returns false if some controls do not satisfy their constraints. Fires an event named invalid at any control that does not satisfy its constraints; such controls are considered invalid if the event is not canceled. It is up to the programmer to decide how to respond to false.
277              
278             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/checkValidity>
279              
280             =head2 reportValidity
281              
282             In perl, this always returns true, or whatever value you would have set.
283              
284             In JavaScript environment, this returns true if the element's child controls satisfy their validation constraints. When false is returned, cancelable invalid events are fired for each invalid child and validation problems are reported to the user.
285              
286             Example:
287              
288             $doc->forms->myform->addEventListener( submit => sub
289             {
290             $doc->forms->myform->reportValidity();
291             }, { capture => 0 });
292              
293             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/reportValidity>
294              
295             =head2 requestSubmit
296              
297             Requests that the form be submitted using the specified L<submit button|HTML::Object::DOM::Element> object and its corresponding configuration.
298              
299             Example:
300              
301             my $myForm = $doc->querySelector( 'form' );
302             my $submitButton = $myForm->querySelector( '#main-submit' );
303              
304             if( $myForm->requestSubmit )
305             {
306             if( $submitButton )
307             {
308             $myForm->requestSubmit( $submitButton );
309             }
310             else
311             {
312             $myForm->requestSubmit();
313             }
314             }
315             else
316             {
317             $myForm->submit();
318             }
319              
320             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit>
321              
322             =head2 submit
323              
324             This does nothing and returns C<undef> under perl environment.
325              
326             In JavaScript environment, this submits the form to the server.
327              
328             Example:
329              
330             $doc->forms->myform->submit();
331              
332             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit>
333              
334             =head1 AUTHOR
335              
336             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
337              
338             =head1 SEE ALSO
339              
340             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement>, L<Mozilla documentation on form element|https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form>
341              
342             =head1 COPYRIGHT & LICENSE
343              
344             Copyright(c) 2021 DEGUEST Pte. Ltd.
345              
346             All rights reserved
347              
348             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
349              
350             =cut