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