NAME

Examples - Sample uses of Text::FormBuilder

EXAMPLES

Event Form

This is the formspec for an input form for an event calendar. It exercises many of the features of the formspec language. This is close to a real world project that I have been developing.

!title Add Event
!author Peter Eichman
!description {
    Start and end times are not required, but are recommended. If you leave 
    both of them blank, the event will be considered an all day event.
}

!pattern TIME /^\s*\d{1,2}(:\d{2})?(\s*[ap]m)?\s*$/
!pattern DAY  /^\s*(([1-3][0-9])|[1-9])\s*$/
!pattern YEAR /^\s*\d{4}\s*$/

!list MONTHS {
    1[January],    2[February], 3[March],     4[April],
    5[May],        6[June],     7[July],      8[August],
    9[September], 10[October], 11[November], 12[December]
}

!group DATE {
    month@MONTHS//VALUE
    day[2]//DAY
    year[4]//YEAR
}

!group TIME {
    start[8]|' '//TIME?
    end[8]|'–'[(hh:mm am/pm)]//TIME?
}

!group SERIES {
    old|Existing:select
    new[40]|or New
}

# input fields start here

event_type:select//VALUE

title[60]//VALUE

!field %DATE date
!field %TIME time

series_old|Existing series:select
series_new[60]|New series

description[6,60]:textarea
contact[60]
email[40]//EMAIL?
location[60]
url[60]|Website

Both of the fields event_type and series_old get filled in from a database in the actual CGI script. The relevant bits of the CGI script which uses this form go something like this:

# the module containing the FormBuilder-building code
use Calendar::Forms::AddEvent;
my $form = Calendar::Forms::AddEvent::get_form($q);

# now we have a CGI::FormBuilder object in $form

# fill in dropdown lists
$form->field(name => 'event_type', values => \@event_types);
$form->field(name => 'series_old', values => \@existing_series);

unless ($form->submitted && $form->validate) {
    print $q->header;
    print $form->render;
} else {
    # process the data ...
}

CGI::FormBuilder EXAMPLES

Here are some of CGI::FormBuilder's examples, translated into Text::FormBuilder's terms.

Ex1: order.cgi

Formspec example1:

!title Order Info

!list STATES {
    AL, AK, AZ, AR, CA, CO, CT, DE, DC, FL, GE, HI, ID, IL, IN, IA, KS,
    KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC,
    ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
}

first_name
last_name
email//EMAIL
address
state@STATES
zipcode//ZIPCODE
credit_card//CARD
details[10,50]:textarea

Parse and create Example1.pm:

$ perl -MText::FormBuilder \
    -e'Text::FormBuilder->parse("example1")->build(method => "POST") \
    ->write_module("MyForms::Example1")'

Script:

#!/usr/bin/perl -w
use strict;

use CGI;    # you have to use CGI.pm explicitly
use MyForms::Example1;

my $q = CGI->new;

my $form = MyForms::Example1::get_form($q);

# try to validate it first
if ($form->submitted && $form->validate) {
    # ... more code goes here to do stuff ...
    print $form->confirm;
} else {
    print $form->render;
}

Ex2: order_form.cgi

You can also include the formspec in your script; the only downside to this is that your script has to parse the spec every time it gets called, so this method is definitely not recommended for high-traffic forms.

Script order_form.cgi:

#!/usr/bin/perl -w
use strict;

use CGI;    # you have to use CGI.pm explicitly
use Text::FormBuilder;

my $parser = Text::FormBuilder->parse_text(q[
first_name
last_name
email
address
state@STATE
zipcode
credit_card
details[10,50]:textarea
]);

my $q = CGI->new;
$parser->build(params => $q, method => 'POST', smartness => 2, debug => 2);

my $form = $parser->form;

# try to validate it first
if ($form->submitted && $form->validate) {
    # ... more code goes here to do stuff ...
    print $form->confirm;
} else {
    print $form->render;
}

Ex4: user_info.cgi

#!/usr/bin/perl -w
use strict;

use Text::FormBuilder;
use CGI;
use DBI;

my $dbh = DBI->connect('dbi:Oracle:db', 'user', 'pass');

my $parser = Text::FormBuilder->parse_text(q[
username
password
confirm_password
first_name
last_name
email
]);


my $q = CGI->new;
my $form = $parser->build(params => $q)->form;

# Now get the value of the username from our app
my $user = $form->cgi_param('user');
my $sth = $dbh->prepare("select * from user_info where user = '$user'");
$sth->execute;
my $default_hashref = $sth->fetchrow_hashref;
# Render our form with the defaults we got in our hashref
print $form->render(values => $default_hashref,
                    title  => "User information for '$user'",
);

SEE ALSO

Text::FormBuilder, CGI::FormBuilder

AUTHOR

Peter Eichman, <peichman@cpan.org>

COPYRIGHT AND LICENSE

Copyright ©2004 by Peter Eichman.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Text::FormBuilder

perl -MCPAN -e shell
install Text::FormBuilder