NAME

HTML::FormTemplate - Store definition, make persist forms, report

DEPENDENCIES

Perl Version

5.004

Standard Modules

I<none>

Nonstandard Modules

Class::ParamParser 1.03
HTML::EasyTags 1.03
Data::MultiValuedHash 1.03
CGI::MultiValuedHash 1.03

SYNOPSIS

use strict;

use HTML::FormTemplate;

my @definitions = (
	{
		visible_title => "What's your name?",
		type => 'textfield',
		name => 'name',
	}, {
		visible_title => "What's the combination?",
		type => 'checkbox_group',
		name => 'words',
		'values' => ['eenie', 'meenie', 'minie', 'moe'],
		default => ['eenie', 'minie'],
	}, {
		visible_title => "What's your favorite colour?",
		type => 'popup_menu',
		name => 'color',
		'values' => ['red', 'green', 'blue', 'chartreuse'],
	}, {
		type => 'submit', 
	},
);

my $query_string = '';
if( $ENV{'REQUEST_METHOD'} =~ /^(GET|HEAD)$/ ) {
	$query_string = $ENV{'QUERY_STRING'};
} else {
	read( STDIN, $query_string, $ENV{'CONTENT_LENGTH'} );
}

my $form = HTML::FormTemplate->new();
$form->form_submit_url( $ENV{'SCRIPT_NAME'} );
$form->field_definitions( \@definitions );
$form->user_input( $query_string );

my ($mail_worked, $mail_failed);
unless( $form->new_form() ) {
	if( open( MAIL, "|/usr/lib/sendmail -t") ) {
		print MAIL "To: perl\@DarrenDuncan.net\n";
		print MAIL "From: perl\@DarrenDuncan.net\n";
		print MAIL "Subject: A Simple Example Submission\n";
		print MAIL $form->make_text_input_echo()."\n";
		close ( MAIL );
		$mail_worked = 1;
	} else {
		$mail_failed = 1;
	}
}

print
	'Content-type: text/html'."\n\n",
	$form->prologue_tag,
	$form->html_start, 
	$form->head_start,
	$form->title( 'A Simple Example' ),
	$form->head_end, 
	$form->body_start,
	$form->h1( 'A Simple Example' ),
	$form->make_html_input_form( 1 ),
	$form->hr,
	$form->new_form() ? '' : $form->make_html_input_echo( 1 ),
	$mail_worked ? "<P>Your favorites were emailed.</P>\n" : '',
	$mail_failed ? "<P>Error emailing your favorites.</P>\n" : '',
	$form->body_end, 
	$form->html_end;

DESCRIPTION

This Perl 5 object class can create web fill-out forms as well as parse, error-check, and report their contents. Forms can start out blank or with initial values, or by repeating the user's last input values. Facilities for interactive user-input-correction are also provided.

The class is designed so that a form can be completely defined, using field_definitions(), before any html is generated or any error-checking is done. For that reason, a form can be generated multiple times, each with a single function call, while the form only has to be defined once. Form descriptions can optionally be read from a file by the calling code, making that code a lot more generic and robust than code which had to define the field manually.

OVERVIEW

If the calling code provides a MultiValuedHash object or HASH ref containing the parsed user input from the last time the form was submitted, via user_input(), then the newly generated form will incorporate that, making the entered values persistant. Since the calling code has control over the provided "user input", they can either get it live or read it from a file, which is transparent to us. This makes it easy to make programs that allow the user to "come back later" and continue editing where they left off, or to seed a form with initial values. (Field definitions can also contain initial values.)

Based on the provided field definitions, this module can do some limited user input checking, and automatically generate error messages and help text beside the appropriate form fields when html is generated, so to show the user exactly what they have to fix. The "error state" for each field is stored in a hash, which the calling code can obtain and edit using invalid_input(), so that results of its own input checking routines are reflected in the new form.

This class also provides utility methods that you can use to create form field definitions that, when fed back to this class, generates field html that can be used by CGI scripts to allow users with their web browsers to define other form definitions for use with this class.

Note that this class is a subclass of both Class::ParamParser and HTML::EasyTags, and inherits all of their methods.

HTML CODE FROM SYNOPSIS PROGRAM

