The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Form-Tiny-2.12
River stage one • 1 direct dependent • 1 total dependent
5 ++
/ 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 DSL for form building.

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;

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 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;
        field_filter Form::Tiny::Filter->new(...);

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.

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 <bbrtj.pro@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2020 - 2022 by Bartosz Jarzyna

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