The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Form-Tiny-2.01
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 -base;
        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

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_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;.

form_filter

        form_filter $type, $coderef;

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