/ 
Form-Tiny-2.25
River stage one • 2 direct dependents • 2 total dependents
/ Form::Tiny

NAME

Form::Tiny - Input validator centered around Type::Tiny

SYNOPSIS

package MyForm;

use Form::Tiny;
use Types::Standard qw(Int);

form_field 'my_field' => (
	required => 1,
);

form_field 'another_field' => (
	type => Int,
	default => sub { 0 },
);

DESCRIPTION

Form::Tiny is a customizable hashref validator with form building Domain-Specific Language (DSL).

DOCUMENTATION INDEX

IMPORTING

When imported, Form::Tiny will turn a package into a Moo class that does the Form::Tiny::Form role. It will also install helper functions in your package that act as a domain-specific language (DSL) for building your form.

package MyForm;

# imports only basic helpers
use Form::Tiny;

# all features offered by base distribution
use Form::Tiny -filtered, -strict;

# external plugins
use Form::Tiny plugins => ['Diva'];

After use Form::Tiny statement, your package gains all the Moo keywords, some Form::Tiny keywords (see "Available import flags") and all Form::Tiny::Form methods.

Available import flags

No matter which flag was used in import, using Form::Tiny always installs these functions: form_field form_cleaner form_hook

  • -nomoo

    This flag stops Form::Tiny from importing Moo into your namespace. Unless you use a different class system (like Moose) will have to declare your own constructor.

  • -filtered

    This flag enables field filtering in your form.

    Additional installed functions: form_filter field_filter form_trim_strings

  • -strict

    This flag makes your form check for input data strictness before the validation.

  • plugins => ['Plugin1', '+Full::Namespace::To::Plugin2']

    Load plugins into Form::Tiny. Plugins may introduce additional keywords, mix in roles or add metaclass roles. See Form::Tiny::Plugin for details on how to implement a plugin.

Form domain-specific language

form_field

form_field $name => %arguments;
form_field $coderef;
form_field($object); # watch out for indirect method call!

This helper declares a new field for your form. Each style of calling this function should contain keys that meet the specification of Form::Tiny::FieldDefinition, or an object of this class.

In the first (hash) version, %arguments need to be a plain hash (not a hashref) and should not include the name in the hash, since it will be overriden by the first argument $name. This form also sets the context for the form being built: see "Context" in Form::Tiny::Manual for details.

In the second (coderef) version, $coderef gets passed the form instance as its only argument and should return a hash reference or a constructed object of Form::Tiny::FieldDefinition. Unlike the first call style, hashref must contain a name. Note that this creates dynamic field, which will be resolved later, before each form validation. Generally, you should avoid using dynamic fields and only use them when there is something special that you are trying to achieve.

If you need a subclass of the default implementation, and you don't need a dynamic field, you can use the third style of the call, which takes a constructed object of Form::Tiny::FieldDefinition or its subclass.

form_message

form_message
	$type1 => $message1,
	$type2 => $message2;

Override form default error messages, possibly multiple at a time. Types can be any of Required (when a mandatory field is missing), IsntStrict (when form is strict and the check for it fails) and InvalidFormat (when passed input format is not a hash reference) - currently only those types have their own dedicated error message.

form_hook

form_hook $stage => $coderef;

This creates a new hook for $stage. Each stage may have multiple hooks and each will pass different arguments to the $coderef. Refer to "Hooks" in Form::Tiny::Manual for details.

form_cleaner

form_cleaner $coderef;

A shortcut for form_hook cleanup => $coderef;.

field_validator

# uses current context
field_validator $message => $coderef;

Adds an additional custom validator, ran after the type of the field is validated. $message should be something that can present itself as a string. If for a given input parameter $coderef returns false, that message will be added to form errors for that field. See "Additional validators" in Form::Tiny::Manual for details.

See "Context" in Form::Tiny::Manual for details on context.

form_filter

form_filter $type, $coderef;

Filters the input value before the validation. $type should be a Type::Tiny (or compatible) type check. For each input field that passes that check, $coderef will be ran.

See "Filters" in Form::Tiny::Manual for details on filters.

field_filter

# uses current context
field_filter $type, $coderef;

Same as form_filter, but is narrowed down to a single form field.

See "Context" in Form::Tiny::Manual for details on context.

form_trim_strings

form_trim_strings;

This helper takes no arguments, but causes your form to filter string values by calling Form::Tiny::Utils::trim on them.

TODO

  • More tests for form inheritance

  • More examples

AUTHOR

Bartosz Jarzyna <bbrtj.pro@gmail.com>

Contributors

In no particular order:

Diab Jerius (CPAN: DJERIUS)

COPYRIGHT AND LICENSE

Copyright (C) 2020 - 2023 by Bartosz Jarzyna

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