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

cpanm CGI::FormBuilder

perl -MCPAN -e shell
install CGI::FormBuilder