/ 
HTML-StickyForm-0.08
River stage zero No dependents
/ HTML::StickyForm

NAME

HTML::StickyForm - Lightweight general-purpose HTML form generation, with sticky values

SYNOPSIS

# mod_perl example

use HTML::StickyForm;
use Apache::Request;

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

  $r->send_http_header;
  print
    '<html><body>',
    $form->form_start,

    "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 />Single radio button:",
    $f->radio(name => 'field3', value => 'xyz', checked => 1),

    "<br />Radio buttons:",
    $f->radio_group(name => 'field4', values => [1,2,3],
      labels => { 1=>'one', 2=>'two', 3=>'three' }, default => 2),

    "<br />Single checkbox:",
    $f->checkbox(name => 'field5', value => 'xyz', checked => 1),

    "<br />Checkbox group:",
    $f->checkbox_group(name => 'field6', values => [4,5,6],
      labels => { 4=>'four', 5=>'five', 6=>'six' }, default => [5,6]),

    "<br />Password field:",
    $f->password(name => 'field7', size => 20),

    '<br />",
    $f->submit(value => ' Hit me! '),

    $f->form_end,
    '</body></html>',
   ;
   return OK;
 }

DESCRIPTION

This module provides a simple interface for generating HTML form elements, with default values chosen from the previous form submission. This module was written with mod_perl (Apache::Request) in mind, but works equally well with CGI.pm, including the new 3.x version, or any other module which implements a param() method, or even completely standalone.

The module does not provide methods for generating all possible HTML elements, only those which are used in form construction. In addition, this module's interface is much less flexible than CGI.pm's; all routines work only as methods, and there is only one way of passing parameters to each method. This was done for two reasons: to keep the API simple and consistent, and to keep the code size down to a minimum.

CLASS METHODS

new([REQUEST])

Creates a new form generation object. The single argument can be:

  • any object which responds to a param method in the same way that CGI and Apache::Request objects do. That is, with no arguments, the names of the parameters are returned as a list. With a single argument, the value(s) of the supplied parameter is/are returned; in scalar context the first value, and in list context all values.

  • a plain arrayref. This will be used to construct an HTML::StickyForm::RequestHash object, which responds as described above. The array will be passed directly to the RequestHash constructor, so both methods for specifying multiple values are allowed.

  • a plain hashref. This will be used to construct an HTML::StickyForm::RequestHash object. Multiple values must be represented as arrayref values.

  • a false value. This will be used to construct an HTML::StickyForm::RequestHash object with no parameters set.

The constructor dies if passed an unrecognised request object.

If an appropriate object is supplied, parameters will be fetched from the object on an as needed basis, which means that changes made to the request object after the form object is constructed may affect the default values used in generated form elements. However, once constructed, the form object's sticky status does not get automatically updated, so if changes made to the request object need to affect the form object's sticky status, set_sticky() must be called between request object modification and form generation.

In contrast, HTML::StickyForm::RequestHash objects created as part of form object construction use copies of the parameters from the supplied hashref or arrayref. This means that the changes made to the original data do not affect the request object, so have absolutely no effect of the behaviour of the form object.

METHODS

Configuration methods

set_sticky([BOOL])

With no arguments, the request object's parameters are counted, and the form object is made sticky if one or more parameters are present, non-sticky otherwise. If an argument is given, its value as a boolean determines whether the form object will be sticky or not. In both cases, the return value will be the new value of the sticky flag.

A non-sticky form object always uses the values supplied to methods when constructing HTML elements, whereas a sticky form object will use the values from the request.

This method is called by the constructor when the 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.

get_sticky()

Returns true if the form object is sticky.

values_as_labels([BOOL])

With no arguments, this method returns the values_as_labels attribute, which determines what should happen 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.

well_formed([BOOL])

With no arguments, this method return the well_formed attribute, which determines whether to generate well-formed XML, by including the trailing slash in non-container elements. If true, all generated elements will be well-formed. If false, no slashes are added - which is unfortunately required by some older browsers.

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

HTML generation methods

Most of these methods are specified as taking PAIRLIST arguments. This means that arguments must be passed as a list of name/value pairs. For example:

$form->text(name => 'fred',value => 'bloggs');

This represents two arguments; "name" with a value of "fred", and "value" with a value of "bloggs".

In cases where sticky values are useful, there are two ways of specifying the values, depending on whether stickiness is required for the element being generated. To set sticky value defaults, use the default argument. Alternatively, to set values which are not affected by previous values entered by the user, use the value argument (or selected or checked, depending on the type of element being generated).

form_start(PAIRLIST)

Generates a <form> start tag. All arguments are interpreted as attributes for the element. All names and values are HTML escaped. The following arguments are treated specially:

