/ 
HTML-StickyForm-0.07
River stage zero No dependents
/ HTML::StickyForms

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

THIS MODULE IS DEPRECATED

This version has exactly the same functionality as version 0.06, and exists only to provide more visibility to its successor, HTML::StickyForm. The new module tidies up a few interface inconsistencies which couldn't be done without breaking backwards compatibility with the existing module, hence the name change.

The new module provides a more consistent API, which allows stickiness to be varied on a per-method basis in an obvious manner. It also diverges slightly from the previous dogma of only supplying methods which strictly benefit from stickiness, as it now provides convenience methods for generating password, hidden and submit elements, as well as the form element itself. This allows cleaner code to be written, since the whole form can now be generated using a single API. Objects created by the new module have the well_formed attribute enabled by default, since most widely-used browsers can handle this now. Finally, the trim_params() method has been removed from the new module, since this would be better located in a module geared towards parameter validation.

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

Copyright (C) Institute of Physics Publishing 2000-2005

Peter Haworth <pmh@edison.ioppublishing.com>

You may use and distribute this module according to the same terms that Perl is distributed under.