1Form(3) User Contributed Perl Documentation Form(3)
2
6 HTTP::Request::Form - Construct HTTP::Request objects for form
7 processing
8
10 use the following as a tool to query Altavista for "perl" from the
11 commandline:
12 use URI::URL;
14 use LWP::UserAgent;
15 use HTTP::Request;
16 use HTTP::Request::Common;
17 use HTTP::Request::Form;
18 use HTML::TreeBuilder 3.0;
19 my $ua = LWP::UserAgent->new;
21 my $url = url 'http://www.altavista.digital.com/';
22 my $res = $ua->request(GET $url);
23 my $tree = HTML::TreeBuilder->new;
24 $tree->parse($res->content);
25 $tree->eof();
26 my @forms = $tree->find_by_tag_name('FORM');
28 die "What, no forms in $url?" unless @forms;
29 my $f = HTTP::Request::Form->new($forms[0], $url);
30 $f->field("q", "perl");
31 my $response = $ua->request($f->press("search"));
32 print $response->content if $response->is_success;
33
35 This is an extension of the HTTP::Request suite. It allows easy
36 processing of forms in a user agent by filling out fields, querying
37 fields, selections and buttons and pressing buttons. It uses
38 HTML::TreeBuilder generated parse trees of documents (especially the
39 forms parts extracted with extract_links) and generates it's own
40 internal representation of forms from which it then generates the
41 request objects to process the form application.
42
44 new($form [, $base [, $debug]])
45 The "new-method" constructs a new form processor. It get's an
46 HTML::Element object that contains a FORM element or ISINDEX
47 element as the single parameter. If an base-url is given as an
48 additional parameter, this is used to make the form-url absolute in
49 regard to the given URL.
50 If debugging is true, the following functions will be a bit "talky"
52 on stdio.
53 new_many($tree_part [, $base [, $debug]])
55 The "new_many" method returns a list of newly constructed form
56 processors. It's just like the "new" method except that it can
57 apply to any part of an HTML::Element tree, including the root; it
58 constructs a new form processor for each FORM element at or under
59 $tree_part.
60 Note that the return list might have zero, one or many new objects
62 in it, depending on how many FORM (or ISINDEX) elements were found.
63 Form elements (like INPUT, etc.) found outside of FORM elements are
65 counted as being part of the preceding FORM element. (And if there
66 is no preceding FORM element, they are ignored.) This feature is
67 useful with the odd parse trees that can result from basd HTML in
68 or around FORM elements. If you need to override that feature, then
69 instead call:
70 map HTTP::Request::Form->new($_), $tree->find_by_tag_name('FORM');
72
74 base()
75 This returns the parameter $base to the "new" constructor.
76 link()
78 This returns the action attribute of the original form structure.
79 This value is cached within the form processor, so you can safely
80 delete the form structure after you created the form processor.
81 method()
83 This returns the method attribute of the original form structure.
84 This value is cached within the form processor, so you can safely
85 delete the form structure as soon as you created the form
86 processor.
87 isindex()
89 This returns true if this came from an original form structure that
90 was actually an ISINDEX element. In that case, the form will hagve
91 only one field, an input/text field named "keywords".
92 name()
94 This returns the name attribute of the original form structure.
95 This value is cached within the form processor, so you can safely
96 delete the form structure after you created the form processor.
97 fields()
99 This method delivers a list of fieldnames that are of "open" type.
100 This excludes the "hidden" and "submit" elements, because they are
101 already filled with a value (and as such declared as "closed") or
102 as in the case of "submit" are buttons, of which only one must be
103 used.
104 allfields()
106 This delivers a list of all fieldnames in the order as they occured
107 in the form-source excluding the submit fields.
108 field($name [, $value])
110 This method retrieves or sets a field-value. The field is
111 identified by its name. You have to be sure that you only put a
112 allowed value into the field.
113 field_type($name)
115 This method gives you the type of the named field, so that you can
116 distinguish on this type. (this is the only way to distinguish
117 selections and radio buttons).
118 is_selection($name)
120 This tests if a field is a selection or an input. Radio-Buttons are
121 used in the same way as standard selection fields, so is_selection
122 returns a true value for radio buttons, too! (Of course, only one
123 value is submitted for a radio button)
124 field_selection($name)
126 This delivers the array of the options of a selection. The element
127 that is marked with selected in the source is given as the default
128 value. This works in the same way for radio buttons, as they are
129 just handled as a special case of selections!
130 is_checkbox($name)
132 This tells you if a field is a checkbox. If it is, there are
133 several support methods to make use of the special features of
134 checkboxes, for example the fact that it is only sent if it is
135 checked.
136 checkboxes()
138 This method delivers a list of all checkbox fields much in the same
139 way as the buttons method.
140 checkbox_check($name)
142 checkbox_uncheck($name)
143 checkbox_toggle($name)
144 These methods set, unset or toggle the checkbox checked state.
145 Checkbox values are only added to the result if they are checked.
146 checkbox_ischecked($name)
148 This methods tells you wether a checkbox is checked or not. This is
149 important if you want to analyze the state of fields directly after
150 the parse.
151 buttons()
153 This delivers a list of all defined and named buttons of a form.
154 button($button [, $value])
156 This gets or sets the value of a button. Normally only getting a
157 button value is needed. The value of a button is a reference to an
158 array of values (because a button can exist multiple times).
159 button_type($button)
161 This gives you the type of a button (submit/reset/image). The
162 result is an array of type names, as a button with one name can
163 exist multiple times.
164 button_exists($button)
166 This gives true if the named button exists, false (undef)
167 otherwise.
168 referer([$value])
170 This returns or sets the referer header for an request. This is
171 useful if a CGI needs a set referer for authentication.
172 press([$name [, $coord ] [, $number]])
174 This method creates a HTTP::Request object (via
175 HTTP::Request::Common) that sends the formdata to the server with
176 the requested method. If you give a button-name, that button is
177 used. If you give no button name, it assumes a button without a
178 name and just leaves out this last parameter. If the number of the
179 button is given, that button value is delivered. If the number is
180 not given, 0 (the first button of this name) is assumed.
181 The "coord" parameter comes in handy if you have an image button.
183 If this is the case, the button press will simulate a press at
184 coordinates [2,2] unless you provide an anonymous array with
185 different coordinates.
186 dump()
188 This method dumps the form-data on stdio for debugging purpose.
189
191 HTTP::Request, HTTP::Request::Common, LWP::UserAgent, HTML::Element,
192 URI::URL
193
195 perl Makefile.PL
196 make install
197 or see perlmodinstall
199
201 Perl version 5.004 or later
202 HTTP::Request::Common
204 HTML::TreeBuilder
205 LWP::UserAgent
206
208 HTTP::Request::Form version 0.9, February 8th, 2001
209
211 Only a subset of all possible form elements are currently supported.
212 The list of supported tags as of this version includes:
213 INPUT/CHECKBOX
215 INPUT/HIDDEN
216 INPUT/IMAGE
217 INPUT/RADIO
218 INPUT/RESET
219 INPUT/SUBMIT
220 INPUT/FILE
221 INPUT/* (are all handled as simple text entry)
222 OPTION
223 SELECT
224 TEXTAREA
225 ISINDEX
226
228 There is currently no support for multiple selections (you can do them
229 yourself by setting a selection to a comma-delimited list of values).
230 Multiple fields are not properly handled, only the last value is
232 available. Exception are buttons, they are handled in the right way.
233 If there are several fields with the same name, you can only set the
235 value of the first of this fields (this is especially problematic with
236 checkboxes). This does work with buttons that have the same name,
237 though (you can press each instance identified by number).
238 Error-Checking is currently very limited (not to say nonexistant).
240 Support for HTML 4.0 optgroup tags is missing (as is with allmost all
242 current browsers, so that is not a great loss).
243 The button tag (HTML 4.0) is just handled as an alias for the input tag
245 - this is of course incorrect, but sufficient for support of the usual
246 button types.
247
249 Copyright 1998, 1999, 2000 Georg Bauer <Georg_Bauer@muensterland.org>
250 This library is free software; you can redistribute it and/or modify it
252 under the same terms as Perl itself.
253
255 Sean M. Burke (ISINDEX, new_many)
256perl v5.28.0 2001-12-01 Form(3)