MAN page from Old RedHat 6.X perl-HTTP-Request-Form-0.5-6.i386.rpm

Form

Section: User Contributed Perl Documentation (3)
Updated: perl 5.005, patch 03
Index

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 processingof forms in a user agent by filling out fields, querying fields, selectionsand buttons and pressing buttons. It uses HTML::TreeBuilder generated parsetriees of documents (especially the forms parts extracted with extract_links)and generates it's own internal representation of forms from which it thengenerates the request objects to process the form application.

CLASS METHODS

new($form [, $base [, $debug]]): The new-method constructs a new form processor. It get's an HTML::Elementobject that contains a form as the single parameter. If an base-url is givenas an additional parameter, this is used to make the form-url absolute inregard 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 valueis cached within the form processor, so you can safely delete the formstructure after you created the form processor.
method(): This returns the method attribute of the original form structure. This valueis cached within the form processor, so you can safely delete the formstructure as soon as you created the form processor.
fields(): This method delivers a list of fieldnames that are of ``open'' type. Thisexcludes the ``hidden'' and ``submit'' elements, because they are already filledwith 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 theform-source excluding the submit fields.
field($name [, $value]): This method retrieves or sets a field-value. The field is identified byit's name. You have to be sure that you only put a allowed value into thefield.
field_type($name): This method gives you the type of the named field, so that you candistinguish on this type. (this is the only way to distinguishselections and radio buttons).
is_selection($name): This tests if a field is a selection or an input. Radio-Buttons areused in the same way as standard selection fields, so is_selectionreturns a true value for radio buttons, too! (Of course, only onevalue is submitted for a radio button)
field_selection($name): This delivers the array of the options of a selection. The element that ismarked with selected in the source is given as the default value. Thisworks in the same way for radio buttons, as they are just handledas a special case of selections!
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 valueis needed. The value of a button is a reference to an array of values (becausea button can exist multiple times).
button_type($button): This gives you the type of a button (submit/reset/image). The resultis an array of type names, as a button with one name can existmultiple times.
button_exists($button): This gives true if the named button exists, false (undef) otherwise.
press([$name [, $number]]): This method creates a HTTP::Request object (via HTTP::Request::Common) thatsends the formdata to the server with the requested method. If you give abutton-name, that button is used. If you give no button name, it assumes abutton without a name and just leaves out this last parameter. If the numberof the button is given, that button value is delivered. If the number is notgiven, 0 (the first button of this name) is assumed.
dump(): This method dumps the form-data on stdio for debugging purpose.

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.2, July 15th, 1998

RESTRICTIONS

Only a subset of all possible form elements are currently supported. The listof supported tags as of this version includes:

  INPUT/CHECKBOX  INPUT/HIDDEN  INPUT/IMAGE  INPUT/RADIO  INPUT/RESET  INPUT/SUBMIT  INPUT/* (are all handled as simple text entry)  OPTION  SELECT  TEXTAREA

BUGS

There is currently no support for multiple selections (you can dothem yourself by setting a selection to a comma-delimited list ofvalues).

If there are several fields with the same name, you can only setthe value of the first of this fields (this is especially problematicwith checkboxes). This does work with buttons that have the samename, 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 allmostall current browsers, so that is not a great loss).

The button tag (HTML 4.0) is just handled as an alias for the inputtag - this is of course incorrect, but sufficient for support ofthe usual button types.

COPYRIGHT

This library is free software; you can redistribute it and/ormodify it under the same terms as Perl itself.

This document was created byman2html,using the manual pages.