NAME

Data::MuForm::Field - Base field package

VERSION

version 0.01

SYNOPSIS

Instances of Field subclasses are generally built by Data::MuForm from 'has_field' declarations or the field_list.

has_field 'my_field' => ( type => 'Integer' );
field_list => [
   my_field => { type => 'Integer' }
]

Fields can also be added with add_field:

$form->add_field( name => 'my_field', type => 'Integer' );

You can create custom field classes:

package MyApp::Field::MyText;
use Moo;
use Data::MuForm::Meta;
extends 'Data::MuForm::Field::Text';

has 'my_attribute' => ( is => 'rw' );

sub validate { <perform validation> }

1;

DESCRIPTION

This is the base class for form fields. The 'type' of a field class is used in the MuForm field_list or has_field to identify which field class to load from the 'field_namespace' (or directly, when prefixed with '+'). If the type is not specified, it defaults to Text.

See Data::MuForm::Manual::Fields for a list of the fields and brief descriptions of their structure.

NAME

Data::MuForm::Field

ATTRIBUTES

Names, types, accessor

name

The name of the field. Used in the HTML form. Often a db accessor. The only required attribute.

type

The class or type of the field. The 'type' of Data::MuForm::Field::Currency is 'Currency'. Classes that you define yourself are prefixed with '+'.

id

The id to use when rendering.

accessor

If the name of your field is different than your database accessor, use this attribute to provide the accessor.

full_name

The name of the field with all parents:

'event.start_date.month'

full_accessor

The field accessor with all parents.

prefixed_name

The full_name plus the prefix provided in 'field_prefix'. Useful for multiple forms on the same page.

input_param

By default we expect an input parameter based on the field name. This allows you to look for a different input parameter.

Field data

active, inactive, is_active, is_inactive

Determines which fields will be processed and rendered.

Can be changed on a process call, and cleared afterward:

$form->process( active => [ 'foo', 'bar' ], params => $params );

You can use the is_inactive and is_active methods to check whether this particular field is active. May be necessary to use in templates if you're changing the active/inactive of some fields.

if( $form->field('foo')->is_active ) { ... }

input

The input string from the parameters passed in. This is not usually set by the user.

value

The value as it would come from or go into the database, after being acted on by transforms and validation code. Used to construct the $form->values hash. Before validation is performed, the input is copied to the 'value', and validation and constraints should act on 'value'. After validation, $form->value will get a hashref of the values.

fif

Values used to fill in the form. Read only.

[% form.field('title').fif %]

init_value

Initial value populated by fill_from_object. You can tell if a field has changed by comparing 'init_value' and 'value'. You wouldn't normally change this.

input_without_param

Input for this field if there is no param. Set by default for Checkbox, and Select, since an unchecked checkbox or unselected pulldown does not return a parameter.

Form, parent, etc

form: A reference to the containing form.
parent: A reference to the parent of this field. Compound fields are the parents for the fields they contain.
localizer: Set from the form when fields are created.
renderer: Set from the form when fields are created.

Errors

errors

Returns the error list (arrayref) for the field. Also provides 'all_errors', 'num_errors', 'has_errors', 'push_error' and 'clear_errors'. Use 'add_error' to add an error to the array if you want to localize the error message, or 'push_error' to skip the localization.

add_error

Add an error to the list of errors. Error message will be localized using 'localize' method, and the Localizer (default is Data::MuForm::Localizer, which use a gettext style .po file).

return $field->add_error( 'bad data' ) if $bad;

push_error

Adds an error to the list of errors without localization.

error_fields

The form and Compound fields will have an array of errors from the subfields.

methods

A 'methods' hashref allows setting various coderefs, 'build_id', 'build_label', 'build_options', 'validate', 'default'.

methods => { build_id => \&my_build_id } - coderef for constructing the id
methods => { build_label => \&my_build_label } - coderef for constructing the label

build_id: A coderef to build the field's id. If one doesn't exist, will use a form 'build_field_id' method. Fallback is to use the field's full name.
build_label
build_options
validate
default

render_args

The 'render_args' hashref contains keys which are used in rendering, with shortcuts for easier specification in a field definition.

element_attr         - ea
label_attr           - la
wrapper_attr         - wa
error_attr           - era
element_wrapper_attr - ewa

