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

VERSION

9       version 2.03
10

SYNOPSIS

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

SETUP

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

METHODS

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

BUILDING FORMS

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

COMMON ARGUMENTS

399       The following items are supported in the optional "config" hash-ref
400       argument to the methods default_values, update and create.
401
402       base
403           If you want the method to process a particular Block element,
404           rather than the whole form, you can pass the element as a "base"
405           argument.
406
407               $form->default_values(
408                   $row,
409                   {
410                       base => $formfu_element,
411                   },
412               );
413
414       nested_base
415           If you want the method to process a particular Block element by
416           name, you can pass the name as an argument.
417
418               $form->default_values(
419                   $row,
420                   {
421                       nested_base => 'foo',
422                   }'
423               );
424

CONFIGURATION

426   Config options for fields
427       The following items are supported as "model_config" options on form
428       fields.
429
430       accessor
431           If set, "accessor" will be used as a method-name accessor on the
432           "DBIx::Class" row object, instead of using the field name.
433
434       ignore_if_empty
435           If the submitted value is blank, no attempt will be made to save it
436           to the database.
437
438       null_if_empty
439           If the submitted value is blank, save it as NULL to the database.
440           Normally an empty string is saved as NULL when its corresponding
441           field is numeric, and as an empty string when its corresponding
442           field is a text field. This option is useful for changing the
443           default behavior for text fields.
444
445       delete_if_empty
446           Useful for editing a "might_have" related row containing only one
447           field.
448
449           If the submitted value is blank, the related row is deleted.
450
451           For the following DBIx::Class schemas:
452
453               package MySchema::Book;
454               use base 'DBIx::Class';
455
456               __PACKAGE__->load_components(qw/ Core /);
457
458               __PACKAGE__->table("book");
459
460               __PACKAGE__->add_columns(
461                   id    => { data_type => "INTEGER" },
462                   title => { data_type => "TEXT" },
463               );
464
465               __PACKAGE__->set_primary_key("id");
466
467               __PACKAGE__->might_have( review => 'MySchema::Review', 'book' );
468
469               1;
470
471
472               package MySchema::Review;
473               use base 'DBIx::Class';
474
475               __PACKAGE__->load_components(qw/ Core /);
476
477               __PACKAGE__->table("review");
478
479               __PACKAGE__->add_columns(
480                   book        => { data_type => "INTEGER" },
481                   review_text => { data_type => "TEXT" },
482               );
483
484               __PACKAGE__->set_primary_key("book");
485
486               __PACKAGE__->belongs_to( book => 'MySchema::Book' );
487
488               1;
489
490           A suitable form for this would be:
491
492               elements:
493                 - type: Text
494                   name: title
495
496                 - type: Block
497                   nested_name: review
498                   elements:
499                     - type: Text
500                       name: review_text
501                       model_config:
502                         delete_if_empty: 1
503
504       label
505           To use a column value for a form field's label.
506
507   Config options for fields within a Repeatable block
508       delete_if_true
509           Intended for use on a Checkbox field.
510
511           If the checkbox is checked, the following occurs: for a has-many
512           relationship, the related row is deleted; for a many-to-many
513           relationship, the relationship link is removed.
514
515           An example of use might be:
516
517               elements:
518                 - type: Text
519                   name: title
520
521                 - type: Hidden
522                   name: review_count
523
524                 - type: Repeatable
525                   nested_name: review
526                   counter_name: review_count
527                   elements:
528                     - type: Hidden
529                       name: book
530
531                     - type: Textarea
532                       name: review_text
533
534                     - type: Checkbox
535                       name: delete_review
536                       label: 'Delete Review?'
537                       model_config:
538                         delete_if_true: 1
539
540           Note: make sure the name of this field does not clash with one of
541           your DBIx::Class::Row method names (e.g. "delete") - see "CAVEATS".
542
543   Config options for Repeatable blocks
544       empty_rows
545           For a Repeatable block corresponding to a has-many or many-to-many
546           relationship, to allow the user to insert new rows, set
547           "empty_rows" to the number of extra repetitions you wish added to
548           the end of the Repeatable block.
549
550       new_rows_max
551           Set to the maximum number of new rows that a Repeatable block is
552           allowed to add.
553
554           If not set, it will fallback to the value of "empty_rows".
555
556   Config options for options_from_model
557       The column used for the element values is set with the "model_config"
558       value "id_column" - or if not set, the table's primary column is used.
559
560           element:
561             - type: Select
562               name: foo
563               model_config:
564                 resultset: TableClass
565                 id_column: pk_col
566
567       The column used for the element labels is set with the "model_config"
568       value "label_column" - or if not set, the first text/varchar column
569       found in the table is used - or if one is not found, the "id_column" is
570       used instead.
571
572           element:
573             - type: Select
574               name: foo
575               model_config:
576                 resultset: TableClass
577                 label_column: label_col
578
579       To pass the database label values via the form's localization object,
580       set "localize_label"
581
582           element:
583             - type: Select
584               name: foo
585               model_config:
586                 localize_label: 1
587
588       You can set a "condition", which will be passed as the 1st argument to
589       "search" in DBIx::Class::ResultSet.
590
591           element:
592             - type: Select
593               name: foo
594               model_config:
595                 resultset: TableClass
596                 condition:
597                   type: is_foo
598
599       You can set a "condition_from_stash", which will be passed as the 1st
600       argument to "search" in DBIx::Class::ResultSet.
601
602       "key" is the column-name to be passed to search, and "stash_key" is the
603       name of a key on the form stash from which the value to be passed to
604       search is found.
605
606           element:
607             - type: Select
608               name: foo
609               model_config:
610                 resultset: TableClass
611                 condition_from_stash:
612                   key: stash_key
613
614       Is comparable to:
615
616           $form->element({
617               type => 'Select',
618               name => 'foo',
619               model_config => {
620                   resultset => 'TableClass',
621                   condition => {
622                       key => $form->stash->{stash_key}
623                   }
624               }
625           })
626
627       If the value in the stash is nested in a data-structure, you can access
628       it by setting "expand_stash_dots". As you can see in the example below,
629       it automatically handles calling methods on objects, accessing hash-
630       keys on hash-references, and accessing array-slots on array references.
631
632           element:
633             - type: Select
634               name: foo
635               model_config:
636                 resultset: TableClass
637                 condition_from_stash:
638                   key: foo.bar.0
639                 expand_stash_dots: 1
640
641       Is comparable to:
642
643           $form->element({
644               type => 'Select',
645               name => 'foo',
646               model_config => {
647                   resultset => 'TableClass',
648                   condition => {
649                       key => $form->stash->{foo}->bar->[0];
650                   }
651               }
652           })
653           # Where stash returns a hashref.
654           # The 'foo' hash-key returns an object.
655           # The object-method 'bar' returns an arrayref.
656           # The first array slot returns the value used in the query.
657
658       You can set "attributes", which will be passed as the 2nd argument to
659       "search" in DBIx::Class::ResultSet.
660
661       ENUM Column Type
662
663       If the field name matches (case-insensitive) a column name with type
664       'ENUM' and the Schema contains enum values in
665       "$resultset->column_info($name)->{extra}{list}", the field's options
666       will be populated with the enum values.
667