Content-type: text/html


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<HTML>
<HEAD>
<TITLE>A Simple Example</TITLE>
</HEAD>
<BODY>
<H1>A Simple Example</H1>
<FORM METHOD="post" ACTION="localhost">
<TABLE CELLSPACING="5">
<INPUT TYPE="hidden" NAME=".is_submit" VALUE="1">
<TR>
<TD VALIGN="top" ALIGN="left"></TD>
<TD VALIGN="top" ALIGN="left">
<STRONG>What's your name?:</STRONG></TD>
<TD VALIGN="top" ALIGN="left">
<INPUT TYPE="text" NAME="name"></TD></TR>
<TR>
<TD VALIGN="top" ALIGN="left"></TD>
<TD VALIGN="top" ALIGN="left">
<STRONG>What's the combination?:</STRONG></TD>
<TD VALIGN="top" ALIGN="left">
<INPUT TYPE="checkbox" NAME="words" CHECKED VALUE="eenie">eenie
<INPUT TYPE="checkbox" NAME="words" VALUE="meenie">meenie
<INPUT TYPE="checkbox" NAME="words" CHECKED VALUE="minie">minie
<INPUT TYPE="checkbox" NAME="words" VALUE="moe">moe</TD></TR>
<TR>
<TD VALIGN="top" ALIGN="left"></TD>
<TD VALIGN="top" ALIGN="left">
<STRONG>What's your favorite colour?:</STRONG></TD>
<TD VALIGN="top" ALIGN="left">
<SELECT NAME="color" SIZE="1">
<OPTION VALUE="red">red
<OPTION VALUE="green">green
<OPTION VALUE="blue">blue
<OPTION VALUE="chartreuse">chartreuse
</SELECT></TD></TR>
<TR>
<TD VALIGN="top" ALIGN="left"></TD>
<TD VALIGN="top" ALIGN="left"></TD>
<TD VALIGN="top" ALIGN="left">
<INPUT TYPE="submit" NAME="nonamefield001"></TD></TR>
</TABLE>
</FORM>
<HR>
</BODY>
</HTML>

RECOGNIZED FORM FIELD TYPES

This class recognizes 10 form field types, and a complete field of that type can be made either by providing a "field definition" with the same "type" attribute value, or by calling a method with the same name as the field type. Likewise, groups of related form fields can be made with either a single field definition or method call, for 6 of those field types.

Standalone fields of the following types are recognized:

0

reset - makes a reset button

0

submit - makes a submit button

0

hidden - makes a hidden field, which the user won't see

0

textfield - makes a text entry field, one row high

0

password_field - same as textfield except contents are bulleted out

0

textarea - makes a big text entry field, several rows high

0

checkbox - makes a standalone check box

0

radio - makes a standalone radio button

0

popup_menu - makes a popup menu, one item can be selected at once

0

scrolling_list - makes a scrolling list, multiple selections possible

Groups of related fields of the following types are recognized:

0

hidden_group - makes a group of related hidden fields

0

textfield_group - makes a group of related text entry fields

0

password_field_group - makes a group of related password fields

0

textarea_group - makes a group of related big text entry fields

0

checkbox_group - makes a group of related checkboxes

0

radio_group - makes a group of related radio buttons

Other field types aren't intrinsicly recognized, but can still be generated as ordinary html tags by calling a method with the name of that tag. A list of all the valid field types is returned by the valid_field_type_list() method.

SYNTAX

This class does not export any functions or methods, so you need to call them using object notation. This means using Class->function() for functions and $object->method() for methods. If you are inheriting this class for your own modules, then that often means something like $self->method().

Methods of this class always "return" their results, rather than printing them out to a file or the screen. Not only is this simpler, but it gives the calling code the maximum amount of control over what happens in the program. They may wish to do post-processing with the generated HTML, or want to output it in a different order than it is generated.

SPECIAL FIELD DEFINITION PARAMETERS

In addition to the form field parameters shown in the next section, there are several additional ones that are only used when this class generates an entire form or echoing report at once, or when it does user input checking:

0

is_required - boolean - 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 a blue asterisk ("*"), that this is so. You need to make your own legend explaining this where appropriate.

0

is_private - boolean - A visual cue is provided to the user in the form of a green 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.

0

validation_rule - string - A Perl 5 regular expression that is applied to user input, and if it evaluates to false then an error condition is present. 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 red question mark ("?"), that this is so. You need to make your own legend explaining this where appropriate.

0

visible_title - string - This is the "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.

0

help_message - string - This 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.

