perldoc > CGI::FormBuilder::Source::File(3pm)

man perldoc info pydoc3 ri search

🏷️ NAME

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

🚀 Quick Reference

Use Case	Command	Description
Create form from config file	my $form = CGI::FormBuilder->new(source => 'form.conf');	Directly load a configuration file to build the form
Override defaults while parsing	my $source = CGI::FormBuilder::Source::File->new(javascript => 0); my %conf = $source->parse('form.conf');	Set default options that the config file can override
Generate a reusable module	$source->write_module('MyForm'); use MyForm; my $form = MyForm->new;	Write a .pm file to avoid re‑parsing the config every time
Add validation rules	validate:   email: EMAIL   phone: /^1?-?\d{3}-?\d{3}-?\d{4}$/	Define per‑field validation in the config 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.

🏷️ NAME 🚀 Quick Reference 📖 SYNOPSIS 📘 DESCRIPTION ⚙️ METHODS 📌 NOTES 🔗 SEE ALSO 🔢 REVISION 👤 AUTHOR