NAME

Data::FormValidator::Results - Object which contains the results of an input validation.

SYNOPSIS

    my $results = $validator->check( \%fdat, "customer_infos" );

    # Print the name of missing fields
    if ( $results->has_missing ) {
        foreach my $f ( $results->missing ) {
            print $f, " is missing\n";
        }
    }

    # Print the name of invalid fields
    if ( $results->has_invalid ) {
        foreach my $f ( $results->invalid ) {
            print $f, " is invalid: ", $results->invalid( $f ) \n";
        }
    }

    # Print unknown fields
    if ( $results->has_unknown ) {
        foreach my $f ( $results->unknown ) {
            print $f, " is unknown\n";
        }
    }

    # Print valid fields
    foreach my $f ( $results->valid() ) {
        print $f, " =  ", $result->valid( $f ), "\n";
    }

DESCRIPTION

This is the object returned by the Data::FormValidator check method. It can be queried for information about the validation results.

valid( [field], [value] );

This method returns in an array context the list of fields which contains valid value. In a scalar context, it returns an hash reference which contains the valid fields and their value.

If called with one argument, it returns the value of that field if it contains valid data, undef otherwise.

If called with two arguments, the first is taken as a field in the valid hash, and this field is set to the value of the second argument. The value is returned.

This can be useful in some cases to call from within a constraint to alter the results of the valid hash.

has_missing()

This method returns true if the results contains missing fields.

missing( [field] )

This method returns in an array context the list of fields which are missing. In a scalar context, it returns an array reference to the list of missing fields.

If called with an argument, it returns true if that field is missing, undef otherwise.

has_invalid()

This method returns true if the results contains fields with invalid data.

invalid( [field] )

This method returns in an array context the list of fields which contains invalid value.

In a scalar context, it returns an hash reference which contains the invalid fields as keys, and references to arrays of failed constraints as values.

If called with an argument, it returns the reference to an array of failed constraints for this field.

has_unknown()

This method returns true if the results contains unknown fields.

unknown( [field] )

This method returns in an array context the list of fields which are unknown. In a scalar context, it returns an hash reference which contains the unknown fields and their value.

If called with an argument, it returns the value of that field if it is unknown, undef otherwise.

msgs([config parameters])

This method returns a hash reference to error messages. The exact format is determined by parameters in th msgs area of the validation profile, described in the Data::FormValidator documentation.

This method takes one possible parameter, a hash reference containing the same options that you can define in the validation profile. This allows you to seperate the controls for message display from the rest of the profile. While validation profiles may be different for every form, you may wish to format messages the same way across many projects.

Controls passed into the <msgs> method will be applied first, followed by ones applied in the profile. This allows you to keep the controls you pass to msgs as "global" and override them in a specific profile if needed.

WRITING YOUR OWN VALIDATION ROUTINES

It's easy to create your own module of validation routines. The easiest approach to this may be to check the source code of the Data::FormValidator module for example syntax. Also notice the validator_packages option in the input profile.

You will find that validation routines are named two ways. Some are named with the prefix match_ while others start with valid_. The difference is that the match_ routines are built to untaint the data and routine a safe version of it if it validates, while valid_ routines simply return a true value if the validation succeeds and false otherwise.

It is preferable to write "match" routines that untaint data for the extra security benefits. Plus, Data::FormValidator will AUTOLOAD a "valid_" version if anyone tries to use it, so you only need to write one routine to cover both cases.

Usually validation routines only need one input, the value being specified. However, sometimes more than one value is needed. For that, the following syntax is recommended for calling the routines:

Example:

                image_field  => {  
                        constraint_method  => 'max_image_dimensions',
                        params => [\100,\200],
                },

Using this syntax, the first parameter that will be passed to the routine is the Data::FormValidator object. The remaining parameters will come from the params array. Strings will be replaced by the values of fields with the same names, and references will be passed directly.

A couple of of useful methods to use on the Data::FormValidator::Results object are available to you to use inside of your routine.

get_input_data

Returns the raw input data. This may be a CGI object if that's what was used in the validation routine.

Example

 my $data = $self->get_input_data;

get_current_constraint_field

Returns the name of the current field being tested in the constraint.

Example:

 my $field = $self->get_current_constraint_field;

This reduces the number of parameters that need to be passed into the routine and allows multi-valued constraints to be used with constraint_regexp_map.

For complete examples of multi-valued constraints, see Data::FormValidator::Constraints::Upload

get_current_constraint_value

Returns the name of the current value being tested in the constraint.

Example:

 my $value = $self->get_current_constraint_value;

This reduces the number of parameters that need to be passed into the routine and allows multi-valued constraints to be used with constraint_regexp_map.

get_current_constraint_name

Returns the name of the current constraint being applied

Example:

 my $value = $self->get_current_constraint_name;

This is useful for building a constraint on the fly based on it's name. It's used internally as part of the interface to the Regexp::Commmon regular expressions.

SEE ALSO

Data::FormValidator, Data::FormValidator::Filters, Data::FormValidator::Constraints, Data::FormValidator::ConstraintsFactory

AUTHOR

Author: Francis J. Lacoste <francis.lacoste@iNsu.COM> Maintainer: Mark Stosberg <mark@summersault.com>

COPYRIGHT

Copyright (c) 1999,2000 iNsu Innovations Inc. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms as perl itself.

cpanm Data::FormValidator

perl -MCPAN -e shell
install Data::FormValidator