The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
HTML-StickyForms-0.03
River stage zero No dependents
/ HTML::StickyForms

NAME

HTML::StickyForms - HTML form generation for CGI or mod_perl

SYSNOPSIS

 # mod_perl example

 use HTML::StickyForms;
 use Apache::Request;

 sub handler{
   my($r)=@_;
   $r=Apache::Request->new($r);
   my $f=HTML::StickyForms->new($r);

   $r->send_http_header;
   print
     "<HTML><BODY><FORM>",
     "Text field:",
     $f->text(name => 'field1', size => 40, value => 'default value'),
     "<BR>Text area:",
     $r->textarea(name => 'field2', cols => 60, rows => 5, value => 'stuff'),
     "<BR>Radio buttons:",
     $r->radio_group(name => 'field3', values => [1,2,3],
       labels => { 1=>'one', 2=>'two', 3=>'three' }, default => 2),
     "<BR>Single checkbox:",
     $r->checkbox(name => 'field4', value => 'xyz', checked => 1),
     "<BR>Checkbox group:",
     $r->checkbox_group(name => 'field5', values => [4,5,6],
       labels => { 4=>'four', 5=>'five', 6=>'six' }, defaults => [5,6]),
     "<BR>Password field:",
     $r->password(name => 'field6', size => 20),
     '<BR><INPUT type="submit" value=" Hit me! ">',
     '</FORM></BODY></HTML>',
    ;
    return OK;
  }

DESCRIPTION

This module provides a simple interface for generating HTML <FORM> fields, with default values chosen from the previous form submission. This module was written with mod_perl in mind, but works equally well with CGI.pm, including the new 3.x version.

The module does not provide methods for generating all possible form fields, only those which benefit from having default values overridden by the previous form submission. This means that, unlike CGI.pm, there are no routines for generating <FORM> tags, hidden fields or submit fields. Also this module's interface is much less flexible than CGI.pm's. This was done mainly to keep the size and complexity down.

METHODS

HTML::StickyForms->new($req)

Creates a new form generation object. The single argument can be an Apache::Request object, a CGI object (v2.x), a CGI::State object (v3.x), or an object of a subclass of any of the above. As a special case, if the argument is undef or '', the object created will behave as if a request object with no submitted fields was given.

$f->trim_params()

Removes leading and trailing whitespace from all submitted values.

$f->text(%args)

Generates an <INPUT> tag, with a type of "text". All arguments are used directly to generate attributes for the tag, with the following exceptions:

type

Defaults to "text"

name

The value passed will have all HTML-special characters escaped.

default

Specifies the default value of the field if no fields were submitted in the request object passed to new(). The value used will have all HTML-special characters escaped.

$f->password(%args)

As text(), but generates a "password" type field.

$f->textarea(%args)

Generates a <TEXTAREA> container. All arguments are used directly to generate attributes for the start tag, except for:

name

This value will be HTML-escaped.

default

Specifies the default contents of the container if no fields were submitted. The value used will be HTML-escaped.

$f->checkbox(%args)

Generates a single "checkbox" type <INPUT> tag. All arguments are used directly to generate attributes for the tag, except for:

name, value

The values passed will be HTML-escaped.

checked

Specifies the default state of the field if no fields were submitted.

$f->checkbox_group(%args)

Generates a group of "checkbox" type <INPUT> tags. If called in list context, returns a list of tags, otherwise a single string containing all tags. All arguments are used directly to generate attributes in each tag, except for the following:

type

Defaults to "checkbox".

name

This value will be HTML-escaped.

values or value

An arrayref of values. One tag will be generated for each element. The values will be HTML-escaped. Defaults to label keys.

labels or label

A hashref of labels. Each tag generated will be followed by the label keyed by the value. If no label is present for a given value, no label will be generated. Defaults to an empty hashref.

escape

If this value is true, the labels will be HTML-escaped.

defaults or default

A single value or arrayref of values to be checked if no fields were submitted. Defaults to an empty arrayref.

linebreak

If true, each tag/label will be followed by a <BR> tag.

$f->radio_group(%args)

As checkbox_group(), but generates "radio" type tags.

$f->select(%args)

Generates a <SELECT> tags. All arguments are used directly to generate attributes in the <SELECT> tag, except for the following:

name

This value will be HTML-escaped.

values or value

An arrayref of values. One <OPTION> tag will be created inside the <SELECT> tag for each element. The values will be HTML-escaped. Defaults to label keys.

labels or label

A hashref of labels. Each <OPTION> tag generated will contain the label keyed by its value. If no label is present for a given value, no label will be generated. Defaults to an empty hashref.

defaults or default

A single value or arrayref of values to be selected if no fields were submitted. Defaults to an empty arrayref.

multiple

If a true value is passed, the MULTIPLE attribute is set.

AUTHOR

Peter Haworth <pmh@edison.ioppublishing.com>