1HTML::FormFu::Model::DBUIsCe(r3)Contributed Perl DocumenHtTaMtLi:o:nFormFu::Model::DBIC(3)
2
6 HTML::FormFu::Model::DBIC - Integrate HTML::FormFu with DBIx::Class
7
9 version 2.03
10
12 Example of typical use in a Catalyst controller:
13 sub edit : Chained {
15 my ( $self, $c ) = @_;
16 my $form = $c->stash->{form};
18 my $book = $c->stash->{book};
19 if ( $form->submitted_and_valid ) {
21 # update dbic row with submitted values from form
23 $form->model->update( $book );
25 $c->response->redirect( $c->uri_for('view', $book->id) );
27 return;
28 }
29 elsif ( !$form->submitted ) {
30 # use dbic row to set form's default values
32 $form->model->default_values( $book );
34 }
35 return;
37 }
38
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 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 For example, if your model is named "MyApp::Model::Corp", you would set
47 this (in Config::General format):
48 <Controller::HTML::FormFu>
50 <model_stash>
51 schema Corp
52 </model_stash>
53 </Controller::HTML::FormFu>
54 Or if your app's config file is in YAML format:
56 'Controller::HTML::FormFu':
58 model_stash:
59 schema: Corp
60
62 default_values
63 Arguments: $dbic_row, [\%config]
64 Return Value: $form
66 $form->model->default_values( $dbic_row );
68 Set a form's default values from the database, to allow a user to edit
70 them.
71 update
73 Arguments: [$dbic_row], [\%config]
74 Return Value: $dbic_row
76 $form->model->update( $dbic_row );
78 Update the database with the submitted form values.
80 create
82 Arguments: [\%config]
83 Return Value: $dbic_row
85 my $dbic_row = $form->model->create( {resultset => 'Book'} );
87 Like "update", but doesn't require a $dbic_row argument.
89 You need to ensure the DBIC schema is available on the form stash - see
91 "SYNOPSIS" for an example config.
92 The "resultset" must be set either in the method arguments, or the form
94 or block's "model_config".
95 An example of setting the ResultSet name on a Form:
97 ---
99 model_config:
100 resultset: FooTable
101 elements:
103 # [snip]
104 options_from_model
106 Populates a multi-valued field with values from the database.
107 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 HTML::FormFu::Element::Select
113 HTML::FormFu::Element::Checkboxgroup
114 HTML::FormFu::Element::Radiogroup
115 HTML::FormFu::Element::ComboBox
116 To use you must set the appropriate "resultset" on the element
118 "model_config":
119 element:
121 - type: Select
122 name: foo
123 model_config:
124 resultset: TableClass
125
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 For the following DBIx::Class schema:
132 package MySchema::Book;
134 use base 'DBIx::Class';
135 __PACKAGE__->load_components(qw/ Core /);
137 __PACKAGE__->table("book");
139 __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 __PACKAGE__->set_primary_key("id");
148 1;
150 A suitable form for this might be:
152 elements:
154 - type: Text
155 name: title
156 - type: Text
158 name: author
159 - type: Textarea
161 name: blurb
162 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 For the following DBIx::Class schemas:
170 package MySchema::Book;
172 use base 'DBIx::Class';
173 __PACKAGE__->load_components(qw/ Core /);
175 __PACKAGE__->table("book");
177 __PACKAGE__->add_columns(
179 id => { data_type => "INTEGER" },
180 title => { data_type => "TEXT" },
181 );
182 __PACKAGE__->set_primary_key("id");
184 __PACKAGE__->might_have( review => 'MySchema::Review', 'book' );
186 1;
188 package MySchema::Review;
191 use base 'DBIx::Class';
192 __PACKAGE__->load_components(qw/ Core /);
194 __PACKAGE__->table("review");
196 __PACKAGE__->add_columns(
198 id => { data_type => "INTEGER" },
199 book => { data_type => "INTEGER", is_nullable => 1 },
200 review_text => { data_type => "TEXT" },
201 );
202 __PACKAGE__->set_primary_key("book");
204 __PACKAGE__->belongs_to( book => 'MySchema::Book' );
206 1;
208 A suitable form for this would be:
210 elements:
212 - type: Text
213 name: title
214 - type: Block
216 nested_name: review
217 elements:
218 - type: Textarea
219 name: review_text
220 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 You can also set a "has_one" or "might_have" relationship using a multi
226 value field like Select.
227 elements:
229 - type: Text
230 name: title
231 - type: Select
233 nested: review
234 model_config:
235 resultset: Review
236 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 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 The Repeatable block's nested_name must be set to the name of the
249 relationship.
250 The Repeable block's increment_field_names must be true (which is the
252 default value).
253 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 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 For the following DBIx::Class schemas:
266 package MySchema::Book;
268 use base 'DBIx::Class';
269 __PACKAGE__->load_components(qw/ Core /);
271 __PACKAGE__->table("book");
273 __PACKAGE__->add_columns(
275 id => { data_type => "INTEGER" },
276 title => { data_type => "TEXT" },
277 );
278 __PACKAGE__->set_primary_key("id");
280 __PACKAGE__->has_many( review => 'MySchema::Review', 'book' );
282 1;
284 package MySchema::Review;
287 use base 'DBIx::Class';
288 __PACKAGE__->load_components(qw/ Core /);
290 __PACKAGE__->table("review");
292 __PACKAGE__->add_columns(
294 book => { data_type => "INTEGER" },
295 review_text => { data_type => "TEXT" },
296 );
297 __PACKAGE__->set_primary_key("book");
299 __PACKAGE__->belongs_to( book => 'MySchema::Book' );
301 1;
303 A suitable form for this might be:
305 elements:
307 - type: Text
308 name: title
309 - type: Hidden
311 name: review_count
312 - 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 - type: Textarea
323 name: review_text
324 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 elements:
333 - type: ComboBox
334 name: author
335 model_config:
336 resultset: Author
337 select_column: id
338 text_column: name
339 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 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 The field's name must be set to the name of the "many_to_many"
351 relationship.
352 default_column
354 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 ---
359 element:
360 - type: Checkboxgroup
361 name: authors
362 model_config:
363 default_column: foo
364 link_values
366 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 ---
371 element:
372 - type: Checkboxgroup
373 name: authors
374 model_config:
375 link_values:
376 foo: bar
377 additive
379 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 ---
387 element:
388 - type: Checkboxgroup
389 name: authors
390 model_config:
391 additive: 1
392 options_from_model: 0
393 "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
399 The following items are supported in the optional "config" hash-ref
400 argument to the methods default_values, update and create.
401 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 $form->default_values(
408 $row,
409 {
410 base => $formfu_element,
411 },
412 );
413 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 $form->default_values(
419 $row,
420 {
421 nested_base => 'foo',
422 }'
423 );
424
426 Config options for fields
427 The following items are supported as "model_config" options on form
428 fields.
429 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 ignore_if_empty
435 If the submitted value is blank, no attempt will be made to save it
436 to the database.
437 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 delete_if_empty
446 Useful for editing a "might_have" related row containing only one
447 field.
448 If the submitted value is blank, the related row is deleted.
450 For the following DBIx::Class schemas:
452 package MySchema::Book;
454 use base 'DBIx::Class';
455 __PACKAGE__->load_components(qw/ Core /);
457 __PACKAGE__->table("book");
459 __PACKAGE__->add_columns(
461 id => { data_type => "INTEGER" },
462 title => { data_type => "TEXT" },
463 );
464 __PACKAGE__->set_primary_key("id");
466 __PACKAGE__->might_have( review => 'MySchema::Review', 'book' );
468 1;
470 package MySchema::Review;
473 use base 'DBIx::Class';
474 __PACKAGE__->load_components(qw/ Core /);
476 __PACKAGE__->table("review");
478 __PACKAGE__->add_columns(
480 book => { data_type => "INTEGER" },
481 review_text => { data_type => "TEXT" },
482 );
483 __PACKAGE__->set_primary_key("book");
485 __PACKAGE__->belongs_to( book => 'MySchema::Book' );
487 1;
489 A suitable form for this would be:
491 elements:
493 - type: Text
494 name: title
495 - type: Block
497 nested_name: review
498 elements:
499 - type: Text
500 name: review_text
501 model_config:
502 delete_if_empty: 1
503 label
505 To use a column value for a form field's label.
506 Config options for fields within a Repeatable block
508 delete_if_true
509 Intended for use on a Checkbox field.
510 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 An example of use might be:
516 elements:
518 - type: Text
519 name: title
520 - type: Hidden
522 name: review_count
523 - type: Repeatable
525 nested_name: review
526 counter_name: review_count
527 elements:
528 - type: Hidden
529 name: book
530 - type: Textarea
532 name: review_text
533 - type: Checkbox
535 name: delete_review
536 label: 'Delete Review?'
537 model_config:
538 delete_if_true: 1
539 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 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 new_rows_max
551 Set to the maximum number of new rows that a Repeatable block is
552 allowed to add.
553 If not set, it will fallback to the value of "empty_rows".
555 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 element:
561 - type: Select
562 name: foo
563 model_config:
564 resultset: TableClass
565 id_column: pk_col
566 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 element:
573 - type: Select
574 name: foo
575 model_config:
576 resultset: TableClass
577 label_column: label_col
578 To pass the database label values via the form's localization object,
580 set "localize_label"
581 element:
583 - type: Select
584 name: foo
585 model_config:
586 localize_label: 1
587 You can set a "condition", which will be passed as the 1st argument to
589 "search" in DBIx::Class::ResultSet.
590 element:
592 - type: Select
593 name: foo
594 model_config:
595 resultset: TableClass
596 condition:
597 type: is_foo
598 You can set a "condition_from_stash", which will be passed as the 1st
600 argument to "search" in DBIx::Class::ResultSet.
601 "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 element:
607 - type: Select
608 name: foo
609 model_config:
610 resultset: TableClass
611 condition_from_stash:
612 key: stash_key
613 Is comparable to:
615 $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 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 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 Is comparable to:
642 $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 You can set "attributes", which will be passed as the 2nd argument to
659 "search" in DBIx::Class::ResultSet.
660 ENUM Column Type
662 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
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 my $passwd = generate_passwd();
674 $form->add_valid( passwd => $passwd );
676 $form->model->update( $row );
678 "add_valid" works for fieldnames that don't exist in the form.
680 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 $field->model_config->{read_only} = 1;
686 - Name: field
688 model_config:
689 read_only: 1
690 See HTML::FormFu::Element::Label.
692
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 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
703 new_empty_row
704 See "empty_rows" in "Config options for Repeatable blocks" instead.
705 new_empty_row_multi
707 See "new_rows_max" in "Config options for Repeatable blocks" instead.
708 Range constraint
710 See "empty_rows" in "Config options for Repeatable blocks" instead.
711
713 Project Page:
714 <http://code.google.com/p/html-formfu/>
716 Mailing list:
718 <http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/html-formfu>
720 Mailing list archives:
722 <http://lists.scsys.co.uk/pipermail/html-formfu/>
724
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
731 This module's sourcecode is maintained in a git repository at
732 <git://github.com/fireartist/HTML-FormFu-Model-DBIC.git>
733 The project page is
735 <https://github.com/fireartist/HTML-FormFu-Model-DBIC>
736
738 HTML::FormFu, DBIx::Class, Catalyst::Controller::HTML::FormFu
739
741 Carl Franks
742
744 Based on the code of "DBIx::Class::HTML::FormFu", which was contributed
745 to by:
746 Adam Herzog
748 Daisuke Maki
750 Mario Minati
752
754 Copyright (C) 2007 by Carl Franks
755 Based on the original source code of DBIx::Class::HTMLWidget, copyright
757 Thomas Klausner.
758 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.
762perl v5.38.0 2023-07-20 HTML::FormFu::Model::DBIC(3)