NAME

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

SYNOPSIS

 # 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, default => 'default value'),
     "<BR>Text area:",
     $r->textarea(name => 'field2', cols => 60, rows => 5, default => '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->set_sticky([BOOL])

If a true argument is passed, the form object will be sticky, using the request object's parameters to fill the form. If a false argument is passed, the form object will not be sticky, using the user-supplied default values to fill the form. If no argument is passed, the request object's parameters are counted, and the form object is made sticky if one or more parameters are present, non-sticky otherwise.

This method is called by the constructor when a form object is created, so it is not usually necessary to call it explicitly. However, it may be necessary to call this method if parameters are set with the param() method after the form object is created.

$f->trim_params()

Removes leading and trailing whitespace from all submitted values.

$f->values_as_labels([BOOL])

With no arguments, this method returns the values_as_labels attribute. This attribute determines what to do when a value has no label in the checkbox_group(), radio_group() and select() methods. If this attribute is false (the default), no labels will be automatically generated. If it is true, labels will default to the corresponding value if they are not supplied by the user.

If an argument is passed, it is used to set the values_as_labels attribute.

$f->well_formed([BOOL])

With no arguments, this method return the well_formed attribute. This attribute determines whether to generate well-formed XML, by including the trailing slash in non-container elements. If this attribute is false, no slashes are added - this is the default, since some older browsers don't behave sensibly in the face of such elements. If true, all elements will be well-formed.

If an argument is passed, it is used to set the well_formed attribute.

$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.
values_as_labels: Overrides the form object's values_as_labels attribute.

$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.
values_as_labels: Overrides the form object's values_as_labels attribute.

AUTHOR

Peter Haworth <pmh@edison.ioppublishing.com>

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