CGI::EZForm.pm
use CGI::EZForm; $form = CGI::EZForm->new; $form->set(parameters); $form->clear(keys); $form->get(key); $form->dump(keys); $form->receive(); $form->draw(parameters); $form->hidden(list); $form->form_start (parameters); $form->form_end(); $form->table_start (parameters); $form->table_end(); $form->default(parameters); $form->use_table(true|false);
CGI::EZForm.pm provides basic functionality for CGI web form processing.
Yes, you could use the commonly used CGI.pm module by Lincoln Stein, but for many tasks this seems like overkill -- rather like driving a Formula-1 racing car to the supermarket. I wrote CGI::EZForm.pm because I wanted something simple and easy to use.
Some advantages of EZForm are:
EZForm provides intelligent and reasonable (IMHO) defaults for most things. This means that there's a lot of stuff you can leave out if you want minimal typing. E.g. there's a default field type of "text" which means you can omit that for all your text boxes.
All defaults can be changed if you want.
By default, your form input fields are drawn in a 2-column table format, with a label in the left column and the input fields in the right. EZForm will draw all this for you. You only need supply the field definitions, not the formatting. (You DO still need to provide all the other HTML around the form, though. USe CGI.pm if you want something which does everything.
Here's a sample script to demonstrate its use:
#!/usr/local/bin/perl -w # # test script for CGI module # use CGI::EZForm qw(form_start form_end draw); # Create somewhere to put the form data $form = new CGI::EZForm; # Pre-set some form values $form->{station} = 'JJJ'; # Get any form data provided from the browser $form->receive; # Start our web page to be returned to the browser ... print "Content-type: text/html\r\n\r\n"; # probably good practice to add some HTML header etc. here # Now let's print a form ... print $form->form_start(action => '/cgi-bin/test.pl'), $form->draw(type => 'text', name => 'account', label => 'Account number', size => 30), $form->draw(type => 'radio', name => 'station', values => ['JJJ', 'MMM'], captions => ['Triple-J', 'Triple-M']), $form->draw(type => 'select', name => 'choice', label => 'Choose', selected => 'one', options => ['First', 'Second', 'Third'], values => ['one', 'two', 'three']), $form->draw(type => 'submit', value => 'Send'), $form->form_end; exit;
Available methods are:
Creates a new form:
In reality, this just creates a reference to a hash which will hold the field values, so you can access particular form field values directly, as in
$xyz = $form->{xyz};
providing you are not an OOP purist, I guess. (If you are, use the get method.)
allows you to set value on one or more form fields. E.g.
$form->set(me => 'Tarzan', you => 'Jane');
Of course, you can just set individual fields using
which is probably faster.
clears form field values from the form. If called with no parameters, clears all fields, otherwise clears only the named fields. E.g.
$form->clear; # clears all fields $form->clear('name', 'addr'); # clears only the name and addr fields
returns the value of KEY. Included only for the OOP fanatic. Utilitarians will use $form->{KEY} instead to retrieve values directly.
Probably the first call you'll want to make after new, receive will check for incoming data by various methods, and fill your hash with any values it finds.
returns HTML for a form header:
$form->form_start( action => '/cgi/myscript.pl', method => 'POST', enctype => $encoding, name => $name);
Everything can be defaulted except name. 'action' defaults to the current script, which is common enough to be useful, so that you can get away with just
$form->form_start();
This will produce the equivalent of this HTML:
<form action="$ENV{SCRIPT_NAME}" method="POST" enctype="application/x-www-form-urlencoded">
returns the form end tag. If table formatting is on, then it also returns html to close the table.
returns a string of HTML to display a particular form "object" (using the term loosly). draw expects to receive parameters as a hash, probably anonymous. The hash keys should correspond with the attribute names for the html tag being requested, with the addition of "label" to specify a text label for the field, and "caption" for radio and checkbox. Radio and select types are a bit special, in that some of their parameters are lists.
All attributes have reasonable defaults, so you only need to specify those where you want something different from the default.
Note that "value" will always default to the current value for the field name, if any.
Note that every field requires a name (except reset buttons). But, if you omit name, CGI::EZForm will use "assign-dynamic". The request function will detect this and replace it with the value of the field. E.g. "assign-dynamic=fred" will transform into "fred=fred". This may or may not be useful.
Note that you can include any attribute that you think is useful, even if it is not valid HTML. CGI::EZForm.pm doesn't validate these, it just assumes you know what you are doing. Usefully, you can add additional, _valid_ HTML, as in:
$form->draw( ..., onSubmit => 'javascript:...');
Some examples:
Input fields:
$form->draw( type => 'text', name => 'boris', value => 'natasha', size => 30, readonly => 1, label => 'field description' ); will draw an input text field. Note that if you don't specify a value, the current value in $form{boris} will be used. type can be one of 'text', 'password' or 'hidden' (in which case size will be ignored, if present).
Checkbox fields:
$form->draw( type => 'checkbox', name => 'spam', value => 'yes', caption = 'click to receive junk mail', label => 'Tell me more?' );
Radio buttons are a bit more complex, since they usually come in groups:
$form->draw( type => 'radio', name => 'station', values => [ 'JJJ', 'MMM' ], captions => [ 'Triple-J', 'Triple-M' ], vertical = 1, label => 'Choose your station' ); captions appear to the right of the radio button. values are what get returned if the button is "on". vertical will place your radio buttons in a vertical list, otherwise they'll be drawn horizontally.
Selection lists are like radio groups, only different. Aside from the actual formatting, one difference is that select lists allow for multiple values to be selected:
$form->draw( type => 'select', name => 'boris', options => [ 'First', 'Second', 'Third' ], values => [ 'one', 'two', 'three' ], selected => [ 'First', 'Third' ], multiple => 'true', label => 'Choose one or more' ); options is a reference to a list of options values is a reference to a list of values to be returned. selected is a reference to a list of values to be pre-selected. If selected is not specified, a value will be selected if it matches $form->{name}
Buttons:
$form->draw( type => 'image', src => 'file.jpg', name => 'next', value => 'Next'); $form->draw( type => 'submit', name => 'next', value => 'Next'); $form->draw( type => 'reset');
returns html for all your hidden fields, specified in LIST, which should be a list of form field names. This is useful if you have a bunch of hidden fields. It is assumed that $form contains values for all the fields named in LIST. E.g.
$form->set( return_to => $ENV{HTTP_REFERRER}, code => '987'); ... $form->hidden('return_to', 'code');
produces
<input type="hidden" name="return_to" value="some url"> <input type="hidden" name="code" value="987">
To draw hidden fields without pre-setting form values, use the draw function instead. But you'll have to draw them one at a time.
Input fields often look better when laid out in a table, with a label in column 1 and the input field in column 2. use_table can be called to turn table-formatting on or off. E.g.
$form->use_table(0);
You can also call default to toggle table formatting:
$form->default(table => 0);
Note that in neither case, if a table is already started, does the function close the table. You need to call table_start and table_end to explicitly start/end a table.
If desired, you can call these routines to start and end tables as and when. If table formatting is turned on, a table is automatically started when you call form_start, and terminated when you call form_end.
table_start can also be called to change the defaults for borders (0), and width (80%).
The module supplies defaults for most parameters, but you can change any default(s) with this function. E.g. this will set all the defaults to their default values:
$form->default( # field receive defaults multivalue_sep => ';', # separator for multiple values of a field # table formatting defaults table => 1, # draw fields within a table table_border => 0, # table border is invisible table_width => '80%', # table is 80% of window wide table_align => 'center', # table is centered cellspacing => 0, cellpadding => 10, label_width => '20%', # label column is 20% of table width label_align => 'right', # label alignment td_valign => 'top', # table cell vertical alignment # field defaults type => 'text', # default field type is text size => 30, # default text/textarea width is 30 chars checkbox => 'Y', # default value for checkbox rows => 3, # default textarea rows # form header defaults method => 'POST', enctype => 'application/x-www-form-urlencoded' );
will dump out the values in your hash, sorted by key. This is provided mainly for debugging purposes.
dump optionally takes a list a keys to be dumped. With no options, it dumps all keys.
CGI::EZForm.pm does not produce pretty HTML. Generally, only a browser sees the HTML, and it doesn't care.
CGI::EZForm.pm doesn't do (much) validation of input parameters. If you want to break rules, go ahead. Generally, it is assumed that you know enough HTML to know what's required.
Version 2002.0403
The latest version of this script should be found at: http://www.library.adelaide.edu.au/~sthomas/scripts/EZForm/
Steve Thomas <stephen.thomas@adelaide.edu.au>
Copyright (C) 2002 Steve Thomas. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install CGI::EZForm, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::EZForm
CPAN shell
perl -MCPAN -e shell install CGI::EZForm
For more information on module installation, please visit the detailed CPAN module installation guide.