0

error_message - string - This 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 and is colored red.

0

exclude_in_echo - boolean - 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.

FORM FIELD PARAMETERS PREFACE

When form field html is generated by calling a method with the same name as the field type, several method parameter formats are supported, including named arguments and positional parameters. When using named parameters, the parameter name can optionally be preceeded by a "-". See the documentation for Class::ParamParser for details. Not all parameters are supported in positional format, so that is only sometimes suitable.

When a form field is being defined in advance using field_definitions(), then only the named format is acceptable, and the names must not be preceeded by a "-", or they won't be recognized. Additionally, parameter names are case sensitive when used in field_definitions(), so make them entirely lowercase. The uppercase names below are just for ease of visibility.

When using field definitions, a "type" parameter should be provided in a definition, or "textfield" will be used by default. Also, if a field "name" isn't provided, then "nonamefieldNNN" will be used by default. This is fine only if you don't need to reference fields by name in your own code.

In either case, many field parameters can accept aliases to their names, when using named format, and this varies by field type. You must never use more than one alias for a parameter in a single field definition, or confusion will result and all but one of them will be lost.

Note that the form field name ".is_submit" is reserved for internal use by this class, so do not use it!

PARAMETERS BY FIELD TYPE

The listings below show known positional arguments, inside the parenthesis, and known named arguments, in the vertical list below. When brackets appear to group several named arguments, they indicate that all of them are aliases for each other.

But first, here is a brief description of each argument you will see. Given that the same named argument can have different meanings for different field types, the following descriptions are only valid when the argument name is the one on the very left of alias names for a field:

0

type - string - What field type this is. Same as the method names.

0

name - string - Name for the field that the browser/script cares about.

0

defaults - array - Optional default values for multi-valued fields.

0

default - scalar - Same as defaults except for single-valued fields.

0

values - array - Required values for selection-type fields, that the browser/script care about, including checkbox, radio, popup menu, scrolling list.

0

value - scalar - Same as value except for single-valued fields.

0

size - number - Two possibilities: 1. Visible width of text entry fields in characters. 2. Visible height of scrolling list in characters.

0

maxlength - number - Maximum characters that can be in text fields.

0

rows - number - Height of textarea fields in characters.

0

cols - number - Width of textarea fields in characters.

0

multiple - boolean - User may choose several scrolling list items?

0

labels - array - User-visible text that appears in selection-type fields; these elements correspond to elements in the values argument. If this argument is not provided, the actual values are used as labels.

0

label - array - Same as labels but for single-valued fields.

0

nolabels - boolean - Suppresses any field value labels from showing.

0

override - boolean - Ensures that default values are always used instead of persistant user input.

0

linebreak - boolean - Delimit members of field groups with linebreak?

0

list - boolean - Force field group html to be returned as an array ref rather than a string, with the html for each field in a separate array element. This lets you delimit the fields in any way you choose. This option can cause strange results when used with the methods that return a whole form at once, so use it with care.

reset( NAME, DEFAULT )

NAME
[DEFAULT or VALUE or LABEL]

submit( NAME, DEFAULT )

NAME
[DEFAULT or VALUE or LABEL]

hidden( NAME, DEFAULT )

NAME
[DEFAULT or VALUE]

textfield( NAME, DEFAULT, SIZE, MAXLENGTH )

NAME
[DEFAULT or VALUE]
SIZE
MAXLENGTH
[OVERRIDE or FORCE]

password_field( NAME, DEFAULT, SIZE, MAXLENGTH )

NAME
[DEFAULT or VALUE]
SIZE
MAXLENGTH
[OVERRIDE or FORCE]

textarea( NAME, DEFAULT, ROWS, COLS )

NAME
[DEFAULT or VALUE or TEXT]
ROWS
[COLS or COLUMNS]
[OVERRIDE or FORCE]

checkbox( NAME, DEFAULT, VALUE, LABEL )

NAME
VALUE
[DEFAULT or CHECKED or SELECTED or ON]
[LABEL or TEXT]
NOLABEL
[OVERRIDE or FORCE]

radio( NAME, DEFAULT, VALUE, LABEL )

NAME
VALUE
[DEFAULT or CHECKED or SELECTED or ON]
[LABEL or TEXT]
NOLABEL
[OVERRIDE or FORCE]

popup_menu( NAME, DEFAULTS, VALUES, LABELS )

