1HTML::FormFu::Model::DBUIsCe(r3)Contributed Perl DocumenHtTaMtLi:o:nFormFu::Model::DBIC(3)
2
3
4

NAME

6       HTML::FormFu::Model::DBIC - Integrate HTML::FormFu with DBIx::Class
7

SYNOPSIS

9       Example of typical use in a Catalyst controller:
10
11           sub edit : Chained {
12               my ( $self, $c ) = @_;
13
14               my $form = $c->stash->{form};
15               my $book = $c->stash->{book};
16
17               if ( $form->submitted_and_valid ) {
18
19                   # update dbic row with submitted values from form
20
21                   $form->model->update( $book );
22
23                   $c->response->redirect( $c->uri_for('view', $book->id) );
24                   return;
25               }
26               elsif ( !$form->submitted ) {
27
28                   # use dbic row to set form's default values
29
30                   $form->model->default_values( $book );
31               }
32
33               return;
34           }
35

SETUP

37       For the form object to be able to access your DBIx::Class schema, it
38       needs to be placed on the form stash, with the name "schema".
39
40       This is easy if you're using Catalyst-Controller-HTML-FormFu, as you
41       can set this up to happen in your Catalyst app's config file.
42
43       For example, if your model is named "MyApp::Model::Corp", you would set
44       this (in Config::General format):
45
46           <Controller::HTML::FormFu>
47               <model_stash>
48                   schema Corp
49               </model_stash>
50           </Controller::HTML::FormFu>
51
52       Or if your app's config file is in YAML format:
53
54           'Controller::HTML::FormFu':
55               model_stash:
56                   schema: Corp
57

METHODS

59   default_values
60       Arguments: $dbic_row, [\%config]
61
62       Return Value: $form
63
64           $form->model->default_values( $dbic_row );
65
66       Set a form's default values from the database, to allow a user to edit
67       them.
68
69   update
70       Arguments: [$dbic_row], [\%config]
71
72       Return Value: $dbic_row
73
74           $form->model->update( $dbic_row );
75
76       Update the database with the submitted form values.
77
78   create
79       Arguments: [\%config]
80
81       Return Value: $dbic_row
82
83           my $dbic_row = $form->model->create( {resultset => 'Book'} );
84
85       Like "update", but doesn't require a $dbic_row argument.
86
87       You need to ensure the DBIC schema is available on the form stash - see
88       "SYNOPSIS" for an example config.
89
90       The "resultset" must be set either in the method arguments, or the form
91       or block's "model_config".
92
93       An example of setting the ResultSet name on a Form:
94
95           ---
96           model_config:
97             resultset: FooTable
98
99           elements:
100             # [snip]
101
102   options_from_model
103       Populates a multi-valued field with values from the database.
104
105       This method should not be called directly, but is called for you during
106       "$form->process" by fields that inherit from
107       HTML::FormFu::Element::_Group. This includes:
108
109       HTML::FormFu::Element::Select
110       HTML::FormFu::Element::Checkboxgroup
111       HTML::FormFu::Element::Radiogroup
112       HTML::FormFu::Element::ComboBox
113
114       To use you must set the appropriate "resultset" on the element
115       "model_config":
116
117           element:
118             - type: Select
119               name: foo
120               model_config:
121                 resultset: TableClass
122

BUILDING FORMS

