1HTML::Form(3)         User Contributed Perl Documentation        HTML::Form(3)
2
3
4

NAME

6       HTML::Form - Class that represents an HTML form element
7

SYNOPSIS

9        use HTML::Form;
10        $form = HTML::Form->parse($html, $base_uri);
11        $form->value(query => "Perl");
12
13        use LWP::UserAgent;
14        $ua = LWP::UserAgent->new;
15        $response = $ua->request($form->click);
16

DESCRIPTION

18       Objects of the "HTML::Form" class represents a single HTML "<form> ...
19       </form>" instance.  A form consists of a sequence of inputs that
20       usually have names, and which can take on various values.  The state of
21       a form can be tweaked and it can then be asked to provide
22       "HTTP::Request" objects that can be passed to the request() method of
23       "LWP::UserAgent".
24
25       The following methods are available:
26
27       @forms = HTML::Form->parse( $html_document, $base_uri )
28       @forms = HTML::Form->parse( $html_document, base => $base_uri, %opt )
29       @forms = HTML::Form->parse( $response, %opt )
30           The parse() class method will parse an HTML document and build up
31           "HTML::Form" objects for each <form> element found.  If called in
32           scalar context only returns the first <form>.  Returns an empty
33           list if there are no forms to be found.
34
35           The required arguments is the HTML document to parse
36           ($html_document) and the URI used to retrieve the document
37           ($base_uri).  The base URI is needed to resolve relative action
38           URIs.  The provided HTML document should be a Unicode string (or
39           US-ASCII).
40
41           By default HTML::Form assumes that the original document was UTF-8
42           encoded and thus encode forms that don't specify an explicit
43           accept-charset as UTF-8.  The charset assumed can be overridden by
44           providing the "charset" option to parse().  It's a good idea to be
45           explicit about this parameter as well, thus the recommended
46           simplest invocation becomes:
47
48               my @forms = HTML::Form->parse(
49                   Encode::decode($encoding, $html_document_bytes),
50                   base => $base_uri,
51                   charset => $encoding,
52               );
53
54           If the document was retrieved with LWP then the response object
55           provide methods to obtain a proper value for "base" and "charset":
56
57               my $ua = LWP::UserAgent->new;
58               my $response = $ua->get("http://www.example.com/form.html");
59               my @forms = HTML::Form->parse($response->decoded_content,
60                   base => $response->base,
61                   charset => $response->content_charset,
62               );
63
64           In fact, the parse() method can parse from an "HTTP::Response"
65           object directly, so the example above can be more conveniently
66           written as:
67
68               my $ua = LWP::UserAgent->new;
69               my $response = $ua->get("http://www.example.com/form.html");
70               my @forms = HTML::Form->parse($response);
71
72           Note that any object that implements a decoded_content(), base()
73           and content_charset() method with similar behaviour as
74           "HTTP::Response" will do.
75
76           Additional options might be passed in to control how the parse
77           method behaves.  The following are all the options currently
78           recognized:
79
80           "base => $uri"
81               This is the URI used to retrieve the original document.  This
82               option is not optional ;-)
83
84           "charset => $str"
85               Specify what charset the original document was encoded in.
86               This is used as the default for accept_charset.  If not
87               provided this defaults to "UTF-8".
88
89           "verbose => $bool"
90               Warn (print messages to STDERR) about any bad HTML form
91               constructs found.  You can trap these with $SIG{__WARN__}.  The
92               default is not to issue warnings.
93
94           "strict => $bool"
95               Initialize any form objects with the given strict attribute.
96               If the strict is turned on the methods that change values of
97               the form will croak if you try to set illegal values or modify
98               readonly fields.  The default is not to be strict.
99
100       $form->push_input( $type, \%attr, $verbose )
101           This method adds additional inputs to the form.  The first argument
102           is the type of input (e.g. hidden, option, etc.).  The second
103           argument is a reference to a hash of the input attributes.  The
104           third argument is optional, and will issue warnings about unknown
105           input types.
106
107           Example:
108
109               push_input( 'hidden', {
110                   name  => 'NewFormElement',
111                   id    => 'NewFormElementId',
112                   value => 'some value',
113               });
114
115       $method = $form->method
116       $form->method( $new_method )
117           This method is gets/sets the method name used for the
118           "HTTP::Request" generated.  It is a string like "GET" or "POST".
119
120       $action = $form->action
121       $form->action( $new_action )
122           This method gets/sets the URI which we want to apply the request
123           method to.
124
125       $enctype = $form->enctype
126       $form->enctype( $new_enctype )
127           This method gets/sets the encoding type for the form data.  It is a
128           string like "application/x-www-form-urlencoded" or
129           "multipart/form-data".
130
131       $accept = $form->accept_charset
132       $form->accept_charset( $new_accept )
133           This method gets/sets the list of charset encodings that the server
134           processing the form accepts. Current implementation supports only
135           one-element lists.  Default value is "UNKNOWN" which we interpret
136           as a request to use document charset as specified by the 'charset'
137           parameter of the parse() method.
138
139       $value = $form->attr( $name )
140       $form->attr( $name, $new_value )
141           This method give access to the original HTML attributes of the
142           <form> tag.  The $name should always be passed in lower case.
143
144           Example:
145
146              @f = HTML::Form->parse( $html, $foo );
147              @f = grep $_->attr("id") eq "foo", @f;
148              die "No form named 'foo' found" unless @f;
149              $foo = shift @f;
150
151       $bool = $form->strict
152       $form->strict( $bool )
153           Gets/sets the strict attribute of a form.  If the strict is turned
154           on the methods that change values of the form will croak if you try
155           to set illegal values or modify readonly fields.  The default is
156           not to be strict.
157
158       @inputs = $form->inputs
159           This method returns the list of inputs in the form.  If called in
160           scalar context it returns the number of inputs contained in the
161           form.  See "INPUTS" for what methods are available for the input
162           objects returned.
163
164       $input = $form->find_input( $selector )
165       $input = $form->find_input( $selector, $type )
166       $input = $form->find_input( $selector, $type, $index )
167           This method is used to locate specific inputs within the form.  All
168           inputs that match the arguments given are returned.  In scalar
169           context only the first is returned, or "undef" if none match.
170
171           If $selector is not "undef", then the input's name, id, class
172           attribute must match.  A selector prefixed with '#' must match the
173           id attribute of the input.  A selector prefixed with '.' matches
174           the class attribute.  A selector prefixed with '^' or with no
175           prefix matches the name attribute.
176
177           If $type is not "undef", then the input must have the specified
178           type.  The following type names are used: "text", "password",
179           "hidden", "textarea", "file", "image", "submit", "radio",
180           "checkbox" and "option".
181
182           The $index is the sequence number of the input matched where 1 is
183           the first.  If combined with $name and/or $type, then it selects
184           the nth input with the given name and/or type.
185
186       $value = $form->value( $selector )
187       $form->value( $selector, $new_value )
188           The value() method can be used to get/set the value of some input.
189           If strict is enabled and no input has the indicated name, then this
190           method will croak.
191
192           If multiple inputs have the same name, only the first one will be
193           affected.
194
195           The call:
196
197               $form->value('foo')
198
199           is basically a short-hand for:
200
201               $form->find_input('foo')->value;
202
203       @names = $form->param
204       @values = $form->param( $name )
205       $form->param( $name, $value, ... )
206       $form->param( $name, \@values )
207           Alternative interface to examining and setting the values of the
208           form.
209
210           If called without arguments then it returns the names of all the
211           inputs in the form.  The names will not repeat even if multiple
212           inputs have the same name.  In scalar context the number of
213           different names is returned.
214
215           If called with a single argument then it returns the value or
216           values of inputs with the given name.  If called in scalar context
217           only the first value is returned.  If no input exists with the
218           given name, then "undef" is returned.
219
220           If called with 2 or more arguments then it will set values of the
221           named inputs.  This form will croak if no inputs have the given
222           name or if any of the values provided does not fit.  Values can
223           also be provided as a reference to an array.  This form will allow
224           unsetting all values with the given name as well.
225
226           This interface resembles that of the param() function of the CGI
227           module.
228
229       $form->try_others( \&callback )
230           This method will iterate over all permutations of unvisited
231           enumerated values (<select>, <radio>, <checkbox>) and invoke the
232           callback for each.  The callback is passed the $form as argument.
233           The return value from the callback is ignored and the try_others()
234           method itself does not return anything.
235
236       $request = $form->make_request
237           Will return an "HTTP::Request" object that reflects the current
238           setting of the form.  You might want to use the click() method
239           instead.
240
241       $request = $form->click
242       $request = $form->click( $selector )
243       $request = $form->click( $x, $y )
244       $request = $form->click( $selector, $x, $y )
245           Will "click" on the first clickable input (which will be of type
246           "submit" or "image").  The result of clicking is an "HTTP::Request"
247           object that can then be passed to "LWP::UserAgent" if you want to
248           obtain the server response.
249
250           If a $selector is specified, we will click on the first clickable
251           input matching the selector, and the method will croak if no
252           matching clickable input is found.  If $selector is not specified,
253           then it is ok if the form contains no clickable inputs.  In this
254           case the click() method returns the same request as the
255           make_request() method would do.  See description of the
256           find_input() method above for how the $selector is specified.
257
258           If there are multiple clickable inputs with the same name, then
259           there is no way to get the click() method of the "HTML::Form" to
260           click on any but the first.  If you need this you would have to
261           locate the input with find_input() and invoke the click() method on
262           the given input yourself.
263
264           A click coordinate pair can also be provided, but this only makes a
265           difference if you clicked on an image.  The default coordinate is
266           (1,1).  The upper-left corner of the image is (0,0), but some badly
267           coded CGI scripts are known to not recognize this.  Therefore (1,1)
268           was selected as a safer default.
269
270       @kw = $form->form
271           Returns the current setting as a sequence of key/value pairs.  Note
272           that keys might be repeated, which means that some values might be
273           lost if the return values are assigned to a hash.
274
275           In scalar context this method returns the number of key/value pairs
276           generated.
277
278       $form->dump
279           Returns a textual representation of current state of the form.
280           Mainly useful for debugging.  If called in void context, then the
281           dump is printed on STDERR.
282