NAME
[VALUES or VALUE]
[DEFAULTS or DEFAULT or CHECKED or SELECTED or ON]
[LABELS or LABEL or TEXT]
[OVERRIDE or FORCE]

scrolling_list( NAME, DEFAULTS, VALUES, LABELS )

NAME
[VALUES or VALUE]
[DEFAULTS or DEFAULT or CHECKED or SELECTED or ON]
[LABELS or LABEL or TEXT]
SIZE
MULTIPLE
[OVERRIDE or FORCE]

hidden_group( NAME, DEFAULTS )

NAME
[DEFAULTS or DEFAULT or VALUES or VALUE]
LIST

textfield_group( NAME, DEFAULTS, LINEBREAK, SIZE, MAXLENGTH )

NAME
[DEFAULTS or DEFAULT or VALUES or VALUE]
SIZE
MAXLENGTH
[OVERRIDE or FORCE]
LINEBREAK
LIST

password_field_group( NAME, DEFAULTS, LINEBREAK, SIZE, MAXLENGTH )

NAME
[DEFAULTS or DEFAULT or VALUES or VALUE]
SIZE
MAXLENGTH
[OVERRIDE or FORCE]
LINEBREAK
LIST

textarea_group( NAME, DEFAULTS, LINEBREAK, ROWS, COLS )

NAME
[DEFAULTS or DEFAULT or VALUES or VALUE or TEXT]
ROWS
[COLS or COLUMNS]
[OVERRIDE or FORCE]
LINEBREAK
LIST

checkbox_group( NAME, VALUES, DEFAULTS, LINEBREAK, LABELS )

NAME
[VALUES or VALUE]
[DEFAULTS or DEFAULT or CHECKED or SELECTED or ON]
[LABELS or LABEL or TEXT]
[NOLABELS or NOLABEL]
[OVERRIDE or FORCE]
LINEBREAK
LIST

radio_group( NAME, VALUES, DEFAULTS, LINEBREAK, LABELS )

NAME
[VALUES or VALUE]
[DEFAULTS or DEFAULT or CHECKED or SELECTED or ON]
[LABELS or LABEL or TEXT]
[NOLABELS or NOLABEL]
[OVERRIDE or FORCE]
LINEBREAK
LIST

FUNCTIONS AND METHODS

new()

This function creates a new HTML::FormTemplate object and returns it.

initialize()

This method is used by new() to set the initial properties of an object, that it creates.

clone([ CLONE ])

This method initializes a new object to have all of the same properties of the current object and returns it. This new object can be provided in the optional argument CLONE (if CLONE is an object of the same class as the current object); otherwise, a brand new object of the current class is used. Only object properties recognized by HTML::FormTemplate are set in the clone; other properties are not changed.

positional_by_default([ VALUE ])

This method is an accessor for the boolean "positional arguments" property of this object, which it returns. If VALUE is defined, this property is set to it. With methods whose parameters could be either named or positional, when we aren't sure what we are given, do we guess positional? Default is named.

field_definitions([ DEFIN ])

This method is an accessor for the "field definitions" list property of this object, which it returns. If DEFIN is defined, this property is set to it. This property is a list of either MultiValuedHash objects or HASH refs, each of which contains a description for one field or field group that is to be made. Fields will be processed in the same order they appear in this list. The list is empty by default. The method also clears any error conditions.

fields_normalized()

This method returns true if the field definitions have been "normalized". The boolean property that tracks this condition is false by default and only becomes true when normalize_field_definitions() is called. It becomes false when field_definitions() is called.

reset_to_new_form()

This method sets the boolean property "new form" to true, wipes out any user input (putting form to factory defaults), and clears all error conditions. You can use this method to implement your own "defaults" button if you wish.

user_input([ INPUT ])

This method is an accessor for the "user input" property of this object, which it returns. If INPUT is defined, this property is set to it. This property is a single MultiValuedHash object or HASH ref whose keys are the form fields that the user filled in and whose values are what they entered. These values are used when creating form field html to preserve what the user previously entered, and they are used when doing our own input checking, and they are used when generating input echo reports. This property is also examined when it is set and automatically changes the "new form" property accordingly. The property is undefined by default. The method also clears any error conditions.

new_form([ VALUE ])

