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