INPUTS

284       An "HTML::Form" objects contains a sequence of inputs.  References to
285       the inputs can be obtained with the $form->inputs or $form->find_input
286       methods.
287
288       Note that there is not a one-to-one correspondence between input
289       objects and <input> elements in the HTML document.  An input object
290       basically represents a name/value pair, so when multiple HTML elements
291       contribute to the same name/value pair in the submitted form they are
292       combined.
293
294       The input elements that are mapped one-to-one are "text", "textarea",
295       "password", "hidden", "file", "image", "submit" and "checkbox".  For
296       the "radio" and "option" inputs the story is not as simple: All <input
297       type="radio"> elements with the same name will contribute to the same
298       input radio object.  The number of radio input objects will be the same
299       as the number of distinct names used for the <input type="radio">
300       elements.  For a <select> element without the "multiple" attribute
301       there will be one input object of type of "option".  For a <select
302       multiple> element there will be one input object for each contained
303       <option> element.  Each one of these option objects will have the same
304       name.
305
306       The following methods are available for the input objects:
307
308       $input->type
309           Returns the type of this input.  The type is one of the following
310           strings: "text", "password", "hidden", "textarea", "file", "image",
311           "submit", "radio", "checkbox" or "option".
312
313       $name = $input->name
314       $input->name( $new_name )
315           This method can be used to get/set the current name of the input.
316
317       $input->id
318       $input->class
319           These methods can be used to get/set the current id or class
320           attribute for the input.
321
322       $input->selected( $selector )
323           Returns TRUE if the given selector matched the input.  See the
324           description of the find_input() method above for a description of
325           the selector syntax.
326
327       $value = $input->value
328       $input->value( $new_value )
329           This method can be used to get/set the current value of an input.
330
331           If strict is enabled and the input only can take an enumerated list
332           of values, then it is an error to try to set it to something else
333           and the method will croak if you try.
334
335           You will also be able to set the value of read-only inputs, but a
336           warning will be generated if running under "perl -w".
337
338       $autocomplete = $input->autocomplete
339       $input->autocomplete( $new_autocomplete )
340           This method can be used to get/set the current value (if any) of
341           "autcomplete" for the input.
342
343       $input->possible_values
344           Returns a list of all values that an input can take.  For inputs
345           that do not have discrete values, this returns an empty list.
346
347       $input->other_possible_values
348           Returns a list of all values not tried yet.
349
350       $input->value_names
351           For some inputs the values can have names that are different from
352           the values themselves.  The number of names returned by this method
353           will match the number of values reported by
354           $input->possible_values.
355
356           When setting values using the value() method it is also possible to
357           use the value names in place of the value itself.
358
359       $bool = $input->readonly
360       $input->readonly( $bool )
361           This method is used to get/set the value of the readonly attribute.
362           You are allowed to modify the value of readonly inputs, but setting
363           the value will generate some noise when warnings are enabled.
364           Hidden fields always start out readonly.
365
366       $bool = $input->disabled
367       $input->disabled( $bool )
368           This method is used to get/set the value of the disabled attribute.
369           Disabled inputs do not contribute any key/value pairs for the form
370           value.
371
372       $input->form_name_value
373           Returns a (possible empty) list of key/value pairs that should be
374           incorporated in the form value from this input.
375
376       $input->check
377           Some input types represent toggles that can be turned on/off.  This
378           includes "checkbox" and "option" inputs.  Calling this method turns
379           this input on without having to know the value name.  If the input
380           is already on, then nothing happens.
381
382           This has the same effect as:
383
384               $input->value($input->possible_values[1]);
385
386           The input can be turned off with:
387
388               $input->value(undef);
389
390       $input->click($form, $x, $y)
391           Some input types (currently "submit" buttons and "images") can be
392           clicked to submit the form.  The click() method returns the
393           corresponding "HTTP::Request" object.
394
395       If the input is of type "file", then it has these additional methods:
396
397       $input->file
398           This is just an alias for the value() method.  It sets the filename
399           to read data from.
400
401           For security reasons this field will never be initialized from the
402           parsing of a form.  This prevents the server from triggering
403           stealth uploads of arbitrary files from the client machine.
404
405       $filename = $input->filename
406       $input->filename( $new_filename )
407           This get/sets the filename reported to the server during file
408           upload.  This attribute defaults to the value reported by the
409           file() method.
410
411       $content = $input->content
412       $input->content( $new_content )
413           This get/sets the file content provided to the server during file
414           upload.  This method can be used if you do not want the content to
415           be read from an actual file.
416
417       @headers = $input->headers
418       input->headers($key => $value, .... )
419           This get/set additional header fields describing the file uploaded.
420           This can for instance be used to set the "Content-Type" reported
421           for the file.
422

SEE ALSO

424       LWP, LWP::UserAgent, HTML::Parser
425
427       Copyright 1998-2008 Gisle Aas.
428
429       This library is free software; you can redistribute it and/or modify it
430       under the same terms as Perl itself.
431
432
433
434perl v5.30.1                      2020-01-30                     HTML::Form(3)
Impressum