---
name: "CGI::FormBuilder::Source::File"
section: "3pm"
platform: "linux"
package: "perl-cgi-formbuilder"
version: "3.20-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/CGI::FormBuilder::Source::File"
---

# CGI::FormBuilder::Source::File(3pm)

Initialize FormBuilder from external file

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