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";
    <html>
    <body>
        <form>
        Text Field: $text<br>
        Text Area: $textarea<br>
        Select: $select
        </form>
    </body>
    </html>
    END_HTML


        $r->content_type('text/html');
        $r->send_http_header;

        $r->print($output);
        return OK;
    }

    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";
    <html>
    <body>
        <form>
        Text Field: $text<br>
        Text Area: $textarea<br>
        Select: $select
        </form>
    </body>
    </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($r, $field_object), new($r), 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 = <<END_JAVASCRIPT;
    <script language="JavaScript">
    function Increment(field) {
        field.value++;
    }

    function Decrement(field) {
        field.value--;
    }
    </script>
    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|<a style="cursor: pointer" onmouseup="Increment($js_name)"><img src="/icons/up.gif" border=0></a>|);
        $self->set(dec => qq|<a style="cursor: pointer" onmouseup="Decrement($js_name)"><img src="/icons/down.gif" border=0></a>|);
    }

    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 = "<table>\n";
        $tag .= qq|    <tr>\n|;
        $tag .= qq|        <td align="center">$text</td>\n|;
        $tag .= qq|        <td align="center">$inc<br/>$dec</td>\n|;
        $tag .= qq|    </tr>\n|;
        $tag .= "</table>\n";
        
        return $tag;
    }

    sub arrows_left {
        my $self = shift;

        my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');

        my $tag = "<table>\n";
        $tag .= qq|    <tr>\n|;
        $tag .= qq|        <td align="center">$inc<br/>$dec</td>\n|;
        $tag .= qq|        <td align="center">$text</td>\n|;
        $tag .= qq|    </tr>\n|;
        $tag .= "</table>\n";
        
        return $tag;
    }

    sub default_layout {
        my $self = shift;

        my ($text, $inc, $dec) = $self->get('text', 'inc', 'dec');

        my $tag = "<table>\n";
        $tag .= qq|    <tr><td align="center">$inc</td></tr>\n|;
        $tag .= qq|    <tr><td align="center">$text</td></tr>\n|;
        $tag .= qq|    <tr><td align="center">$dec</td></tr>\n|;
        $tag .= "</table>\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:

    <html>
        <head>
        <title>Flexibility with HTML::SuperForm</title>
        [% form.javascript %]
        </head>
        <body>
        [% form.start_form %]
        Default Counter Layout: [% form.counter(name => 'counter1', default => 0) %] <br/>
        Counter with increment/decrement buttons on the left: [% form.counter(name => 'counter2', default => 0).arrows_left %] <br/>
        Counter with increment/decrement buttons on the right: [% form.counter(name => 'counter3', default => 0).arrows_right %] <br/>
        Counter with multiple increment/decrement buttons wherever you want: <br/>
        [% counter = form.counter(name => 'counter4', default => 0) %]
        <table>
            <tr><td>[% counter.inc %]</td><td></td><td>[% counter.inc %]</tr>
            <tr><td></td><td></td>[% counter.text %]<td></tr>
            <tr><td>[% counter.dec %]</td><td></td><td>[% counter.dec %]</tr>
        </table>
        [% form.submit %]
        [% form.end_form %]
        </body>
    </html>

AUTHOR

John Allwine <jallwine86@yahoo.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.