1Catalyst::Controller::FUosremrBuCiolndterri(b3u)ted PerlCaDtoacluymsetn:t:aCtoinotnroller::FormBuilder(3)
2
3
4

NAME

6       Catalyst::Controller::FormBuilder - Catalyst FormBuilder Base Con‐
7       troller
8

SYNOPSIS

10           package MyApp::Controller::Books;
11           use base 'Catalyst::Controller::FormBuilder';
12
13           # optional config setup
14           __PACKAGE__->config(
15               'Controller::FormBuilder' = {
16                   template_type => 'HTML::Template',    # default is 'TT' (e.g. TT2)
17               }
18           );
19
20           # looks for books/edit.fb form configuration file, based on the presence of
21           # the ":Form" attribute.
22           sub edit : Local Form {
23               my ( $self, $c, @args ) = @_;
24
25               my $form = $self->formbuilder;
26
27               # add email form field to fields already defined edit.fb
28               $form->field( name => 'email', validate => 'EMAIL' );
29
30               if ( $form->submitted ) {
31                   if ( $form->validate ) {
32                       return $c->response->body("VALID FORM");
33                   }
34                   else {
35                       $c->stash->{ERROR}          = "INVALID FORM";
36                       $c->stash->{invalid_fields} =
37                         [ grep { !$_->validate } $form->fields ];
38                   }
39               }
40           }
41
42           # explicitedly use books/edit.fb, otherwise books/view.fb is used
43           sub view : Local Form('/books/edit') {
44               my ( $self, $c ) = @_;
45               $c->stash->{template} = "books/edit.tt" # TT2 template;
46           }
47

DESCRIPTION

49       This base controller merges the functionality of CGI::FormBuilder with
50       Catalyst and the following templating systems: Template Toolkit, Mason
51       and HTML::Template. This gives you access to all of FormBuilder's
52       niceties, such as controllablefield stickiness, multilingual support,
53       and Javascript generation. For more details, see CGI::FormBuilder or
54       the website at:
55
56           http://www.formbuilder.org
57
58       FormBuilder usage within Catalyst is straightforward. Since Catalyst
59       handles page rendering, you don't call FormBuilder's "render()" method,
60       as you would normally. Instead, you simply add a ":Form" attribute to
61       each method that you want to associate with a form. This will give you
62       access to a FormBuilder "$self->formbuilder" object within that con‐
63       troller method:
64
65           # An editing screen for books
66           sub edit : Local Form {
67               my ( $self, $c ) = @_;
68               $self->formbuilder->method('post');   # set form method
69           }
70
71       The out-of-the-box setup is to look for a form configuration file that
72       follows the CGI::FormBuilder::Source::File format (essentially YAML),
73       named for the current action url. So, if you were serving
74       "/books/edit", this plugin would look for:
75
76           root/forms/books/edit.fb
77
78       (The path is configurable.) If no source file is found, then it is
79       assumed you'll be setting up your fields manually. In your controller,
80       you will have to use the "$self->formbuilder" object to create your
81       fields, validation, and so on.
82
83       Here is an example "edit.fb" file:
84
85           # Form config file root/forms/books/edit.fb
86           name: books_edit
87           method: post
88           fields:
89               title:
90                   label: Book Title
91                   type:  text
92                   size:  40
93                   required: 1
94               author:
95                   label: Author's Name
96                   type:  text
97                   size:  80
98                   validate: NAME
99                   required: 1
100               isbn:
101                   label: ISBN#
102                   type:  text
103                   size:  20
104                   validate: /^(\d{10}⎪\d{13})$/
105                   required: 1
106               desc:
107                   label: Description
108                   type:  textarea
109                   cols:  80
110                   rows:  5
111
112           submit: Save New Book
113
114       This will automatically create a complete form for you, using the spec‐
115       ified fields. Note that the "root/forms" path is configurable; this
116       path is used by default to integrate with the "TTSite" helper.
117
118       Within your controller, you can call any method that you would on a
119       normal "CGI::FormBuilder" object on the "$self->formbuilder" object.
120       To manipulate the field named "desc", simply call the "field()" method:
121
122           # Change our desc field dynamically
123           $self->formbuilder->field(
124               name     => 'desc',
125               label    => 'Book Description',
126               required => 1
127           );
128
129       To populate field options for "country", you might use something like
130       this to iterate through the database:
131
132           $self->formbuilder->field(
133               name    => 'country',
134               options =>
135                 [ map { [ $_->id, $_->name ] } $c->model('MyApp::Country')->all ],
136               other => 1,    # create "Other:" box
137           );
138
139       This would create a select list with the last element as "Other:" to
140       allow the addition of more countries. See CGI::FormBuilder for methods
141       available to the form object.
142
143       The FormBuilder methodolody is to handle both rendering and validation
144       of the form. As such, the form will "loop back" onto the same con‐
145       troller method. Within your controller, you would then use the standard
146       FormBuilder submit/validate check:
147
148           if ( $self->formbuilder->submitted && $self->formbuilder->validate ) {
149               $c->forward('/books/save');
150           }
151
152       This would forward to "/books/save" if the form was submitted and
153       passed field validation. Otherwise, it would automatically re-render
154       the form with invalid fields highlighted, leaving the database
155       unchanged.
156
157       To render the form in your tt2 template for example, you can use "ren‐
158       der" to get a default table-based form:
159
160           <!-- root/src/books/edit.tt -->
161           [% FormBuilder.render %]
162
163       You can also get fine-tuned control over your form layout from within
164       your template.
165