has_field 'foo' => ( render_args => { element_attr => { readonly => 1, my_attr => 'abc' }} );
has_field 'foo' => ( 'ra.ea' => { readonly => 1, my_attr => 'abc' } );
has_field 'foo' => ( 'ra'.wa.class' => ['mb10', 'wr66'] );

Note the the 'name', 'id', and 'value' of fields is set by field attributes. Though it is possible to override the id in render_args, it then won't be available for other code such as 'errors_by_id'. There is some behavior associated with the 'disabled' flag too.

label       - Text label for this field. Defaults to ucfirst field name.
id          - Used in 'id="<id>"' in HTML
disabled    - Boolean to set field disabled

The order attribute may be used to set the order in which fields are rendered.

order       - Used for sorting errors and fields. Built automatically,
              but may also be explicitly set. Auto sequence is by 5: 5, 10, 15, etc

Flags

password

Prevents the entered value from being displayed in the form

writeonly

The initial value is not taken from the database

no_update

Do not include this field in $form->values, and so it won't be updated in the database.

not_nullable

Fields that contain 'empty' values such as '' are changed to undef in the validation process. If this flag is set, the value is not changed to undef. If your database column requires an empty string instead of a null value (such as a NOT NULL column), set this attribute.

has_field 'description' => (
    type => 'TextArea',
    not_nullable => 1,
);

This attribute is also used when you want an empty array to stay an empty array and not be set to undef.

It's also used when you have a compound field and you want the 'value' returned to contain subfields with undef, instead of the whole field to be undef.

Defaults

See also the documentation on Data::MuForm::Manual::Defaults.

default method

Note: do *not* set defaults by setting the 'checked' or 'selected' attributes in options. The code will be unaware that defaults have been set.

has_field 'foo' => (  methods => { default => \&my_default } );
sub my_default { }
OR
has_field 'foo';
sub default_foo { }

Supply a coderef (which will be a method on the field). If not specified and a form method with a name of default_<field_name> exists, it will be used.

default

Provide an initial value in the field declaration:

has_field 'bax' => ( default => 'Default bax' );

Constraints and Validations

Constraints set in attributes

required

Flag indicating whether this field must have a value

unique

For DB field - check for uniqueness. Action is performed by the DB model.

apply

Use the 'apply' keyword to specify an ArrayRef of constraints and coercions to be executed on the field at field_validate time.

has_field 'test' => (
   apply => [ TinyType,
              { check => sub {...}, message => { } },
              { transform => sub { ... lc(shift) ... } }
            ],
);

messages

has_field 'foo' => ( messages => { required => '...', unique => '...' } );
or
has_field 'foo' => ( 'msg.required' => '...' );

Set messages created by MuForm by setting in the 'messages' hashref or with the 'msg.<msg_name>' shortcut. Some field subclasses have additional settable messages.

required: Error message text added to errors if required field is not present. The default is "Field <field label> is required".

Transforms

There are a number of methods to provide finely tuned transformation of the input or value.

transform_input_to_value

In FH was 'inflate_method'.

Transforms the string that was submitted in params (and copied to 'input') when it's stored in the 'value' attribute during validation.

transform_value_to_fif

In FH was 'deflate_method'.

When you get 'fif' for the field and the 'value' is used (as opposed to input) transforms the value to a string suitable for filling in a form field.

transform_default_to_value

In FH was inflate_default_method.

Transform the 'default' provided by an 'model' or 'init_values' or 'default' when it's stored in the 'value'.

transform_value_after_validate

In FH was 'deflate_value_method';

Transform the value after validation has been performs, in order to return a different form in $form->value.

transform_param_to_input

Transform the param when it's stored in 'input'. Will change what the user sees in a re-presented form.

trim

A transform to trim the field. The default 'trim' sub strips beginning and trailing spaces. Set this attribute to null to skip trimming, or supply a different sub.

trim => sub {
    my $string = shift;
    <do something>
    return $string;
}

Trimming is performed before any other defined actions.

Processing and validating the field

Validate method

has_field 'foo' => ( methods => { validate => \&foo_validation } );
sub foo_validation { }
OR
has_field 'foo';
sub validate_foo { }

Supply a coderef (which will be a method on the field). If not specified and a form method with a name of validate_<field_name> exists, it will be used instead.

Periods in field names will be replaced by underscores, so that the field 'addresses.city' will use the 'validate_addresses_city' method for validation.

apply actions

Use Type::Tiny types;

use Types::Standard ('PosInteger');
has_field 'foo' => ( apply => [ PosInteger ] );

validate

This field method can be used in addition to or instead of 'apply' actions in custom field classes. It should validate the field data and set error messages on errors with $field->add_error.

sub validate {
    my $field = shift;
    my $value = $field->value;
    return $field->add_error( ... ) if ( ... );
}

AUTHOR

Gerda Shank

COPYRIGHT AND LICENSE

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

To install Data::MuForm, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::MuForm

CPAN shell

perl -MCPAN -e shell
install Data::MuForm

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

NAME

ATTRIBUTES

Names, types, accessor

Field data

Form, parent, etc

Errors

methods

render_args

Flags

Defaults

Constraints and Validations

Constraints set in attributes

messages

Transforms

Processing and validating the field

Validate method

apply actions

validate

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions