1Catalyst::Controller::FUosremrBuCiolndterri(b3u)ted PerlCaDtoacluymsetn:t:aCtoinotnroller::FormBuilder(3)
2
6 Catalyst::Controller::FormBuilder - Catalyst FormBuilder Base Con‐
7 troller
8
10 package MyApp::Controller::Books;
11 use base 'Catalyst::Controller::FormBuilder';
12 # optional config setup
14 __PACKAGE__->config(
15 'Controller::FormBuilder' = {
16 template_type => 'HTML::Template', # default is 'TT' (e.g. TT2)
17 }
18 );
19 # 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 my $form = $self->formbuilder;
26 # add email form field to fields already defined edit.fb
28 $form->field( name => 'email', validate => 'EMAIL' );
29 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 # 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
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 http://www.formbuilder.org
57 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 # An editing screen for books
66 sub edit : Local Form {
67 my ( $self, $c ) = @_;
68 $self->formbuilder->method('post'); # set form method
69 }
70 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 root/forms/books/edit.fb
77 (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 Here is an example "edit.fb" file:
84 # 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 submit: Save New Book
113 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 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 # Change our desc field dynamically
123 $self->formbuilder->field(
124 name => 'desc',
125 label => 'Book Description',
126 required => 1
127 );
128 To populate field options for "country", you might use something like
130 this to iterate through the database:
131 $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 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 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 if ( $self->formbuilder->submitted && $self->formbuilder->validate ) {
149 $c->forward('/books/save');
150 }
151 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 To render the form in your tt2 template for example, you can use "ren‐
158 der" to get a default table-based form:
159 <!-- root/src/books/edit.tt -->
161 [% FormBuilder.render %]
162 You can also get fine-tuned control over your form layout from within
164 your template.
165
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 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 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 <!-- 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 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 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 You can also get some ideas based on FormBuilder's native Template
219 Toolkit support at CGI::FormBuilder::Template::TT2.
220
222 You can set defaults for your forms using Catalyst's config method
223 inside your controller.
224 __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 "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 "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 File::Spec->catfile( $c->config->{home}, 'root', 'forms' )
253 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 "form_suffix"
259 The suffix that configuration files have. By default, it is "fb".
260 "method_name"
262 Accessor method name available in your controller. By default, it
263 is "formbuilder".
264 "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 "stash_name"
271 Not applicable for HTML::Template view. By default, it is "form‐
272 builder". e.g. $c->stash->{formbuilder} = $formbuilder->prepare.
273 "obj_name"
275 Not applicable for HTML::Template view. By default, it is "Form‐
276 Builder". e.g. $c->stash->{FormBuilder} = $formbuilder.
277 "attr_name"
279 The attribute name. By default, it is "Form". e.g. sub edit : Form
280 { ... }
281 "source_type"
283 The source adapter class name. By default, it is "CGI::Form‐
284 Builder::Source::File". See CGI::FormBuilder::Source
285 In addition, the following FormBuilder options are automatically set
287 for you:
288 "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 $self->formbuilder->action('/action/url');
296 The default setting is "$c->req->path".
298 "cookies"
300 Handling these are disabled (use Catalyst).
301 "debug"
303 This is set to correspond with Catalyst's debug setting.
304 "header"
306 This is disabled. Instead, use Catalyst's header routines.
307 "params"
309 This is set to get parameters from Catalyst, using "$c->req". To
310 override this, use the "$self->formbuilder" object:
311 $self->formbuilder->params(\%param_hashref);
313 Overriding this is not recommended.
315 "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 To override this, include the path as the argument to the method
323 attribute:
324 sub edit : Local Form('/books/myEditForm') { }
326 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
333 CGI::FormBuilder, CGI::FormBuilder::Source::File, CGI::Form‐
334 Builder::Template::TT2, Catalyst::Manual, Catalyst::Request, Cata‐
335 lyst::Response
336
338 Copyright (c) 2006 Juan Camacho <formbuilder@suspenda.com>. All Rights
339 Reserved.
340 Thanks to Laurent Dami and Roy-Magne Mo for suggestions.
342 This library is free software, you can redistribute it and/or modify it
344 under the same terms as Perl itself.
345perl v5.8.8 2007-06-1C8atalyst::Controller::FormBuilder(3)