HTML::...efaults(3pm)

💅 HTML::FormHandler::Manual::Defaults

ok so bestie, this is the page about form defaults — like, where do the pre-filled values in your fields even come from?? spoilers: a lot of places. buckle up 🎀

VERSION: version 0.40068 ✨ (yes we're citing it, it matters)

---

🌸 SYNOPSIS

• Manual Index
• How to set defaults for your fields.

that's it, that's the synopsis. it's giving "table of contents energy" and honestly? valid. 🦋

---

💖 Defaults

okay so, defaults for form fields come from a number of different places. like, a whole little ecosystem of places. the simplest way to set a field's default is right on the field definition:

has_field 'foo' => ( type => 'Text', default => 'my_foo' );
has_field 'select_many' => ( type => 'Multiple', default => [1, 2, 3] );

easy. gorgeous. no notes. 💅

you can ALSO set a field's default with a method in the form named default_<field_name> — and here's the lil detail, any periods in the field name get replaced with underscores:

has_field 'foo';
sub default_foo { 'my_default' }

(so foo.bar would become default_foo_bar, iykyk 🫶)

like the other field attributes, the default attribute can be modified on new with the field_list attribute, or on process with the update_field_list parameter (or its shorthand form, defaults):

my $form => MyApp::Form->new( field_list => { '+foo' => { default => 'my_foo' } } );
$form->process( update_field_list => { foo => { default => 'my_foo' } } );
$form->process( defaults => { foo => 'my_foo' }, params => $params );

---

so for forms where you pass in an item (usually a database row object), the values in that object get used preferentially — like, main character priority. if an accessor exists in the item object, then the defaults won't be used. (but if an accessor doesn't exist, the defaults will be used. the way that works 🧚)

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

for that call above, the default on the field will not be used — which is usually exactly what you want. slay.

---

when you're creating a new database record with your form, if you don't pass in an empty row, then the field defaults get used. or you can just provide defaults in an init_object:

note: the form class has 'item_class' set already.
$form->process( schema => $schema, init_object => $obj ... );

BUT. 😭 if you provide an empty row object for create-type actions, you might actually want some defaults filled in. you can do that by filling the values into the row object, or by turning on the form flag use_defaults_over_obj:

$form->process( item => $empty_row, use_defaults_over_obj => 1 );

and if you always want new DBIC results to be ignored, you could set that flag in a base form method:

sub set_active {
    my $self = shift;
    $self->next::method;
    if ( $self->item and ! $self->item->in_storage ) {
        $self->use_defaults_over_obj(1);
    }
}

---

you could also pass in another object or hashref in the init_object attribute, and set the use_init_obj_over_item flag:

$form->process( item => $empty_row, init_object => $example,
                use_init_obj_over_item => 1 );

⚠️ heads up bestie: the use_init_obj_over_item and use_defaults_over_obj flags get automatically cleared (that is, if you're using persistent forms).

---

okay now for the messy-but-real scenario: forms where some defaults come from a database row and some come from another dynamic source (so, like, putting them into the field definitions makes zero sense). for that you can use the use_init_obj_when_no_accessor_in_item flag to provide two different sets of defaults — one set in the item (usually a db row) and one set in the init_obj. if the item is undefined, the values in the init_object get used. 💜

in form: has '+use_init_obj_when_no_accessor_in_item' => ( default => 1 );
$form->process( item => $item, init_object => { foo => '...' }, .. );

---

there's also a convenience method for setting defaults on a bunch of fields at once: the form's defaults attribute, which uses the same mechanism as update_field_list but only sets defaults. 🎀 note that this hashref is structured like the update_field_list with regard to field names, while the init_object uses "structured" data:

my $defaults = {
    model => 'standard',
    'opts.color' => 'Red',
    'opts.size'  => 'Big',
};
my $init_object => {
    model => 'standard',
    opts  => { color => 'Red', size => 'Big' }
};

$form->process( defaults => $defaults, ... );
$form->process( init_object => $init_object ... );

plus — and this is the tea ☕ — the defaults actually changes the default stored in the field definitions, while the init_object does not. no cap.

there's also an alternative attribute in the fields, default_over_obj, but the new use_defaults_over_obj and use_init_obj_over_item flags make it less necessary. (note that the default_over_obj attribute only provides a default if an item/init_object and accessor exists.) 🦋

🌈 Defaults when processing params

normally when a form is posted, the params will contain all the values necessary to fill in the form. but when a form is used in an API-like fashion — like, complex search forms, you know the vibe — sometimes it's convenient to only provide particular params and let the others use defaults. ✨

here's the catch though 🙈: when the results are built from input, fields with no input are skipped unless the field has a value for input_without_param. there's an additional form-level flag, use_fields_for_input_without_param, which will cause fields with no param entry to be built from the fields. this means that defaults on the field will be used to provide a value and an input for the field. iconic.

🦋 Query parameters for defaults

you can use either the defaults hashref or the init_object to provide query parameter defaults.

🔥 do NOT put them in the params hash, because then FormHandler will assume the form has been posted and attempt to validate — which you don't want to do until the form has actually been submitted. literally do not.

or you can use the posted flag to indicate whether or not to perform validation:

$form->process( posted => ( $c->req->method eq 'POST' ), params => $c->req->params );

and PSA for the Catalyst girlies 💖: in Catalyst there are query_parameters and body_parameters, and parameters contains both query_parameters and body_parameters.

---

👑 AUTHOR

FormHandler Contributors - see HTML::FormHandler

🎀 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.

---

ok bye bestie, go forth and default responsibly 🫶 this was perl v5.34.0, dated 2022-03-25, and you were reading HTML::...efaults(3pm) — mwah 💋