This method is an accessor for the boolean "new form" property of this object, which it returns. If VALUE is defined, this property is set to it. If this property is true, then we act like this is the first time we were called. That means that the form is blank except for factory defaults, and there are no error conditions. If this property is false then we are being called again after the user submitted the form at least once, and we do perform input checking. This property is true by default. No other properties are changed.

invalid_input([ NAMES ])

This method is an accessor for the "invalid input" property of this object, which it returns. If NAMES is a valid hash ref, this property is set to it. This property is a hash that indicates which fields have invalid input. The property is undefined by default, and is set when validate_form_input() is called. The optional NAMES argument lets you override the internal input checking to apply your own input checking. If you want both to happen, then call it once with no arguments (internal is automatically done), then edit the results, then call this again providing your new hash as an argument.

field_html([ NAME ])

This method returns generated html code for form fields that were defined using field_definitions(). If NAME is defined it only returnes code for the field (or group) with that name; otherwise it returns a list of html for all fields. This is useful if you want to define your form fields ahead of time, but still want to roll your own complete form.

form_submit_url([ VALUE ])

This method is an accessor for the scalar "submit url" property of this object, which it returns. If VALUE is defined, this property is set to it. This property defines the URL of a processing script that the web browser would use to process the generated form. The default value is "localhost".

form_submit_method([ VALUE ])

This method is an accessor for the scalar "submit method" property of this object, which it returns. If VALUE is defined, this property is set to it. This property defines the method that the web browser would use to submit form data to a processor script. The default value is "post", and "get" is the other option.

normalize_field_definitions()

This method edits the "field definitions" such that any fields without names are given one (called "nonamefieldNNN"), any unknown field types become textfields, and any special fields we use internally are created. It returns true when finished. This method is called by any input checking or html making routines if "normalized" is false because it is a precondition for them to work properly.

validate_form_input()

This method sets the "invalid input" property by applying the "is requrired" and "validation rule" field attributes to the user input for those fields. If "new form" is true then all fields are declared to be error free. It returns a count of the number of erroneous fields, and 0 if there are no errors. This method is called by make_html_input_form() and invalid_input() if "invalid input" is false because it is a precondition for them to work properly.

make_field_html()

This method goes through all the fields and has html made for them, then puts it away for those that need it, namely make_html_input_form() and field_html(). It returns a count of the number of fields generated, which includes all hidden fields and buttons.

make_html_input_form([ TABLE[, FORCE] ])

This method returns a complete html input form, including all form field tags, reflected user input values, various text headings and labels, and any visual cues indicating special status for various fields. The first optional boolean argument, TABLE, says to return the form within an HTML table, with one field or field group per row. Field headings and help text appear on the left and the field or group itself appears on the right. All table cells are top-left-aligned, and no widths or heights are specified. If TABLE is false then each field or group is returned in a paragraph that starts with its title. The second optional boolean argument, FORCE, causes the resulting form body to be returned as an array ref whose elements are pieces of the page. If this is false then everything is returned in a single scalar.

make_html_input_echo([ TABLE[, EXCLUDE[, EMPTY[, FORCE]]] ])

This method returns a complete html-formatted input "echo" report that includes all the field titles and reflected user input values. Any buttons or hidden fields are excluded. There is nothing that indicates whether the user input has errors or not. There is one heading per field group, and the values from each member of the group are displayed together in a list. The first optional boolean argument, TABLE, says to return the report within an HTML table, with one field or field group per row. All table cells are top-left-aligned, and no widths or heights are specified. If TABLE is false then each field or group input is returned in a paragraph that starts with its title. The second optional boolean argument, EXCLUDE, ensures that any fields that were defined to be "private" are excluded from this report; by default they are included. The third optional string argument, EMPTY, specifies the string to use in place of the user's input where the user left the field empty; by default nothing is shown. The fourth optional boolean argument, FORCE, causes the resulting form body to be returned as an array ref whose elements are pieces of the page. If this is false then everything is returned in a single scalar.

make_text_input_echo([ EXCLUDE[, EMPTY[, FORCE]] ])

