/ 
Text-FormBuilder-0.05
River stage zero No dependents
/ Text::FormBuilder

NAME

Text::FormBuilder - Parser for a minilanguage for generating web forms

SYNOPSIS

use Text::FormBuilder;

my $parser = Text::FormBuilder->new;
$parser->parse($src_file);

# returns a new CGI::FormBuilder object with
# the fields from the input form spec
my $form = $parser->form;

# write a My::Form module to Form.pm
$parser->write_module('My::Form');

DESCRIPTION

new

parse

# parse a file
$parser->parse($filename);

# or pass a scalar ref for parse a literal string
$parser->parse(\$string);

Parse the file or string. Returns the parser object.

parse_file

$parser->parse_file($src_file);

# or as a class method
my $parser = Text::FormBuilder->parse($src_file);

parse_text

$parser->parse_text($src);

Parse the given $src text. Returns the parser object.

build

$parser->build(%options);

Builds the CGI::FormBuilder object. Options directly used by build are:

form_only

Only uses the form portion of the template, and omits the surrounding html, title, author, and the standard footer. This does, however, include the description as specified with the !description directive.

All other options given to build are passed on verbatim to the CGI::FormBuilder constructor. Any options given here override the defaults that this module uses.

The form, write, and write_module methods will all call build with no options for you if you do not do so explicitly. This allows you to say things like this:

my $form = Text::FormBuilder->new->parse('formspec.txt')->form;

However, if you need to specify options to build, you must call it explictly after parse.

form

my $form = $parser->form;

Returns the CGI::FormBuilder object. Remember that you can modify this object directly, in order to (for example) dynamically populate dropdown lists or change input types at runtime.

write

$parser->write($out_file);
# or just print to STDOUT
$parser->write;

Calls render on the FormBuilder form, and either writes the resulting HTML to a file, or to STDOUT if no filename is given.

write_module

$parser->write_module($package, $use_tidy);

Takes a package name, and writes out a new module that can be used by your CGI script to render the form. This way, you only need CGI::FormBuilder on your server, and you don't have to parse the form spec each time you want to display your form. The generated module has one function (not exported) called get_form, that takes a CGI object as its only argument, and returns a CGI::FormBuilder object.

First, you parse the formspec and write the module, which you can do as a one-liner:

$ perl -MText::FormBuilder -e"Text::FormBuilder->parse('formspec.txt')->write_module('My::Form')"

And then, in your CGI script, use the new module:

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

use CGI;
use My::Form;

my $q = CGI->new;
my $form = My::Form::get_form($q);

# do the standard CGI::FormBuilder stuff
if ($form->submitted && $form->validate) {
    # process results
} else {
    print $q->header;
    print $form->render;
}

If you pass a true value as the second argument to write_module, the parser will run Perl::Tidy on the generated code before writing the module file.

# write tidier code
$parser->write_module('My::Form', 1);

dump

Uses YAML to print out a human-readable representation of the parsed form spec.

LANGUAGE

field_name[size]|descriptive label[hint]:type=default{option1[display string],...}//validate

!title ...

!author ...

!description {
    ...
}

!pattern name /regular expression/

!list name {
    option1[display string],
    option2[display string],
    ...
}

!list name &{ CODE }

!head ...

Directives

!pattern

Defines a validation pattern.

!list

Defines a list for use in a radio, checkbox, or select field.

!title
!author
!description

A brief description of the form. Suitable for special instructions on how to fill out the form.

!head

Inserts a heading between two fields. There can only be one heading between any two fields; the parser will warn you if you try to put two headings right next to each other.

Fields

Form fields are each described on a single line. The simplest field is just a name:

color

This yields a form with one text input field of the default size named `color'. The label for this field as generated by CGI::FormBuilder would be ``Color''. To add a longer or more descriptive label, use:

color|Favorite color

Field names cannot contain whitespace, but the descriptive label can.

To use a different input type:

color|Favorite color:select{red,blue,green}

Recognized input types are the same as those used by CGI::FormBuilder:

text        # the default
textarea
select
radio
checkbox
static

This example also shows how you can list multiple values for the input types that take multiple values (select, radio, and checkbox). Values are in a comma-separated list inside curly braces. Whitespace between values is irrelevant, although there cannot be any whitespace within a value.

To add more descriptive display text to a vlaue in a list, add a square-bracketed ``subscript,'' as in:

...:select{red[Scarlet],blue[Azure],green[Olive Drab]}

As you can see, spaces are allowed within the display text for a value.

If you have a list of options that is too long to fit comfortably on one line, consider using the !list directive:

!list MONTHS {
    1[January],
    2[February],
    3[March],
    # and so on...
}

month:select@MONTHS

There is another form of the !list directive: the dynamic list:

!list RANDOM &{ map { rand } (0..5) }

The code inside the &{ ... } is evaled by build, and the results are stuffed into the list. The evaled code can either return a simple list, as the example does, or the fancier ( { value1 = 'Description 1'}, { value2 => 'Description 2}, ...)> form.

NOTE: This feature of the language may go away unless I find a compelling reason for it in the next few versions. What I really wanted was lists that were filled in at run-time (e.g. from a database), and that can be done easily enough with the CGI::FormBuilder object directly.

You can also supply a default value to the field. To get a default value of green for the color field:

color|Favorite color:select=green{red,blue,green}

To validate a field, include a validation type at the end of the field line:

email|Email address//EMAIL

Valid validation types include any of the builtin defaults from CGI::FormBuilder, or the name of a pattern that you define with the !pattern directive elsewhere in your form spec:

!pattern DAY /^([1-3][0-9])|[1-9]$/

last_day//DAY

If you just want a required value, use the builtin validation type VALUE:

title//VALUE

Comments

# comment ...

Any line beginning with a # is considered a comment.

TODO

!include directive to include external formspec files

Field groups all on one line in the generated form

Better tests!

SEE ALSO

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.