NAME

PDT::Server::Validator - PDT form field validator

*EARLY STAGE WARNING*

This module is currently in the early stages. For the latest please check the github page at http://github.com/exodist/PDT

DESCRIPTION

This is the validator used to validate form input from html forms. This is heavily influenced by CGI::ValidOp. I have adopted what I like from CGI::ValidOp, but have modified it to better suit my workflow.

CONTROLLER SYNOPSYS

    package My::Controller;
    use strict;
    use warnings;

    # Use the validator and bring int he shortcut function.
    use PDT::Server::Validator qw/validate/;

    sub fields {
        [
            {
                # Name this set (optional)
                -name => 'field-set name',

                # Make this field set optional contingent on the value of
                # 'field_name', if bool is true then this set is only required
                # when 'field_name' is true. When bool is false this set is
                # only required when 'field_name' is false.
                -optional => [ field_name, bool ],

                # Define fields in 1 of 3 ways

                # Basic, type is the html form input type
                name => type,

                # Basic with a premade validator or a codref validator
                name => [ type, (validator || sub {}) ],

                # Complete
                name => {
                    type => type,
                    validation => (validator || sub ),
                    label => label,
                },
            },
            { ... },
        ]
    }

    # Using shortcut
    sub do_stuff_a {
        my $self = shift;
        my %params = @_;
        my $validator = validate( \%params );

        # Check for errors, warn for each
        warn $_ for @{ $validator->errors } if $validator->errors;

        $self->save( $validator->values );

        # Get value of param 'a' only if it passed validation
        print $validator->value( 'a' );

        # Get value of param 'a' even if it failed validation
        print $validation->unsafe( 'a' );
    }

    # no shortcut
    sub do_dtuff_b {
        my $self = shift;
        my %params = @_;

        my $validator = PDT::Server::Validator->new( fields => $self->fields, args => \%params );
        my $no_errors = $valdiator->validate();

        # Check for errors, warn for each
        warn $_ for @{ $validator->errors } if $validator->errors;

        $self->save( $validator->values );

        # Get value of param 'a' only if it passed validation
        print $validator->value( 'a' );

        # Get value of param 'a' even if it failed validation
        print $validation->unsafe( 'a' );
    }

PLUGIN SYNOPSYS

Plugins should use the validator and import add_validator(). add_validator() takes a validator name, and a coderef. The coderef should accept a single value as an argument. The coderef should return true when valid, false and an error message when not valid.

    package PDT::Server::Validator::Basic;
    use strict;
    use warnings;

    use PDT::Server::Validator qw/add_validator/;

    add_validator integer => sub {
        my ( $value ) = @_;
        return 1 if $value =~ m/^\d+$/;
        return ( 0, "'$value' is not an integer" );
    };

    1;

CLASS METHODS

$class->import()

$class->import( qw/validate/ )

$class->import( qw/add_validator/ )

$class->import( qw/validate add_validator/ )

Called automatically by use. Exports helper/shortcut functions to the current package. Nothing special here.

$class->new( args => {}, fields => [{},{},...] )

Create a new instance. args shoudl be a hash of field => value to be validated. Fields should be a field defenition like that in the synopsys.

$class->validator( $name )

Get the validator coderef for the given name.

OBJECT METHODS

$obj->args()

Get the argument hash provided at construction.

$obj->fields()

Get the field defenitions provided at construction.

$obj->values()

Get the hash of validated field values.

$errors = $obj->errors()

$obj->errors( 'error1', 'error2' )

Add errors, retrieve errors, check for errors.

$obj->value( $param )

$obj->value( $param, $value );

Used to get/set a value after validation.

I don't recommend changing a value manually.

$val = $obj->unsafe( $param )

Get the value of the parameter, even if it does not validate.

$bool = $obj->validate()

Run the validation checks. Make validated values available and record errors.

AUTHORS

Chad Granum exodist7@gmail.com

COPYRIGHT

Copyright (C) 2010 Chad Granum

PDT is free software; Standard perl licence.

PDT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.