view release on metacpan or  search on metacpan

lib/Form/Tiny/Manual.pod  view on Meta::CPAN

=over

=item * it is ran before data is rejected due to not being a hash reference

=item * its return value is used for the rest of the validation process as input

=back

This hook does require you to return a new input value to the validation. It is
passed the same data as C<before_validate>.

B<Note>: This hook is ran inside a try/catch block, so you can throw an
exception inside in order to stop form validation if the input is malformed.
This will add I<Form::Tiny::Error::InvalidFormat> error to the form.

=head3 after_error

	form_hook after_error => sub {
		my $form_instance = shift;
		my $error_instance = shift;

		if ($error_instance->field eq 'some_field') {
			$error_instance->set_error('new error message');
		}

		# no need to return
	};

Called after an error has been added to the form. Gets passed two arguments:
object instance and a newly created error instance. Can be used to log/debug or
transform error messages in any way, like internationalize them.

This hook does not require you to return anything.

=head2 Optional behavior

The module provides optional predefined behaviors which can be enabled with an
import flag.

=head3 Strict mode

Turned on by L<Form::Tiny::Plugin::Strict> plugin or with the C<-strict> flag
in L<Form::Tiny>.

Enables strict mode for the form. Validation will fail if form input contains
any data not specified in the field definitions. This additional check is added
to the form as a C<before_validate> hook.

Strict mode is helpful when you want to make sure you're not getting any extra
data in your input. It does not affect the output of forms, only the validation
result. Form::Tiny does not copy fields that are not declared explicitly to
output regardless of the strict mode being turned on.

For example, if your form contains many optional fields which change often, you
may want to ensure that your users are not sending anything you're not going to
handle. This can help debugging and prevent errors.

B<Important note>: Strict mode will cause the system to crawl your entire input
data to search for any odd elements. This will cause validation to only run at
about half the speed, and more importantly it will not be able to cope with
circular references (even weakened). If your input data may contain circular
references you should not make use of the strict mode.

=head3 Filters

Turned on by L<Form::Tiny::Plugin::Filtered> plugin or with the C<-filtered>
flag in L<Form::Tiny>.

Enables initial filtering for the input fields. This behavior is added to the
form as a C<before_mangle> hook.

The filtering system performs a type check on field values and only apply a
filtering subroutine when the type matches. This is done before the validation,
and so can affect the validation result. Filters behave much like type
coercion, but they are more flexible and can be stacked by having multiple
filters for the same field, each using value returned by the previous one.

Filter subroutines should accept two parameters: C<($self, $value)>, and must
return a C<$value>, changed or unchanged.

An example filter that turns integers into their absolute values:

	form_filter Int, sub {
		my ($self, $value) = @_;
		return abs $value;
	};

A filter can be also narrowed down to a single form field with C<field_filter>
keyword, which will apply to the last field declared:

	form_field 'my_field';
	field_filter Int, sub { abs pop() };

One special keyword exists for string trimming using the filters system:

	form_trim_strings;

When the field is filtered, the form filters are applied before field filters.
Each type of filter is applied in the order they were defined.

=head3 Plugins

Form::Tiny can be extended with plugins:

	use Form::Tiny plugins => [qw(Plugin1 +Namespace::Plugin2)];

Added behavior is entirely up to the plugin. See L<Form::Tiny::Plugin> for
details on how to implement a plugin.

=head2 Inline forms

The module enables a way to create a form without the need of a dedicated
package. This is done with the L<Form::Tiny::Inline> class. This requires the
user to pass all the data to the constructor, as shown in the example:

	my $form = Form::Tiny::Inline          #     An inline form ...
	           ->is(qw/strict filtered/)   # ... with Strict and Filtered plugins ...
	           ->new(                      # ... will be created with properties:
		fields => {my_field => { ... }},
		cleaner => sub { ... },
	);