|
/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/CGI-EZForm/blib/lib/CGI/EZForm.pm |
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:
All defaults can be changed if you want.
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:
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.)
$form->set(me => 'Tarzan', you => 'Jane');
Of course, you can just set individual fields using
$xyz = $form->{xyz};
which is probably faster.
$form->clear; # clears all fields
$form->clear('name', 'addr'); # clears only the name and addr fields
$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">
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');
$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.
$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.
table_start can also be called to change the defaults for borders (0), and width (80%).
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'
);
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.
|
/export/home/cpanrun/depot/main/contrib-patched/perl/CPAN/src/CGI-EZForm/blib/lib/CGI/EZForm.pm |