1CGI::FormBuilder(3) User Contributed Perl Documentation CGI::FormBuilder(3)
2
6 CGI::FormBuilder - Easily generate and process stateful forms
7
9 use CGI::FormBuilder;
10 # Assume we did a DBI query to get existing values
12 my $dbval = $sth->fetchrow_hashref;
13 # First create our form
15 my $form = CGI::FormBuilder->new(
16 name => 'acctinfo',
17 method => 'post',
18 stylesheet => '/path/to/style.css',
19 values => $dbval, # defaults
20 );
21 # Now create form fields, in order
23 # FormBuilder will automatically determine the type for you
24 $form->field(name => 'fname', label => 'First Name');
25 $form->field(name => 'lname', label => 'Last Name');
26 # Setup gender field to have options
28 $form->field(name => 'gender',
29 options => [qw(Male Female)] );
30 # Include validation for the email field
32 $form->field(name => 'email',
33 size => 60,
34 validate => 'EMAIL',
35 required => 1);
36 # And the (optional) phone field
38 $form->field(name => 'phone',
39 size => 10,
40 validate => '/^1?-?\d{3}-?\d{3}-?\d{4}$/',
41 comment => '<i>optional</i>');
42 # Check to see if we're submitted and valid
44 if ($form->submitted && $form->validate) {
45 # Get form fields as hashref
46 my $field = $form->fields;
47 # Do something to update your data (you would write this)
49 do_data_update($field->{lname}, $field->{fname},
50 $field->{email}, $field->{phone},
51 $field->{gender});
52 # Show confirmation screen
54 print $form->confirm(header => 1);
55 } else {
56 # Print out the form
57 print $form->render(header => 1);
58 }
59
61 If this is your first time using FormBuilder, you should check out the
62 website for tutorials and examples at <http://formbuilder.org>.
63 You should also consider joining the google group at
65 <http://groups.google.com/group/perl-formbuilder>. There are some
66 pretty smart people on the list that can help you out.
67 Overview
69 I hate generating and processing forms. Hate it, hate it, hate it, hate
70 it. My forms almost always end up looking the same, and almost always
71 end up doing the same thing. Unfortunately, there haven't really been
72 any tools out there that streamline the process. Many modules simply
73 substitute Perl for HTML code:
74 # The manual way
76 print qq(<input name="email" type="text" size="20">);
77 # The module way
79 print input(-name => 'email', -type => 'text', -size => '20');
80 The problem is, that doesn't really gain you anything - you still have
82 just as much code. Modules like "CGI.pm" are great for decoding
83 parameters, but not for generating and processing whole forms.
84 The goal of CGI::FormBuilder (FormBuilder) is to provide an easy way
86 for you to generate and process entire CGI form-based applications.
87 Its main features are:
88 Field Abstraction
90 Viewing fields as entities (instead of just params), where the HTML
91 representation, CGI values, validation, and so on are properties of
92 each field.
93 DWIMmery
95 Lots of built-in "intelligence" (such as automatic field typing),
96 giving you about a 4:1 ratio of the code it generates versus what
97 you have to write.
98 Built-in Validation
100 Full-blown regex validation for fields, even including JavaScript
101 code generation.
102 Template Support
104 Pluggable support for external template engines, such as
105 "HTML::Template", "Text::Template", "Template Toolkit", and
106 "CGI::FastTemplate".
107 Plus, the native HTML generated is valid XHTML 1.0 Transitional.
109 Quick Reference
111 For the incredibly impatient, here's the quickest reference you can
112 get:
113 # Create form
115 my $form = CGI::FormBuilder->new(
116 # Important options
118 fields => \@array | \%hash, # define form fields
119 header => 0 | 1, # send Content-type?
120 method => 'post' | 'get', # default is get
121 name => $string, # namespace (recommended)
122 reset => 0 | 1 | $str, # "Reset" button
123 submit => 0 | 1 | $str | \@array, # "Submit" button(s)
124 text => $text, # printed above form
125 title => $title, # printed up top
126 required => \@array | 'ALL' | 'NONE', # required fields?
127 values => \%hash | \@array, # from DBI, session, etc
128 validate => \%hash, # automatic field validation
129 # Lesser-used options
131 action => $script, # not needed (loops back)
132 cookies => 0 | 1, # use cookies for sessionid?
133 debug => 0 | 1 | 2 | 3, # gunk into error_log?
134 fieldsubs => 0 | 1, # allow $form->$field()
135 javascript => 0 | 1 | 'auto', # generate JS validate() code?
136 keepextras => 0 | 1 | \@array, # keep non-field params?
137 params => $object, # instead of CGI.pm
138 sticky => 0 | 1, # keep CGI values "sticky"?
139 messages => $file | \%hash | $locale | 'auto',
140 template => $file | \%hash | $object, # custom HTML
141 # HTML formatting and JavaScript options
143 body => \%attr, # {background => 'black'}
144 disabled => 0 | 1, # display as grayed-out?
145 fieldsets => \@arrayref # split form into <fieldsets>
146 font => $font | \%attr, # 'arial,helvetica'
147 jsfunc => $jscode, # JS code into validate()
148 jshead => $jscode, # JS code into <head>
149 linebreaks => 0 | 1, # put breaks in form?
150 selectnum => $threshold, # for auto-type generation
151 smartness => 0 | 1 | 2, # tweak "intelligence"
152 static => 0 | 1 | 2, # show non-editable form?
153 styleclass => $string, # style class to use ("fb")
154 stylesheet => 0 | 1 | $path, # turn on style class=
155 table => 0 | 1 | \%attr, # wrap form in <table>?
156 td => \%attr, # <td> options
157 tr => \%attr, # <tr> options
158 # These are deprecated and you should use field() instead
160 fieldtype => 'type',
161 fieldattr => \%attr,
162 labels => \%hash,
163 options => \%hash,
164 sortopts => 'NAME' | 'NUM' | 1 | \&sub,
165 # External source file (see CGI::FormBuilder::Source::File)
167 source => $file,
168 );
169 # Tweak fields individually
171 $form->field(
172 # Important options
174 name => $name, # name of field (required)
175 label => $string, # shown in front of <input>
176 type => $type, # normally auto-determined
177 multiple => 0 | 1, # allow multiple values?
178 options => \@options | \%options, # radio/select/checkbox
179 value => $value | \@values, # default value
180 # Lesser-used options
182 fieldset => $string, # put field into <fieldset>
183 force => 0 | 1, # override CGI value?
184 growable => 0 | 1 | $limit, # expand text/file inputs?
185 jsclick => $jscode, # instead of onclick
186 jsmessage => $string, # on JS validation failure
187 message => $string, # other validation failure
188 other => 0 | 1, # create "Other:" input?
189 required => 0 | 1, # must fill field in?
190 validate => '/regex/', # validate user input
191 # HTML formatting options
193 cleanopts => 0 | 1, # HTML-escape options?
194 columns => 0 | $width, # wrap field options at $width
195 comment => $string, # printed after field
196 disabled => 0 | 1, # display as grayed-out?
197 labels => \%hash, # deprecated (use "options")
198 linebreaks => 0 | 1, # insert breaks in options?
199 nameopts => 0 | 1, # auto-name options?
200 sortopts => 'NAME' | 'NUM' | 1 | \&sub, # sort options?
201 # Change size, maxlength, or any other HTML attr
203 $htmlattr => $htmlval,
204 );
205 # Check for submission
207 if ($form->submitted && $form->validate) {
208 # Get single value
210 my $value = $form->field('name');
211 # Get list of fields
213 my @field = $form->field;
214 # Get hashref of key/value pairs
216 my $field = $form->field;
217 my $value = $field->{name};
218 }
220 # Print form
222 print $form->render(any_opt_from_new => $some_value);
223 That's it. Keep reading.
225 Walkthrough
227 Let's walk through a whole example to see how FormBuilder works. We'll
228 start with this, which is actually a complete (albeit simple) form
229 application:
230 use CGI::FormBuilder;
232 my @fields = qw(name email password confirm_password zipcode);
234 my $form = CGI::FormBuilder->new(
236 fields => \@fields,
237 header => 1
238 );
239 print $form->render;
241 The above code will render an entire form, and take care of maintaining
243 state across submissions. But it doesn't really do anything useful at
244 this point.
245 So to start, let's add the "validate" option to make sure the data
247 entered is valid:
248 my $form = CGI::FormBuilder->new(
250 fields => \@fields,
251 header => 1,
252 validate => {
253 name => 'NAME',
254 email => 'EMAIL'
255 }
256 );
257 We now get a whole bunch of JavaScript validation code, and the
259 appropriate hooks are added so that the form is validated by the
260 browser "onsubmit" as well.
261 Now, we also want to validate our form on the server side, since the
263 user may not be running JavaScript. All we do is add the statement:
264 $form->validate;
266 Which will go through the form, checking each field specified to the
268 "validate" option to see if it's ok. If there's a problem, then that
269 field is highlighted, so that when you print it out the errors will be
270 apparent.
271 Of course, the above returns a truth value, which we should use to see
273 if the form was valid. That way, we only update our database if
274 everything looks good:
275 if ($form->validate) {
277 # print confirmation screen
278 print $form->confirm;
279 } else {
280 # print the form for them to fill out
281 print $form->render;
282 }
283 However, we really only want to do this after our form has been
285 submitted, since otherwise this will result in our form showing errors
286 even though the user hasn't gotten a chance to fill it out yet. As
287 such, we want to check for whether the form has been "submitted()" yet:
288 if ($form->submitted && $form->validate) {
290 # print confirmation screen
291 print $form->confirm;
292 } else {
293 # print the form for them to fill out
294 print $form->render;
295 }
296 Now that know that our form has been submitted and is valid, we need to
298 get our values. To do so, we use the "field()" method along with the
299 name of the field we want:
300 my $email = $form->field(name => 'email');
302 Note we can just specify the name of the field if it's the only option:
304 my $email = $form->field('email'); # same thing
306 As a very useful shortcut, we can get all our fields back as a hashref
308 of field/value pairs by calling "field()" with no arguments:
309 my $fields = $form->field; # all fields as hashref
311 To make things easy, we'll use this form so that we can pass it easily
313 into a sub of our choosing:
314 if ($form->submitted && $form->validate) {
316 # form was good, let's update database
317 my $fields = $form->field;
318 # update database (you write this part)
320 do_data_update($fields);
321 # print confirmation screen
323 print $form->confirm;
324 }
325 Finally, let's say we decide that we like our form fields, but we need
327 the HTML to be laid out very precisely. No problem! We simply create an
328 "HTML::Template" compatible template and tell FormBuilder to use it.
329 Then, in our template, we include a couple special tags which
330 FormBuilder will automatically expand:
331 <html>
333 <head>
334 <title><tmpl_var form-title></title>
335 <tmpl_var js-head><!-- this holds the JavaScript code -->
336 </head>
337 <tmpl_var form-start><!-- this holds the initial form tag -->
338 <h3>User Information</h3>
339 Please fill out the following information:
340 <!-- each of these tmpl_var's corresponds to a field -->
341 <p>Your full name: <tmpl_var field-name>
342 <p>Your email address: <tmpl_var field-email>
343 <p>Choose a password: <tmpl_var field-password>
344 <p>Please confirm it: <tmpl_var field-confirm_password>
345 <p>Your home zipcode: <tmpl_var field-zipcode>
346 <p>
347 <tmpl_var form-submit><!-- this holds the form submit button -->
348 </form><!-- can also use "tmpl_var form-end", same thing -->
349 Then, all we need to do add the "template" option, and the rest of the
351 code stays the same:
352 my $form = CGI::FormBuilder->new(
354 fields => \@fields,
355 header => 1,
356 validate => {
357 name => 'NAME',
358 email => 'EMAIL'
359 },
360 template => 'userinfo.tmpl'
361 );
362 So, our complete code thus far looks like this:
364 use CGI::FormBuilder;
366 my @fields = qw(name email password confirm_password zipcode);
368 my $form = CGI::FormBuilder->new(
370 fields => \@fields,
371 header => 1,
372 validate => {
373 name => 'NAME',
374 email => 'EMAIL'
375 },
376 template => 'userinfo.tmpl',
377 );
378 if ($form->submitted && $form->validate) {
380 # form was good, let's update database
381 my $fields = $form->field;
382 # update database (you write this part)
384 do_data_update($fields);
385 # print confirmation screen
387 print $form->confirm;
388 } else {
390 # print the form for them to fill out
391 print $form->render;
392 }
393 You may be surprised to learn that for many applications, the above is
395 probably all you'll need. Just fill in the parts that affect what you
396 want to do (like the database code), and you're on your way.
397 Note: If you are confused at all by the backslashes you see in front of
399 some data pieces above, such as "\@fields", skip down to the brief
400 section entitled "REFERENCES" at the bottom of this document (it's
401 short).
402
404 This documentation is very extensive, but can be a bit dizzying due to
405 the enormous number of options that let you tweak just about anything.
406 As such, I recommend that you stop and visit:
407 www.formbuilder.org
409 And click on "Tutorials" and "Examples". Then, use the following
411 section as a reference later on.
412 new()
414 This method creates a new $form object, which you then use to generate
415 and process your form. In the very shortest version, you can just
416 specify a list of fields for your form:
417 my $form = CGI::FormBuilder->new(
419 fields => [qw(first_name birthday favorite_car)]
420 );
421 As of 3.02:
423 my $form = CGI::FormBuilder->new(
425 source => 'myform.conf' # form and field options
426 );
427 For details on the external file format, see
429 CGI::FormBuilder::Source::File.
430 Any of the options below, in addition to being specified to "new()",
432 can also be manipulated directly with a method of the same name. For
433 example, to change the "header" and "stylesheet" options, either of
434 these works:
435 # Way 1
437 my $form = CGI::FormBuilder->new(
438 fields => \@fields,
439 header => 1,
440 stylesheet => '/path/to/style.css',
441 );
442 # Way 2
444 my $form = CGI::FormBuilder->new(
445 fields => \@fields
446 );
447 $form->header(1);
448 $form->stylesheet('/path/to/style.css');
449 The second form is useful if you want to wrap certain options in
451 conditionals:
452 if ($have_template) {
454 $form->header(0);
455 $form->template('template.tmpl');
456 } else {
457 $form->header(1);
458 $form->stylesheet('/path/to/style.css');
459 }
460 The following is a description of each option, in alphabetical order:
462 action => $script
464 What script to point the form to. Defaults to itself, which is the
465 recommended setting.
466 body => \%attr
468 This takes a hashref of attributes that will be stuck in the
469 "<body>" tag verbatim (for example, bgcolor, alink, etc). See the
470 "fieldattr" tag for more details, and also the "template" option.
471 charset
473 This forcibly overrides the charset. Better handled by loading an
474 appropriate "messages" module, which will set this for you. See
475 CGI::FormBuilder::Messages for more details.
476 debug => 0 | 1 | 2 | 3
478 If set to 1, the module spits copious debugging info to STDERR. If
479 set to 2, it spits out even more gunk. 3 is too much. Defaults to
480 0.
481 fields => \@array | \%hash
483 As shown above, the "fields" option takes an arrayref of fields to
484 use in the form. The fields will be printed out in the same order
485 they are specified. This option is needed if you expect your form
486 to have any fields, and is the central option to FormBuilder.
487 You can also specify a hashref of key/value pairs. The advantage is
489 you can then bypass the "values" option. However, the big
490 disadvantage is you cannot control the order of the fields. This is
491 ok if you're using a template, but in real-life it turns out that
492 passing a hashref to "fields" is not very useful.
493 fieldtype => 'type'
495 This can be used to set the default type for all fields in the
496 form. You can then override it on a per-field basis using the
497 "field()" method.
498 fieldattr => \%attr
500 This option allows you to specify any HTML attribute and have it be
501 the default for all fields. This used to be good for stylesheets,
502 but now that there is a "stylesheet" option, this is fairly
503 useless.
504 fieldsets => \@attr
506 This allows you to define fieldsets for your form. Fieldsets are
507 used to group fields together. Fields are rendered in order, inside
508 the fieldset they belong to. If a field does not have a fieldset,
509 it is appended to the end of the form.
510 To use fieldsets, specify an arrayref of "<fieldset>" names:
512 fieldsets => [qw(account preferences contacts)]
514 You can get a different "<legend>" tag if you specify a nested
516 arrayref:
517 fieldsets => [
519 [ account => 'Account Information' ],
520 [ preferences => 'Website Preferences' ],
521 [ contacts => 'Email and Phone Numbers' ],
522 ]
523 If you're using the source file, that looks like this:
525 fieldsets: account=Account Information,preferences=...
527 Then, for each field, specify which fieldset it belongs to:
529 $form->field(name => 'first_name', fieldset => 'account');
531 $form->field(name => 'last_name', fieldset => 'account');
532 $form->field(name => 'email_me', fieldset => 'preferences');
533 $form->field(name => 'home_phone', fieldset => 'contacts');
534 $form->field(name => 'work_phone', fieldset => 'contacts');
535 You can also automatically create a new "fieldset" on the fly by
537 specifying a new one:
538 $form->field(name => 'remember_me', fieldset => 'advanced');
540 To set the "<legend>" in this case, you have two options. First,
542 you can just choose a more readable "fieldset" name:
543 $form->field(name => 'remember_me',
545 fieldset => 'Advanced');
546 Or, you can change the name using the "fieldset" accessor:
548 $form->fieldset(advanced => 'Advanced Options');
550 Note that fieldsets without fields are silently ignored, so you can
552 also just specify a huge list of possible fieldsets to "new()", and
553 then only add fields as you need them.
554 fieldsubs => 0 | 1
556 This allows autoloading of field names so you can directly access
557 them as:
558 $form->$fieldname(opt => 'val');
560 Instead of:
562 $form->field(name => $fieldname, opt => 'val');
564 Warning: If present, it will hide any attributes of the same name.
566 For example, if you define "name" field, you won't be able to
567 change your form's name dynamically. Also, you cannot use this
568 format to create new fields. Use with caution.
569 font => $font | \%attr
571 The font face to use for the form. This is output as a series of
572 "<font>" tags for old browser compatibility, and will properly nest
573 them in all of the table elements. If you specify a hashref instead
574 of just a font name, then each key/value pair will be taken as part
575 of the "<font>" tag:
576 font => {face => 'verdana', size => '-1', color => 'gray'}
578 The above becomes:
580 <font face="verdana" size="-1" color="gray">
582 I used to use this all the time, but the "stylesheet" option is SO
584 MUCH BETTER. Trust me, take a day and learn the basics of CSS, it's
585 totally worth it.
586 header => 0 | 1
588 If set to 1, a valid "Content-type" header will be printed out,
589 along with a whole bunch of HTML "<body>" code, a "<title>" tag,
590 and so on. This defaults to 0, since often people end up using
591 templates or embedding forms in other HTML.
592 javascript => 0 | 1
594 If set to 1, JavaScript is generated in addition to HTML, the
595 default setting.
596 jserror => 'function_name'
598 If specified, this will get called instead of the standard JS
599 "alert()" function on error. The function signature is:
600 function_name(form, invalid, alertstr, invalid_fields)
602 The function can be named anything you like. A simple one might
604 look like this:
605 my $form = CGI::FormBuilder->new(
607 jserror => 'field_errors',
608 jshead => <<'EOJS',
609 function field_errors(form, invalid, alertstr, invalid_fields) {
610 // first reset all fields
611 for (var i=0; i < form.elements.length; i++) {
612 form.elements[i].className = 'normal_field';
613 }
614 // now attach a special style class to highlight the field
615 for (var i=0; i < invalid_fields.length; i++) {
616 form.elements[invalid_fields[i]].className = 'invalid_field';
617 }
618 alert(alertstr);
619 return false;
620 }
621 EOJS
622 );
623 Note that it should return false to prevent form submission.
625 This can be used in conjunction with "jsfunc", which can add
627 additional manual validations before "jserror" is called.
628 jsfunc => $jscode
630 This is verbatim JavaScript that will go into the "validate"
631 JavaScript function. It is useful for adding your own validation
632 code, while still getting all the automatic hooks. If something
633 fails, you should do two things:
634 1. append to the JavaScript string "alertstr"
636 2. increment the JavaScript number "invalid"
637 For example:
639 my $jsfunc = <<'EOJS'; # note single quote (see Hint)
641 if (form.password.value == 'password') {
642 alertstr += "Moron, you can't use 'password' for your password!\\n";
643 invalid++;
644 }
645 EOJS
646 my $form = CGI::FormBuilder->new(... jsfunc => $jsfunc);
648 Then, this code will be automatically called when form validation
650 is invoked. I find this option can be incredibly useful. Most
651 often, I use it to bypass validation on certain submit modes. The
652 submit button that was clicked is "form._submit.value":
653 my $jsfunc = <<'EOJS'; # note single quotes (see Hint)
655 if (form._submit.value == 'Delete') {
656 if (confirm("Really DELETE this entry?")) return true;
657 return false;
658 } else if (form._submit.value == 'Cancel') {
659 // skip validation since we're cancelling
660 return true;
661 }
662 EOJS
663 Hint: To prevent accidental expansion of embedding strings and
665 escapes, you should put your "HERE" string in single quotes, as
666 shown above.
667 jshead => $jscode
669 If using JavaScript, you can also specify some JavaScript code that
670 will be included verbatim in the <head> section of the document.
671 I'm not very fond of this one, what you probably want is the
672 previous option.
673 keepextras => 0 | 1 | \@array
675 If set to 1, then extra parameters not set in your fields
676 declaration will be kept as hidden fields in the form. However, you
677 will need to use "cgi_param()", NOT "field()", to access the
678 values.
679 This is useful if you want to keep some extra parameters like mode
681 or company available but not have them be valid form fields:
682 keepextras => 1
684 That will preserve any extra params. You can also specify an
686 arrayref, in which case only params in that list will be preserved.
687 For example:
688 keepextras => [qw(mode company)]
690 Will only preserve the params "mode" and "company". Again, to
692 access them:
693 my $mode = $form->cgi_param('mode');
695 $form->cgi_param(name => 'mode', value => 'relogin');
696 See "CGI.pm" for details on "param()" usage.
698 labels => \%hash
700 Like "values", this is a list of key/value pairs where the keys are
701 the names of "fields" specified above. By default, FormBuilder does
702 some snazzy case and character conversion to create pretty labels
703 for you. However, if you want to explicitly name your fields, use
704 this option.
705 For example:
707 my $form = CGI::FormBuilder->new(
709 fields => [qw(name email)],
710 labels => {
711 name => 'Your Full Name',
712 email => 'Primary Email Address'
713 }
714 );
715 Usually you'll find that if you're contemplating this option what
717 you really want is a template.
718 lalign => 'left' | 'right' | 'center'
720 A legacy shortcut for:
721 th => { align => 'left' }
723 Even better, use the "stylesheet" option and tweak the ".fb_label"
725 class. Either way, don't use this.
726 lang
728 This forcibly overrides the lang. Better handled by loading an
729 appropriate "messages" module, which will set this for you. See
730 CGI::FormBuilder::Messages for more details.
731 method => 'post' | 'get'
733 The type of CGI method to use, either "post" or "get". Defaults to
734 "get" if nothing is specified. Note that for forms that cause
735 changes on the server, such as database inserts, you should use the
736 "post" method.
737 messages => 'auto' | $file | \%hash | $locale
739 This option overrides the default FormBuilder messages in order to
740 provide multilingual locale support (or just different text for the
741 picky ones). For details on this option, please refer to
742 CGI::FormBuilder::Messages.
743 name => $string
745 This names the form. It is optional, but when used, it renames
746 several key variables and functions according to the name of the
747 form. In addition, it also adds the following "<div>" tags to each
748 row of the table:
749 <tr id="${form}_${field}_row">
751 <td id="${form}_${field}_label">Label</td>
752 <td id="${form}_${field}_input"><input tag></td>
753 <td id="${form}_${field}_error">Error</td><!-- if invalid -->
754 </tr>
755 These changes allow you to (a) use multiple forms in a sequential
757 application and/or (b) display multiple forms inline in one
758 document. If you're trying to build a complex multi-form app and
759 are having problems, try naming your forms.
760 options => \%hash
762 This is one of several meta-options that allows you to specify
763 stuff for multiple fields at once:
764 my $form = CGI::FormBuilder->new(
766 fields => [qw(part_number department in_stock)],
767 options => {
768 department => [qw(hardware software)],
769 in_stock => [qw(yes no)],
770 }
771 );
772 This has the same effect as using "field()" for the "department"
774 and "in_stock" fields to set options individually.
775 params => $object
777 This specifies an object from which the parameters should be
778 derived. The object must have a "param()" method which will return
779 values for each parameter by name. By default a CGI object will be
780 automatically created and used.
781 However, you will want to specify this if you're using "mod_perl":
783 use Apache::Request;
785 use CGI::FormBuilder;
786 sub handler {
788 my $r = Apache::Request->new(shift);
789 my $form = CGI::FormBuilder->new(... params => $r);
790 print $form->render;
791 }
792 Or, if you need to initialize a "CGI.pm" object separately and are
794 using a "post" form method:
795 use CGI;
797 use CGI::FormBuilder;
798 my $q = new CGI;
800 my $form = CGI::FormBuilder->new(... params => $q);
801 Usually you don't need to do this, unless you need to access other
803 parameters outside of FormBuilder's control.
804 required => \@array | 'ALL' | 'NONE'
806 This is a list of those values that are required to be filled in.
807 Those fields named must be included by the user. If the "required"
808 option is not specified, by default any fields named in "validate"
809 will be required.
810 In addition, the "required" option also takes two other settings,
812 the strings "ALL" and "NONE". If you specify "ALL", then all fields
813 are required. If you specify "NONE", then none of them are in spite
814 of what may be set via the "validate" option.
815 This is useful if you have fields that are optional, but that you
817 want to be validated if filled in:
818 my $form = CGI::FormBuilder->new(
820 fields => qw[/name email/],
821 validate => { email => 'EMAIL' },
822 required => 'NONE'
823 );
824 This would make the "email" field optional, but if filled in then
826 it would have to match the "EMAIL" pattern.
827 In addition, it is very important to note that if the "required"
829 and "validate" options are specified, then they are taken as an
830 intersection. That is, only those fields specified as "required"
831 must be filled in, and the rest are optional. For example:
832 my $form = CGI::FormBuilder->new(
834 fields => qw[/name email/],
835 validate => { email => 'EMAIL' },
836 required => [qw(name)]
837 );
838 This would make the "name" field mandatory, but the "email" field
840 optional. However, if "email" is filled in, then it must match the
841 builtin "EMAIL" pattern.
842 reset => 0 | 1 | $string
844 If set to 0, then the "Reset" button is not printed. If set to
845 text, then that will be printed out as the reset button. Defaults
846 to printing out a button that says "Reset".
847 selectnum => $threshold
849 This detects how FormBuilder's auto-type generation works. If a
850 given field has options, then it will be a radio group by default.
851 However, if more than "selectnum" options are present, then it will
852 become a select list. The default is 5 or more options. For
853 example:
854 # This will be a radio group
856 my @opt = qw(Yes No);
857 $form->field(name => 'answer', options => \@opt);
858 # However, this will be a select list
860 my @states = qw(AK CA FL NY TX);
861 $form->field(name => 'state', options => \@states);
862 # Single items are checkboxes (allows unselect)
864 $form->field(name => 'answer', options => ['Yes']);
865 There is no threshold for checkboxes since, if you think about it,
867 they are really a multi-radio select group. As such, a radio group
868 becomes a checkbox group if the "multiple" option is specified and
869 the field has less than "selectnum" options. Got it?
870 smartness => 0 | 1 | 2
872 By default CGI::FormBuilder tries to be pretty smart for you, like
873 figuring out the types of fields based on their names and number of
874 options. If you don't want this behavior at all, set "smartness" to
875 0. If you want it to be really smart, like figuring out what type
876 of validation routines to use for you, set it to 2. It defaults to
877 1.
878 sortopts => BUILTIN | 1 | \&sub
880 If specified to "new()", this has the same effect as the same-named
881 option to "field()", only it applies to all fields.
882 source => $filename
884 You can use this option to initialize FormBuilder from an external
885 configuration file. This allows you to separate your field code
886 from your form layout, which is pretty cool. See
887 CGI::FormBuilder::Source::File for details on the format of the
888 external file.
889 static => 0 | 1 | 2
891 If set to 1, then the form will be output with static hidden
892 fields. If set to 2, then in addition fields without values will
893 be omitted. Defaults to 0.
894 sticky => 0 | 1
896 Determines whether or not form values should be sticky across
897 submissions. This defaults to 1, meaning values are sticky.
898 However, you may want to set it to 0 if you have a form which does
899 something like adding parts to a database. See the "EXAMPLES"
900 section for a good example.
901 submit => 0 | 1 | $string | \@array
903 If set to 0, then the "Submit" button is not printed. It defaults
904 to creating a button that says "Submit" verbatim. If given an
905 argument, then that argument becomes the text to show. For example:
906 print $form->render(submit => 'Do Lookup');
908 Would make it so the submit button says "Do Lookup" on it.
910 If you pass an arrayref of multiple values, you get a key benefit.
912 This will create multiple submit buttons, each with a different
913 value. In addition, though, when submitted only the one that was
914 clicked will be sent across CGI via some JavaScript tricks. So
915 this:
916 print $form->render(submit => ['Add A Gift', 'No Thank You']);
918 Would create two submit buttons. Clicking on either would submit
920 the form, but you would be able to see which one was submitted via
921 the "submitted()" function:
922 my $clicked = $form->submitted;
924 So if the user clicked "Add A Gift" then that is what would end up
926 in the variable $clicked above. This allows nice conditionality:
927 if ($form->submitted eq 'Add A Gift') {
929 # show the gift selection screen
930 } elsif ($form->submitted eq 'No Thank You')
931 # just process the form
932 }
933 See the "EXAMPLES" section for more details.
935 styleclass => $string
937 The string to use as the "style" name, if the following option is
938 enabled.
939 stylesheet => 0 | 1 | $path
941 This option turns on stylesheets in the HTML output by FormBuilder.
942 Each element is printed with the "class" of "styleclass" ("fb" by
943 default). It is up to you to provide the actual style definitions.
944 If you provide a $path rather than just a 1/0 toggle, then that
945 $path will be included in a "<link>" tag as well.
946 The following tags are created by this option:
948 ${styleclass} top-level table/form class
950 ${styleclass}_required labels for fields that are required
951 ${styleclass}_invalid any fields that failed validate()
952 If you're contemplating stylesheets, the best thing is to just turn
954 this option on, then see what's spit out.
955 See the section on "STYLESHEETS" for more details on FormBuilder
957 style sheets.
958 table => 0 | 1 | \%tabletags
960 By default FormBuilder decides how to layout the form based on the
961 number of fields, values, etc. You can force it into a table by
962 specifying 1, or force it out of one with 0.
963 If you specify a hashref instead, then these will be used to create
965 the "<table>" tag. For example, to create a table with no
966 cellpadding or cellspacing, use:
967 table => {cellpadding => 0, cellspacing => 0}
969 Also, you can specify options to the "<td>" and "<tr>" elements as
971 well in the same fashion.
972 template => $filename | \%hash | \&sub | $object
974 This points to a filename that contains an "HTML::Template"
975 compatible template to use to layout the HTML. You can also specify
976 the "template" option as a reference to a hash, allowing you to
977 further customize the template processing options, or use other
978 template engines.
979 If "template" points to a sub reference, that routine is called and
981 its return value directly returned. If it is an object, then that
982 object's "render()" routine is called and its value returned.
983 For lots more information, please see CGI::FormBuilder::Template.
985 text => $text
987 This is text that is included below the title but above the actual
988 form. Useful if you want to say something simple like "Contact $adm
989 for more help", but if you want lots of text check out the
990 "template" option above.
991 title => $title
993 This takes a string to use as the title of the form.
994 values => \%hash | \@array
996 The "values" option takes a hashref of key/value pairs specifying
997 the default values for the fields. These values will be overridden
998 by the values entered by the user across the CGI. The values are
999 used case-insensitively, making it easier to use DBI hashref
1000 records (which are in upper or lower case depending on your
1001 database).
1002 This option is useful for selecting a record from a database or
1004 hardwiring some sensible defaults, and then including them in the
1005 form so that the user can change them if they wish. For example:
1006 my $rec = $sth->fetchrow_hashref;
1008 my $form = CGI::FormBuilder->new(fields => \@fields,
1009 values => $rec);
1010 You can also pass an arrayref, in which case each value is used
1012 sequentially for each field as specified to the "fields" option.
1013 validate => \%hash | $object
1015 This option takes either a hashref of key/value pairs or a
1016 Data::FormValidator object.
1017 In the case of the hashref, each key is the name of a field from
1019 the "fields" option, or the string "ALL" in which case it applies
1020 to all fields. Each value is one of the following:
1021 - a regular expression in 'quotes' to match against
1023 - an arrayref of values, of which the field must be one
1024 - a string that corresponds to one of the builtin patterns
1025 - a string containing a literal code comparison to do
1026 - a reference to a sub to be used to validate the field
1027 (the sub will receive the value to check as the first arg)
1028 In addition, each of these can also be grouped together as:
1030 - a hashref containing pairings of comparisons to do for
1032 the two different languages, "javascript" and "perl"
1033 By default, the "validate" option also toggles each field to make
1035 it required. However, you can use the "required" option to change
1036 this, see it for more details.
1037 Let's look at a concrete example. Note that the javascript
1039 validation is a negative match, while the perl validation is a
1040 positive match.
1041 my $form = CGI::FormBuilder->new(
1043 fields => [qw(
1044 username password confirm_password
1045 first_name last_name email
1046 )],
1047 validate => {
1048 username => [qw(nate jim bob)],
1049 first_name => '/^\w+$/', # note the
1050 last_name => '/^\w+$/', # single quotes!
1051 email => 'EMAIL',
1052 password => \&check_password,
1053 confirm_password => {
1054 javascript => '!= form.password.value', # neg
1055 perl => 'eq $form->field("password")', # pos
1056 },
1057 },
1058 );
1059 # simple sub example to check the password
1061 sub check_password ($) {
1062 my $v = shift; # first arg is value
1063 return unless $v =~ /^.{6,8}/; # 6-8 chars
1064 return if $v eq "password"; # dummy check
1065 return unless passes_crack($v); # you write "passes_crack()"
1066 return 1; # success
1067 }
1068 This would create both JavaScript and Perl routines on the fly that
1070 would ensure:
1071 - "username" was either "nate", "jim", or "bob"
1073 - "first_name" and "last_name" both match the regex's specified
1074 - "email" is a valid EMAIL format
1075 - "password" passes the checks done by check_password(), meaning
1076 that the sub returns true
1077 - "confirm_password" is equal to the "password" field
1078 Any regular expressions you specify must be enclosed in single
1080 quotes because they need to be used in both JavaScript and Perl
1081 code. As such, specifying a "qr//" will NOT work.
1082 Note that for both the "javascript" and "perl" hashref code
1084 options, the form will be present as the variable named "form". For
1085 the Perl code, you actually get a complete $form object meaning
1086 that you have full access to all its methods (although the
1087 "field()" method is probably the only one you'll need for
1088 validation).
1089 In addition to taking any regular expression you'd like, the
1091 "validate" option also has many builtin defaults that can prove
1092 helpful:
1093 VALUE - is any type of non-null value
1095 WORD - is a word (\w+)
1096 NAME - matches [a-zA-Z] only
1097 FNAME - person's first name, like "Jim" or "Joe-Bob"
1098 LNAME - person's last name, like "Smith" or "King, Jr."
1099 NUM - number, decimal or integer
1100 INT - integer
1101 FLOAT - floating-point number
1102 PHONE - phone number in form "123-456-7890" or "(123) 456-7890"
1103 INTPHONE- international phone number in form "+prefix local-number"
1104 EMAIL - email addr in form "name@host.domain"
1105 CARD - credit card, including Amex, with or without -'s
1106 DATE - date in format MM/DD/YYYY
1107 EUDATE - date in format DD/MM/YYYY
1108 MMYY - date in format MM/YY or MMYY
1109 MMYYYY - date in format MM/YYYY or MMYYYY
1110 CCMM - strict checking for valid credit card 2-digit month ([0-9]|1[012])
1111 CCYY - valid credit card 2-digit year
1112 ZIPCODE - US postal code in format 12345 or 12345-6789
1113 STATE - valid two-letter state in all uppercase
1114 IPV4 - valid IPv4 address
1115 NETMASK - valid IPv4 netmask
1116 FILE - UNIX format filename (/usr/bin)
1117 WINFILE - Windows format filename (C:\windows\system)
1118 MACFILE - MacOS format filename (folder:subfolder:subfolder)
1119 HOST - valid hostname (some-name)
1120 DOMAIN - valid domainname (www.i-love-bacon.com)
1121 ETHER - valid ethernet address using either : or . as separators
1122 I know some of the above are US-centric, but then again that's
1124 where I live. :-) So if you need different processing just create
1125 your own regular expression and pass it in. If there's something
1126 really useful let me know and maybe I'll add it.
1127 You can also pass a Data::FormValidator object as the value of
1129 "validate". This allows you to do things like requiring any one of
1130 several fields (but where you don't care which one). In this case,
1131 the "required" option to "new()" is ignored, since you should be
1132 setting the required fields through your FormValidator profile.
1133 By default, FormBuilder will try to use a profile named `fb' to
1135 validate itself. You can change this by providing a different
1136 profile name when you call "validate()".
1137 Note that currently, doing validation through a FormValidator
1139 object doesn't generate any JavaScript validation code for you.
1140 Note that any other options specified are passed to the "<form>" tag
1142 verbatim. For example, you could specify "onsubmit" or "enctype" to add
1143 the respective attributes.
1144 prepare()
1146 This function prepares a form for rendering. It is automatically called
1147 by "render()", but calling it yourself may be useful if you are using
1148 Catalyst or some other large framework. It returns the same hash that
1149 will be used by "render()":
1150 my %expanded = $form->prepare;
1152 You could use this to, say, tweak some custom values and then pass it
1154 to your own rendering object.
1155 render()
1157 This function renders the form into HTML, and returns a string
1158 containing the form. The most common use is simply:
1159 print $form->render;
1161 You can also supply options to "render()", just like you had called the
1163 accessor functions individually. These two uses are equivalent:
1164 # this code:
1166 $form->header(1);
1167 $form->stylesheet('style.css');
1168 print $form->render;
1169 # is the same as:
1171 print $form->render(header => 1,
1172 stylesheet => 'style.css');
1173 Note that both forms make permanent changes to the underlying object.
1175 So the next call to "render()" will still have the header and
1176 stylesheet options in either case.
1177 field()
1179 This method is used to both get at field values:
1180 my $bday = $form->field('birthday');
1182 As well as make changes to their attributes:
1184 $form->field(name => 'fname',
1186 label => "First Name");
1187 A very common use is to specify a list of options and/or the field
1189 type:
1190 $form->field(name => 'state',
1192 type => 'select',
1193 options => \@states); # you supply @states
1194 In addition, when you call "field()" without any arguments, it returns
1196 a list of valid field names in an array context:
1197 my @fields = $form->field;
1199 And a hashref of field/value pairs in scalar context:
1201 my $fields = $form->field;
1203 my $name = $fields->{name};
1204 Note that if you call it in this manner, you only get one single value
1206 per field. This is fine as long as you don't have multiple values per
1207 field (the normal case). However, if you have a field that allows
1208 multiple options:
1209 $form->field(name => 'color', options => \@colors,
1211 multiple => 1); # allow multi-select
1212 Then you will only get one value for "color" in the hashref. In this
1214 case you'll need to access it via "field()" to get them all:
1215 my @colors = $form->field('color');
1217 The "name" option is described first, and the remaining options are in
1219 order:
1220 name => $name
1222 The field to manipulate. The "name =>" part is optional if it's the
1223 only argument. For example:
1224 my $email = $form->field(name => 'email');
1226 my $email = $form->field('email'); # same thing
1227 However, if you're specifying more than one argument, then you must
1229 include the "name" part:
1230 $form->field(name => 'email', size => '40');
1232 add_after_option => $html
1234 Adds the specified HTML code after each checkbox (or radio) option.
1235 add_before_option => $html
1237 Adds the specified HTML code before each checkbox (or radio)
1238 option.
1239 columns => 0 | $width
1241 If set and the field is of type 'checkbox' or 'radio', then the
1242 options will be wrapped at the given width.
1243 comment => $string
1245 This prints out the given comment after the field. A good use of
1246 this is for additional help on what the field should contain:
1247 $form->field(name => 'dob',
1249 label => 'D.O.B.',
1250 comment => 'in the format MM/DD/YY');
1251 The above would yield something like this:
1253 D.O.B. [____________] in the format MM/DD/YY
1255 The comment is rendered verbatim, meaning you can use HTML links or
1257 code in it if you want.
1258 cleanopts => 0 | 1
1260 If set to 1 (the default), field options are escaped to make sure
1261 any special chars don't screw up the HTML. Set to 0 if you want to
1262 include verbatim HTML in your options, and know what you're doing.
1263 cookies => 0 | 1
1265 Controls whether to generate a cookie if "sessionid" has been set.
1266 This also requires that "header" be set as well, since the cookie
1267 is wrapped in the header. Defaults to 1, meaning it will
1268 automatically work if you turn on "header".
1269 force => 0 | 1
1271 This is used in conjunction with the "value" option to forcibly
1272 override a field's value. See below under the "value" option for
1273 more details. For compatibility with "CGI.pm", you can also call
1274 this option "override" instead, but don't tell anyone.
1275 growable => 0 | 1 | $limit
1277 This option adds a button and the appropriate JavaScript code to
1278 your form to allow the additional copies of the field to be added
1279 by the client filling out the form. Currently, this only works with
1280 "text" and "file" field types.
1281 If you set "growable" to a positive integer greater than 1, that
1283 will become the limit of growth for that field. You won't be able
1284 to add more than $limit extra inputs to the form, and FormBuilder
1285 will issue a warning if the CGI params come in with more than the
1286 allowed number of values.
1287 jsclick => $jscode
1289 This is a cool abstraction over directly specifying the JavaScript
1290 action. This turns out to be extremely useful, since if a field
1291 type changes from "select" to "radio" or "checkbox", then the
1292 action changes from "onchange" to "onclick". Why?!?!
1293 So if you said:
1295 $form->field(name => 'credit_card',
1297 options => \@cards,
1298 jsclick => 'recalc_total();');
1299 This would generate the following code, depending on the number of
1301 @cards:
1302 <select name="credit_card" onchange="recalc_total();"> ...
1304 <radio name="credit_card" onclick="recalc_total();"> ...
1306 You get the idea.
1308 jsmessage => $string
1310 You can use this to specify your own custom message for the field,
1311 which will be printed if it fails validation. The "jsmessage"
1312 option affects the JavaScript popup box, and the "message" option
1313 affects what is printed out if the server-side validation fails.
1314 If "message" is specified but not "jsmessage", then "message" will
1315 be used for JavaScript as well.
1316 $form->field(name => 'cc',
1318 label => 'Credit Card',
1319 message => 'Invalid credit card number',
1320 jsmessage => 'The card number in "%s" is invalid');
1321 The %s will be filled in with the field's "label".
1323 label => $string
1325 This is the label printed out before the field. By default it is
1326 automatically generated from the field name. If you want to be
1327 really lazy, get in the habit of naming your database fields as
1328 complete words so you can pass them directly to/from your form.
1329 labels => \%hash
1331 This option to field() is outdated. You can get the same effect by
1332 passing data structures directly to the "options" argument (see
1333 below). If you have well-named data, check out the "nameopts"
1334 option.
1335 This takes a hashref of key/value pairs where each key is one of
1337 the options, and each value is what its printed label should be:
1338 $form->field(name => 'state',
1340 options => [qw(AZ CA NV OR WA)],
1341 labels => {
1342 AZ => 'Arizona',
1343 CA => 'California',
1344 NV => 'Nevada',
1345 OR => 'Oregon',
1346 WA => 'Washington
1347 });
1348 When rendered, this would create a select list where the option
1350 values were "CA", "NV", etc, but where the state's full name was
1351 displayed for the user to select. As mentioned, this has the exact
1352 same effect:
1353 $form->field(name => 'state',
1355 options => [
1356 [ AZ => 'Arizona' ],
1357 [ CA => 'California' ],
1358 [ NV => 'Nevada' ],
1359 [ OR => 'Oregon' ],
1360 [ WA => 'Washington ],
1361 ]);
1362 I can think of some rare situations where you might have a set of
1364 predefined labels, but only some of those are present in a given
1365 field... but usually you should just use the "options" arg.
1366 linebreaks => 0 | 1
1368 Similar to the top-level "linebreaks" option, this one will put
1369 breaks in between options, to space things out more. This is useful
1370 with radio and checkboxes especially.
1371 message => $string
1373 Like "jsmessage", this customizes the output error string if
1374 server-side validation fails for the field. The "message" option
1375 will also be used for JavaScript messages if it is specified but
1376 "jsmessage" is not. See above under "jsmessage" for details.
1377 multiple => 0 | 1
1379 If set to 1, then the user is allowed to choose multiple values
1380 from the options provided. This turns radio groups into checkboxes
1381 and selects into multi-selects. Defaults to automatically being
1382 figured out based on number of values.
1383 nameopts => 0 | 1
1385 If set to 1, then options for select lists will be automatically
1386 named using the same algorithm as field labels. For example:
1387 $form->field(name => 'department',
1389 options => qw[(molecular_biology
1390 philosophy psychology
1391 particle_physics
1392 social_anthropology)],
1393 nameopts => 1);
1394 This would create a list like:
1396 <select name="department">
1398 <option value="molecular_biology">Molecular Biology</option>
1399 <option value="philosophy">Philosophy</option>
1400 <option value="psychology">Psychology</option>
1401 <option value="particle_physics">Particle Physics</option>
1402 <option value="social_anthropology">Social Anthropology</option>
1403 </select>
1404 Basically, you get names for the options that are determined in the
1406 same way as the names for the fields. This is designed as a simpler
1407 alternative to using custom "options" data structures if your data
1408 is regular enough to support it.
1409 other => 0 | 1 | \%attr
1411 If set, this automatically creates an "other" field to the right of
1412 the main field. This is very useful if you want to present a
1413 present list, but then also allow the user to enter their own
1414 entry:
1415 $form->field(name => 'vote_for_president',
1417 options => [qw(Bush Kerry)],
1418 other => 1);
1419 That would generate HTML somewhat like this:
1421 Vote For President: [ ] Bush [ ] Kerry [ ] Other: [______]
1423 If the "other" button is checked, then the box becomes editable so
1425 that the user can write in their own text. This "other" box will be
1426 subject to the same validation as the main field, to make sure your
1427 data for that field is consistent.
1428 options => \@options | \%options | \&sub
1430 This takes an arrayref of options. It also automatically results in
1431 the field becoming a radio (if < 5) or select list (if >= 5),
1432 unless you explicitly set the type with the "type" parameter:
1433 $form->field(name => 'opinion',
1435 options => [qw(yes no maybe so)]);
1436 From that, you will get something like this:
1438 <select name="opinion">
1440 <option value="yes">yes</option>
1441 <option value="no">no</option>
1442 <option value="maybe">maybe</option>
1443 <option value="so">so</option>
1444 </select>
1445 Also, this can accept more complicated data structures, allowing
1447 you to specify different labels and values for your options. If a
1448 given item is either an arrayref or hashref, then the first element
1449 will be taken as the value and the second as the label. For
1450 example, this:
1451 push @opt, ['yes', 'You betcha!'];
1453 push @opt, ['no', 'No way Jose'];
1454 push @opt, ['maybe', 'Perchance...'];
1455 push @opt, ['so', 'So'];
1456 $form->field(name => 'opinion', options => \@opt);
1457 Would result in something like the following:
1459 <select name="opinion">
1461 <option value="yes">You betcha!</option>
1462 <option value="no">No way Jose</option>
1463 <option value="maybe">Perchance...</option>
1464 <option value="so">So</option>
1465 </select>
1466 And this code would have the same effect:
1468 push @opt, { yes => 'You betcha!' };
1470 push @opt, { no => 'No way Jose' };
1471 push @opt, { maybe => 'Perchance...' };
1472 push @opt, { so => 'So' };
1473 $form->field(name => 'opinion', options => \@opt);
1474 Finally, you can specify a "\&sub" which must return either an
1476 "\@arrayref" or "\%hashref" of data, which is then expanded using
1477 the same algorithm.
1478 optgroups => 0 | 1 | \%hashref
1480 If "optgroups" is specified for a field ("select" fields only),
1481 then the above "options" array is parsed so that the third argument
1482 is taken as the name of the optgroup, and an "<optgroup>" tag is
1483 generated appropriately.
1484 An example will make this behavior immediately obvious:
1486 my $opts = $dbh->selectall_arrayref(
1488 "select id, name, category from software
1489 order by category, name"
1490 );
1491 $form->field(name => 'software_title',
1493 options => $opts,
1494 optgroups => 1);
1495 The "optgroups" setting would then parse the third element of $opts
1497 so that you'd get an "optgroup" every time that "category" changed:
1498 <optgroup label="antivirus">
1500 <option value="12">Norton Anti-virus 1.2</option>
1501 <option value="11">McAfee 1.1</option>
1502 </optgroup>
1503 <optgroup label="office">
1504 <option value="3">Microsoft Word</option>
1505 <option value="4">Open Office</option>
1506 <option value="6">WordPerfect</option>
1507 </optgroup>
1508 In addition, if "optgroups" is instead a hashref, then the name of
1510 the optgroup is gotten from that. Using the above example, this
1511 would help if you had the category name in a separate table, and
1512 were just storing the "category_id" in the "software" table. You
1513 could provide an "optgroups" hash like:
1514 my %optgroups = (
1516 1 => 'antivirus',
1517 2 => 'office',
1518 3 => 'misc',
1519 );
1520 $form->field(..., optgroups => \%optgroups);
1521 Note: No attempt is made by FormBuilder to properly sort your
1523 option optgroups - it is up to you to provide them in a sensible
1524 order.
1525 required => 0 | 1
1527 If set to 1, the field must be filled in:
1528 $form->field(name => 'email', required => 1);
1530 This is rarely useful - what you probably want are the "validate"
1532 and "required" options to "new()".
1533 selectname => 0 | 1 | $string
1535 By default, this is set to 1 and any single-select lists are
1536 prefixed by the message "form_select_default" ("-select-" for
1537 English). If set to 0, then this string is not prefixed. If set to
1538 a $string, then that string is used explicitly.
1539 Philosophically, the "-select-" behavior is intentional because it
1541 allows a null item to be transmitted (the same as not checking any
1542 checkboxes or radio buttons). Otherwise, the first item in a select
1543 list is automatically sent when the form is submitted. If you
1544 would like an item to be "pre-selected", consider using the "value"
1545 option to specify the default value.
1546 sortopts => BUILTIN | 1 | \&sub
1548 If set, and there are options, then the options will be sorted in
1549 the specified order. There are four possible values for the
1550 "BUILTIN" setting:
1551 NAME Sort option values by name
1553 NUM Sort option values numerically
1554 LABELNAME Sort option labels by name
1555 LABELNUM Sort option labels numerically
1556 For example:
1558 $form->field(name => 'category',
1560 options => \@cats,
1561 sortopts => 'NAME');
1562 Would sort the @cats options in alphabetic ("NAME") order. The
1564 option "NUM" would sort them in numeric order. If you specify "1",
1565 then an alphabetic sort is done, just like the default Perl sort.
1566 In addition, you can specify a sub reference which takes pairs of
1568 values to compare and returns the appropriate return value that
1569 Perl "sort()" expects.
1570 type => $type
1572 The type of input box to create. Default is "text", and valid
1573 values include anything allowed by the HTML specs, including
1574 "select", "radio", "checkbox", "textarea", "password", "hidden",
1575 and so on.
1576 By default, the type is automatically determined by FormBuilder
1578 based on the following algorithm:
1579 Field options?
1581 No = text (done)
1582 Yes:
1583 Less than 'selectnum' setting?
1584 No = select (done)
1585 Yes:
1586 Is the 'multiple' option set?
1587 Yes = checkbox (done)
1588 No:
1589 Have just one single option?
1590 Yes = checkbox (done)
1591 No = radio (done)
1592 I recommend you let FormBuilder do this for you in most cases, and
1594 only tweak those you really need to.
1595 value => $value | \@values
1597 The "value" option can take either a single value or an arrayref of
1598 multiple values. In the case of multiple values, this will result
1599 in the field automatically becoming a multiple select list or radio
1600 group, depending on the number of options specified.
1601 If a CGI value is present it will always win. To forcibly change a
1603 value, you need to specify the "force" option:
1604 # Example that hides credit card on confirm screen
1606 if ($form->submitted && $form->validate) {
1607 my $val = $form->field;
1608 # hide CC number
1610 $form->field(name => 'credit_card',
1611 value => '(not shown)',
1612 force => 1);
1613 print $form->confirm;
1615 }
1616 This would print out the string "(not shown)" on the "confirm()"
1618 screen instead of the actual number.
1619 validate => '/regex/'
1621 Similar to the "validate" option used in "new()", this affects the
1622 validation just of that single field. As such, rather than a
1623 hashref, you would just specify the regex to match against.
1624 This regex must be specified as a single-quoted string, and NOT as
1626 a qr// regex. The reason for this is it needs to be usable by the
1627 JavaScript routines as well.
1628 $htmlattr => $htmlval
1630 In addition to the above tags, the "field()" function can take any
1631 other valid HTML attribute, which will be placed in the tag
1632 verbatim. For example, if you wanted to alter the class of the
1633 field (if you're using stylesheets and a template, for example),
1634 you could say:
1635 $form->field(name => 'email', class => 'FormField',
1637 size => 80);
1638 Then when you call "$form-"render> you would get a field something
1640 like this:
1641 <input type="text" name="email" class="FormField" size="80">
1643 (Of course, for this to really work you still have to create a
1645 class called "FormField" in your stylesheet.)
1646 See also the "fieldattr" option which provides global attributes to
1648 all fields.
1649 cgi_param()
1651 The above "field()" method will only return fields which you have
1652 explicitly defined in your form. Excess parameters will be silently
1653 ignored, to help ensure users can't mess with your form.
1654 But, you may have some times when you want extra params so that you can
1656 maintain state, but you don't want it to appear in your form. Branding
1657 is an easy example:
1658 http://hr-outsourcing.com/newuser.cgi?company=mr_propane
1660 This could change your page's HTML so that it displayed the appropriate
1662 company name and logo, without polluting your form parameters.
1663 This call simply redispatches to "CGI.pm"'s "param()" method, so
1665 consult those docs for more information.
1666 tmpl_param()
1668 This allows you to manipulate template parameters directly. Extending
1669 the above example:
1670 my $form = CGI::FormBuilder->new(template => 'some.tmpl');
1672 my $company = $form->cgi_param('company');
1674 $form->tmpl_param(company => $company);
1675 Then, in your template:
1677 Hello, <tmpl_var company> employee!
1679 <p>
1680 Please fill out this form:
1681 <tmpl_var form-start>
1682 <!-- etc... -->
1683 For really precise template control, you can actually create your own
1685 template object and then pass it directly to FormBuilder. See
1686 CGI::FormBuilder::Template for more details.
1687 sessionid()
1689 This gets and sets the sessionid, which is stored in the special form
1690 field "_sessionid". By default no session ids are generated or used.
1691 Rather, this is intended to provide a hook for you to easily integrate
1692 this with a session id module like "CGI::Session".
1693 Since you can set the session id via the "_sessionid" field, you can
1695 pass it as an argument when first showing the form:
1696 http://mydomain.com/forms/update_info.cgi?_sessionid=0123-091231
1698 This would set things up so that if you called:
1700 my $id = $form->sessionid;
1702 This would get the value "0123-091231" in your script. Conversely, if
1704 you generate a new sessionid on your own, and wish to include it
1705 automatically, simply set is as follows:
1706 $form->sessionid($id);
1708 If the sessionid is set, and "header" is set, then FormBuilder will
1710 also automatically generate a cookie for you.
1711 See "EXAMPLES" for "CGI::Session" example.
1713 submitted()
1715 This returns the value of the "Submit" button if the form has been
1716 submitted, undef otherwise. This allows you to either test it in a
1717 boolean context:
1718 if ($form->submitted) { ... }
1720 Or to retrieve the button that was actually clicked on in the case of
1722 multiple submit buttons:
1723 if ($form->submitted eq 'Update') {
1725 ...
1726 } elsif ($form->submitted eq 'Delete') {
1727 ...
1728 }
1729 It's best to call "validate()" in conjunction with this to make sure
1731 the form validation works. To make sure you're getting accurate info,
1732 it's recommended that you name your forms with the "name" option
1733 described above.
1734 If you're writing a multiple-form app, you should name your forms with
1736 the "name" option to ensure that you are getting an accurate return
1737 value from this sub. See the "name" option above, under "render()".
1738 You can also specify the name of an optional field which you want to
1740 "watch" instead of the default "_submitted" hidden field. This is
1741 useful if you have a search form and also want to be able to link to it
1742 from other documents directly, such as:
1743 mysearch.cgi?lookup=what+to+look+for
1745 Normally, "submitted()" would return false since the "_submitted" field
1747 is not included. However, you can override this by saying:
1748 $form->submitted('lookup');
1750 Then, if the lookup field is present, you'll get a true value.
1752 (Actually, you'll still get the value of the "Submit" button if
1753 present.)
1754 validate()
1756 This validates the form based on the validation criteria passed into
1757 "new()" via the "validate" option. In addition, you can specify
1758 additional criteria to check that will be valid for just that call of
1759 "validate()". This is useful is you have to deal with different geos:
1760 if ($location eq 'US') {
1762 $form->validate(state => 'STATE', zipcode => 'ZIPCODE');
1763 } else {
1764 $form->validate(state => '/^\w{2,3}$/');
1765 }
1766 You can also provide a Data::FormValidator object as the first
1768 argument. In that case, the second argument (if present) will be
1769 interpreted as the name of the validation profile to use. A single
1770 string argument will also be interpreted as a validation profile name.
1771 Note that if you pass args to your "validate()" function like this, you
1773 will not get JavaScript generated or required fields placed in bold.
1774 So, this is good for conditional validation like the above example, but
1775 for most applications you want to pass your validation requirements in
1776 via the "validate" option to the "new()" function, and just call the
1777 "validate()" function with no arguments.
1778 confirm()
1780 The purpose of this function is to print out a static confirmation
1781 screen showing a short message along with the values that were
1782 submitted. It is actually just a special wrapper around "render()",
1783 twiddling a couple options.
1784 If you're using templates, you probably want to specify a separate
1786 success template, such as:
1787 if ($form->submitted && $form->validate) {
1789 print $form->confirm(template => 'success.tmpl');
1790 } else {
1791 print $form->render(template => 'fillin.tmpl');
1792 }
1793 So that you don't get the same screen twice.
1795 mailconfirm()
1797 This sends a confirmation email to the named addresses. The "to"
1798 argument is required; everything else is optional. If no "from" is
1799 specified then it will be set to the address "auto-reply" since that is
1800 a common quasi-standard in the web app world.
1801 This does not send any of the form results. Rather, it simply prints
1803 out a message saying the submission was received.
1804 mailresults()
1806 This emails the form results to the specified address(es). By default
1807 it prints out the form results separated by a colon, such as:
1808 name: Nate Wiger
1810 email: nate@wiger.org
1811 colors: red green blue
1812 And so on. You can change this by specifying the "delimiter" and
1814 "joiner" options. For example this:
1815 $form->mailresults(to => $to, delimiter => '=', joiner => ',');
1817 Would produce an email like this:
1819 name=Nate Wiger
1821 email=nate@wiger.org
1822 colors=red,green,blue
1823 Note that now the last field ("colors") is separated by commas since
1825 you have multiple values and you specified a comma as your "joiner".
1826 mailresults() with plugin
1828 Now you can also specify a plugin to use with mailresults, in the
1829 namespace "CGI::FormBuilder::Mail::*". These plugins may depend on
1830 other libraries. For example, this:
1831 $form->mailresults(
1833 plugin => 'FormatMultiPart',
1834 from => 'Mark Hedges <hedges@ucsd.edu>',
1835 to => 'Nate Wiger <nwiger@gmail.com>',
1836 smtp => $smtp_host_or_ip,
1837 format => 'plain',
1838 );
1839 will send your mail formatted nicely in text using "Text::FormatTable".
1841 (And if you used format => 'html' it would use "HTML::QuickTable".)
1842 This particular plugin uses "MIME::Lite" and "Net::SMTP" to communicate
1844 directly with the SMTP server, and does not rely on a shell escape.
1845 See CGI::FormBuilder::Mail::FormatMultiPart for more information.
1846 This establishes a simple mail plugin implementation standard for your
1848 own mailresults() plugins. The plugin should reside under the
1849 "CGI::FormBuilder::Mail::*" namespace. It should have a constructor
1850 new() which accepts a hash-as-array of named arg parameters, including
1851 form => $form. It should have a mailresults() object method that does
1852 the right thing. It should use "CGI::FormBuilder::Util" and puke() if
1853 something goes wrong.
1854 Calling $form->mailresults( plugin => 'Foo', ... ) will load
1856 "CGI::FormBuilder::Mail::Foo" and will pass the FormBuilder object as a
1857 named param 'form' with all other parameters passed intact.
1858 If it should croak, confess, die or otherwise break if something goes
1860 wrong, FormBuilder.pm will warn any errors and the built-in
1861 mailresults() method will still try.
1862 mail()
1864 This is a more generic version of the above; it sends whatever is given
1865 as the "text" argument via email verbatim to the "to" address. In
1866 addition, if you're not running "sendmail" you can specify the "mailer"
1867 parameter to give the path of your mailer. This option is accepted by
1868 the above functions as well.
1869
1871 The following methods are provided to make FormBuilder behave more like
1872 other modules, when desired.
1873 header()
1875 Returns a "CGI.pm" header, but only if "header => 1" is set.
1876 param()
1878 This is an alias for "field()", provided for compatibility. However,
1879 while "field()" does act "compliantly" for easy use in "CGI::Session",
1880 "Apache::Request", etc, it is not 100% the same. As such, I recommend
1881 you use "field()" in your code, and let receiving objects figure the
1882 "param()" thing out when needed:
1883 my $sess = CGI::Session->new(...);
1885 $sess->save_param($form); # will see param()
1886 query_string()
1888 This returns a query string similar to "CGI.pm", but ONLY containing
1889 form fields and any "keepextras", if specified. Other params are
1890 ignored.
1891 self_url()
1893 This returns a self url, similar to "CGI.pm", but again ONLY with form
1894 fields.
1895 script_name()
1897 An alias for "$form->action".
1898
1900 If the "stylesheet" option is enabled (by setting it to 1 or the path
1901 of a CSS file), then FormBuilder will automatically output style
1902 classes for every single form element:
1903 fb main form table
1905 fb_label td containing field label
1906 fb_field td containing field input tag
1907 fb_submit td containing submit button(s)
1908 fb_input input types
1910 fb_select select types
1911 fb_checkbox checkbox types
1912 fb_radio radio types
1913 fb_option labels for checkbox/radio options
1914 fb_button button types
1915 fb_hidden hidden types
1916 fb_static static types
1917 fb_required span around labels for required fields
1919 fb_invalid span around labels for invalid fields
1920 fb_comment span around field comment
1921 fb_error span around field error message
1922 Here's a simple example that you can put in "fb.css" which spruces up a
1924 couple basic form features:
1925 /* FormBuilder */
1927 .fb {
1928 background: #ffc;
1929 font-family: verdana,arial,sans-serif;
1930 font-size: 10pt;
1931 }
1932 .fb_label {
1934 text-align: right;
1935 padding-right: 1em;
1936 }
1937 .fb_comment {
1939 font-size: 8pt;
1940 font-style: italic;
1941 }
1942 .fb_submit {
1944 text-align: center;
1945 }
1946 .fb_required {
1948 font-weight: bold;
1949 }
1950 .fb_invalid {
1952 color: #c00;
1953 font-weight: bold;
1954 }
1955 .fb_error {
1957 color: #c00;
1958 font-style: italic;
1959 }
1960 Of course, if you're familiar with CSS, you know alot more is possible.
1962 Also, you can mess with all the id's (if you name your forms) to
1963 manipulate fields more exactly.
1964
1966 I find this module incredibly useful, so here are even more examples,
1967 pasted from sample code that I've written:
1968 Ex1: order.cgi
1970 This example provides an order form, complete with validation of the
1971 important fields, and a "Cancel" button to abort the whole thing.
1972 #!/usr/bin/perl
1974 use strict;
1976 use CGI::FormBuilder;
1977 my @states = my_state_list(); # you write this
1979 my $form = CGI::FormBuilder->new(
1981 method => 'post',
1982 fields => [
1983 qw(first_name last_name
1984 email send_me_emails
1985 address state zipcode
1986 credit_card expiration)
1987 ],
1988 header => 1,
1990 title => 'Finalize Your Order',
1991 submit => ['Place Order', 'Cancel'],
1992 reset => 0,
1993 validate => {
1995 email => 'EMAIL',
1996 zipcode => 'ZIPCODE',
1997 credit_card => 'CARD',
1998 expiration => 'MMYY',
1999 },
2000 required => 'ALL',
2001 jsfunc => <<EOJS,
2002 // skip js validation if they clicked "Cancel"
2003 if (this._submit.value == 'Cancel') return true;
2004 EOJS
2005 );
2006 # Provide a list of states
2008 $form->field(name => 'state',
2009 options => \@states,
2010 sortopts=> 'NAME');
2011 # Options for mailing list
2013 $form->field(name => 'send_me_emails',
2014 options => [[1 => 'Yes'], [0 => 'No']],
2015 value => 0); # "No"
2016 # Check for valid order
2018 if ($form->submitted eq 'Cancel') {
2019 # redirect them to the homepage
2020 print $form->cgi->redirect('/');
2021 exit;
2022 }
2023 elsif ($form->submitted && $form->validate) {
2024 # your code goes here to do stuff...
2025 print $form->confirm;
2026 }
2027 else {
2028 # either first printing or needs correction
2029 print $form->render;
2030 }
2031 This will create a form called "Finalize Your Order" that will provide
2033 a pulldown menu for the "state", a radio group for "send_me_emails",
2034 and normal text boxes for the rest. It will then validate all the
2035 fields, using specific patterns for those fields specified to
2036 "validate".
2037 Ex2: order_form.cgi
2039 Here's an example that adds some fields dynamically, and uses the
2040 "debug" option spit out gook:
2041 #!/usr/bin/perl
2043 use strict;
2045 use CGI::FormBuilder;
2046 my $form = CGI::FormBuilder->new(
2048 method => 'post',
2049 fields => [
2050 qw(first_name last_name email
2051 address state zipcode)
2052 ],
2053 header => 1,
2054 debug => 2, # gook
2055 required => 'NONE',
2056 );
2057 # This adds on the 'details' field to our form dynamically
2059 $form->field(name => 'details',
2060 type => 'textarea',
2061 cols => '50',
2062 rows => '10');
2063 # And this adds user_name with validation
2065 $form->field(name => 'user_name',
2066 value => $ENV{REMOTE_USER},
2067 validate => 'NAME');
2068 if ($form->submitted && $form->validate) {
2070 # ... more code goes here to do stuff ...
2071 print $form->confirm;
2072 } else {
2073 print $form->render;
2074 }
2075 In this case, none of the fields are required, but the "user_name"
2077 field will still be validated if filled in.
2078 Ex3: ticket_search.cgi
2080 This is a simple search script that uses a template to layout the
2081 search parameters very precisely. Note that we set our options for our
2082 different fields and types.
2083 #!/usr/bin/perl
2085 use strict;
2087 use CGI::FormBuilder;
2088 my $form = CGI::FormBuilder->new(
2090 fields => [qw(type string status category)],
2091 header => 1,
2092 template => 'ticket_search.tmpl',
2093 submit => 'Search', # search button
2094 reset => 0, # and no reset
2095 );
2096 # Need to setup some specific field options
2098 $form->field(name => 'type',
2099 options => [qw(ticket requestor hostname sysadmin)]);
2100 $form->field(name => 'status',
2102 type => 'radio',
2103 options => [qw(incomplete recently_completed all)],
2104 value => 'incomplete');
2105 $form->field(name => 'category',
2107 type => 'checkbox',
2108 options => [qw(server network desktop printer)]);
2109 # Render the form and print it out so our submit button says "Search"
2111 print $form->render;
2112 Then, in our "ticket_search.tmpl" HTML file, we would have something
2114 like this:
2115 <html>
2117 <head>
2118 <title>Search Engine</title>
2119 <tmpl_var js-head>
2120 </head>
2121 <body bgcolor="white">
2122 <center>
2123 <p>
2124 Please enter a term to search the ticket database.
2125 <p>
2126 <tmpl_var form-start>
2127 Search by <tmpl_var field-type> for <tmpl_var field-string>
2128 <tmpl_var form-submit>
2129 <p>
2130 Status: <tmpl_var field-status>
2131 <p>
2132 Category: <tmpl_var field-category>
2133 <p>
2134 </form>
2135 </body>
2136 </html>
2137 That's all you need for a sticky search form with the above HTML
2139 layout. Notice that you can change the HTML layout as much as you want
2140 without having to touch your CGI code.
2141 Ex4: user_info.cgi
2143 This script grabs the user's information out of a database and lets
2144 them update it dynamically. The DBI information is provided as an
2145 example, your mileage may vary:
2146 #!/usr/bin/perl
2148 use strict;
2150 use CGI::FormBuilder;
2151 use DBI;
2152 use DBD::Oracle
2153 my $dbh = DBI->connect('dbi:Oracle:db', 'user', 'pass');
2155 # We create a new form. Note we've specified very little,
2157 # since we're getting all our values from our database.
2158 my $form = CGI::FormBuilder->new(
2159 fields => [qw(username password confirm_password
2160 first_name last_name email)]
2161 );
2162 # Now get the value of the username from our app
2164 my $user = $form->cgi_param('user');
2165 my $sth = $dbh->prepare("select * from user_info where user = '$user'");
2166 $sth->execute;
2167 my $default_hashref = $sth->fetchrow_hashref;
2168 # Render our form with the defaults we got in our hashref
2170 print $form->render(values => $default_hashref,
2171 title => "User information for '$user'",
2172 header => 1);
2173 Ex5: add_part.cgi
2175 This presents a screen for users to add parts to an inventory database.
2176 Notice how it makes use of the "sticky" option. If there's an error,
2177 then the form is presented with sticky values so that the user can
2178 correct them and resubmit. If the submission is ok, though, then the
2179 form is presented without sticky values so that the user can enter the
2180 next part.
2181 #!/usr/bin/perl
2183 use strict;
2185 use CGI::FormBuilder;
2186 my $form = CGI::FormBuilder->new(
2188 method => 'post',
2189 fields => [qw(sn pn model qty comments)],
2190 labels => {
2191 sn => 'Serial Number',
2192 pn => 'Part Number'
2193 },
2194 sticky => 0,
2195 header => 1,
2196 required => [qw(sn pn model qty)],
2197 validate => {
2198 sn => '/^[PL]\d{2}-\d{4}-\d{4}$/',
2199 pn => '/^[AQM]\d{2}-\d{4}$/',
2200 qty => 'INT'
2201 },
2202 font => 'arial,helvetica'
2203 );
2204 # shrink the qty field for prettiness, lengthen model
2206 $form->field(name => 'qty', size => 4);
2207 $form->field(name => 'model', size => 60);
2208 if ($form->submitted) {
2210 if ($form->validate) {
2211 # Add part to database
2212 } else {
2213 # Invalid; show form and allow corrections
2214 print $form->render(sticky => 1);
2215 exit;
2216 }
2217 }
2218 # Print form for next part addition.
2220 print $form->render;
2221 With the exception of the database code, that's the whole application.
2223 Ex6: Session Management
2225 This creates a session via "CGI::Session", and ties it in with
2226 FormBuilder:
2227 #!/usr/bin/perl
2229 use CGI::Session;
2231 use CGI::FormBuilder;
2232 my $form = CGI::FormBuilder->new(fields => \@fields);
2234 # Initialize session
2236 my $session = CGI::Session->new('driver:File',
2237 $form->sessionid,
2238 { Directory=>'/tmp' });
2239 if ($form->submitted && $form->validate) {
2241 # Automatically save all parameters
2242 $session->save_param($form);
2243 }
2244 # Ensure we have the right sessionid (might be new)
2246 $form->sessionid($session->id);
2247 print $form->render;
2249 Yes, it's pretty much that easy. See CGI::FormBuilder::Multi for how to
2251 tie this into a multi-page form.
2252
2254 There are a couple questions and subtle traps that seem to poke people
2255 on a regular basis. Here are some hints.
2256 I'm confused. Why doesn't this work like CGI.pm?
2258 If you're used to "CGI.pm", you have to do a little bit of a brain
2259 shift when working with this module.
2260 FormBuilder is designed to address fields as abstract entities. That
2262 is, you don't create a "checkbox" or "radio group" per se. Instead,
2263 you create a field for the data you want to collect. The HTML
2264 representation is just one property of this field.
2265 So, if you want a single-option checkbox, simply say something like
2267 this:
2268 $form->field(name => 'join_mailing_list',
2270 options => ['Yes']);
2271 If you want it to be checked by default, you add the "value" arg:
2273 $form->field(name => 'join_mailing_list',
2275 options => ['Yes'],
2276 value => 'Yes');
2277 You see, you're creating a field that has one possible option: "Yes".
2279 Then, you're saying its current value is, in fact, "Yes". This will
2280 result in FormBuilder creating a single-option field (which is a
2281 checkbox by default) and selecting the requested value (meaning that
2282 the box will be checked).
2283 If you want multiple values, then all you have to do is specify
2285 multiple options:
2286 $form->field(name => 'join_mailing_list',
2288 options => ['Yes', 'No'],
2289 value => 'Yes');
2290 Now you'll get a radio group, and "Yes" will be selected for you! By
2292 viewing fields as data entities (instead of HTML tags) you get much
2293 more flexibility and less code maintenance. If you want to be able to
2294 accept multiple values, simply use the "multiple" arg:
2295 $form->field(name => 'favorite_colors',
2297 options => [qw(red green blue)],
2298 multiple => 1);
2299 In all of these examples, to get the data back you just use the
2301 "field()" method:
2302 my @colors = $form->field('favorite_colors');
2304 And the rest is taken care of for you.
2306 How do I make a multi-screen/multi-mode form?
2308 This is easily doable, but you have to remember a couple things. Most
2309 importantly, that FormBuilder only knows about those fields you've told
2310 it about. So, let's assume that you're going to use a special parameter
2311 called "mode" to control the mode of your application so that you can
2312 call it like this:
2313 myapp.cgi?mode=list&...
2315 myapp.cgi?mode=edit&...
2316 myapp.cgi?mode=remove&...
2317 And so on. You need to do two things. First, you need the "keepextras"
2319 option:
2320 my $form = CGI::FormBuilder->new(..., keepextras => 1);
2322 This will maintain the "mode" field as a hidden field across requests
2324 automatically. Second, you need to realize that since the "mode" is not
2325 a defined field, you have to get it via the "cgi_param()" method:
2326 my $mode = $form->cgi_param('mode');
2328 This will allow you to build a large multiscreen application easily,
2330 even integrating it with modules like "CGI::Application" if you want.
2331 You can also do this by simply defining "mode" as a field in your
2333 "fields" declaration. The reason this is discouraged is because when
2334 iterating over your fields you'll get "mode", which you likely don't
2335 want (since it's not "real" data).
2336 Why won't CGI::FormBuilder work with post requests?
2338 It will, but chances are you're probably doing something like this:
2339 use CGI qw(:standard);
2341 use CGI::FormBuilder;
2342 # Our "mode" parameter determines what we do
2344 my $mode = param('mode');
2345 # Change our form based on our mode
2347 if ($mode eq 'view') {
2348 my $form = CGI::FormBuilder->new(
2349 method => 'post',
2350 fields => [qw(...)],
2351 );
2352 } elsif ($mode eq 'edit') {
2353 my $form = CGI::FormBuilder->new(
2354 method => 'post',
2355 fields => [qw(...)],
2356 );
2357 }
2358 The problem is this: Once you read a "post" request, it's gone forever.
2360 In the above code, what you're doing is having "CGI.pm" read the "post"
2361 request (on the first call of "param()").
2362 Luckily, there is an easy solution. First, you need to modify your code
2364 to use the OO form of "CGI.pm". Then, simply specify the "CGI" object
2365 you create to the "params" option of FormBuilder:
2366 use CGI;
2368 use CGI::FormBuilder;
2369 my $cgi = CGI->new;
2371 # Our "mode" parameter determines what we do
2373 my $mode = $cgi->param('mode');
2374 # Change our form based on our mode
2376 # Note: since it is post, must specify the 'params' option
2377 if ($mode eq 'view') {
2378 my $form = CGI::FormBuilder->new(
2379 method => 'post',
2380 fields => [qw(...)],
2381 params => $cgi # get CGI params
2382 );
2383 } elsif ($mode eq 'edit') {
2384 my $form = CGI::FormBuilder->new(
2385 method => 'post',
2386 fields => [qw(...)],
2387 params => $cgi # get CGI params
2388 );
2389 }
2390 Or, since FormBuilder gives you a "cgi_param()" function, you could
2392 also modify your code so you use FormBuilder exclusively, as in the
2393 previous question.
2394 How can I change option XXX based on a conditional?
2396 To change an option, simply use its accessor at any time:
2397 my $form = CGI::FormBuilder->new(
2399 method => 'post',
2400 fields => [qw(name email phone)]
2401 );
2402 my $mode = $form->cgi_param('mode');
2404 if ($mode eq 'add') {
2406 $form->title('Add a new entry');
2407 } elsif ($mode eq 'edit') {
2408 $form->title('Edit existing entry');
2409 # do something to select existing values
2411 my %values = select_values();
2412 $form->values(\%values);
2414 }
2415 print $form->render;
2416 Using the accessors makes permanent changes to your object, so be aware
2418 that if you want to reset something to its original value later, you'll
2419 have to first save it and then reset it:
2420 my $style = $form->stylesheet;
2422 $form->stylesheet(0); # turn off
2423 $form->stylesheet($style); # original setting
2424 You can also specify options to "render()", although using the
2426 accessors is the preferred way.
2427 How do I manually override the value of a field?
2429 You must specify the "force" option:
2430 $form->field(name => 'name_of_field',
2432 value => $value,
2433 force => 1);
2434 If you don't specify "force", then the CGI value will always win. This
2436 is because of the stateless nature of the CGI protocol.
2437 How do I make it so that the values aren't shown in the form?
2439 Turn off sticky:
2440 my $form = CGI::FormBuilder->new(... sticky => 0);
2442 By turning off the "sticky" option, you will still be able to access
2444 the values, but they won't show up in the form.
2445 I can't get "validate" to accept my regular expressions!
2447 You're probably not specifying them within single quotes. See the
2448 section on "validate" above.
2449 Can FormBuilder handle file uploads?
2451 It sure can, and it's really easy too. Just change the "enctype" as an
2452 option to "new()":
2453 use CGI::FormBuilder;
2455 my $form = CGI::FormBuilder->new(
2456 enctype => 'multipart/form-data',
2457 method => 'post',
2458 fields => [qw(filename)]
2459 );
2460 $form->field(name => 'filename', type => 'file');
2462 And then get to your file the same way as "CGI.pm":
2464 if ($form->submitted) {
2466 my $file = $form->field('filename');
2467 # save contents in file, etc ...
2469 open F, ">$dir/$file" or die $!;
2470 while (<$file>) {
2471 print F;
2472 }
2473 close F;
2474 print $form->confirm(header => 1);
2476 } else {
2477 print $form->render(header => 1);
2478 }
2479 In fact, that's a whole file upload program right there.
2481
2483 This really doesn't belong here, but unfortunately many people are
2484 confused by references in Perl. Don't be - they're not that tricky.
2485 When you take a reference, you're basically turning something into a
2486 scalar value. Sort of. You have to do this if you want to pass arrays
2487 intact into functions in Perl 5.
2488 A reference is taken by preceding the variable with a backslash (\).
2490 In our examples above, you saw something similar to this:
2491 my @fields = ('name', 'email'); # same as = qw(name email)
2493 my $form = CGI::FormBuilder->new(fields => \@fields);
2495 Here, "\@fields" is a reference. Specifically, it's an array reference,
2497 or "arrayref" for short.
2498 Similarly, we can do the same thing with hashes:
2500 my %validate = (
2502 name => 'NAME';
2503 email => 'EMAIL',
2504 );
2505 my $form = CGI::FormBuilder->new( ... validate => \%validate);
2507 Here, "\%validate" is a hash reference, or "hashref".
2509 Basically, if you don't understand references and are having trouble
2511 wrapping your brain around them, you can try this simple rule: Any time
2512 you're passing an array or hash into a function, you must precede it
2513 with a backslash. Usually that's true for CPAN modules.
2514 Finally, there are two more types of references: anonymous arrayrefs
2516 and anonymous hashrefs. These are created with "[]" and "{}",
2517 respectively. So, for our purposes there is no real difference between
2518 this code:
2519 my @fields = qw(name email);
2521 my %validate = (name => 'NAME', email => 'EMAIL');
2522 my $form = CGI::FormBuilder->new(
2524 fields => \@fields,
2525 validate => \%validate
2526 );
2527 And this code:
2529 my $form = CGI::FormBuilder->new(
2531 fields => [ qw(name email) ],
2532 validate => { name => 'NAME', email => 'EMAIL' }
2533 );
2534 Except that the latter doesn't require that we first create @fields and
2536 %validate variables.
2537
2539 FORMBUILDER_DEBUG
2540 This toggles the debug flag, so that you can control FormBuilder
2541 debugging globally. Helpful in mod_perl.
2542
2544 Parameters beginning with a leading underscore are reserved for future
2545 use by this module. Use at your own peril.
2546 The "field()" method has the alias "param()" for compatibility with
2548 other modules, allowing you to pass a $form around just like a $cgi
2549 object.
2550 The output of the HTML generated natively may change slightly from
2552 release to release. If you need precise control, use a template.
2553 Every attempt has been made to make this module taint-safe (-T).
2555 However, due to the way tainting works, you may run into the message
2556 "Insecure dependency" or "Insecure $ENV{PATH}". If so, make sure you
2557 are setting $ENV{PATH} at the top of your script.
2558
2560 This module has really taken off, thanks to very useful input, bug
2561 reports, and encouraging feedback from a number of people, including:
2562 Norton Allen
2564 Mark Belanger
2565 Peter Billam
2566 Brad Bowman
2567 Jonathan Buhacoff
2568 Godfrey Carnegie
2569 Jakob Curdes
2570 Laurent Dami
2571 Bob Egert
2572 Peter Eichman
2573 Adam Foxson
2574 Jorge Gonzalez
2575 Florian Helmberger
2576 Mark Hedges
2577 Mark Houliston
2578 Victor Igumnov
2579 Robert James Kaes
2580 Dimitry Kharitonov
2581 Randy Kobes
2582 William Large
2583 Kevin Lubic
2584 Robert Mathews
2585 Mehryar
2586 Klaas Naajikens
2587 Koos Pol
2588 Shawn Poulson
2589 Victor Porton
2590 Dan Collis Puro
2591 Wolfgang Radke
2592 David Siegal
2593 Stephan Springl
2594 Ryan Tate
2595 John Theus
2596 Remi Turboult
2597 Andy Wardley
2598 Raphael Wegmann
2599 Emanuele Zeppieri
2600 Thanks!
2602
2604 CGI::FormBuilder::Template, CGI::FormBuilder::Messages,
2605 CGI::FormBuilder::Multi, CGI::FormBuilder::Source::File,
2606 CGI::FormBuilder::Field, CGI::FormBuilder::Util,
2607 CGI::FormBuilder::Util, HTML::Template, Text::Template
2608 CGI::FastTemplate
2609
2611 $Id: FormBuilder.pm 65 2006-09-07 18:11:43Z nwiger $
2612
2614 Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.
2615 This module is free software; you may copy this under the terms of the
2617 GNU General Public License, or the Artistic License, copies of which
2618 should have accompanied your Perl kit.
2619perl v5.34.0 2021-07-22 CGI::FormBuilder(3)