---

Manual Reference Pages  - CGI::FormBuilder::Source::File (3)

---

CGI::FormBuilder::Source::File - Initialize FormBuilder from external file

CONTENTS

    # use the main module
    use CGI::FormBuilder;

    my $form = CGI::FormBuilder->new(source => ’form.conf’);

    my $lname = $form->field(’lname’);  # like normal

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.

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.

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);

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.

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

CGI::FormBuilder, Text::FormBuilder

$Id: File.pm,v 1.23 2006/02/24 01:42:29 nwiger Exp $

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.

Jump to page    or go to Top of page |  Section 3 |  Main Index.