NAME
CGI::FormMagick - easily create CGI form-based applications
SYNOPSIS
use CGI::FormMagick;
my $f = new CGI::FormMagick();
my $f = new CGI::FormMagick(TYPE => FILE, SOURCE => $myxmlfile, DEBUG => 1);
my $f = new CGI::FormMagick(TYPE => STRING, SOURCE => $data , DEBUG => 1);
$f->add_lexicon("fr", { "Yes" => "Oui", "No" => "Non"});
$f->display();DESCRIPTION
FormMagick is a toolkit for easily building fairly complex form-based web applications. It allows the developer to specify the structure of a multi-page "wizard" style form using XML, then display that form using only a few lines of Perl.
How it works:
You (the developer) provide at least:
Form descriptions (XML)
HTML templates (Text::Template format) for the page headers and footers
And may optionally provide:
L10N lexicon entries
Validation routines for user input data
Routines to run before or after a page of the form is displayed
FormMagick brings them all together to create a full application.
METHODS
new()
The new() method requires no arguments, but may take the following optional arguments (as a hash):
- TYPE
-
Defaults to "FILE" (the only currently implemented type). Eventually we'll also allow such things as FILEHANDLE, STRING, etc (c.f. Text::Template, which does this quite nicely).
- SOURCE
-
Defaults to a filename matching that of your script, only with an extension of .xml (we got this idea from XML::Simple).
- DEBUG
-
Defaults to 0 (no debug output). Setting it to 1 (or any other true value) will cause debugging messages to be output.
display()
The display method displays your form. It takes no arguments.
add_lexicon()
This method takes two arguments. The first is a two-letter string representing the language to which entries should be added. These are standard ISO language abbreviations, eg "en" for English, "fr" for French, "de" for German, etc.
The second argument is a hashref in which the keys of the hash are the phrases to be translated and the values are the translations.
For more information about how localization (L10N) works in FormMagick, see CGI::FormMagick::L10N.
debug($msg)
The debug method prints out a nicely formatted debug message. It's usually called from your script as $f-debug($msg)>
Form descriptions
Sample form description
The following is an example of how a form is described in XML. More complete examples can be found in the examples/ subdirectory in the CGI::FormMagick distribution.
<FORM TITLE="My form application" HEADER="myform_header.tmpl"
FOOTER="myform_footer.tmpl" POST-EVENT="submit_order">
<PAGE NAME="Personal" TITLE="Personal details" DESCRIPTION="Please
provide us with the following personal details for our records">
<FIELD ID="firstname" LABEL="Your first name" TYPE="TEXT"
VALIDATION="nonblank"/>
<FIELD ID="lastname" LABEL="Your surname" TYPE="TEXT"
VALIDATION="nonblank"/>
<FIELD ID="username" LABEL="Choose a username" TYPE="TEXT"
VALIDATION="username" DESCRIPTION="Your username must
be between 3 and 8 characters in length and contain only letters
and numbers."/>
</PAGE>
<PAGE NAME="Payment" TITLE="Payment details"
POST-EVENT="check_credit_card" DESCRIPTION="We need your full credit
card details to process your order. Please fill in all fields.
Your card will be charged within 48 hours.">
<FIELD ID="cardtype" LABEL="Credit card type" TYPE="SELECT"
OPTIONS="list_credit_card_types" VALIDATION="credit_card_type"/>
<FIELD ID="cardnumber" LABEL="Credit card number" TYPE="TEXT"
VALIDATION="credit_card_number"/>
<FIELD ID="cardexpiry" LABEL="Expiry date (MM/YY)" TYPE="TEXT"
VALIDATION="credit_card_expiry"/>
</PAGE>
<PAGE NAME="Random" TITLE="Random fields">
<FIELD ID="confirm" LABEL="Click here to confirm" TYPE="CHECKBOX"
VALUE="confirm" CHECKED="0"/>
<FIELD ID="color" LABEL="Choose a color" TYPE="RADIO"
OPTIONS="'red', 'green', 'blue'"/>
</PAGE>
</FORM>The XML must comply with the FormMagick DTD (included in the distribution as FormMagick.dtd). A command-line tool to test compliance is planned for a future release.
Field types
The following values are permitted in the TYPE attribute of the FIELD element:
TEXT
SELECT (requires OPTIONS attribute)
RADIO (requires OPTIONS attribute)
CHECKBOX (CHECKED attribute is optional)
Notes on parsing of OPTIONS attribute
The OPTIONS attribute has automagical Do What I Mean (DWIM) abilities. You can give it a value which looks like a Perl list, a Perl hash, or a subroutine name. For instance:
OPTIONS="'red', 'green', 'blue'"
OPTIONS="'ff0000' => 'red', '00ff00' => 'green', '0000ff' => 'blue'"
OPTIONS="get_colors()"How it works is that FormMagick looks for the => operator, and if it finds it it evals the OPTIONS string and assigns the result to a hash. If it finds a comma (but no little => arrows) it figures it's a list, and evals it and assigns the results to an array. Otherwise, it tries to interpret what's there as the name of a subroutine in the scope of the script that called FormMagick.
A few gotchas to look out for:
Make sure you quote strings in lists and hashes. "red,blue,green" will fail (silently) because of the barewords.
Single-element lists ("red") will fail because the DWIM parsing doesn't find a comma there and treats it as the name of a subroutine. But then, a single-element radio button group or select dropdown is pretty meaningless anyway, so why would you do that?
Arrays will result in options being sorted in the same order they were listed. Hashes will be sorted by key using the default Perl
sort().An anti-gotcha: subroutine names do not require the parens on them. "get_colors" and "get_colors()" will work the same.
SEE ALSO
CGI::FormMagick::L10N
CGI::FormMagick::Validator
CGI::FormMagick::FAQ
BUGS
There are a number of features which have not yet been implemented. Also, there are probably mismatches between this perldoc and the actual functionality.
AUTHOR
Kirrily "Skud" Robert <skud@infotrope.net>
Contributors:
Shane R. Landrum <slandrum@turing.csc.smith.edu>
James Ramirez <jamesr@cogs.susx.ac.uk>
More information about FormMagick may be found at http://sourceforge.net/projects/formmagick/