This method returns a complete plain-text-formatted input "echo" report that includes all the field titles and reflected user input values. This report is designed not for web display but for text reports or for inclusion in e-mail messages. Any buttons or hidden fields are excluded. There is nothing that indicates whether the user input has errors or not. There is one heading per field group, and the values from each member of the group are displayed together in a list. For each field, the title is displayed on one line, then followed by a blank line, then followed by the user inputs. The title is preceeded by the text "Q: ", indicating it is the "question". The first optional boolean argument, EXCLUDE, ensures that any fields that were defined to be "private" are excluded from this report; by default they are included. The second optional string argument, EMPTY, specifies the string to use in place of the user's input where the user left the field empty; by default nothing is shown. The third optional boolean argument, FORCE, causes the resulting form body to be returned as an array ref whose elements are pieces of the page. If this is false then everything is returned in a single scalar, and there is a delimiter placed between each field or group that consists of a line of asterisks ("*").

bad_input_marker()

This method returns the string that is used to visually indicate in which form fields the user has entered invalid input.

required_field_marker()

This method returns the string that is used to visually indicate which form fields are required, and must be filled in by users for the form to be processed.

private_field_marker()

This method returns the string that is used to visually indicate which form fields are private, meaning that their content won't be shown to the public.

start_form([ METHOD[, ACTION] ])

This method returns the top of an HTML form. It consists of the opening 'form' tag. This method can take its optional two arguments in either named or positional format; in the first case, the names look the same as the positional placeholders above, except they must be in lower case. The two arguments, METHOD and ACTION, are scalars which respectively define the method that the form are submitted with and the URL it is submitted to. If either argument is undefined, then the appropriate scalar properties of this object are used instead, and their defaults are "POST" for METHOD and "localhost" for ACTION. See the form_submit_url() and form_submit_method() methods to access these properties.

end_form()

This method returns the bottom of an HTML form. It consists of the closing 'form' tag.

make_input_tag( TYPE, PARAMS[, USER] )

This method is used internally to do the actual construction of all standalone input form fields. You can call it directly when you want faster code and/or more control over how fields are made. The first argument, TYPE, is a scalar that names the field type we are making; it is case-insensitive. Valid types are: [reset, submit, hidden, textfield, password_field, textarea, checkbox, radio, popup_menu, scrolling_list]; an invalid TYPE results in a normal HTML tag with its name being made. The second argument, PARAMS, is an ARRAY ref containing attribute names and values for the new form field; this is identical to the argument list that is passed to methods of this class whose names are the same as the form field types. The third optional argument, USER, is an ARRAY ref containing the values that users would have entered into this same field during this form's previous invocation. These USER values override the field values provided by the "default" property for this field, if present. If the "new form" object property is true, or if this field's "override" property is true, then the USER values are ignored. This method returns a scalar containing the new form field html.

make_input_tag_group( TYPE, PARAMS[, USER] )

This method is used internally to do the actual construction of all groups of related input form fields. You can call it directly when you want faster code and/or more control over how fields are made. The first argument, TYPE, is a scalar that names the field type we are making; it is case-insensitive. Valid types are: [hidden, textfield, password_field, textarea, checkbox, radio]; an invalid TYPE results in a normal HTML tag with its name being made. The second argument, PARAMS, is an ARRAY ref containing attribute names and values for the new form fields; this is identical to the argument list that is passed to methods of this class whose names are the same as the form field types. The third optional argument, USER, is an ARRAY ref containing the values that users would have entered into this same field during this form's previous invocation. Each sequential element in that array will initialize one of the fields in this new group. These USER values override the field values provided by the "default" property for this field, if present. If the "new form" object property is true, or if this field's "override" property is true, then the USER values are ignored. By default, this method returns a scalar containing the concatenated html for all the fields in this group. However, if this field's "list" property is true, then an ARRAY ref is returned instead, with html for one field in each element. Otherwise, if the "linebreak" property is true, then a scalar is returned as by default, except that a "<BR>" tag is inserted between the html for each field.

valid_types([ TYPE ])

This method returns a list of all the form field types that this class can recognize when they are used either in the 'type' attribute of a field definition, or as the name of an html-field-generating method. This list contains the same types listed in the "Recognized Form Field Types" of this documentation. If the optional scalar argument, TYPE, is defined, then this method will instead return true if TYPE is a valid field type or false if not.

valid_multivalue_types([ TYPE ])

This method returns true if a form field of the type defined by the optional scalar argument, TYPE, makes use of multiple values; either presenting them to the user or accepting them for user input. If called without any arguments, this method returns a list of all field types that make use of multiple values.

valid_attributes( TYPE[, ATTRIB] )