method: Defaults to GET

form_start_multipart(PAIRLIST)

As form_start(), but the enctype argument defaults to multipart/form-data.

form_end()

Generates a <form> end tag.

text(PAIRLIST)

Generates an <input> element. In general, arguments are interpreted as attributes for the element. All names and values are HTML escaped. The following arguments are treated specially:

type: Defaults to text

value: Unconditional value. If present, causes default and any sticky value to be ignored.

default: Conditional value, ignored if value is present. If the form is sticky, the sticky value will be used for the value attribute's value. Otherwise, the supplied default will be used. A default attribute is never created.

hidden(PAIRLIST)

As text(), but produces an input element of type hidden.

password(PAIRLIST)

As text(), but produces an input element of type password.

textarea(PAIRLIST)

Generates a <textarea> container. All arguments are used directly to generate attributes for the start tag, except for those listed below. All values are HTML-escaped.

value: Unconditional value. If present, specifies the contents of the container, and causes default and any sticky value to be ignored. A value attribute is never created.

default: Conditional value, ignored if value is present. If the form is stikcy, the sticky value wil be used for the container contents. Otherwise, sticky, the supplied default will be used. A default attribute is never created.

checkbox(PAIRLIST)

Generates a single checkbox type <input> element. All arguments are used directly to generate attributes for the tag, except for those listed below. All values are HTML-escaped.

checked: Unconditional status. If present, used to decide whether to include a checked attribute, and causes default and any sticky value to be ignored.

default: Conditional status, ignored if checked is present. If the form is sticky, the sticky value will be used to determine whether to include a checked attribute. Otherwise, the supplied default will be used.

If the decision to include the checked attribute is based on the sticky value, the sticky parameter must include at least one value which is the same as the supplied value argument. If the decision is based on the value of the checked or default arguments, the supplied argument need only be true for the checked attribute to be created.

checkbox_group(PAIRLIST)

Generates a group of checkbox type <input> elements. If called in list context, returns a list of elements, otherwise a single string containing all tags. All arguments are used directly to generate attributes in each tag, except for those listed below. Arguments with scalar values result in that value being used for each element, whereas hashref values result in the value keyed by the element's value attribute being used. Unless otherwise stated, all names and values are HTML-escaped.

values: An arrayref of values. One element will be generated for each element, in the order supplied. If not supplied, the label keys will be used instead.

labels: A hashref of labels. Each element generated will be followed by the label keyed by the value. Values will be HTML-escaped unless a false escape argument is supplied. If no label is present for a given value and values_as_labels is true, the value will also be used for the label.

escape_labels: If present and false, labels will not be HTML-escaped.

checked: Unconditional status. If present, used to decide whether each checkbox is marked as checked, and causes default, defaults and any sticky values to be ignored. May be a single value or arrayref of values.

default: Conditional status, ignored if checked is present. If the form is sticky, individual checkboxes are marked as checked if the sticky parameter includes at least one value which is the same as the individual checkbox's value. Otherwise, the supplied default values are used in the same way. May be a single value or arrayref of values.

linebreak: If true, each element/label will be followed by a <br> element.

values_as_labels: If supplied, overrides the form object's values_as_labels attribute.

radio(PAIRLIST)

As radio_group(), but setting type to radio.

radio_group(PAIRLIST)

As checkbox_group(), but setting type to radio.

select(PAIRLIST)

Generates a <select> element. Arguments starting with a dash are used directly to generate attributes in the <option> elements. All other arguments are used directly to generate attributes in the <select> element, except for those listed below. Unless otherwise stated, all names and values are HTML-escaped.

values: An arrayref of values and/or option groups. Scalar values are used directly to create <option> elements, whereas arrayrefs represent option groups. The first element in an option group is either the group's label or a hashref holding all of the group's attributes, of which disabled is special cased to produce the attribute value disabled if true, and no attribute if false. Defaults to label keys.

labels: 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.

selected: Unconditional status. If present, the supplied values will be used to decide which options to mark as selected, and default and any sticky values will be ignored. May be a single value or arrayref.

default: Conditional status, ignored if selected is supplied. If the form is sticky, the sticky values will be used to decide which options are selected. Otherwise, the supplied values will be used. May be a single value or arrayref.

multiple: If true, the multiple attribute is set to multiple.

values_as_labels: Overrides the form object's values_as_labels attribute. This is of little value, since it's the default behaviour of HTML in any case.

submit(PAIRLIST)

Generates an <input> of type submit. All of the supplied arguments are HTML-escaped, and used directly as attributes. submit fields are not sticky.

AUTHOR

Copyright (C) Institute of Physics Publishing 2000-2011

Peter Haworth <pmh@edison.ioppublishing.com>

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