NAME
Data::FormValidator::Tutorial
TUTORIAL
Introduction
Trust the user. Don't trust their data.Have you ever needed some code to verify the user entered the right data, much less even entered it at all in the first place? You may start off with an if branch, then more and more. Then you may start with a fancy %required hash with the field name keys and description values. And you copy-n-paste that code everywhere? Sound familiar? It does to me and I wish I had someone point me in the direction of this module a long time ago. I hope we are reaching you in time!
This tutorial will start off really basic and then get into how it can help even with complex situations. So let's get started!
And so we begin...
To begin with, I'm going to assume that you're a Web developer, working on a CGI or mod_perl program. You can also use this module for other application types and these examples will still apply, but it will help me if I can relate to what you're doing. This tutorial is also based on the latest & greatest version - 3.62. I hope I just didn't date myself.
So let's start off with a simple CGI script that handles when the user submits their input:
use CGI;
# This is a simple script that is the "action" of a subscribe form
# that has fname, lname, over18 checkbox, dob, email, password1,
# password2 and avatar form fields.
my ( $cgi );
$cgi = new CGI;
# We need to make sure they provided all those fields!So now let's create a new Data::FormValidator (you know, let's call it dfv for short from here on out, ok?) object. First, we'll need to add the use Data::FormValidator; line at the top of your code and then call dfv's check method on the $cgi object. Here's what that code looks like so far:
use CGI;
use Data::FormValidator;
my ( $cgi, $dfv_profile, $results );
$cgi = new CGI;
# We need to make sure they provided all those fields!
$dfv_profile = {};
$results = Data::FormValidator->check( $cgi, $dfv_profile );I hope you don't object to me taking out those comments ... just showing the pertinent lines now that you have the grasp of what we're trying to do.
That code won't work (yet). The $dfv_profile data structure is blank. So dfv doesn't have anything to check, so everything will be hunky-dorey. As you get this framework meshed out, you'll find yourself refining the $dfv_profile data structure long after (What? Management changes their mind on what's important? Or how something looks?), so some people actually remove it to a separate subroutine:
...
$results = Data::FormValidator->check( $cgi, dfv_profile() );
...
sub dfv_profile {
return {
};
}Ok, so now let's hammer out the dfv profile. We'll just keep it as a separate data structure, instead of using the subroutine method. Let's first start off by saying we are going to require the fname, lname, email, password1, and password2 fields. So here's how that would look:
$dfv_profile =
{
'required' => [ qw( fname lname email password1 password2 ) ],
# FYI, I always leave a comma at the end to make future changes easy
};So if the user doesn't provide any of those fields (or if the field only contains spaces), it will trigger has_missing() to return true.
So after establishing the $results variable through the check() call, we can then use it to call dfv's support methods: has_invalid and has_missing
...
$results = Data::FormValidator->check( $cgi, $dfv_profile );
if ( $results->has_missing() || $results->has_invalid() ) {
# There was something wrong w/ the data...
} else {
# We're in the clear! The user has provided you with
# good data
}
...So now if the user submits the form with any of those fields not filled out (or filled with spaces), then it will trigger the has_missing() method.
Our code isn't setup to handle that, so let's flesh that part out. There are several ways to let the user know their data wasn't accepted. Let's keep it simple and have a results page that either shows an error message or a message saying the data was accepted. To do this, I will employ HTML::Template, though there are several ways to do this, too.
First, let's create the template code:
<html>
<head>
<title>Subscription Results</title>
</head>
<body>
<h2>Subscription Results</h2>
<!-- TMPL_IF NAME="some_errors" -->
<p>I'm sorry, but there were some problems with your subscription:</p>
<ul>
<!-- TMPL_IF NAME="err_fname" -->
<li>You missed your first name.</li>
<!-- /TMPL_IF -->
<!-- TMPL_IF NAME="err_lname" -->
<li>You missed your last name.</li>
<!-- /TMPL_IF -->
<!-- ... AND SO ON FOR EACH FIELD NAME ... -->
</ul>
<p>RESULTS Data Structure:</p>
<pre>
<!-- TMPL_VAR NAME="results" -->
</pre>
<!-- TMPL_ELSE -->
<p>Your subscription has been processed.</p>
<p><a href="/">Back to the Home Page?</a></p>
<!-- /TMPL_IF -->
</body>
</html>Now we need to modify the subscribe.cgi script to use the results.TMPL file. Here's what I have so far:
#!/usr/bin/perl -wT
use strict;
$|++;
use CGI;
use CGI::Carp qw( fatalsToBrowser );
use Data::FormValidator;
use HTML::Template;
use Data::Dumper;
my ( $cgi, $dfv_profile, $results, $template );
$cgi = new CGI;
print $cgi->header;
$dfv_profile =
{
'required' => [ qw(
fname lname emails
password1 password2
) ],
};
$results = Data::FormValidator->check(
$cgi, $dfv_profile
);
$template = HTML::Template->new(
'filename' => 'results.TMPL',
'die_on_bad_params' => 0,
);
if (
$results->has_invalid or
$results->has_missing
) {
# something's wrong, which you can
# access what exactly from the
# $results object
my $res_dump = Dumper( $results );
$template->param(
'some_errors' => 1,
'results' => $res_dump,
);
} else {
# the user provided complete and valid
# data ... it's cool to proceed
}
print $template->output;This script and template are in a debug type of mode. If you actually run this (without filling out the required fields), you'll see the $results object all written out in the results, which is probably not what you want your user to see. We'll take it out when we go "live" (it'd be good to make a comment in your code to remind yourself later).
Ok, so now let's talk about the msgs stuff. You see, you could pick apart the results object to get the missing and invalid fields and then pass them in, individually or you can shortcut it with dfv's msgs support. Dfv's msgs also supports a flag for the overall error status. To use it, we would extend the $dfv_profile, like so:
$dfv_profile =
{
'required' # ... [snip] ...
'msgs' => {
'prefix' => 'err_',
'any_errors' => 'some_errors',
},
};Then you can use dfv's 'msgs' method from the $results object and pass that directly into the $template object:
$template->param( $results->msgs );
# I'm keeping this next line in here for debugging
# purposes... take out when we go live
$template->param(
'results' => $res_dump,
);So now dfv will take care of passing along the right template parameters dynamically. Give it a shot and go back & forth between filling out particular form fields (make sure you've fleshed out the rest of the template code).
So this is great! Now you have a system in place to verify that the user is providing all of the information in an user-friendly method as well as easy-to-maintain/read code for you.
Now the pointed-haired boss steps into your office and says "Hey, we're getting a lot of registrations with bogus email information and Marketing can't spam 'em! Fix that code to only accept valid email addresses." This is where constraints comes into the picture. Constraints take a closer look at the input to see if it's valid. If not, it will trigger has_invalid() to return true.
$dfv_profile =
{
'required' => [ qw( fname lname email password1 password2 ) ],
'constraints' => {
'email' => qr/\w+\@\w+\.\w+/,
},
};This is saying that the email field is valid only when the regex pattern fits the input. Now I just gave a very rough (and probably inaccurate) pattern, just so you get the idea. So many people have come across this type of thing, that there's a shortcut for the bona-fide and accurate email address pattern that's built into the dfv package (you can see Data::FormValidator::Constraints for other built-in constraint types, too).
...
'email' => 'email',
...Pretty sweet, huh? There are other things you can do on the right-hand side of a constraint, too. Right now, you've seen a regexp pattern and using a built-in constraint, but you can also point to a subroutine and do your own methodology:
...
'email' => sub {
my $email = shift;
if ( $email =~ /purdy\.info$/ ) {
# only accepting emails from my domain
return 1;
} else {
return 0;
}
},
...You could also bump that subroutine outside the data structure somewhere and refer to it by name:
...
'email' => \&my_domain_email(),
...
sub my_domain_email {
...
}Lastly, either you or the PHB (pointed-haired boss) will note that password1 and password2 should be confirmed to be the same thing, to make sure the user didn't typo the password wrong. I think you can handle that yourself, given the ammo I've given above, but it does use a twist, so let me introduce it. First off, it would be a constraint and it would point to a subroutine, but there are multiple parameters involved: password1 and password2. Whenever that happens, you define the constraint like so:
...
'constraints' => {
'email' => 'email',
'password1' => {
'constraint' => "check_passwords",
'params' => [ qw( password1 password2 ) ],
},
},
...So what this is saying is to check password1, but instead of pointing to a regexp pattern, a built-in constraint or a subroutine, it's actually pointing to a more complex hashref. Within that hashref is constraint, which could be confusing, but it simply is the name of a subroutine that will be called. Also within the hashref is params, which is a list of the parameters to pass in as arguments to the subroutine. So then somewhere in your code, you'll have the check_passwords method:
sub check_passwords {
my ( $pw1, $pw2 ) = @_;
if ( $pw1 eq $pw2 ) {
return 1;
} else {
return 0;
}
}TODO
This is just an early release of this tutorial - we're using the release early & often mentality, so there's still a few things left to do. We want to address of of the more complicated aspects of dfv, like Filters, etc.
SEE ALSO
Data::FormValidator and the dfv mailing list: http://lists.sourceforge.net/lists/listinfo/cascade-dataform
Also, Jason Purdy will be presenting at ApacheCon 2005 (http://www.apachecon.com) on dfv. We'll release again afterwards to point to his papers (which are also being incorporated into this doc) and slides.
AUTHORS
Originally written by T. M. Brannon, <tbone@cpan.org>
William McKee, <william@knowmad.com> and Jason Purdy, <jason@purdy.info>
LICENSE
Copyright (C) 2004-2005 Jason Purdy, <jason@purdy.info> and William McKee, <william@knowmad.com>
This library is free software. You can modify and or distribute it under the same terms as Perl itself.