HTML::...atabase(3pm)

💅 HTML::FormHandler::Manual::Database

okay bestie, so this is the HTML::FormHandler::Manual::Database page from the User Contributed Perl Documentation — it's the FormHandler use recipes manual, and it's literally about hooking your forms up to a database. let's get into it 🎀

✨ VERSION ✨

version 0.40068 — that's the one, no cap 💖

🌸 SYNOPSIS 🌸

Manual Index — yes queen, it's a manual, it's indexed, it's iconic.

This is all the info on interfacing FormHandler forms and fields with a database. Also see HTML::FormHandler::TraitFor::Model::DBIC (iykyk). 🦋

---

🫶 Form Models 🫶

For a database form, you use a model base class that interfaces with the database — like HTML::FormHandler::Model::DBIC, which needs to be installed as a separate package (not me reminding you to install your deps 😭). There's also a sample 'object' model in HTML::FormHandler::Model::Object, which will update a simple object.

When you're using a database model, the form field values for the row are retrieved from the database using the field 'accessor' attributes (which default to the field name) as database class accessors. lowkey elegant.

FormHandler will use relationships to populate single and multiple selection lists, and validate input. A 'single' relationship is processed by HTML::FormHandler::Field::Compound. A 'has_many' relationship is processed by HTML::FormHandler::Field::Repeatable.

⚠️ Do not use database row method names — like 'delete' — as field names in a database form. just don't. please. 🙈

You can pass in either the primary key or a row object to the form. If a primary key (item_id) is passed in, you must also provide the schema. The model will use the item_class (DBIC source name) to fetch the row from the database. If you pass in a row object (item), the schema, item_class, and item_id will be set from the row. slay, so convenient.

Executing this:

$form->process( item => $row, params => $params );

...will validate the parameters and then update or create the database row object. main character behaviour fr fr 👑

---

💜 Fields that map to database relationships 💜

⭐ Select

A select field will automatically retrieve a select list from the database — if the proper column names are provided. Single selects handle 'belongs_to' relationships, where the related table is used to construct a selection list from the database. chef's kiss.

See also HTML::FormHandler::Field::Select and 'lookup_options' in HTML::FormHandler::TraitFor::Model::DBIC.

🌈 Multiple Select

A multiple select is either a 'Select' with multiple => 1 set, or a field of the 'Multiple' type. The name of a Multiple select which pulls options from the database automatically should be the name of the 'many_to_many' relationship. The 'value' of the field is derived from the 'has_many' part of the relationship. the way that just works 💅

The primary key is used for the 'id' of the select. The 'label' column of the select is assumed to be 'name'. If the label column has a different name, it must be specified with 'label_column'.

Pertinent attributes (write these down bestie 🎀):

label_column
active_column
sort_column

See also HTML::FormHandler::Field::Select and HTML::FormHandler::Model::DBIC.

🧚 Compound fields

A compound field represents a single relationship to another table. Although most compound relations can be handled without providing a primary key, in some circumstances you may need to provide a PrimaryKey field, or add extra values in update_model.

See also HTML::FormHandler::Field::Compound.

The default for compound fields is that if all subfields are empty, the value of the compound field is set to undef (null). For some types of relations, you may want to set the 'not_nullable' flag to force the field to contain all subfields anyway — like when the related rows are not deleted when empty. See test t/compound/empty.t for a demonstration of the difference in output. 👀

🍓 Repeatable fields

The 'Repeatable' field type allows you to update arrays of columns from related tables easily. You will need to provide a 'PrimaryKey' hidden field in the compound field contained in the Repeatable. like this:

has_field 'addresses' => ( type => 'Repeatable' );
has_field 'addresses.address_id' => ( type => 'PrimaryKey' );
has_field 'addresses.street';
has_field 'addresses.city';
has_field 'addresses.state';

There are some complications with creating Repeatable elements (with the PrimaryKey field set to undef) in a database and re-presenting the form. See HTML::FormHandler::Field::Repeatable for more info. (the drama of it all 😭)

---

🔥 Flags 🔥

🌸 writeonly

Do not read the value from the 'item' when populating the form.

🌸 noupdate

Do not update the database with this field, i.e. do not include it in $form->value.

---

👑 Form generator 👑

A DBIC form generator is installed with the HTML::FormHandler::Model::DBIC package. See HTML::FormHandler::Generator::DBIC.

There's also a role, HTML::FormHandler::TraitFor::DBICFields, that allows simple form fields to be auto-generated from a DBIC result class. absolutely ate:

my $form = HTML::FormHandler::Model::DBIC->new_with_traits(
    traits => ['HTML::FormHandler::TraitFor::DBICFields'],
    includes => ['title', 'author' ],
    field_list => [ 'submit' => { type => 'Submit', value => 'Save', order => 99 } ],
    item => $book );

---

💖 AUTHOR 💖

FormHandler Contributors — see HTML::FormHandler. (community queens 🫶)

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2017 by Gerda Shank.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. periodt. 💅✨

---

and that's the tea, bestie 🦋 this page comes to you from perl v5.34.0, dated 2022-03-25, and it's the HTML::...atabase(3pm) manpage — now go forth and slay your database forms 💖🌸💜