/ 
formmagick-0.2.9
/ FormMagick

NAME

FormMagick - easily create CGI form-based applications

SYNOPSIS

use FormMagick;

my $f = new FormMagick();
my $f = new FormMagick(TYPE => FILE,  SOURCE => $myxmlfile, 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 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 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>
  </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.

SEE ALSO

FormMagick::L10N

FormMagick::Validator

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/