124   single table
125       To edit the values in a row with no related rows, the field names
126       simply have to correspond to the database column names.
127
128       For the following DBIx::Class schema:
129
130           package MySchema::Book;
131           use base 'DBIx::Class';
132
133           __PACKAGE__->load_components(qw/ Core /);
134
135           __PACKAGE__->table("book");
136
137           __PACKAGE__->add_columns(
138               id     => { data_type => "INTEGER" },
139               title  => { data_type => "TEXT" },
140               author => { data_type => "TEXT" },
141               blurb  => { data_type => "TEXT" },
142           );
143
144           __PACKAGE__->set_primary_key("id");
145
146           1;
147
148       A suitable form for this might be:
149
150           elements:
151             - type: Text
152               name: title
153
154             - type: Text
155               name: author
156
157             - type: Textarea
158               name: blurb
159
160   might_have and has_one relationships
161       Set field values from a related row with a "might_have" or "has_one"
162       relationship by placing the fields within a Block (or any element that
163       inherits from Block, such as Fieldset) with its "nested_name" in
164       HTML::FormFu set to the relationship name.
165
166       For the following DBIx::Class schemas:
167
168           package MySchema::Book;
169           use base 'DBIx::Class';
170
171           __PACKAGE__->load_components(qw/ Core /);
172
173           __PACKAGE__->table("book");
174
175           __PACKAGE__->add_columns(
176               id    => { data_type => "INTEGER" },
177               title => { data_type => "TEXT" },
178           );
179
180           __PACKAGE__->set_primary_key("id");
181
182           __PACKAGE__->might_have( review => 'MySchema::Review', 'book' );
183
184           1;
185
186
187           package MySchema::Review;
188           use base 'DBIx::Class';
189
190           __PACKAGE__->load_components(qw/ Core /);
191
192           __PACKAGE__->table("review");
193
194           __PACKAGE__->add_columns(
195               id          => { data_type => "INTEGER" },
196               book        => { data_type => "INTEGER", is_nullable => 1 },
197               review_text => { data_type => "TEXT" },
198           );
199
200           __PACKAGE__->set_primary_key("book");
201
202           __PACKAGE__->belongs_to( book => 'MySchema::Book' );
203
204           1;
205
206       A suitable form for this would be:
207
208           elements:
209             - type: Text
210               name: title
211
212             - type: Block
213               nested_name: review
214               elements:
215                 - type: Textarea
216                   name: review_text
217
218       For "might_have" and "has_one" relationships, you generally shouldn't
219       need to have a field for the related table's primary key, as
220       DBIx::Class will handle retrieving the correct row automatically.
221
222       You can also set a "has_one" or "might_have" relationship using a multi
223       value field like Select.
224
225           elements:
226             - type: Text
227               name: title
228
229             - type: Select
230               nested: review
231               model_config:
232                 resultset: Review
233
234       This will load all reviews into the select field. If you select a
235       review from that list, a current relationship to a review is removed
236       and the new one is added. This requires that the primary key of the
237       "Review" table and the foreign key do not match.
238
239   has_many and many_to_many relationships
240       The general principle is the same as for "might_have" and "has_one"
241       above, except you should use a Repeatable element instead of a Block,
242       and it needs to contain a Hidden field corresponding to the foreign
243       key.
244
245       The Repeatable block's nested_name must be set to the name of the
246       relationship.
247
248       The Repeable block's increment_field_names must be true (which is the
249       default value).
250
251       The Repeable block's counter_name must be set to the name of a Hidden
252       field, which is placed outside of the Repeatable block.  This field is
253       used to store a count of the number of repetitions of the Repeatable
254       block were created.  When the form is submitted, this value is used
255       during "$form->process" to ensure the form is rebuilt with the correct
256       number of repetitions.
257
258       For the following DBIx::Class schemas:
259
260           package MySchema::Book;
261           use base 'DBIx::Class';
262
263           __PACKAGE__->load_components(qw/ Core /);
264
265           __PACKAGE__->table("book");
266
267           __PACKAGE__->add_columns(
268               id    => { data_type => "INTEGER" },
269               title => { data_type => "TEXT" },
270           );
271
272           __PACKAGE__->set_primary_key("id");
273
274           __PACKAGE__->has_many( review => 'MySchema::Review', 'book' );
275
276           1;
277
278
279           package MySchema::Review;
280           use base 'DBIx::Class';
281
282           __PACKAGE__->load_components(qw/ Core /);
283
284           __PACKAGE__->table("review");
285
286           __PACKAGE__->add_columns(
287               book        => { data_type => "INTEGER" },
288               review_text => { data_type => "TEXT" },
289           );
290
291           __PACKAGE__->set_primary_key("book");
292
293           __PACKAGE__->belongs_to( book => 'MySchema::Book' );
294
295           1;
296
297       A suitable form for this would be:
298
299           elements:
300             - type: Text
301               name: title
302
303             - type: Hidden
304               name: review_count
305
306             - type: Repeatable
307               nested_name: review
308               counter_name: review_count
309               elements:
310                 - type: Hidden
311                   name: book
312
313                 - type: Textarea
314                   name: review_text
315
316   many_to_many selection
317       To select / deselect rows from a "many_to_many" relationship, you must
318       use a multi-valued element, such as a Checkboxgroup or a Select with
319       multiple set.
320
321       The field's name must be set to the name of the "many_to_many"
322       relationship.
323
324       default_column
325           If you want to search / associate the related table by a column
326           other it's primary key, set
327           "$field->model_config->{default_column}".
328
329               ---
330               element:
331                   - type: Checkboxgroup
332                     name: authors
333                     model_config:
334                       default_column: foo
335
336           If you want to set columns on the link table you can do so if you
337           add a "link_values" attribute to "model_config":
338
339               ---
340               element:
341                   - type: Checkboxgroup
342                     name: authors
343                     model_config:
344                       link_values:
345                         foo: bar
346
347           The default implementation will first remove all related objects
348           and set the new ones (see
349           <http://search.cpan.org/perldoc?DBIx::Class::Relationship::Base#set_$rel>).
350           If you want to add the selected objects to the current set of
351           objects set "additive" in the "model_config".
352
353               ---
354               element:
355                   - type: Checkboxgroup
356                     name: authors
357                     model_config:
358                       additive: 1
359                       options_from_model: 0
360
361           (<options_from_model> is set to 0 because this "options_from_model"
362           will try to fetch all objects from the result class "Authors" if
363           "model_config" is specified without a "resultset" attribute.)
364

COMMON ARGUMENTS

366       The following items are supported in the optional "config" hash-ref
367       argument to the methods default_values, update and create.
368
369       base
370           If you want the method to process a particular Block element,
371           rather than the whole form, you can pass the element as a "base"
372           argument.
373
374               $form->default_values(
375                   $row,
376                   {
377                       base => $formfu_element,
378                   },
379               );
380
381       nested_base
382           If you want the method to process a particular Block element by
383           name, you can pass the name as an argument.
384
385               $form->default_values(
386                   $row,
387                   {
388                       nested_base => 'foo',
389                   }'
390               );
391

CONFIGURATION

393   Config options for fields
394       The following items are supported as "model_config" options on form
395       fields.
396
397       accessor
398           If set, "accessor" will be used as a method-name accessor on the
399           "DBIx::Class" row object, instead of using the field name.
400
401       delete_if_empty
402           Useful for editing a "might_have" related row containing only one
403           field.
404
405           If the submitted value is blank, the related row is deleted.
406
407           For the following DBIx::Class schemas:
408
409               package MySchema::Book;
410               use base 'DBIx::Class';
411
412               __PACKAGE__->load_components(qw/ Core /);
413
414               __PACKAGE__->table("book");
415
416               __PACKAGE__->add_columns(
417                   id    => { data_type => "INTEGER" },
418                   title => { data_type => "TEXT" },
419               );
420
421               __PACKAGE__->set_primary_key("id");
422
423               __PACKAGE__->might_have( review => 'MySchema::Review', 'book' );
424
425               1;
426
427
428               package MySchema::Review;
429               use base 'DBIx::Class';
430
431               __PACKAGE__->load_components(qw/ Core /);
432
433               __PACKAGE__->table("review");
434
435               __PACKAGE__->add_columns(
436                   book        => { data_type => "INTEGER" },
437                   review_text => { data_type => "TEXT" },
438               );
439
440               __PACKAGE__->set_primary_key("book");
441
442               __PACKAGE__->belongs_to( book => 'MySchema::Book' );
443
444               1;
445
446           A suitable form for this would be:
447
448               elements:
449                 - type: Text
450                   name: title
451
452                 - type: Block
453                   nested_name: review
454                   elements:
455                     - type: Text
456                       name: review_text
457                       model_config:
458                         delete_if_empty: 1
459
460       label
461           To use a column value for a form field's label.
462
463   Config options for fields within a Repeatable block
464       delete_if_true
465           Intended for use on a Checkbox field.
466
467           If the checkbox is checked, the following occurs: for a has-many
468           relationship, the related row is deleted; for a many-to-many
469           relationship, the relationship link is removed.
470
471           An example of use might be:
472
473               elements:
474                 - type: Text
475                   name: title
476
477                 - type: Hidden
478                   name: review_count
479
480                 - type: Repeatable
481                   nested_name: review
482                   counter_name: review_count
483                   elements:
484                     - type: Hidden
485                       name: book
486
487                     - type: Textarea
488                       name: review_text
489
490                     - type: Checkbox
491                       name: delete_review
492                       label: 'Delete Review?'
493                       model_config:
494                         delete_if_true: 1
495
496           Note: make sure the name of this field does not clash with one of
497           your DBIx::Class::Row method names (e.g. "delete") - see "CAVEATS".
498
499   Config options for Repeatable blocks
500       empty_rows
501           For a Repeatable block corresponding to a has-many or many-to-many
502           relationship, to allow the user to insert new rows, set
503           "empty_rows" to the number of extra repetitions you wish added to
504           the end of the Repeatable block.
505
506       new_rows_max
507           Set to the maximum number of new rows that a Repeatable block is
508           allowed to add.
509
510           If not set, it will fallback to the value of "empty_rows".
511
512   Config options for options_from_model
513       The column used for the element values is set with the "model_config"
514       value "id_column" - or if not set, the table's primary column is used.
515
516           element:
517             - type: Select
518               name: foo
519               model_config:
520                 resultset: TableClass
521                 id_column: pk_col
522
523       The column used for the element labels is set with the "model_config"
524       value "label_column" - or if not set, the first text/varchar column
525       found in the table is used - or if one is not found, the "id_column" is
526       used instead.
527
528           element:
529             - type: Select
530               name: foo
531               model_config:
532                 resultset: TableClass
533                 label_column: label_col
534
535       To pass the database label values via the form's localization object,
536       set "localize_label"
537
538           element:
539             - type: Select
540               name: foo
541               model_config:
542                 localize_label: 1
543
544       You can set a "condition", which will be passed as the 1st arguement to
545       "search" in DBIx::Class::ResultSet.
546
547           element:
548             - type: Select
549               name: foo
550               model_config:
551                 resultset: TableClass
552                 condition:
553                   type: is_foo
554
555       You can set "attributes", which will be passed as the 2nd arguement to
556       "search" in DBIx::Class::ResultSet.
557

FAQ

559   Add extra values not in the form
560       To update values to the database which weren't submitted to the form,
561       you can first add them to the form with add_valid.
562
563           my $passwd = generate_passwd();
564
565           $form->add_valid( passwd => $passwd );
566
567           $form->model->update( $row );
568
569       "add_valid" works for fieldnames that don't exist in the form.
570
571   Set a field read only
572       You can make a field read only. The value of such fields cannot be
573       changed by the user even if they submit a value for it.
574
575         $field->model_config->{read_only} = 1;
576
577         - Name: field
578           model_config:
579             read_only: 1
580
581       See HTML::FormFu::Element::Label.
582

DEPRECATED

584   new_empty_row
585       Is deprecated and provided only for backwards compatability.  Will be
586       removed at some point in the future.
587
588       See "empty_rows" in "Config options for Repeatable blocks" instead.
589
590   new_empty_row_multi
591       Is deprecated and provided only for backwards compatability.  Will be
592       removed at some point in the future.
593
594       See "new_rows_max" in "Config options for Repeatable blocks" instead.
595
596   Range constraint
597       The suggestion to use a "Range" constraint on the "count" field to
598       limit the number of repetitions of a Repeatable block, has been
599       withdrawn.
600
601       This was only useful in the case that there were no initial rows to be
602       edited, otherwise the "max()" value could not be known ahead of time.
603
604       See "empty_rows" in "Config options for Repeatable blocks" instead.
605

CAVEATS

607       To ensure your column's inflators and deflators are called, we have to
608       get / set values using their named methods, and not with "get_column" /
609       "set_column".
610
611       Because of this, beware of having column names which clash with
612       DBIx::Class built-in method-names, such as "delete". - It will have
613       obviously undesirable results!
614

SUPPORT

616       Project Page:
617
618       http://code.google.com/p/html-formfu/ <http://code.google.com/p/html-
619       formfu/>
620
621       Mailing list:
622
623       http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu
624       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
625
626       Mailing list archives:
627
628       http://lists.scsys.co.uk/pipermail/html-formfu/
629       <http://lists.scsys.co.uk/pipermail/html-formfu/>
630

BUGS

632       Please submit bugs / feature requests to
633       http://code.google.com/p/html-formfu/issues/list
634       <http://code.google.com/p/html-formfu/issues/list> (preferred) or
635       <http://rt.perl.org>.
636

SUBVERSION REPOSITORY

638       The publicly viewable subversion code repository is at
639       http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC
640       <http://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC>.
641
642       If you wish to contribute, you'll need a GMAIL email address. Then just
643       ask on the mailing list for commit access.
644
645       If you wish to contribute but for some reason really don't want to sign
646       up for a GMAIL account, please post patches to the mailing list
647       (although you'll have to wait for someone to commit them).
648
649       If you have commit permissions, use the HTTPS repository url:
650       https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC
651       <https://html-formfu.googlecode.com/svn/trunk/HTML-FormFu-Model-DBIC>
652

SEE ALSO

654       HTML::FormFu, DBIx::Class, Catalyst::Controller::HTML::FormFu
655

AUTHOR

657       Carl Franks
658

CONTRIBUTORS

660       Based on the code of "DBIx::Class::HTML::FormFu", which was contributed
661       to by:
662
663       Adam Herzog
664
665       Daisuke Maki
666
667       Mario Minati
668

670       Copyright (C) 2007 by Carl Franks
671
672       Based on the original source code of DBIx::Class::HTMLWidget, copyright
673       Thomas Klausner.
674
675       This library is free software; you can redistribute it and/or modify it
676       under the same terms as Perl itself, either Perl version 5.8.8 or, at
677       your option, any later version of Perl 5 you may have available.
678

POD ERRORS

680       Hey! The above document had some coding errors, which are explained
681       below:
682
683       Around line 1403:
684           '=item' outside of any '=over'
685
686       Around line 1444:
687           You forgot a '=back' before '=head1'
688
689
690
691perl v5.12.0                      2009-12-10      HTML::FormFu::Model::DBIC(3)
Impressum