.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CGI::FormBuilder::Source::File 3pm"
.TH CGI::FormBuilder::Source::File 3pm "2019-01-19" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::FormBuilder::Source::File \- Initialize FormBuilder from external file
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # use the main module
\&    use CGI::FormBuilder;
\&
\&    my $form = CGI::FormBuilder\->new(source => \*(Aqform.conf\*(Aq);
\&
\&    my $lname = $form\->field(\*(Aqlname\*(Aq);  # like normal
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This parses a file that contains \fBFormBuilder\fR configuration options,
and returns a hash suitable for creating a new \f(CW$form\fR object.
Usually, you should not use this directly, but instead pass a \f(CW$filename\fR
into \f(CW\*(C`CGI::FormBuilder\*(C'\fR, which calls this module.
.PP
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:
.PP
.Vb 4
\&    # 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(\*(AqChange your mind??\*(Aq)
\&
\&        # custom options and sorting sub
\&        state:
\&            options:  \e&getstates
\&            sortopts: \e&sortstates
\&
\&        datafile:
\&            label:   Upload Survey Data
\&            type:    file
\&            growable:   1
\&
\&    # validate our above fields
\&    validate:
\&        email:  EMAIL
\&        phone:  /^1?\-?\ed{3}\-?\ed{3}\-?\ed{4}$/
\&
\&    required: ALL
\&
\&    # create two submit buttons, and skip validation on "Cancel"
\&    submit:  Update, Cancel
\&    jsfunc:  <<EOJS
\&  // skip validation
\&  if (this._submit.value == \*(AqCancel\*(Aq) return true;
\&EOJS
\&
\&    # CSS
\&    styleclass: acctInfoForm
\&    stylesheet: /style/acct.css
.Ve
.PP
Any option that \fBFormBuilder\fR accepts is supported by this
configuration file. Basically, any time that you would place
a new bracket to create a nested data structure in \fBFormBuilder\fR,
you put a newline and indent instead.
.PP
\&\fBMultiple options \s-1MUST\s0 be separated by commas\fR. All whitespace
is preserved intact, so don't be confused and do something
like this:
.PP
.Vb 3
\&    fields:
\&        send_me_emails:
\&            options: Yes No
.Ve
.PP
Which will result in a single \*(L"Yes No\*(R" option. You want:
.PP
.Vb 3
\&    fields:
\&        send_me_emails:
\&            options: Yes, No
.Ve
.PP
Or even better:
.PP
.Vb 3
\&    fields:
\&        send_me_emails:
\&            options: 1=Yes, 0=No
.Ve
.PP
Or perhaps best of all:
.PP
.Vb 3
\&    fields:
\&        send_me_emails:
\&            options: 1=Yes Please, 0=No Thanks
.Ve
.PP
If you're confused, please join the mailing list:
.PP
.Vb 1
\&    fbusers\-subscribe@formbuilder.org
.Ve
.PP
We'll be able to help you out.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBnew()\fP"
.IX Subsection "new()"
This creates a new \f(CW\*(C`CGI::FormBuilder::Source::File\*(C'\fR object.
.PP
.Vb 1
\&    my $source = CGI::FormBuilder::Source::File\->new;
.Ve
.PP
Any arguments specified are taken as defaults, which the file
then overrides. For example, to always turn off \f(CW\*(C`javascript\*(C'\fR
(so you don't have to in all your config files), use:
.PP
.Vb 3
\&    my $source = CGI::FormBuilder::Source::File\->new(
\&                      javascript => 0
\&                 );
.Ve
.PP
Then, every file parsed by \f(CW$source\fR will have \f(CW\*(C`javascript => 0\*(C'\fR
in it, unless that file has a \f(CW\*(C`javascript:\*(C'\fR setting itself.
.SS "parse($source)"
.IX Subsection "parse($source)"
This parses the specified source, which is either a \f(CW$file\fR,
\&\f(CW\*(C`\e$string\*(C'\fR, or \f(CW\*(C`\e@array\*(C'\fR, and returns a hash which can
be passed directly into \f(CW\*(C`CGI::FormBuilder\*(C'\fR:
.PP
.Vb 2
\&    my %conf = $source\->parse(\*(Aqmyform.conf\*(Aq);
\&    my $form = CGI::FormBuilder\->new(%conf);
.Ve
.SS "write_module($modname)"
.IX Subsection "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:
.PP
.Vb 2
\&    $source\->parse(\*(Aqmyform.conf\*(Aq);
\&    $source\->write_module(\*(AqMyForm\*(Aq);    # write MyForm.pm
\&
\&    # then in your Perl code
\&    use MyForm;
\&    my $form = MyForm\->new;
.Ve
.PP
You can also override settings from \f(CW\*(C`MyForm\*(C'\fR the same as you
would in \fBFormBuilder\fR:
.PP
.Vb 4
\&    my $form = MyForm\->new(
\&                    header => 1,
\&                    submit => [\*(AqSave Changes\*(Aq, \*(AqAbort\*(Aq]
\&               );
.Ve
.PP
This will speed things up, since you don't have to re-parse
the file every time. Nice idea Peter.
.SH "NOTES"
.IX Header "NOTES"
This module was completely inspired by Peter Eichman's 
\&\f(CW\*(C`Text::FormBuilder\*(C'\fR, though the syntax is different.
.PP
Remember that to get a new level in a hashref, you need
to add a newline and indent. So to get something like this:
.PP
.Vb 3
\&    table => {cellpadding => 1, cellspacing => 4},
\&    td    => {align => \*(Aqcenter\*(Aq, bgcolor => \*(Aqgray\*(Aq},
\&    font  => {face => \*(Aqarial,helvetica\*(Aq, size => \*(Aq+1\*(Aq},
.Ve
.PP
You need to say:
.PP
.Vb 3
\&    table:
\&        cellpadding: 1
\&        cellspacing: 4
\&
\&    td:
\&        align: center
\&        bgcolor: gray
\&
\&    font:
\&        face: arial,helvetica
\&        size: +1
.Ve
.PP
You get the idea...
.SH "SEE ALSO"
.IX Header "SEE ALSO"
CGI::FormBuilder, Text::FormBuilder
.SH "REVISION"
.IX Header "REVISION"
\&\f(CW$Id:\fR File.pm 100 2007\-03\-02 18:13:13Z nwiger $
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
.PP
This module is free software; you may copy this under the terms of
the \s-1GNU\s0 General Public License, or the Artistic License, copies of
which should have accompanied your Perl kit.