NAME

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

VERSION 1.28

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

INSTALLATION

Prerequisites

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

CPAN

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

You have also the possibility to use the Bundle to install all the extensions and prerequisites of the CBF in just one step. Please, notice that the Bundle will install A LOT of modules that you might not need, so use it specially if you want to extensively try the CBF.

    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
   
   # $s->dfv_results is always set to the results object
    
   $results = $s->dfv_results

DESCRIPTION

Note: You should know CGI::Builder.

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.

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 field has this problem: $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, put the labels in the template and 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

Your CBB:

    package My::WebAppMagic ;
    use CGI::Builder
    qw| CGI::Builder::DFVCheck
        CGI::Builder::Magic
      |;
    
    sub SH_thank_you
    {
      my $s = shift ;
      $s->dfv_check({ required => 'email',
                      msgs     => { prefix     => 'err_' },
                    })
        || $s->switch_to('input_form');
    }
    
    # the PH_thank_you and the PH_input_form handlers are optional
    # if you have the templates 'thank_you.html' and 'input_form.html'

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

    <!--{err_email}-->

This might be the input_form.html template file:

    <!--{FillInForm}-->
    <form action="thank_you" method="get">
    Name: <input name="name" type="text" value=""><br>
    Email: <input name="email" type="text" value=""><!--{err_email}--><br>
    <input type="submit" name="submit" value="Submit">
    </form>
    <!--{/FillInForm}-->

Note: The 'FillInForm' block is optional, but it will automatically re-fills the fields on error (if you are using CGI::Builder::Magic >= 1.2).

CGI::Builder::Magic Example 2

Your CBB:

    package My::WebAppMagic ;
    use CGI::Builder
    qw| CGI::Builder::DFVCheck
        CGI::Builder::Magic
      |;
    
    sub SH_thank_you
    {
      my $s = shift ;
      $s->dfv_check({ required => 'email',
                      msgs     => { prefix => 'err_' }
                   })
        || $s->switch_to('input_form');
    }
    
    # the PH_thank_you and the PH_input_form handlers are optional
    # if you have the templates 'thank_you.html' and 'input_form.html'
    
    package WebAppMagic::Lookups;
    
    sub MISSING {
        my $s = shift ;
        my $missing;
        if ( $s->dfv_resuts->has_missing ) {
            foreach my $f ( $s->dfv_resuts->missing ) {
               $missing .= "<b>$f</b> value is missing<br>\n";
            }
        }
        $missing;
    }

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

    <!--{MISSING}-->

This might be the input_form.html template file:

    <!--{FillInForm}-->
    <form action="thank_you" method="get">
    <!--{MISSING}-->
    Name: <input name="name" type="text" value=""><br>
    Email: <input name="email" type="text" value=""><br>
    <input type="submit" name="submit" value="Submit">
    </form>
    <!--{/FillInForm}-->

Note: The 'FillInForm' block is optional, but it will automatically re-fills the fields on error (if you are using CGI::Builder::Magic >= 1.2).

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 page_error WebApp 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 read only property allows you to access the Data::FormValidator::Results object set by the dfv_check() method.

EFFICIENCY

The Data::FormValidator module is required only if-and-when you use the dfv_check method, that usually occours at run time. That will save loading time in CGI environment (i.e. false $ENV{MOD_PERL}) but if most requests use any dfv_check method, it might be more efficient add a 'use Data::FormValidator;' to your code, which will load the module at compile time (regardless the request will actually use it).

SUPPORT

See "SUPPORT" in CGI::Builder.

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