view release on metacpan or  search on metacpan

lib/CGI/FormBuilder.pod  view on Meta::CPAN

=item cleanopts => 0 | 1

If set to 1 (the default), field options are escaped to make sure
any special chars don't screw up the HTML. Set to 0 if you want to
include verbatim HTML in your options, and know what you're doing.

=item cookies => 0 | 1

Controls whether to generate a cookie if C<sessionid> has been set.
This also requires that C<header> be set as well, since the cookie
is wrapped in the header. Defaults to 1, meaning it will automatically
work if you turn on C<header>.

=item force => 0 | 1

This is used in conjunction with the C<value> option to forcibly
override a field's value. See below under the C<value> option for
more details. For compatibility with C<CGI.pm>, you can also call
this option C<override> instead, but don't tell anyone.

=item growable => 0 | 1 | $limit

This option adds a button and the appropriate JavaScript code to 
your form to allow the additional copies of the field to be added
by the client filling out the form. Currently, this only works with
C<text> and C<file> field types.

If you set C<growable> to a positive integer greater than 1, that
will become the limit of growth for that field. You won't be able
to add more than C<$limit> extra inputs to the form, and FormBuilder 
will issue a warning if the CGI params come in with more than the
allowed number of values.

=item jsclick => $jscode

This is a cool abstraction over directly specifying the JavaScript
action. This turns out to be extremely useful, since if a field
type changes from C<select> to C<radio> or C<checkbox>, then the
action changes from C<onchange> to C<onclick>. Why?!?!

So if you said:

    $form->field(name    => 'credit_card', 
                 options => \@cards,
                 jsclick => 'recalc_total();');

This would generate the following code, depending on the number
of C<@cards>:

    <select name="credit_card" onchange="recalc_total();"> ...

    <radio name="credit_card" onclick="recalc_total();"> ...

You get the idea.

=item jsmessage => $string

You can use this to specify your own custom message for the field,
which will be printed if it fails validation. The C<jsmessage>
option affects the JavaScript popup box, and the C<message> option
affects what is printed out if the server-side validation fails.
If C<message> is specified but not C<jsmessage>, then C<message>
will be used for JavaScript as well.

    $form->field(name      => 'cc',
                 label     => 'Credit Card',
                 message   => 'Invalid credit card number',
                 jsmessage => 'The card number in "%s" is invalid');

The C<%s> will be filled in with the field's C<label>.

=item label => $string

This is the label printed out before the field. By default it is 
automatically generated from the field name. If you want to be
really lazy, get in the habit of naming your database fields as
complete words so you can pass them directly to/from your form.

=item labels => \%hash

B<This option to field() is outdated.> You can get the same effect by
passing data structures directly to the C<options> argument (see below).
If you have well-named data, check out the C<nameopts> option.

This takes a hashref of key/value pairs where each key is one of
the options, and each value is what its printed label should be:

    $form->field(name    => 'state',
                 options => [qw(AZ CA NV OR WA)],
                 labels  => {
                      AZ => 'Arizona',
                      CA => 'California',
                      NV => 'Nevada',
                      OR => 'Oregon',
                      WA => 'Washington
                 });

When rendered, this would create a select list where the option
values were "CA", "NV", etc, but where the state's full name
was displayed for the user to select. As mentioned, this has
the exact same effect:

    $form->field(name    => 'state',
                 options => [
                    [ AZ => 'Arizona' ], 
                    [ CA => 'California' ],
                    [ NV => 'Nevada' ],
                    [ OR => 'Oregon' ],
                    [ WA => 'Washington ],
                 ]);

I can think of some rare situations where you might have a set
of predefined labels, but only some of those are present in a
given field... but usually you should just use the C<options> arg.

=item linebreaks => 0 | 1

Similar to the top-level "linebreaks" option, this one will put
breaks in between options, to space things out more. This is
useful with radio and checkboxes especially.