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.07
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, 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
178 prefix matches the name attribute.
179 If $type is not "undef", then the input must have the specified
181 type. The following type names are used: "text", "password",
182 "hidden", "textarea", "file", "image", "submit", "radio",
183 "checkbox" and "option".
184 The $index is the sequence number of the input matched where 1 is
186 the first. If combined with $name and/or $type, then it selects
187 the nth input with the given name and/or type.
188 $value = $form->value( $selector )
190 $form->value( $selector, $new_value )
191 The value() method can be used to get/set the value of some input.
192 If strict is enabled and no input has the indicated name, then this
193 method will croak.
194 If multiple inputs have the same name, only the first one will be
196 affected.
197 The call:
199 $form->value('foo')
201 is basically a short-hand for:
203 $form->find_input('foo')->value;
205 @names = $form->param
207 @values = $form->param( $name )
208 $form->param( $name, $value, ... )
209 $form->param( $name, \@values )
210 Alternative interface to examining and setting the values of the
211 form.
212 If called without arguments then it returns the names of all the
214 inputs in the form. The names will not repeat even if multiple
215 inputs have the same name. In scalar context the number of
216 different names is returned.
217 If called with a single argument then it returns the value or
219 values of inputs with the given name. If called in scalar context
220 only the first value is returned. If no input exists with the
221 given name, then "undef" is returned.
222 If called with 2 or more arguments then it will set values of the
224 named inputs. This form will croak if no inputs have the given
225 name or if any of the values provided does not fit. Values can
226 also be provided as a reference to an array. This form will allow
227 unsetting all values with the given name as well.
228 This interface resembles that of the param() function of the CGI
230 module.
231 $form->try_others( \&callback )
233 This method will iterate over all permutations of unvisited
234 enumerated values (<select>, <radio>, <checkbox>) and invoke the
235 callback for each. The callback is passed the $form as argument.
236 The return value from the callback is ignored and the try_others()
237 method itself does not return anything.
238 $request = $form->make_request
240 Will return an HTTP::Request object that reflects the current
241 setting of the form. You might want to use the click() method
242 instead.
243 $request = $form->click
245 $request = $form->click( $selector )
246 $request = $form->click( $x, $y )
247 $request = $form->click( $selector, $x, $y )
248 Will "click" on the first clickable input (which will be of type
249 "submit" or "image"). The result of clicking is an HTTP::Request
250 object that can then be passed to LWP::UserAgent if you want to
251 obtain the server response.
252 If a $selector is specified, we will click on the first clickable
254 input matching the selector, and the method will croak if no
255 matching clickable input is found. If $selector is not specified,
256 then it is ok if the form contains no clickable inputs. In this
257 case the click() method returns the same request as the
258 make_request() method would do. See description of the
259 find_input() method above for how the $selector is specified.
260 If there are multiple clickable inputs with the same name, then
262 there is no way to get the click() method of the "HTML::Form" to
263 click on any but the first. If you need this you would have to
264 locate the input with find_input() and invoke the click() method on
265 the given input yourself.
266 A click coordinate pair can also be provided, but this only makes a
268 difference if you clicked on an image. The default coordinate is
269 (1,1). The upper-left corner of the image is (0,0), but some badly
270 coded CGI scripts are known to not recognize this. Therefore (1,1)
271 was selected as a safer default.
272 @kw = $form->form
274 Returns the current setting as a sequence of key/value pairs. Note
275 that keys might be repeated, which means that some values might be
276 lost if the return values are assigned to a hash.
277 In scalar context this method returns the number of key/value pairs
279 generated.
280 $form->dump
282 Returns a textual representation of current state of the form.
283 Mainly useful for debugging. If called in void context, then the
284 dump is printed on STDERR.
285
287 An "HTML::Form" objects contains a sequence of inputs. References to
288 the inputs can be obtained with the $form->inputs or $form->find_input
289 methods.
290 Note that there is not a one-to-one correspondence between input
292 objects and <input> elements in the HTML document. An input object
293 basically represents a name/value pair, so when multiple HTML elements
294 contribute to the same name/value pair in the submitted form they are
295 combined.
296 The input elements that are mapped one-to-one are "text", "textarea",
298 "password", "hidden", "file", "image", "submit" and "checkbox". For
299 the "radio" and "option" inputs the story is not as simple: All <input
300 type="radio"> elements with the same name will contribute to the same
301 input radio object. The number of radio input objects will be the same
302 as the number of distinct names used for the <input type="radio">
303 elements. For a <select> element without the "multiple" attribute
304 there will be one input object of type of "option". For a <select
305 multiple> element there will be one input object for each contained
306 <option> element. Each one of these option objects will have the same
307 name.
308 The following methods are available for the input objects:
310 $input->type
312 Returns the type of this input. The type is one of the following
313 strings: "text", "password", "hidden", "textarea", "file", "image",
314 "submit", "radio", "checkbox" or "option".
315 $name = $input->name
317 $input->name( $new_name )
318 This method can be used to get/set the current name of the input.
319 $input->id
321 $input->class
322 These methods can be used to get/set the current id or class
323 attribute for the input.
324 $input->selected( $selector )
326 Returns TRUE if the given selector matched the input. See the
327 description of the find_input() method above for a description of
328 the selector syntax.
329 $value = $input->value
331 $input->value( $new_value )
332 This method can be used to get/set the current value of an input.
333 If strict is enabled and the input only can take an enumerated list
335 of values, then it is an error to try to set it to something else
336 and the method will croak if you try.
337 You will also be able to set the value of read-only inputs, but a
339 warning will be generated if running under "perl -w".
340 $autocomplete = $input->autocomplete
342 $input->autocomplete( $new_autocomplete )
343 This method can be used to get/set the current value (if any) of
344 "autcomplete" for the input.
345 $input->possible_values
347 Returns a list of all values that an input can take. For inputs
348 that do not have discrete values, this returns an empty list.
349 $input->other_possible_values
351 Returns a list of all values not tried yet.
352 $input->value_names
354 For some inputs the values can have names that are different from
355 the values themselves. The number of names returned by this method
356 will match the number of values reported by
357 $input->possible_values.
358 When setting values using the value() method it is also possible to
360 use the value names in place of the value itself.
361 $bool = $input->readonly
363 $input->readonly( $bool )
364 This method is used to get/set the value of the readonly attribute.
365 You are allowed to modify the value of readonly inputs, but setting
366 the value will generate some noise when warnings are enabled.
367 Hidden fields always start out readonly.
368 $bool = $input->disabled
370 $input->disabled( $bool )
371 This method is used to get/set the value of the disabled attribute.
372 Disabled inputs do not contribute any key/value pairs for the form
373 value.
374 $input->form_name_value
376 Returns a (possible empty) list of key/value pairs that should be
377 incorporated in the form value from this input.
378 $input->check
380 Some input types represent toggles that can be turned on/off. This
381 includes "checkbox" and "option" inputs. Calling this method turns
382 this input on without having to know the value name. If the input
383 is already on, then nothing happens.
384 This has the same effect as:
386 $input->value($input->possible_values[1]);
388 The input can be turned off with:
390 $input->value(undef);
392 $input->click($form, $x, $y)
394 Some input types (currently "submit" buttons and "images") can be
395 clicked to submit the form. The click() method returns the
396 corresponding HTTP::Request object.
397 If the input is of type "file", then it has these additional methods:
399 $input->file
401 This is just an alias for the value() method. It sets the filename
402 to read data from.
403 For security reasons this field will never be initialized from the
405 parsing of a form. This prevents the server from triggering
406 stealth uploads of arbitrary files from the client machine.
407 $filename = $input->filename
409 $input->filename( $new_filename )
410 This get/sets the filename reported to the server during file
411 upload. This attribute defaults to the value reported by the
412 file() method.
413 $content = $input->content
415 $input->content( $new_content )
416 This get/sets the file content provided to the server during file
417 upload. This method can be used if you do not want the content to
418 be read from an actual file.
419 @headers = $input->headers
421 input->headers($key => $value, .... )
422 This get/set additional header fields describing the file uploaded.
423 This can for instance be used to set the "Content-Type" reported
424 for the file.
425
427 LWP, LWP::UserAgent, HTML::Parser
428
430 Gisle Aas <gisle@activestate.com>
431
433 This software is copyright (c) 1998 by Gisle Aas.
434 This is free software; you can redistribute it and/or modify it under
436 the same terms as the Perl 5 programming language system itself.
437perl v5.36.0 2022-07-22 HTML::Form(3)