Linux Certif

Toute la documentation sur la certification Linux LPI

CGI::FormBuilder::Source::File.3pm

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) 2005-2006 Nathan Wiger <nate@wiger.org>. 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.