TEMPLATES

167       The simplest way to get your form into HTML is to reference the "Form‐
168       Builder.render" method, as shown above. However, frequently you want
169       more control.
170
171       Only Template Toolkit, Mason and HTML::Template are currently sup‐
172       ported, but if your templating system's stash requirements are identi‐
173       cal to one of these, simply choose and define it via the "tem‐
174       plate_type" config option.  Of course, make sure you have a View to
175       support the template, since this module does not render templates.
176
177       From within your template, you can reference any of FormBuilder's meth‐
178       ods to manipulate form HTML, JavaScript, and so forth. For example, you
179       might want exact control over fields, rendering them in a "<div>"
180       instead of a table. You could do something like this:
181
182           <!-- root/src/books/edit.tt -->
183           <head>
184             <title>[% formbuilder.title %]</title>
185             [% formbuilder.jshead %]<!-- javascript -->
186           </head>
187            <body>
188             [% formbuilder.start -%]
189             <div id="form">
190               [% FOREACH field IN formbuilder.fields -%]
191               <p>
192                   <label>
193                      <span [% IF field.required %]class="required"[%END%]>[%field.label%]</span>
194                   </label>
195                 [% field.field %]
196                 [% IF field.invalid -%]
197                     <span class="error">
198                         Missing or invalid entry, please try again.
199                     </span>
200                 [% END %]
201                 </p>
202               [% END %]
203               <div id="submit">[% formbuilder.submit %]</div>
204               <div id="reset">[% formbuilder.reset %]</div>
205               </div>
206             </div>
207             [% formbuilder.end -%]
208           </body>
209
210       In this case, you would not call "FormBuilder.render", since that would
211       only result in a duplicate form (once using the above expansion, and a
212       second time using FormBuilder's default rendering).
213
214       Note that the above form could become a generic "form.tt" template
215       which you simply included in all your files, since there is nothing
216       specific to a given form hardcoded in (that's the idea, after all).
217
218       You can also get some ideas based on FormBuilder's native Template
219       Toolkit support at CGI::FormBuilder::Template::TT2.
220

CONFIGURATION

222       You can set defaults for your forms using Catalyst's config method
223       inside your controller.
224
225           __PACKAGE__->config(
226               'Controller::FormBuilder' => {
227                   new => {
228                       method     => 'post',
229                       # stylesheet => 1,
230                       messages   => '/locale/fr_FR/form_messages.txt',
231                   },
232                   form_path =>
233                     File::Spec->catfile( $c->config->{home}, 'root', 'forms' ),
234                   method_name   => 'form',
235                   template_type => 'HTML::Template',
236                   stash_name    => 'form',
237                   obj_name      => 'FormBuilder',
238                   form_suffix   => 'fb',
239                   attr_name     => 'Form',
240                   source_type   => 'CGI::FormBuilder::Source::File',
241               }
242           );
243
244       "new"
245           This accepts the exact same options as FormBuilder's "new()" method
246           (which is alot). See CGI::FormBuilder for a full list of options.
247
248       "form_path"
249           The path to configuration files. This should be set to an absolute
250           path to prevent problems. By default, it is set to:
251
252               File::Spec->catfile( $c->config->{home}, 'root', 'forms' )
253
254           This can be a colon-separated list of directories if you want to
255           specify multiple paths (ie, "/templates1:/template2"), or an array
256           ref (ie, [qw/template1 templates2/]).
257
258       "form_suffix"
259           The suffix that configuration files have. By default, it is "fb".
260
261       "method_name"
262           Accessor method name available in your controller. By default, it
263           is "formbuilder".
264
265       "template_type"
266           Defines the Catalyst View that the stash will be prepared for. Pos‐
267           sible values are: HTML::Template, Mason, TT. By default, it is
268           "TT".
269
270       "stash_name"
271           Not applicable for HTML::Template view.  By default, it is "form‐
272           builder".  e.g. $c->stash->{formbuilder} = $formbuilder->prepare.
273
274       "obj_name"
275           Not applicable for HTML::Template view. By default, it is "Form‐
276           Builder".  e.g. $c->stash->{FormBuilder} = $formbuilder.
277
278       "attr_name"
279           The attribute name. By default, it is "Form".  e.g. sub edit : Form
280           { ... }
281
282       "source_type"
283           The source adapter class name. By default, it is "CGI::Form‐
284           Builder::Source::File". See CGI::FormBuilder::Source
285
286       In addition, the following FormBuilder options are automatically set
287       for you:
288
289       "action"
290           This is set to the URL for the current action. FormBuilder is
291           designed to handle a full request cycle, meaning both rendering and
292           submission. If you want to override this, simply use the
293           "$self->formbuilder" object:
294
295               $self->formbuilder->action('/action/url');
296
297           The default setting is "$c->req->path".
298
299       "cookies"
300           Handling these are disabled (use Catalyst).
301
302       "debug"
303           This is set to correspond with Catalyst's debug setting.
304
305       "header"
306           This is disabled. Instead, use Catalyst's header routines.
307
308       "params"
309           This is set to get parameters from Catalyst, using "$c->req".  To
310           override this, use the "$self->formbuilder" object:
311
312               $self->formbuilder->params(\%param_hashref);
313
314           Overriding this is not recommended.
315
316       "source"
317           This determines which source file is loaded, to setup your form. By
318           default, this is set to the name of the action URL, with ".fb"
319           appended.  For example, "edit_form()" would be associated with an
320           "edit_form.fb" source file.
321
322           To override this, include the path as the argument to the method
323           attribute:
324
325               sub edit : Local Form('/books/myEditForm') { }
326
327           If no source file is found, then it is assumed you'll be setting up
328           your fields manually. In your controller, you will have to use the
329           "$self->formbuilder" object to create your fields, validation, and
330           so on.
331

SEE ALSO

333       CGI::FormBuilder, CGI::FormBuilder::Source::File, CGI::Form‐
334       Builder::Template::TT2, Catalyst::Manual, Catalyst::Request, Cata‐
335       lyst::Response
336

AUTHOR

338       Copyright (c) 2006 Juan Camacho <formbuilder@suspenda.com>. All Rights
339       Reserved.
340
341       Thanks to Laurent Dami and Roy-Magne Mo for suggestions.
342
343       This library is free software, you can redistribute it and/or modify it
344       under the same terms as Perl itself.
345
346
347
348perl v5.8.8                       2007-06-1C8atalyst::Controller::FormBuilder(3)
Impressum