NAME HTTP::Request::Form - Construct HTTP::Request objects for form processing SYNOPSIS use the following as a tool to query Altavista for "perl" from the commandline: use HTML::TreeBuilder; use URI::URL; use LWP::UserAgent; use HTTP::Request; use HTTP::Request::Common; use HTTP::Request::Form; my $ua = LWP::UserAgent->new; my $url = url 'http://www.altavista.digital.com/'; my $res = $ua->request(GET $url); my $tb = HTML::TreeBuilder->new; $tb->parse($res->content); my @forms = @{$tb->extract_links(qw(FORM))}; my $f = HTTP::Request::Form->new($forms[0][1], $url); $f->field("q", "perl"); my $response = $ua->request($f->press("search")); print $response->content if ($response->is_success); DESCRIPTION This is an extension of the HTTP::Request suite. It allows easy processing of forms in a user agent by filling out fields, querying fields, selections and buttons and pressing buttons. It uses HTML::TreeBuilder generated parse trees of documents (especially the forms parts extracted with extract_links) and generates it's own internal representation of forms from which it then generates the request objects to process the form application. If you use HTML::TreeBuilder like me, please be aware of the fact that the extract_links call in the above example returns an array with alternating URL and FORM-elements, so the first FORM is actually at index 1 and the second FORM is at index 3! CLASS METHODS new($form [, $base [, $debug]]) The new-method constructs a new form processor. It get's an HTML::Element object that contains a form as the single parameter. If an base-url is given as an additional parameter, this is used to make the form-url absolute in regard to the given URL. If debugging is true, the following functions will be a bit "talky" on stdio. INSTANCE METHODS base() This returns the parameter $base to the "new" constructor. link() This returns the action attribute of the original form structure. This value is cached within the form processor, so you can safely delete the form structure after you created the form processor. method() This returns the method attribute of the original form structure. This value is cached within the form processor, so you can safely delete the form structure as soon as you created the form processor. fields() This method delivers a list of fieldnames that are of "open" type. This excludes the "hidden" and "submit" elements, because they are already filled with a value (and as such declared as "closed") or as in the case of "submit" are buttons, of which only one must be used. allfields() This delivers a list of all fieldnames in the order as they occured in the form-source excluding the submit fields. field($name [, $value]) This method retrieves or sets a field-value. The field is identified by it's name. You have to be sure that you only put a allowed value into the field. field_type($name) This method gives you the type of the named field, so that you can distinguish on this type. (this is the only way to distinguish selections and radio buttons). is_selection($name) This tests if a field is a selection or an input. Radio- Buttons are used in the same way as standard selection fields, so is_selection returns a true value for radio buttons, too! (Of course, only one value is submitted for a radio button) field_selection($name) This delivers the array of the options of a selection. The element that is marked with selected in the source is given as the default value. This works in the same way for radio buttons, as they are just handled as a special case of selections! is_checkbox($name) This tells you if a field is a checkbox. If it is, there are several support methods to make use of the special features of checkboxes, for example the fact that it is only sent if it is checked. checkboxes() This method delivers a list of all checkbox fields much in the same way as the buttons method. checkbox_check($name) =item checkbox_uncheck($name) =item checkbox_toggle($name) These methods set, unset or toggle the checkbox checked state. Checkbox values are only added to the result if they are checked. checkbox_ischecked($name) This methods tells you wether a checkbox is checked or not. This is important if you want to analyze the state of fields directly after the parse. buttons() This delivers a list of all defined and named buttons of a form. button($button [, $value]) This gets or sets the value of a button. Normally only getting a button value is needed. The value of a button is a reference to an array of values (because a button can exist multiple times). button_type($button) This gives you the type of a button (submit/reset/image). The result is an array of type names, as a button with one name can exist multiple times. button_exists($button) This gives true if the named button exists, false (undef) otherwise. referer([$value]) This returns or sets the referer header for an request. This is usefull if a CGI needs a set referer for authentication. press([$name [, $coord ] [, $number]]) This method creates a HTTP::Request object (via HTTP::Request::Common) that sends the formdata to the server with the requested method. If you give a button-name, that button is used. If you give no button name, it assumes a button without a name and just leaves out this last parameter. If the number of the button is given, that button value is delivered. If the number is not given, 0 (the first button of this name) is assumed. The "coord" parameter comes in handy if you have an image button. If this is the case, the button press will simulate a press at coordinates [2,2] unless you provide an anonymous array with different coordinates. dump() This method dumps the form-data on stdio for debugging purpose. SEE ALSO the HTTP::Request manpage, the HTTP::Request::Common manpage, the LWP::UserAgent manpage, the HTML::Element manpage, the URI::URL manpage INSTALLATION perl Makefile.PL make install REQUIRES Perl version 5.004 or later HTTP::Request::Common HTML::TreeBuilder LWP::UserAgent VERSION HTTP::Request::Form version 0.6, March 2nd, 2000 RESTRICTIONS Only a subset of all possible form elements are currently supported. The list of supported tags as of this version includes: INPUT/CHECKBOX INPUT/HIDDEN INPUT/IMAGE INPUT/RADIO INPUT/RESET INPUT/SUBMIT INPUT/FILE INPUT/* (are all handled as simple text entry) OPTION SELECT TEXTAREA BUGS There is currently no support for multiple selections (you can do them yourself by setting a selection to a comma-delimited list of values). If there are several fields with the same name, you can only set the value of the first of this fields (this is especially problematic with checkboxes). This does work with buttons that have the same name, though (you can press each instance identified by number). Error-Checking is currently very limited (not to say nonexistant). Support for HTML 4.0 optgroup tags is missing (as is with allmost all current browsers, so that is not a great loss). The button tag (HTML 4.0) is just handled as an alias for the input tag - this is of course incorrect, but sufficient for support of the usual button types. COPYRIGHT Copyright 1998, 1999, Georg Bauer This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.