NAME

Validation::Class::Plugins - Basic Instructions for Writing Plugins

DESCRIPTION

This documentation serves as a brief overview on writing plugins for Validation::Class. Here are the key points:

When creating official Validation::Class plugins you should use the namespace Validation::Class::Plugin::YourPluginName. This will allow users of your plugin to simply pass YourPluginName to the load_plugins() method. Otherwise you will need to pass the fully-qualified plugin package name prefixed with a "+" symbol. The following is an example of including a plugin.

    package MyApp::Validation;
    
    use Validation::Class;
    
    load {
        plugins => [
            'PluginName',
            '+MyApp::Validation::YourPluginName'
        ]
    };
    
    # a validation rule
    field 'login'  => {
        label      => 'User Login',
        error      => 'Login invalid.',
        required   => 1,
        validation => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'admin' ? 1 : 0;
        }
    };
    
    # a validation rule
    field 'password'  => {
        label         => 'User Password',
        error         => 'Password invalid.',
        required      => 1,
        validation    => sub {
            my ($self, $this_field, $all_params) = @_;
            return $this_field->{value} eq 'pass' ? 1 : 0;
        }
    };
    
    1;
    

Your plugin is loaded at runtime and can manipulate the Validation::Class object by declaring a new method. The following is an example of a fictitious plugin for formatting telephone numbers:

    package Validation::Class::Plugin::TelephoneFormatting;
    
    # hook into the instantiation process
    # of the calling class at runtime
    sub new {
    
        my ($plugin, $caller) = @_;
        
        # US Telephones
        $caller->filters->{telephone_usa} = sub {
            my $phone = shift;
               $phone =~ s/\D//g;
            
            my ($area, $prefix, $xchng) = $phone =~ m/1?(\d{3})(\d{3})(\d{4});
               
            return "+1 ($area) $prefix-$xchng";
        };
        
    }

Once we create, test and deploy our plugin, we can use it in our code as follows:

    package MyApp::Validation;
    
    use Validation::Class;
    
    load {
        plugins => ['TelephoneFormatting']
    };
    
    # a validation rule
    field 'phone'  => {
        label      => 'Telephone Number',
        error      => 'Phone number invalid.',
        required   => 1,
        filters    => 'telephone_usa',
        filtering  => 'post',
        pattern    => '+1 (###) ###-####'
    };
    
    package main ;
    
    my $rules = MyApp::Validation->new(...);
    
    # ...
    

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by awncorp.

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