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

NAME

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

SYNOPSIS

package MyForm;

use Form::Tiny -consistent;
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 DSL for form building.

DOCUMENTATION INDEX

IMPORTING

When imported, Form::Tiny will turn a package it is imported 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;

# fully-featured form:
use Form::Tiny -filtered, -strict;

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

  • -base

    This flag is here only for backwards compatibility. It does not do anything particular on its own.

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

    Installed functions: same as -base

  • -filtered

    This flag enables filters in your form.

    Installed functions: all of -base plus form_filter field_filter form_trim_strings

  • -strict

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

    Installed functions: same as -base

  • -consistent

    Turns on consistent subroutine API in the form package. This will become a default in the future, after the deprecation period. See "Current deprecations" in Form::Tiny::Manual::Compatibility for details.

Form domain-specific language

form_field

form_field $name => %arguments;
form_field $coderef;
form_field $object;

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

In the first (hash) version, %arguments need to be a plain hash (not a hashref) and should not include the name in the hash, as 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 hashref or a constructed object of Form::Tiny::FieldDefinition. A hashref must contain a name. Note that this creates dynamic field, which will be resolved repeatedly during form validation. As such, it should not contain any randomness.

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

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

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.

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

field_filter $type, $coderef; # uses current context
field_filter $name => $type, $coderef;

Same as form_filter, but is narrowed down to a single form field identified by its name. Name can be omitted and the current context will be used. 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.

This was enabled by default once. Refer to "Filtered forms no longer trim strings by default" in Form::Tiny::Manual::Compatibility for details.

TODO

  • Document and test meta classes

  • More tests for form inheritance

  • More examples

AUTHOR

Bartosz Jarzyna <brtastic.dev@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2020 - 2021 by Bartosz Jarzyna

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.