This method returns a list of all the form field definition attributes that this class can recognize when they are used in defining a field whose type is defined by the scalar argument, TYPE. If the optional scalar argument, ATTRIB, is defined, then this method will instead return true if ATTRIB is a valid field definition attribute or false if not. The "list" attribute is not included.

make_attribute_definition( ATTRIB, NAME[, COUNT] )

This method returns a form field definition that can be used with this class to make an HTML form field whose user input is a the value (or value list) to give the attribute whose name is defined by the first scalar argument, ATTRIB, in a field definition for any type that uses that attribute. The second scalar argument, NAME, is used in the definition that this method creates as its 'name' attribute. The optional third scalar argument, COUNT, is only useful when the field being ultimately defined is making use of multiple values. The "list" attribute is not included.

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:

0

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

0

See the related HTML::EasyTags documentation on the autoloaded HTML tag making methods, all of which this module inherits.

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 "localhost". 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.

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".

0

We generally provide a lot more aliases for named arguments to the form field making methods, and these are detailed in the FORM FIELD PARAMETERS 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 all arguments which have plural names also take their singular versions as aliases. Another reasoning for this aliasing is to provide a consistant interface for those who are used to giving all the literal HTML names for various arguments, which is exactly what HTML::EasyTags uses. In the cases where our field argument isn't a true HTML argument, and rather is the text that goes outside the tag (such as textarea values or checkbox labels), we accept "text" as aliases, which is the exact convention that HTML::EasyTags uses when you want to specify such text when using named parameters; this makes literalists happy.

0

The arguments "default" and "labels" in our field making methods can be either an ARRAY ref or a HASH ref (or a scalar) and we can handle them appropriately; this choice translates to greater ease of use. By contrast, CGI.pm only takes Hashes for labels.

0

Our checkbox_group and radio_group methods do not recognize the special parameters that CGI.pm uses to organize new fields into tables. These include [rows, columns, rowheaders, colheaders]. We do, however, provide the new "list" argument, meaning that field groups are returned in a list, and the caller can always organize the field html into tables on its own.

0

We don't give special treatment to any of the special JavaScript related parameters to field making methods that CGI.pm does, and so we use them as ordinary and miscellaneous html attributes.

0

We save on complexity and don't have a special field type called "defaults" like CGI.pm does. Rather, calling code can just ask for a "submit" button with an appropriate name, and then call our reset_to_new_form() method if they discover it was clicked on during a previous form invocation. This method has the same effect, wiping out anything the user entered, but the caller has more control over when the wipeout occurs. For that matter, simply not setting the user_input() property would have the same effect.

0

We don't currently make "File Upload" fields or a "Clickable Image" buttons or "Javascript Action" buttons that CGI.pm does, although we make all the other field types. We can still generate the HTML for these, however, if the appropriate autoloaded HTML tag making methods are called. We do make standalone radio buttons, which CGI.pm does not (as a special case like checkbox anyway), and we do make groups of hidden fields, text fields, big text fields, and password fields as well.

0

We can both predefine all fields before generating them, which CGI.pm does not, and we can also define fields as-needed in the same manner that CGI.pm does.

AUTHOR

Copyright (c) 1999-2001, Darren R. Duncan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. However, I do request that this copyright information remain attached to the file. If you modify this module and redistribute a changed version then please attach a note listing the modifications.

I am always interested in knowing how my work helps others, so if you put this module to use in any of your own code then please send me the URL. Also, if you make modifications to the module because it doesn't work the way you need, please send me a copy so that I can roll desirable changes into the main release.

Address comments, suggestions, and bug reports to perl@DarrenDuncan.net.

CREDITS

Thanks to Lincoln D. Stein for setting a good interface standard in the HTML-related methods of his CGI.pm module. I was heavily influenced by his interfaces when designing my own. Thanks also because I borrowed ideas for my Synopsis program from his aforementioned module.

Thanks to Geir Johannessen <geir.johannessen@nextra.com> for alerting me to several obscure bugs in my POD; these only showed up when manifying, whereas MacPerl's Shuck and CPAN's HTMLizer rendered it properly.

SEE ALSO

perl(1), HTML::EasyTags, CGI::MultiValuedHash, Class::ParamParser, Data::MultiValuedHash, CGI, CGI::QuickForm, CGI::Validate.

cpanm HTML::FormTemplate

perl -MCPAN -e shell
install HTML::FormTemplate