view release on metacpan or  search on metacpan

lib/HTML/FormTemplate.pm  view on Meta::CPAN

always used instead of persistant user input for subsequent form invocations.
You can use FORCE as an alias for OVERRIDE with all field types.

=head2 labels

This list/hash argument provides user-visible text that appears in 
selection-type fields; these list elements correspond to VALUES elements.
If this argument is not provided, the actual VALUES are used as labels.

=head2 nolabels

This boolean argument suppresses any field value labels from showing with single 
or groups of checkboxes or radio buttons.

=head2 tag_attr

This optional argument is a hash ref containing miscellaneous html attributes 
which will be inserted into new form field tags as-is; for field groups these 
are replicated across all of the group members just as NAME is.  Similarly, 
any named arguments which are not explicitely recognized by this class are 
treated as html tag attributes as well; note that in the case of a name 
conflict, the attributes that are pre-existing in TAG_ATTR have lower precedence.
Use TAG_ATTR if you want to pass tag attributes which begin with a "-", as such 
prefixes are removed from normal named method arguments.  Under most 
circumstances, any [size, maxlength, rows, cols/columns, multiple] arguments 
are moved into here.

=head2 min_grp_count

When this numerical argument is defined, methods that make form group fields will
make sure that there are at least this many group members; otherwise, there are
as many group members made as the greater of 1 and the count of DEFAULTS.  This
argument can not be used with checkbox_group and radio_group since they always
have as many group members as VALUES elements.

=head2 list

When this boolean argument is true, methods that make form field groups will 
return their results in an array ref rather than a string, with the html for 
each group member in a separate array element.  Using this lets you delimit the 
fields in any way you choose, rather than only the ways this class understands.

=head2 linebreak

When this boolean argument is true, methods that make form field groups will 
join the html for all group members into a string with the members being 
delimited by linebreaks, that is, '<br />' tags.

=head2 table_cols, table_rows, table_acrf

When either TABLE_COLS or TABLE_ROWS is set, methods that make form field groups 
will arrange the html for all group members into a table using the 
make_table_from_list() method.  The above three arguments correspond to [COLS, 
ROWS, ACROSS] arguments respectively of that method.  For checkbox_group and 
radio_group only, you can use COLS/COLUMNS and ROWS as aliases for the first two.

=head1 PROPERTIES FOR USER-INPUT VALIDATION

In cases where user input has been evaluated to be in error, a visual cue is
provided to the user in the form of a question mark ("?") that this is so. 
You need to make your own legend explaining this where appropriate.
See bad_input_marker().  Note that any empty strings are filtered from the 
user input prior to any validation checks are done.

=head2 is_required

This boolean property is an assertion that the field must be filled in by the 
user, or otherwise there is an error condition.  A visual cue is provided to 
the user in the form of an asterisk ("*") that this is so.  You need to make
your own legend explaining this where appropriate.  See required_field_marker().

=head2 req_min_count, req_max_count

These numerical properties are assertions of how few or many members of field 
groups must be filled in or options selected by the user, or otherwise there is 
an error condition.  Each property can be used independently or together.

=head2 req_opt_match

This boolean property is an assertion that the user input returned from 
selection fields or groups must match the list of VALUES provided for that 
field; if there is any user input that doesn't match, there is an error 
condition.  You can use this to check if users are trying to "cheat" by manually 
providing selection values, or otherwise check for different error conditions.

=head2 validation_rule

This string property is a Perl 5 regular expression that is applied to the 
user input, one group member at a time.  If it evaluates to false on any of 
them then an error condition is present.  If the regular expression fails to 
compile then Perl will throw an exception automatically during runtime of the 
input validation routines.  You should error-check your regular expressions 
before passing them to field_definitions().

=head1 PROPERTIES FOR NON-FIELD HTML IN FORMS AND REPORTS

These properties are only used by make_html_input_form(), make_html_input_echo(), 
and make_text_input_echo().  Likewise, the "visual cues" mentioned in the 
previous section only appear in make_html_input_form().

=head2 visible_title

This string is the "main title" or "name" or "question" or "prompt"
that is visually associated with a form field or field group that lets the user
know what the field is for.  It is printed in bold type with a colon (":")
appended on the end.  This title is also used with the input echo reports, as a
label or heading for each piece of user input.

=head2 help_message

This string is an optional sentance or three that helps
the user further, such as explaining the reason for this' fields existence, or by
providing examples of valid input.  It is printed in smaller type and enclosed in
parenthesis.

=head2 error_message

This string is an optional sentance or three that only
appears when the user didn't enter invalid input.  It helps the user further,
such as explaining what they did wrong or giving examples of valid input.  It is
printed in smaller type.

=head2 str_above_input

This optional string is HTML code that gets inserted directly before input field 
HTML while generating a complete form.  One possible use of this could be to 
store a <DIV> tag above the field.

=head2 str_below_input

This optional string is HTML code that gets inserted directly after input field 
HTML while generating a complete form.  One possible use of this could be to 
store a </DIV> tag below the field.

=head2 is_private

This boolean property results in a visual cue provided to the user in the form
of a tilde ("~"), that you don't intend to make the contents of that field
public.  You need to make your own legend explaining this where appropriate.
See private_field_marker().

=head2 exclude_in_echo

This boolean property is an assertion that this field's value will
never be shown when reports are generated.  This provides an alternative to the
more messy redefining of the form field definitions that would otherwise be
required to exclude fields that aren't private or hidden or buttons.  Normally
the calling code is manually displaying the information from fields excluded this
way in a location outside the report html.

=head1 COMPARISONS WITH CGI.PM

The methods of this class and their parameters are designed to be compatible with
any same-named methods in the popular CGI.pm class. This class will produce
browser-compatible (and often identical) HTML from such methods, and this class
can accept all the same argument formats.  Exceptions to this include:

=over 4

=item 0

None of our methods are exported and must be called using object
notation, whereas CGI.pm can export any of it's methods.

=item 0

We save in module complexity by not talking to any global variables or
files or users directly, expecting rather that the calling code will do this. 
Methods that generate HTML will return their results so the caller can print them
on their own terms, allowing greater control.  The calling code must obtain and
provide the user's submitted input from previous form incarnations, usually with
the user_input() accessor method.  If that method is used prior to generating
html, then the html methods will behave like those in CGI.pm do when instantiated
with a query string, or automatically, or when the "params" were otherwise
manipulated.  The caller must provide the url that the form submits to, usually
with the form_submit_url() accessor method, or the default for this value is 
"127.0.0.1".  That method must be used prior to methods that generate entire
forms, in order for them to work as desired.  By contrast, CGI.pm uses the
current script's url as the default.  Of course, if you build forms
piece-by-piece and call start_form() yourself, you can give it the "action"
argument, which overrides the corresponding property.

=item 0

start_form() doesn't provide a default value for the "encoding" argument,
so if the calling code doesn't provide one then it isn't used.  By contrast,
CGI.pm provides a default encoding of "application/x-www-form-urlencoded".

=item 0

We generally provide a B<lot> more aliases for named arguments to the form field
making methods, and these are detailed in the METHODS NAMED AFTER FIELD-TYPES
part of this documentation.  This is partly to maintain backwards compatability
with the aliases that CGI.pm uses, and partly to provide a more consistant
argument names between the various methods, something that CGI.pm doesn't always
do.  For example, "value" is an alias for "default" in every method where they
don't mean different things.  Another example is that the singular and plural
versions of the [default, value, label, nolabel] arguments are always aliases for
each other. Another reasoning for this aliasing is to provide a consistant