/ 
HTML-FormHandler-0.40002
River stage two • 21 direct dependents • 31 total dependents
/ HTML::FormHandler::Manual::Defaults

NAME

HTML::FormHandler::Manual::Defaults - form defaults documentation

VERSION

version 0.40002

SYNOPSIS

Manual Index

How to set defaults for your fields.

Defaults

Defaults for form fields come from a number of different places. The simplest way to set a field's default is on the field definition:

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

You can also set the default for a field with a method in the form with the name 'default_<field_name>', where any periods in the field name are replaced with underscores.

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

Like 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 the 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 );

For forms where you pass in an 'item' (usually a database row object), the values in that object will be used preferentially; if an accessor exists in the 'item' object, then the defaults won't be used. (If an accessor doesn't exist, the defaults *will* be used.)

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

For the above call the 'default' on the field will not be used, which is usually what you want.

When creating a new database record with your form, if you don't pass in an empty row, then the field defaults will be used, or you can provide defaults in an 'init_object'.

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

If you provide an empty row object for 'create' type actions, however, you might want some defaults filled in. This can be done 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 );

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 );

Note that the 'use_init_obj_over_item' and 'use_defaults_over_obj' flags are automatically cleared (if you're using persistent forms).

There is a convenience method for setting 'defaults' on a number 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 ... );

In addition, the 'defaults' actually changes the 'default' stored in the field definitions, while the init_object does not.

There is 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.

Query parameters for defaults

You can use either the 'defaults' hashref or the 'init_object' to provide query parameter 'defaults'. They should not be provided in the 'params' hash, because then FormHandler will assume that the form has been posted and attempt to validate, which you don't want to do until the form has been submitted.

AUTHOR

FormHandler Contributors - see HTML::FormHandler

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 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.