HTML-SuperForm version 1.04
===========================
INSTALLATION
To install this module type the following:
perl Makefile.PL
make
make test
make install
NAME
HTML::SuperForm - HTML form generator
SYNOPSIS
use HTML::SuperForm;
use Apache::Constants qw(OK);
sub handler {
my $r = shift;
my $form = HTML::SuperForm->new($r);
my $text = $form->text(name => 'text',
default => 'Default Text');
my $textarea = $form->textarea(name => 'textarea',
default => 'More Default Text');
my $select = $form->select(name => 'select',
default => 2,
values => [ 0, 1, 2, 3],
labels => {
0 => 'Zero',
1 => 'One',
2 => 'Two',
3 => 'Three'
});
my $output = <<"END_HTML";
END_HTML
$r->content_type('text/html');
$r->send_http_header;
$r->print($output);
return OK;
}
1;
OR
#!/usr/bin/perl
my $form = HTML::SuperForm->new();
my $text = $form->text(name => 'text',
default => 'Default Text');
my $textarea = $form->textarea(name => 'textarea',
default => 'More Default Text');
my $select = $form->select(name => 'select',
default => 2,
values => [ 0, 1, 2, 3],
labels => {
0 => 'Zero',
1 => 'One',
2 => 'Two',
3 => 'Three'
});
my $output = <<"END_HTML";
END_HTML
print "Content-Type: text/html\n\n";
print $output;
DESCRIPTION
Used in its basic form, this module provides an interface for generating
basic HTML form elements much like HTML::StickyForms does. The main
difference is HTML::SuperForm returns HTML::SuperForm::Field objects
rather than plain HTML. This allows for more flexibilty when generating
forms for a complex application.
To get the most out of this module, use it as a base (Super) class for
your own form object which generates your own custom fields. If you
don't use it this way, I guess there's really nothing Super about it.
Example are shown later in the document.
The interface was designed with mod_perl and the Template Toolkit in
mind, but it works equally well in any cgi environment.
METHODS
CONSTRUCTOR
*new($arg, $field_object)*, *new($arg)*, *new()*
Creates a new HTML::SuperForm object.
If $arg is an Apache object then an Apache::Request object will be
created from it to retrieve the parameters. If you don't have
Apache::Request installed then it behaves as if $arg is undef.
If $arg is an Apache::Request object, CGI object or a hash
reference, then it is used to retrieve the parameters. If no
argument is given or the argument isn't an instance or subclass of
the objects mentioned above then the parameters are retreived
through the environment variables. If called in a non-cgi
environment, no stickyness is applied.
It is recommended to use CGI or Apache::Request because the
parameter parsing included in HTML::SuperForm doesn't include the
complexities that CGI and Apache::Request take in to account and
only works with application/x-www-form-urlencoded forms.
If you pass $field_object, then HTML::SuperForm will use that object
instead of HTML::SuperForm::Field. See *field_object()* below and
HTML::SuperForm::Field for more on this.
ACCESSORS AND MUTATORS
These methods get and set values contained in the form object.
*set_sticky($flag)*, *sticky($flag)*
*set_sticky()*, *sticky()*
Returns the state of the sticky flag. If an argument is given the
sticky flag is set to that value. The sticky flag defaults to false.
The flag determines whether the form uses the default values (false)
or submitted values (true).
*fallback($flag)*, *fallback()*
Sets whether the form's fields "fall back" to their default values
if the form is sticky and no data has been submitted for those
fields. Defaults to false.
*values_as_labels($flag)*, *values_as_labels()*
Returns the state of the values_as_labels flag. If an argument is
given flag is set to that value. The values_as_labels flag defaults
to true. The flag determines whether select fields, checkboxes and
radio buttons use their values as labels if no labels are given.
*well_formed($flag)*, *well_formed()*
Returns the state of the well_formed flag. If an argument is given
flag is set to that value. The well_formed flag defaults to true.
The flag determines whether the HTML generated is also well-formed
XML.
*start_form(%args)*, *start_form(\%args)*
Returns the starting HTML form tag with all the attributes you pass
it. These are some arguments you might give (each is also a method
that returns its value):
*name()*
The name of the form.
*method()*
The method in which the form is submitted (GET or POST). The
default is POST.
If the method set in *start_form()* equals the method that is
detected from the current request then the form is set to
sticky.
*action()*
The url to which the form is submitted.
Any other attribute you specify can be accessed by calling its
method (i.e. if you pass in ( target => 'newWindow', onSubmit =>
'CheckForm()' ), $form->target will return 'newWindow', and
$form->onSubmit will return 'CheckForm()'). The names are case
sensitive so be consistent.
*no_of_fields($name)*
Returns the number of fields which have the given name.
*param(%args)*, *param(\%args)*, *param($name)*
Gets the parameters with name $name or sets parameters with names
equal to the keys of %args and values equal to the values of %args.
The parameters are used by the form object as if they were submitted
values.
*exists_param($name)*
Returns true if a value exists for the parameter named $name.
Otherwise, returns false.
*params()*
Returns a reference to a hash of the submitted parameters.
GET AND SET
Since I intended HTML::SuperForm's main use to be as a base class, I
made these methods so subclasses can store information within the object
without worrying about overriding important keys in the object.
*set(%args)*, *set(\%args)*
Stores infomation in form for later retrieval by get().
*get(@keys)*
When called in list context, returns an array of values that were
previously stored with set(). When called in scalar context, returns
a reference to an array of values or, if only one key is given, the
corresponding single value.
INTERNAL METHODS
You probably won't ever need to use these methods unless you are in a
subclass of HTML::SuperForm or HTML::SuperForm::Field.
*set_default(%args)*, *set_default(\%args)*
Sets default values in form for each key/value pair in %args.
*add_default(%args)*, *add_default(\%args)*
Adds default values to form for each key/value pair in %args.
*field_object()*
Returns the field object (the string, not an actual object) that is
the base class of all the field objects.
This will almost always be HTML::SuperForm::Field. If you subclass
HTML::SuperForm::Field (as a replacement for HTML::SuperForm::Field,
not as a field like Text or Select etc.) then you have to tell the
form object to use it. Also, if you do that, make sure you write
your own field classes (Text, Select etc.). Consult documentation
for HTML::SuperForm::Field for more on this.
FIELD METHODS
These methods return objects with their string operators overloaded to
output HTML.
*text(%args)*, *text(\%args)*
Returns an HTML::SuperForm::Field::Text object.
*textarea(%args)*, *textarea(\%args)*
Returns an HTML::SuperForm::Field::Textarea object.
*hidden(%args)*, *hidden(\%args)*
Returns an HTML::SuperForm::Field::Hidden object.
*password(%args)*, *password(\%args)*
Returns an HTML::SuperForm::Field::Password object.
*select(%args)*, *select(\%args)*
Returns an HTML::SuperForm::Field::Select object.
*checkbox(%args)*, *checkbox(\%args)*
Returns an HTML::SuperForm::Field::Checkbox object.
*radio(%args)*, *radio(\%args)*
Returns an HTML::SuperForm::Field::Radio object.
*checkbox_group(%args)*, *checkbox_group(\%args)*
Returns an HTML::SuperForm::Field::CheckboxGroup object.
*radio_group(%args)*, *radio_group(\%args)*
Returns an HTML::SuperForm::Field::RadioGroup object.
*submit(%args)*, *submit(\%args)*
Returns an HTML::SuperForm::Field::Submit object.
EXAMPLES
This example shows how to make a form object that can generate a counter
field along with all the other basic fields. A counter field consists of
a text field, an increment button and a decrement button. Consult the
documentation for HTML::SuperForm::Field for more information about
field inheritance.
package myForm;
use strict;
use myForm::Counter;
use base 'HTML::SuperForm';
sub counter {
return myForm::Counter->new(@_);
}
sub javascript {
my $js = <
function Increment(field) {
field.value++;
}
function Decrement(field) {
field.value--;
}
END_JAVASCRIPT
return $js;
}
1;
package myForm::Counter;
use strict;
use base 'HTML::SuperForm::Field';
use HTML::SuperForm::Field::Text;
sub prepare {
my $self = shift;
my $form_name = $self->form->name;
my $field_name = $self->name;
my $js_name = "document.$form_name.$field_name";
my $text = HTML::SuperForm::Field::Text->new(name => $self->name, default => $self->value, size => 4);
$self->set(text => $text);
$self->set(inc => qq|
|);
$self->set(dec => qq|
|);
}
sub inc {
my $self = shift;
return $self->get('inc');
}
sub dec {
my $self = shift;
return $self->get('dec');
}
sub text {
my $self = shift;
return $self->get('text');
}
sub arrows_right {
my $self = shift;
my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
my $tag = "\n";
$tag .= qq| \n|;
$tag .= qq| | $text | \n|;
$tag .= qq| $inc
$dec | \n|;
$tag .= qq|
\n|;
$tag .= "
\n";
return $tag;
}
sub arrows_left {
my $self = shift;
my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
my $tag = "\n";
$tag .= qq| \n|;
$tag .= qq| $inc
$dec | \n|;
$tag .= qq| $text | \n|;
$tag .= qq|
\n|;
$tag .= "
\n";
return $tag;
}
sub default_layout {
my $self = shift;
my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');
my $tag = "\n";
$tag .= qq| | $inc |
\n|;
$tag .= qq| | $text |
\n|;
$tag .= qq| | $dec |
\n|;
$tag .= "
\n";
return $tag;
}
sub to_html {
my $self = shift;
my $tag = $self->default_layout;
return $tag;
}
1;
This might seem complex but by using it this way you get the following
functionality:
package myHandler;
use strict;
use myForm;
use Apache::Constants qw(OK);
use Template;
sub handler($$) {
my $self = shift;
my $r = shift;
my $form = myForm->new($r);
my $tt = Template->new(INCLUDE_PATH => '/my/template/path');
my $output;
$tt->process('my_template.tt', { form => $form }, \$output);
$r->content_type('text/html');
$r->send_http_header();
$r->print($output);
return OK;
}
1;
my_template.tt:
Flexibility with HTML::SuperForm
[% form.javascript %]
[% form.start_form %]
Default Counter Layout: [% form.counter(name => 'counter1', default => 0) %]
Counter with increment/decrement buttons on the left: [% form.counter(name => 'counter2', default => 0).arrows_left %]
Counter with increment/decrement buttons on the right: [% form.counter(name => 'counter3', default => 0).arrows_right %]
Counter with multiple increment/decrement buttons wherever you want:
[% counter = form.counter(name => 'counter4', default => 0) %]
| [% counter.inc %] | | [% counter.inc %] |
| | [% counter.text %] |
| [% counter.dec %] | | [% counter.dec %] |
[% form.submit %]
[% form.end_form %]
SEE ALSO
HTML::SuperForm::Field,
HTML::SuperForm::Field::Text,
HTML::SuperForm::Field::Textarea,
HTML::SuperForm::Field::Select,
HTML::SuperForm::Field::Checkbox,
HTML::SuperForm::Field::Radio,
HTML::SuperForm::Field::CheckboxGroup,
HTML::SuperForm::Field::RadioGroup
TODO
Document its usage for fully. Give more examples.
AUTHOR
John Allwine