HTML::SuperForm(3)

📦

version 1.09 · 2 versions

1.09 · fedora 43 (latest)
1.09 · fedora 44

💖 HTML::SuperForm 💖 — the `HTML::SuperForm(3)` page, part 1

okay so bestie, you found the manual for HTML::SuperForm and lemme tell you, this thing slaps. let's get into it 💅

✨ NAME ✨

HTML::SuperForm — HTML form generator 🎀

like. it generates HTML forms. that's the whole serve. iconic behavior honestly.

🌸 SYNOPSIS 🌸

here's the tea, in code form:

    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;

two whole vibes: the mod_perl handler way, OR the plain ol' script way. pick your fighter 🥊

🦋 DESCRIPTION 🦋

So. Used in its basic form, this module gives you an interface for generating basic HTML form elements — much like HTML::StickyForms does. the main difference? HTML::SuperForm returns HTML::SuperForm::Field objects instead of plain HTML. which is lowkey huge, because it means way more flexibilty when you're 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 that generates your own custom fields. if you don't use it that way… I guess there's really nothing Super about it 😭. Examples 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. we love range 💅

👑 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. > ⚠️ yes bestie that's a real limitation, read it twice.
- 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 => BAqCheckForm() ), $form->target will return 'newWindow', and $form->onSubmit will return BAqCheckForm()). The names are case sensitive so be consistent. 💀 fr fr, case sensitive.

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. thoughtful queen behavior 👑

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. iykyk — if you know, you know 💅

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. which is the part that's actually iconic, no cap.

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.

…to be continued, bestie 💖

🧪 EXAMPLES 🧪

okay bestie, this is the glow-up section 💖 This example shows how to make a form object that can generate a counter field along with all the other basic fields. And what even is a counter field? It's literally a text field, an increment button, and a decrement button — that's the whole trio, no cap 🎀 If you wanna go deeper on field inheritance, go read the documentation for HTML::SuperForm::Field, they explain it better than I ever could 🫶

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;

ngl this might seem complex 😭 but the way that using it like this gives you the following functionality? iconic. periodt ✨

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;

and then the template file itself, 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 👀

go read your sisters, they're all slaying 💅

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 📝

the to-do list, aka the "someone please" list 🥺

Document its usage for fully.
Give more examples.

💖 AUTHOR 💖

John Allwine <jallwine86@yahoo.com> — the mastermind, the main character, the one who wrote this whole thing 👑

⚖️ 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.

and that's a wrap, bestie 🎀✨ this whole page comes to you courtesy of perl v5.42.0, dated 2025-07-25 — HTML::SuperForm(3), go build something cute with it 🦋💜

📦 where this page comes from

fedora 43: perl-HTML-SuperForm 1.09-45.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms