NAME

       CGI::FormBuilder::Source::File - Initialize FormBuilder from external file

SYNOPSIS

           # use the main module
           use CGI::FormBuilder;

           my $form = CGI::FormBuilder->new(source => 'form.conf');

           my $lname = $form->field('lname');  # like normal

DESCRIPTION

       This parses a file that contains FormBuilder configuration options, and returns a hash
       suitable for creating a new $form object.  Usually, you should not use this directly, but
       instead pass a $filename into "CGI::FormBuilder", which calls this module.

       The configuration format steals from Python (ack!) which is sensitive to indentation and
       newlines. This saves you work in the long run. Here's a complete form:

           # form basics
           method: POST
           header: 1
           title:  Account Information

           # define fields
           fields:
               fname:
                   label:   First Name
                   size:    40

               minit:
                   label:   Middle Initial
                   size:    1

               lname:
                   label:   Last Name
                   size:    60

               email:
                   size:    80

               phone:
                   label:    Home Phone
                   comment:  (optional)
                   required: 0

               sex:
                   label:   Gender
                   options: M=Male, F=Female
                   jsclick: javascript:alert('Change your mind??')

               # custom options and sorting sub
               state:
                   options:  \&getstates
                   sortopts: \&sortstates

               datafile:
                   label:   Upload Survey Data
                   type:    file
                   growable:   1

           # validate our above fields
           validate:
               email:  EMAIL
               phone:  /^1?-?\d{3}-?\d{3}-?\d{4}$/

           required: ALL

           # create two submit buttons, and skip validation on "Cancel"
           submit:  Update, Cancel
           jsfunc:  <<EOJS
         // skip validation
         if (this._submit.value == 'Cancel') return true;
       EOJS

           # CSS
           styleclass: acctInfoForm
           stylesheet: /style/acct.css

       Any option that FormBuilder accepts is supported by this configuration file. Basically,
       any time that you would place a new bracket to create a nested data structure in
       FormBuilder, you put a newline and indent instead.

       Multiple options MUST be separated by commas. All whitespace is preserved intact, so don't
       be confused and do something like this:

           fields:
               send_me_emails:
                   options: Yes No

       Which will result in a single "Yes No" option. You want:

           fields:
               send_me_emails:
                   options: Yes, No

       Or even better:

           fields:
               send_me_emails:
                   options: 1=Yes, 0=No

       Or perhaps best of all:

           fields:
               send_me_emails:
                   options: 1=Yes Please, 0=No Thanks

       If you're confused, please join the mailing list:

           fbusers-subscribe@formbuilder.org

       We'll be able to help you out.

METHODS

   new()
       This creates a new "CGI::FormBuilder::Source::File" object.

           my $source = CGI::FormBuilder::Source::File->new;

       Any arguments specified are taken as defaults, which the file then overrides. For example,
       to always turn off "javascript" (so you don't have to in all your config files), use:

           my $source = CGI::FormBuilder::Source::File->new(
                             javascript => 0
                        );

       Then, every file parsed by $source will have "javascript => 0" in it, unless that file has
       a "javascript:" setting itself.

   parse($source)
       This parses the specified source, which is either a $file, "\$string", or "\@array", and
       returns a hash which can be passed directly into "CGI::FormBuilder":

           my %conf = $source->parse('myform.conf');
           my $form = CGI::FormBuilder->new(%conf);

   write_module($modname)
       This will actually write a module in the current directory which you can then use in
       subsequent scripts to get the same form:

           $source->parse('myform.conf');
           $source->write_module('MyForm');    # write MyForm.pm

           # then in your Perl code
           use MyForm;
           my $form = MyForm->new;

       You can also override settings from "MyForm" the same as you would in FormBuilder:

           my $form = MyForm->new(
                           header => 1,
                           submit => ['Save Changes', 'Abort']
                      );

       This will speed things up, since you don't have to re-parse the file every time. Nice idea
       Peter.

NOTES

       This module was completely inspired by Peter Eichman's "Text::FormBuilder", though the
       syntax is different.

       Remember that to get a new level in a hashref, you need to add a newline and indent. So to
       get something like this:

           table => {cellpadding => 1, cellspacing => 4},
           td    => {align => 'center', bgcolor => 'gray'},
           font  => {face => 'arial,helvetica', size => '+1'},

       You need to say:

           table:
               cellpadding: 1
               cellspacing: 4

           td:
               align: center
               bgcolor: gray

           font:
               face: arial,helvetica
               size: +1

       You get the idea...

SEE ALSO

       CGI::FormBuilder, Text::FormBuilder

REVISION

       $Id: File.pm 100 2007-03-02 18:13:13Z nwiger $

AUTHOR

       Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.

       This module is free software; you may copy this under the terms of the GNU General Public
       License, or the Artistic License, copies of which should have accompanied your Perl kit.