CGI::FormBuilder::Source::File(3pm)			User Contributed Perl Documentation		       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) 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.

perl v5.14.2							    2011-09-16				       CGI::FormBuilder::Source::File(3pm)