CGI::Fo...e::File(3)

✨ okay bestie, welcome to the CGI::FormBuilder::Source::File(3) page — the user-contributed Perl documentation one, also known up top as CGI::Fo...e::File(3) because truncation is a vibe. 💅 We’re talking external config files for FormBuilder and it’s lowkey iconic. 🎀

✨ NAME ✨

CGI::FormBuilder::Source::File — Initialize FormBuilder from external file. That’s the whole assignment, no cap. 🦋

🌸 SYNOPSIS 🌸

Use the main module first, bestie:

# use the main module
use CGI::FormBuilder;

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

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

Then $lname is just a normal field access — like normal, fr fr. ✨

🦋 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 — instead pass a $filename into CGI::FormBuilder, which calls this module for you. iykyk. 🫶

The configuration format steals from Python (ack!) — yes, the indentation-and-newlines-sensitive one. 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. The way that works is honestly kinda clean. 🌈

Multiple options MUST be separated by commas. All whitespace is preserved intact, so don’t get 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 — go read those too, bestie. 💜

⭐ REVISION ⭐

$Id: File.pm 100 2007-03-02 18:13:13Z nwiger $ — yes, that’s the revision line, preserved exactly. 💅

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

---

okay that’s the whole page, bestie — it ships as perl v5.42.2, dated 2024-09-19, and the manual title is CGI::Fo...e::File(3). byeeee 🎀💋✨