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

1CGI::FormBuilder::SourcUes:e:rFiCloen(t3r)ibuted Perl DoCcGuIm:e:nFtoartmiBounilder::Source::File(3)
2
3
4

NAME

6       CGI::FormBuilder::Source::File - Initialize FormBuilder from external
7       file
8

SYNOPSIS

10           # use the main module
11           use CGI::FormBuilder;
12
13           my $form = CGI::FormBuilder->new(source => 'form.conf');
14
15           my $lname = $form->field('lname');  # like normal
16

DESCRIPTION

18       This parses a file that contains FormBuilder configuration options, and
19       returns a hash suitable for creating a new $form object.  Usually, you
20       should not use this directly, but instead pass a $filename into
21       "CGI::FormBuilder", which calls this module.
22
23       The configuration format steals from Python (ack!) which is sensitive
24       to indentation and newlines. This saves you work in the long run.
25       Here's a complete form:
26
27           # form basics
28           method: POST
29           header: 1
30           title:  Account Information
31
32           # define fields
33           fields:
34               fname:
35                   label:   First Name
36                   size:    40
37
38               minit:
39                   label:   Middle Initial
40                   size:    1
41
42               lname:
43                   label:   Last Name
44                   size:    60
45
46               email:
47                   size:    80
48
49               phone:
50                   label:    Home Phone
51                   comment:  (optional)
52                   required: 0
53
54               sex:
55                   label:   Gender
56                   options: M=Male, F=Female
57                   jsclick: javascript:alert('Change your mind??')
58
59               # custom options and sorting sub
60               state:
61                   options:  \&getstates
62                   sortopts: \&sortstates
63
64               datafile:
65                   label:   Upload Survey Data
66                   type:    file
67                   growable:   1
68
69           # validate our above fields
70           validate:
71               email:  EMAIL
72               phone:  /^1?-?\d{3}-?\d{3}-?\d{4}$/
73
74           required: ALL
75
76           # create two submit buttons, and skip validation on "Cancel"
77           submit:  Update, Cancel
78           jsfunc:  <<EOJS
79         // skip validation
80         if (this._submit.value == 'Cancel') return true;
81       EOJS
82
83           # CSS
84           styleclass: acctInfoForm
85           stylesheet: /style/acct.css
86
87       Any option that FormBuilder accepts is supported by this configuration
88       file. Basically, any time that you would place a new bracket to create
89       a nested data structure in FormBuilder, you put a newline and indent
90       instead.
91
92       Multiple options MUST be separated by commas. All whitespace is
93       preserved intact, so don't be confused and do something like this:
94
95           fields:
96               send_me_emails:
97                   options: Yes No
98
99       Which will result in a single "Yes No" option. You want:
100
101           fields:
102               send_me_emails:
103                   options: Yes, No
104
105       Or even better:
106
107           fields:
108               send_me_emails:
109                   options: 1=Yes, 0=No
110
111       Or perhaps best of all:
112
113           fields:
114               send_me_emails:
115                   options: 1=Yes Please, 0=No Thanks
116
117       If you're confused, please join the mailing list:
118
119           fbusers-subscribe@formbuilder.org
120
121       We'll be able to help you out.
122

METHODS

124   new()
125       This creates a new "CGI::FormBuilder::Source::File" object.
126
127           my $source = CGI::FormBuilder::Source::File->new;
128
129       Any arguments specified are taken as defaults, which the file then
130       overrides. For example, to always turn off "javascript" (so you don't
131       have to in all your config files), use:
132
133           my $source = CGI::FormBuilder::Source::File->new(
134                             javascript => 0
135                        );
136
137       Then, every file parsed by $source will have "javascript => 0" in it,
138       unless that file has a "javascript:" setting itself.
139
140   parse($source)
141       This parses the specified source, which is either a $file, "\$string",
142       or "\@array", and returns a hash which can be passed directly into
143       "CGI::FormBuilder":
144
145           my %conf = $source->parse('myform.conf');
146           my $form = CGI::FormBuilder->new(%conf);
147
148   write_module($modname)
149       This will actually write a module in the current directory which you
150       can then use in subsequent scripts to get the same form:
151
152           $source->parse('myform.conf');
153           $source->write_module('MyForm');    # write MyForm.pm
154
155           # then in your Perl code
156           use MyForm;
157           my $form = MyForm->new;
158
159       You can also override settings from "MyForm" the same as you would in
160       FormBuilder:
161
162           my $form = MyForm->new(
163                           header => 1,
164                           submit => ['Save Changes', 'Abort']
165                      );
166
167       This will speed things up, since you don't have to re-parse the file
168       every time. Nice idea Peter.
169

NOTES

171       This module was completely inspired by Peter Eichman's
172       "Text::FormBuilder", though the syntax is different.
173
174       Remember that to get a new level in a hashref, you need to add a
175       newline and indent. So to get something like this:
176
177           table => {cellpadding => 1, cellspacing => 4},
178           td    => {align => 'center', bgcolor => 'gray'},
179           font  => {face => 'arial,helvetica', size => '+1'},
180
181       You need to say:
182
183           table:
184               cellpadding: 1
185               cellspacing: 4
186
187           td:
188               align: center
189               bgcolor: gray
190
191           font:
192               face: arial,helvetica
193               size: +1
194
195       You get the idea...
196

REVISION

201       $Id: File.pm 100 2007-03-02 18:13:13Z nwiger $
202

AUTHOR

204       Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
205
206       This module is free software; you may copy this under the terms of the
207       GNU General Public License, or the Artistic License, copies of which
208       should have accompanied your Perl kit.
209
210
211
212perl v5.36.0                      2023-01-20 CGI::FormBuilder::Source::File(3)