1HTML::Form(3) User Contributed Perl Documentation HTML::Form(3)
2
6 HTML::Form - Class that represents an HTML form element
7
9 version 6.10
10
12 use HTML::Form;
13 $form = HTML::Form->parse($html, $base_uri);
14 $form->value(query => "Perl");
15 use LWP::UserAgent;
17 $ua = LWP::UserAgent->new;
18 $response = $ua->request($form->click);
19
21 Objects of the "HTML::Form" class represents a single HTML "<form> ...
22 </form>" instance. A form consists of a sequence of inputs that
23 usually have names, and which can take on various values. The state of
24 a form can be tweaked and it can then be asked to provide HTTP::Request
25 objects that can be passed to the request() method of LWP::UserAgent.
26 The following methods are available:
28 @forms = HTML::Form->parse( $html_document, $base_uri )
30 @forms = HTML::Form->parse( $html_document, base => $base_uri, %opt )
31 @forms = HTML::Form->parse( $response, %opt )
32 The parse() class method will parse an HTML document and build up
33 "HTML::Form" objects for each <form> element found. If called in
34 scalar context only returns the first <form>. Returns an empty
35 list if there are no forms to be found.
36 The required arguments is the HTML document to parse
38 ($html_document) and the URI used to retrieve the document
39 ($base_uri). The base URI is needed to resolve relative action
40 URIs. The provided HTML document should be a Unicode string (or
41 US-ASCII).
42 By default HTML::Form assumes that the original document was UTF-8
44 encoded and thus encode forms that don't specify an explicit
45 accept-charset as UTF-8. The charset assumed can be overridden by
46 providing the "charset" option to parse(). It's a good idea to be
47 explicit about this parameter as well, thus the recommended
48 simplest invocation becomes:
49 my @forms = HTML::Form->parse(
51 Encode::decode($encoding, $html_document_bytes),
52 base => $base_uri,
53 charset => $encoding,
54 );
55 If the document was retrieved with LWP then the response object
57 provide methods to obtain a proper value for "base" and "charset":
58 my $ua = LWP::UserAgent->new;
60 my $response = $ua->get("http://www.example.com/form.html");
61 my @forms = HTML::Form->parse($response->decoded_content,
62 base => $response->base,
63 charset => $response->content_charset,
64 );
65 In fact, the parse() method can parse from an HTTP::Response object
67 directly, so the example above can be more conveniently written as:
68 my $ua = LWP::UserAgent->new;
70 my $response = $ua->get("http://www.example.com/form.html");
71 my @forms = HTML::Form->parse($response);
72 Note that any object that implements a decoded_content(), base()
74 and content_charset() method with similar behaviour as
75 HTTP::Response will do.
76 Additional options might be passed in to control how the parse
78 method behaves. The following are all the options currently
79 recognized:
80 "base => $uri"
82 This is the URI used to retrieve the original document. This
83 option is not optional ;-)
84 "charset => $str"
86 Specify what charset the original document was encoded in.
87 This is used as the default for accept_charset. If not
88 provided this defaults to "UTF-8".
89 "verbose => $bool"
91 Warn (print messages to STDERR) about any bad HTML form
92 constructs found. You can trap these with $SIG{__WARN__}. The
93 default is not to issue warnings.
94 "strict => $bool"
96 Initialize any form objects with the given strict attribute.
97 If the strict is turned on the methods that change values of
98 the form will croak if you try to set illegal values or modify
99 readonly fields. The default is not to be strict.
100 $form->push_input( $type, \%attr, $verbose )
102 This method adds additional inputs to the form. The first argument
103 is the type of input (e.g. hidden, option, etc.). The second
104 argument is a reference to a hash of the input attributes. The
105 third argument is optional, and will issue warnings about unknown
106 input types.
107 Example:
109 push_input( 'hidden', {
111 name => 'NewFormElement',
112 id => 'NewFormElementId',
113 value => 'some value',
114 });
115 $method = $form->method
117 $form->method( $new_method )
118 This method is gets/sets the method name used for the HTTP::Request
119 generated. It is a string like "GET" or "POST".
120 $action = $form->action
122 $form->action( $new_action )
123 This method gets/sets the URI which we want to apply the request
124 method to.
125 $enctype = $form->enctype
127 $form->enctype( $new_enctype )
128 This method gets/sets the encoding type for the form data. It is a
129 string like "application/x-www-form-urlencoded" or
130 "multipart/form-data".
131 $accept = $form->accept_charset
133 $form->accept_charset( $new_accept )
134 This method gets/sets the list of charset encodings that the server
135 processing the form accepts. Current implementation supports only
136 one-element lists. Default value is "UNKNOWN" which we interpret
137 as a request to use document charset as specified by the 'charset'
138 parameter of the parse() method.
139 $value = $form->attr( $name )
141 $form->attr( $name, $new_value )
142 This method give access to the original HTML attributes of the
143 <form> tag. The $name should always be passed in lower case.
144 Example:
146 @f = HTML::Form->parse( $html, $foo );
148 @f = grep $_->attr("id") eq "foo", @f;
149 die "No form named 'foo' found" unless @f;
150 $foo = shift @f;
151 $bool = $form->strict
153 $form->strict( $bool )
154 Gets/sets the strict attribute of a form. If the strict is turned
155 on the methods that change values of the form will croak if you try
156 to set illegal values or modify readonly fields. The default is
157 not to be strict.
158 @inputs = $form->inputs
160 This method returns the list of inputs in the form. If called in
161 scalar context it returns the number of inputs contained in the
162 form. See "INPUTS" for what methods are available for the input
163 objects returned.
164 $input = $form->find_input( $selector )
166 $input = $form->find_input( $selector, $type )
167 $input = $form->find_input( $selector, $type, $index )
168 @inputs = $form->find_input( $selector )
169 @inputs = $form->find_input( $selector, $type )
170 This method is used to locate specific inputs within the form. All
171 inputs that match the arguments given are returned. In scalar
172 context only the first is returned, or "undef" if none match.
173 If $selector is not "undef", then the input's name, id or class
175 attribute must match. A selector prefixed with '#' must match the
176 id attribute of the input. A selector prefixed with '.' matches
177 the class attribute. A selector prefixed with '^' or with no prefix
178 matches the name attribute.
179 my @by_id = $form->find_input( '#some-id' );
181 my @by_class = $form->find_input( '.some-class' );
182 my @by_name = $form->find_input( '^some-name' );
183 my @also_by_name = $form->find_input( 'some-name' );
184 If you want to find an input that has no name at all, pass in a
186 reference to "undef".
187 my @nameless_inputs = $form->find_input( \undef );
189 If $type is not "undef", then the input must have the specified
191 type. The following type names are used: "text", "password",
192 "hidden", "textarea", "file", "image", "submit", "radio",
193 "checkbox" and "option".
194 The $index is the sequence number of the input matched where 1 is
196 the first. If combined with $selector and/or $type, then it
197 selects the nth input with the given name and/or type.
198 $value = $form->value( $selector )
200 $form->value( $selector, $new_value )
201 The value() method can be used to get/set the value of some input.
202 If strict is enabled and no input has the indicated name, then this
203 method will croak.
204 If multiple inputs have the same name, only the first one will be
206 affected.
207 The call:
209 $form->value('foo')
211 is basically a short-hand for:
213 $form->find_input('foo')->value;
215 @names = $form->param
217 @values = $form->param( $name )
218 $form->param( $name, $value, ... )
219 $form->param( $name, \@values )
220 Alternative interface to examining and setting the values of the
221 form.
222 If called without arguments then it returns the names of all the
224 inputs in the form. The names will not repeat even if multiple
225 inputs have the same name. In scalar context the number of
226 different names is returned.
227 If called with a single argument then it returns the value or
229 values of inputs with the given name. If called in scalar context
230 only the first value is returned. If no input exists with the
231 given name, then "undef" is returned.
232 If called with 2 or more arguments then it will set values of the
234 named inputs. This form will croak if no inputs have the given
235 name or if any of the values provided does not fit. Values can
236 also be provided as a reference to an array. This form will allow
237 unsetting all values with the given name as well.
238 This interface resembles that of the param() function of the CGI
240 module.
241 $form->try_others( \&callback )
243 This method will iterate over all permutations of unvisited
244 enumerated values (<select>, <radio>, <checkbox>) and invoke the
245 callback for each. The callback is passed the $form as argument.
246 The return value from the callback is ignored and the try_others()
247 method itself does not return anything.
248 $request = $form->make_request
250 Will return an HTTP::Request object that reflects the current
251 setting of the form. You might want to use the click() method
252 instead.
253 $request = $form->click
255 $request = $form->click( $selector )
256 $request = $form->click( $x, $y )
257 $request = $form->click( $selector, $x, $y )
258 Will "click" on the first clickable input (which will be of type
259 "submit" or "image"). The result of clicking is an HTTP::Request
260 object that can then be passed to LWP::UserAgent if you want to
261 obtain the server response.
262 If a $selector is specified, we will click on the first clickable
264 input matching the selector, and the method will croak if no
265 matching clickable input is found. If $selector is not specified,
266 then it is ok if the form contains no clickable inputs. In this
267 case the click() method returns the same request as the
268 make_request() method would do. See description of the
269 find_input() method above for how the $selector is specified.
270 If there are multiple clickable inputs with the same name, then
272 there is no way to get the click() method of the "HTML::Form" to
273 click on any but the first. If you need this you would have to
274 locate the input with find_input() and invoke the click() method on
275 the given input yourself.
276 A click coordinate pair can also be provided, but this only makes a
278 difference if you clicked on an image. The default coordinate is
279 (1,1). The upper-left corner of the image is (0,0), but some badly
280 coded CGI scripts are known to not recognize this. Therefore (1,1)
281 was selected as a safer default.
282 @kw = $form->form
284 Returns the current setting as a sequence of key/value pairs. Note
285 that keys might be repeated, which means that some values might be
286 lost if the return values are assigned to a hash.
287 In scalar context this method returns the number of key/value pairs
289 generated.
290 $form->dump
292 Returns a textual representation of current state of the form.
293 Mainly useful for debugging. If called in void context, then the
294 dump is printed on STDERR.
295
297 An "HTML::Form" objects contains a sequence of inputs. References to
298 the inputs can be obtained with the $form->inputs or $form->find_input
299 methods.
300 Note that there is not a one-to-one correspondence between input
302 objects and <input> elements in the HTML document. An input object
303 basically represents a name/value pair, so when multiple HTML elements
304 contribute to the same name/value pair in the submitted form they are
305 combined.
306 The input elements that are mapped one-to-one are "text", "textarea",
308 "password", "hidden", "file", "image", "submit" and "checkbox". For
309 the "radio" and "option" inputs the story is not as simple: All <input
310 type="radio"> elements with the same name will contribute to the same
311 input radio object. The number of radio input objects will be the same
312 as the number of distinct names used for the <input type="radio">
313 elements. For a <select> element without the "multiple" attribute
314 there will be one input object of type of "option". For a <select
315 multiple> element there will be one input object for each contained
316 <option> element. Each one of these option objects will have the same
317 name.
318 The following methods are available for the input objects:
320 $input->type
322 Returns the type of this input. The type is one of the following
323 strings: "text", "password", "hidden", "textarea", "file", "image",
324 "submit", "radio", "checkbox" or "option".
325 $name = $input->name
327 $input->name( $new_name )
328 This method can be used to get/set the current name of the input.
329 $input->id
331 $input->class
332 These methods can be used to get/set the current id or class
333 attribute for the input.
334 $input->selected( $selector )
336 Returns TRUE if the given selector matched the input. See the
337 description of the find_input() method above for a description of
338 the selector syntax.
339 $value = $input->value
341 $input->value( $new_value )
342 This method can be used to get/set the current value of an input.
343 If strict is enabled and the input only can take an enumerated list
345 of values, then it is an error to try to set it to something else
346 and the method will croak if you try.
347 You will also be able to set the value of read-only inputs, but a
349 warning will be generated if running under "perl -w".
350 $autocomplete = $input->autocomplete
352 $input->autocomplete( $new_autocomplete )
353 This method can be used to get/set the current value (if any) of
354 "autcomplete" for the input.
355 $input->possible_values
357 Returns a list of all values that an input can take. For inputs
358 that do not have discrete values, this returns an empty list.
359 $input->other_possible_values
361 Returns a list of all values not tried yet.
362 $input->value_names
364 For some inputs the values can have names that are different from
365 the values themselves. The number of names returned by this method
366 will match the number of values reported by
367 $input->possible_values.
368 When setting values using the value() method it is also possible to
370 use the value names in place of the value itself.
371 $bool = $input->readonly
373 $input->readonly( $bool )
374 This method is used to get/set the value of the readonly attribute.
375 You are allowed to modify the value of readonly inputs, but setting
376 the value will generate some noise when warnings are enabled.
377 Hidden fields always start out readonly.
378 $bool = $input->disabled
380 $input->disabled( $bool )
381 This method is used to get/set the value of the disabled attribute.
382 Disabled inputs do not contribute any key/value pairs for the form
383 value.
384 $input->form_name_value
386 Returns a (possible empty) list of key/value pairs that should be
387 incorporated in the form value from this input.
388 $input->check
390 Some input types represent toggles that can be turned on/off. This
391 includes "checkbox" and "option" inputs. Calling this method turns
392 this input on without having to know the value name. If the input
393 is already on, then nothing happens.
394 This has the same effect as:
396 $input->value($input->possible_values[1]);
398 The input can be turned off with:
400 $input->value(undef);
402 $input->click($form, $x, $y)
404 Some input types (currently "submit" buttons and "images") can be
405 clicked to submit the form. The click() method returns the
406 corresponding HTTP::Request object.
407 If the input is of type "file", then it has these additional methods:
409 $input->file
411 This is just an alias for the value() method. It sets the filename
412 to read data from.
413 For security reasons this field will never be initialized from the
415 parsing of a form. This prevents the server from triggering
416 stealth uploads of arbitrary files from the client machine.
417 $filename = $input->filename
419 $input->filename( $new_filename )
420 This get/sets the filename reported to the server during file
421 upload. This attribute defaults to the value reported by the
422 file() method.
423 $content = $input->content
425 $input->content( $new_content )
426 This get/sets the file content provided to the server during file
427 upload. This method can be used if you do not want the content to
428 be read from an actual file.
429 @headers = $input->headers
431 input->headers($key => $value, .... )
432 This get/set additional header fields describing the file uploaded.
433 This can for instance be used to set the "Content-Type" reported
434 for the file.
435
437 LWP, LWP::UserAgent, HTML::Parser
438
440 Gisle Aas <gisle@activestate.com>
441
443 This software is copyright (c) 1998 by Gisle Aas.
444 This is free software; you can redistribute it and/or modify it under
446 the same terms as the Perl 5 programming language system itself.
447perl v5.36.0 2023-01-20 HTML::Form(3)