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

NAME

6       HTTP::Request::Form - Construct HTTP::Request objects for form
7       processing
8

SYNOPSIS

10       use the following as a tool to query Altavista for "perl" from the
11       commandline:
12
13         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
20         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
27         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

DESCRIPTION

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

CLASS METHODS

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
51           If debugging is true, the following functions will be a bit "talky"
52           on stdio.
53
54       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
61           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
64           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
71             map HTTP::Request::Form->new($_), $tree->find_by_tag_name('FORM');
72

INSTANCE METHODS

74       base()
75           This returns the parameter $base to the "new" constructor.
76
77       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
82       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
88       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
93       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
98       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
105       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
109       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
114       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
119       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
125       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
131       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
137       checkboxes()
138           This method delivers a list of all checkbox fields much in the same
139           way as the buttons method.
140
141       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
147       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
152       buttons()
153           This delivers a list of all defined and named buttons of a form.
154
155       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
160       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
165       button_exists($button)
166           This gives true if the named button exists, false (undef)
167           otherwise.
168
169       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
173       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
182           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
187       dump()
188           This method dumps the form-data on stdio for debugging purpose.
189

SEE ALSO

191       HTTP::Request, HTTP::Request::Common, LWP::UserAgent, HTML::Element,
192       URI::URL
193

INSTALLATION

195         perl Makefile.PL
196         make install
197
198       or see perlmodinstall
199

REQUIRES

201         Perl version 5.004 or later
202
203         HTTP::Request::Common
204         HTML::TreeBuilder
205         LWP::UserAgent
206

VERSION

208       HTTP::Request::Form version 0.9, February 8th, 2001
209

RESTRICTIONS

211       Only a subset of all possible form elements are currently supported.
212       The list of supported tags as of this version includes:
213
214         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

BUGS

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
231       Multiple fields are not properly handled, only the last value is
232       available. Exception are buttons, they are handled in the right way.
233
234       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
239       Error-Checking is currently very limited (not to say nonexistant).
240
241       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
244       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
251       This library is free software; you can redistribute it and/or modify it
252       under the same terms as Perl itself.
253

MAJOR CONTRIBUTORS

255       Sean M. Burke (ISINDEX, new_many)
256
257
258
259perl v5.34.0                      2021-07-22                           Form(3)
Impressum