CGI::FormBuilder::Source::File - phpMan

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