The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Form-Tiny-2.07
River stage one • 1 direct dependent • 1 total dependent
5 ++
/ Form::Tiny

NAME

Form::Tiny - Input validator implementation 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 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

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 filters in your form.

    Additional installed functions: form_filter field_filter form_trim_strings

  • -strict

    This flag makes your form check for 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 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

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