NAME

CGI::Application::ValidateRM - Help validate CGI::Application run modes using Data::FormValidator

SYNOPSIS

 use CGI::Application::ValidateRM;

 my ($valid_href, $err_page) 
	= $self->validate_rm('form_display' ,$dfv_profile_href );
  return $err_page if $err_page; 

DESCRIPTION

CGI::Application::ValidateRM helps to validate web forms when using the CGI::Application framework and the Data::FormValidator module.

validate_rm

This CGI::Application method takes two required and one optional argument, as follows:

1. Name of the run mode to return with errors.

The errors will be passed in as a hash reference, which can then be handed to a templating system for display. The hash will look like this:

{
	err__	  => 1,
	err_email => '* Invalid',
	err_phone => '* Missing',
}

The first field is just say "We have some errors". You can check for this in your template system to display a general message at the top of the page. The remaining fields will have "err_" prepended to name of the offending field.

HTML::Template users may want to pass die_on_bad_params=>0 to the HTML::Template constructor to prevent the preference of the "err_" tokens from triggering an error when the errors are not being displayed.

By default the text will be styled bold and red. This default can be overridden using the parameterse in the third argument.

2. A hash reference to a Data::FormValidator profile.

You can also put a subroutine call here, as long as the subroutine returns the right hash reference.

3. A hash reference of options to override the default text and formatting.

The defaults are as follows:

{
  error_fmt => 
   '<span style="color:red;font-weight:bold"><span id="vrm_errors">%s</span></span>',
  missing   => 'Missing',
  invalid   => 'Invalid',
}

You can see that the error format first styles the text red and bold, which can be overridden with a style sheet by applying a style to vrm_errors.

To alleviate the need for passing in your own preferences here everytime, the function will check the contents of the vrm CGI::Application parameter, If it contains a hash reference with appropriate keys, it will be tried first.

EXAMPLE

In a CGI::Application module:

# This is the run mode that will be validated. Notice that it accepts
# some errors to be passed in, and on to the template system.
sub form_display {
	my $self = shift;
	my $errs = shift;

	my $t = $self->load_tmpl('page.html');

	$t->param($errs) if $errs;
	return $t->output;
}

sub form_process {
	my $self = shift;

	use CGI::Application::ValidateRM;
	my ($valid_href, $err_page) = $self->validate_rm('form_display', _form_profile() );
	return $err_page if $err_page; 

	my $t = $self->load_tmpl('success.html');
	return $t->output;
}

sub _form_profile {
	return {
		required => 'email',
	};
}

In page.html:

<!-- tmpl_if err__ -->
	<h3>Some fields below are missing or invalid</h3>
<!-- /tmpl_if -->
<form>
	<input type="text" name="email"> <!-- tmpl_var err_email -->
</form>

KNOWN BUGS

Currently Data::FormValidator's ability to apply multiple constraints to a single field is not supported.

There's probably a better way to handle the internationalization of the strings.

SEE ALSO

CGI::Application, Data::FormValidator, perl(1)

AUTHOR

Mark Stosberg <mark@stosberg.com>

LICENSE

Copyright (C) 2003 Mark Stosberg <mark@stosberg.com>

This module is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version,

or

b) the "Artistic License"

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

For a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA