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.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 258:
Non-ASCII character seen before =encoding in '©'. Assuming CP1252