FAQ

669   Add extra values not in the form
670       To update values to the database which weren't submitted to the form,
671       you can first add them to the form with add_valid.
672
673           my $passwd = generate_passwd();
674
675           $form->add_valid( passwd => $passwd );
676
677           $form->model->update( $row );
678
679       "add_valid" works for fieldnames that don't exist in the form.
680
681   Set a field read only
682       You can make a field read only. The value of such fields cannot be
683       changed by the user even if they submit a value for it.
684
685         $field->model_config->{read_only} = 1;
686
687         - Name: field
688           model_config:
689             read_only: 1
690
691       See HTML::FormFu::Element::Label.
692

CAVEATS

694       To ensure your column's inflators and deflators are called, we have to
695       get / set values using their named methods, and not with "get_column" /
696       "set_column".
697
698       Because of this, beware of having column names which clash with
699       DBIx::Class built-in method-names, such as "delete". - It will have
700       obviously undesirable results!
701

REMOVED METHODS

703   new_empty_row
704       See "empty_rows" in "Config options for Repeatable blocks" instead.
705
706   new_empty_row_multi
707       See "new_rows_max" in "Config options for Repeatable blocks" instead.
708
709   Range constraint
710       See "empty_rows" in "Config options for Repeatable blocks" instead.
711

SUPPORT

713       Project Page:
714
715       <http://code.google.com/p/html-formfu/>
716
717       Mailing list:
718
719       <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
720
721       Mailing list archives:
722
723       <http://lists.scsys.co.uk/pipermail/html-formfu/>
724

BUGS

726       Please submit bugs / feature requests to
727       <http://code.google.com/p/html-formfu/issues/list> (preferred) or
728       <http://rt.perl.org>.
729

GITHUB REPOSITORY

731       This module's sourcecode is maintained in a git repository at
732       <git://github.com/fireartist/HTML-FormFu-Model-DBIC.git>
733
734       The project page is
735       <https://github.com/fireartist/HTML-FormFu-Model-DBIC>
736

SEE ALSO

738       HTML::FormFu, DBIx::Class, Catalyst::Controller::HTML::FormFu
739

AUTHOR

741       Carl Franks
742

CONTRIBUTORS

744       Based on the code of "DBIx::Class::HTML::FormFu", which was contributed
745       to by:
746
747       Adam Herzog
748
749       Daisuke Maki
750
751       Mario Minati
752
754       Copyright (C) 2007 by Carl Franks
755
756       Based on the original source code of DBIx::Class::HTMLWidget, copyright
757       Thomas Klausner.
758
759       This library is free software; you can redistribute it and/or modify it
760       under the same terms as Perl itself, either Perl version 5.8.8 or, at
761       your option, any later version of Perl 5 you may have available.
762
763
764
765perl v5.34.0                      2022-01-21      HTML::FormFu::Model::DBIC(3)
Impressum