/ 
CGI-FormMagick-0.49
River stage zero No dependents
/ CGI::FormMagick

NAME

CGI::FormMagick - easily create CGI form-based applications

SYNOPSIS

use CGI::FormMagick;

my $f = new CGI::FormMagick();

# all options available to new()
my $f = new CGI::FormMagick(
    TYPE => FILE,  
    SOURCE => $myxmlfile, 
    DEBUG => 1
    SESSIONDIR = "/tmp/session-tokens"
    PREVIOUSBUTTON = 1,
    RESETBUTTON = 0,
    STARTOVERLINK = 0
);

# other types available
my $f = new CGI::FormMagick(TYPE => STRING,  SOURCE => $data );

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

PREVIOUSBUTTON

Defaults to 1 ("Previous" button is shown).

RESETBUTTON

Defaults to 1 ("Clear this form" button is shown).

Defaults to 1 ("Start over" link at the bottom of the page is shown).

display()

The display method displays your form. It takes no arguments.

FORMMAGICK XML TUTORIAL

Form descriptions

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"
		MULTIPLE="NO"/>
      <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 parameters

Fields must ALWAYS have an ID value, which is a unique name for the field. Optional parameters are:

  • LABEL (a short description)

  • DESCRIPTION (a more verbose description)

  • VALUE (see below)

  • VALIDATION (a list of validation functions: see CGI::FM::Validator)

  • VALIDATION-ERROR-MESSAGE

  • TYPE (see below)

  • OPTIONS (see below)

  • CHECKED (for CHECKBOX fields, does this start off checked?)

  • MULTIPLE (for SELECT fields, can user select more than one value?)

  • SIZE (for SELECT fields, height; for TEXT and TEXTAREA fields, length)

The following field types are supported:

  • TEXT

  • TEXT (SIZE attribute is optional)

  • SELECT (requires OPTIONS attribute, MULTIPLE and SIZE are optional)

  • RADIO (requires OPTIONS attribute)

  • CHECKBOX (CHECKED attribute is optional)

Notes on parsing of VALUE attribute

If your VALUE attribute ends in parens, it'll be taken as a subroutine to run. Otherwise, it'll just be taken as a literal.

This will be literal:

VALUE="username"

This will run a subroutine:

VALUE="get_username()"

The subroutine will be passed the CGI object as an argument, so you can use the CGI params to help you generate the value you need.

Your subroutine should return a string containing the value you want.

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.

INTERNAL, DEVELOPER-ONLY ROUTINES

The following routines are used internally by FormMagick and are documented here as a developers' reference. If you are using FormMagick to develop web applications, you can skip this section entirely.

get_option_labels_and_values ($fieldinfo)

returns labels and values for fields that require them, by running a subroutine or whatever else is needed. Returns a hashref containing:

{ labels => \@options_labels, $vals => \@option_values }

parse_options_attribute($options_field)

parses the OPTIONS attibute from a FIELD element and returns a reference to either a hash or an array containing the relevant data to fill in a SELECT box or a RADIO group.

call_options_routine($self, $options_field)

given the options field (eg OPTIONS="myroutine") call that routine returns a reference to a hash or array with the options list in it

This sets up a reference to the sub that'll fill this SELECT box with data. We need to pass this CGI object to it, in case for some reason the function wants to use a submitted value from the CGI in a database query that populates the SELECT. It ends up looking something like \&main::get_select_options(\$self->{cgi}).

call_defaultvalue_routine($self, $default_field)

Given the default value field (eg "myroutine" in VALUE="myroutine"), call that routine. Returns a scalar with the default value for a field.

XXX: this is largely the same as call_options_routine. We might want to put those 2 functions together in the future.

do_external_routine($self, $routine)

SEE ALSO

CGI::FormMagick::Utils

CGI::FormMagick::Events

CGI::FormMagick::Setup

CGI::FormMagick::L10N

CGI::FormMagick::Validator

CGI::FormMagick::FAQ

BUGS

The VALIDATION attribute must be very carefully formatted, with spaces between the names of routines but not between the arguments to a routine. See description above.

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/