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

NOTES

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

REVISION

204       $Id: File.pm 100 2007-03-02 18:13:13Z nwiger $
205

AUTHOR

207       Copyright (c) 2005-2006 Nathan Wiger <nate@wiger.org>. All Rights
208       Reserved.
209
210       This module is free software; you may copy this under the terms of the
211       GNU General Public License, or the Artistic License, copies of which
212       should have accompanied your Perl kit.
213
214
215
216perl v5.8.8                       2007-03-02 CGI::FormBuilder::Source::File(3)