NAME

CGI::Builder::DFVCheck - CGI::Builder and Data::FormValidator integration

VERSION 1.0

To have the complete list of all the extensions of the CBF, see "Extensions List" in CGI::Builder

INSTALLATION

Prerequisites

CGI::Builder        >= 1.0
Data::FormValidator >= 3.5

CPAN

perl -MCPAN -e 'install CGI::Builder::DFVCheck'

If you want to install all the extensions and prerequisites of the CBF, all in one easy step:

perl -MCPAN -e 'install Bundle::CGI::Builder::Complete'

Standard installation

From the directory where this file is located, type:

perl Makefile.PL
make
make test
make install

SYNOPSIS

use CGI::Builder
qw| CGI::Builder::DFVCheck
  |;
 
$s->dfv_check(\%form_profile)
   || return $s->switch_to('myOtherPage');

# if there is any error
# $s->page_error is automatically set
# to the $result->msgs HASH ref
# and $s->dfv_results to the results object
 
$results = $s->dfv_results

DESCRIPTION

This module integrates the Data::FormValidator capability with CGI::Builder.

It adds to your build an useful dfv_check() method that you can use in your Switch Handlers (or in your Page Handlers) to check the input e.g. from a form. If any error is found, then the methods will return '0' (false) and will set the page_error group accessor to the $results->msgs, and will add the dfv_results property.

CGI::Builder Example

package My::WebApp ;
use CGI::Builder
qw| CGI::Builder::DFVCheck
  |;

sub SH_myPage
{
  my $s = shift ;
  $s->dfv_check({ required => 'email' })
    || $s->switch_to('myOtherPage');
  ...
}

# do something with page_error
sub OH_pre_page {
    my $s  = shift ;
    my $E = $s->page_error ;
    while ( my($field, $err) = each %$E ) {
        $s->page_content .= "$field $err\n"
    }
}

INTEGRATION WITH CGI::Builder::Magic

The integration with CGI::Builder::Magic is very powerful.

You need just to pass the profile to the dfv_check() method and put the labels in the template: no other configuration needed on your side: the error labels in any template will be auto-magically substituted with the error string when needed.

Note: The hash reference returned by the msgs() method will internally set the $s->page_error which is passed as a lookup location to the Template::Magic object.

CGI::Builder::Magic Example 1

package My::WebAppMagic ;
use CGI::Builder
qw| CGI::Builder::DFVCheck
    CGI::Builder::Magic
  |;

sub SH_myPage
{
  my $s = shift ;
  $s->dfv_check({ required => 'email',
                  msgs     => { prefix     => 'err_' },
                })
    || $s->switch_to('myOtherPage');
  ...
}

# the PH_myOtherPage method is optional

Somewhere in the 'myOtherPage.html' template (or in any other template) all the label prefixed with 'err_' will be substitute with the relative error if present (with the profile passed in the example it happens just with 'err_email'):

<!--{err_email}-->

CGI::Builder::Magic Example 2

package My::WebAppMagic ;
use CGI::Builder
qw| CGI::Builder::DFVCheck
    CGI::Builder::Magic
  |;

sub SH_myPage
{
  my $s = shift ;
  $s->dfv_check({ required => 'email',
                  msgs     => { prefix     => 'err_'  }
               })
    || $s->switch_to('myOtherPage');
  ...
}

# the PH_myOtherPage method is optional

package WebAppMagic::Lookups;

sub MISSING {
    my $s = shift ;
    my $missing
    if ( $s->dfv_resuts->has_missing ) {
        foreach my $f ( $s->dfv_resuts->missing ) {
           $missing .= $f, " is missing\n";
        }
    }
    $missing
}

Somewhere in the 'myOtherPage.html' template (or in any other template) all the 'MISSING' labels will be substitute with the relative error if present:

<!--{MISSING}-->

METHODS

dfv_check ( dfv_profile )

Use this method to check the query parameters with the dfv_profile. It returns 1 on success and 0 on failure. If there are some missing or unvalid fields it set also the dfv_results property to the Data::FormValidator::Results object, and the page_error CBF property to the $s->dfv_results->msgs HASH reference.

dfv_new

This method is not intended to be used directly in your CBB. It is used internally to initialize and returns the Data::FormValidator object. You should redefine this method in your CBB if you need some more customized object. (see Data::FormValidator).

PROPERTY and GROUP ACCESSORS

This module adds a couple of properties to the standard CBF properties.

dfv_defaults

This group accessor handles the Data::FormValidator defaults that are used in the creation of the internal Data::FormValidator object.

Note: You can completely override the creation of the internal object by overriding the dfv_new() method.

dfv_results

This property allows you to access the Data::FormValidator::Results object set by the dfv_check() method only if there are some missing or invalid fields.

SUPPORT and FEEDBACK

You can join the CBF mailing list at this url:

http://lists.sourceforge.net/lists/listinfo/cgi-builder-users

AUTHOR and COPYRIGHT

© 2004 by Domizio Demichelis (http://perl.4pro.net)

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

cpanm CGI::Builder::DFVCheck

perl -MCPAN -e shell
install CGI::Builder::DFVCheck