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";
        <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;
        }

        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";
        <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($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 = <<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>

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 <jallwine86@yahoo.com>

