NAME
CGI::FormMagick::Validator - validate data from FormMagick forms
SYNOPSIS
use CGI::FormMagick;
DESCRIPTION
This module provides some common validation routines. Validation routines return the string "OK" if they succeed, or a descriptive message if they fail.
Validation routines provided:
See the following for information on categories of validation we've provided:
Using more than one validation routine per field
You can use multiple validation routines like this:
value="foo" validation="my_routine, my_other_routine"However, there are some requirements on formatting to make sure that FormMagick can parse what you've given it.
Parens are optional on subroutines with no args.
my_routineis equivalent tomy_routine().You MUST put a comma then a space between routine names, eg
my_routine, my_other_routineNOTmy_routine,my_other_routine.You MUST NOT put a space between args to a routine, eg
my_routine(1,2,3)NOTmy_routine(1, 2, 3).
This will be fixed to be more flexible in a later release.
Making your own routines
FormMagick's validation routines may be overridden and others may be added on a per-application basis. To do this, simply define a subroutine in your CGI script that works in a similar way to the routines provided by CGI::FormMagick::Validator and use its name in the validation attribute in your XML.
The arguments passed to the validation routine are the value of the field (to be validated) and any subsequent arguments given in the validation attribute. For example:
value="foo" validation="my_routine"
===> my_routine(foo)
value="foo" validation="my_routine(42)"
===> my_routine(foo, 42)The latter type of validation routine is useful for routines like minlength() and lengthrange() which come with CGI::FormMagick::Validator.
Here's an example routine that you might write:
sub my_grep {
my $data = shift;
my @list = @_;
if (grep /$data/, @list) {
return "OK"
} else {
return "That's not one of: @list"
}
}SECURITY CONSIDERATIONS AND METHODS FOR MANUAL VALIDATION
If you use page post-event or pre-event routines which perform code which is in any way based on user input, your application may be susceptible to a security exploit.
The exploit can occur as follows:
Imagine you have an application with three pages. Page 1 has fields A, B and C. Page 2 has fields D, E and F. Page 3 has fields G, H and I.
The user fills in page 1 and the data FOR THAT PAGE is validated before they're allowed to move on to page 2. When they fill in page 2, the data FOR THAT PAGE is validated before they can move on. Ditto for page 3.
If the user saves a copy of page 2 and edits it to contain an extra field, "A", with an invalid value, then submits that page back to FormMagick, the added field "A" will NOT be validated.
This is because FormMagick relies on the XML description of the page to know what fields to validate. Only the current page's fields are validated, until the very end when all the fields are revalidated one last time before the form post-event is run. This means that we don't suffer the load of validating everything every time, and it will work fine for most applications.
However, if you need to run page post-event or pre-event routines that rely on previous pages' data, you should validate it manually in your post-event or pre-event routine. The following methods are used internally by FormMagick for its validation, but may also be useful to developers.
Note: this stuff may be buggy. Please let us know how you go with it.
$fm->validate_field($fieldname | $fieldref)
This routine allows you to validate a specific field by hand if you need to. It returns an arrayref containing a list of error messages if validation fails, or the string "OK" on success.
Examples of use:
This is how you'd probably call it from your script:
if ($fm->validate_field("credit_card_number") eq "OK")) { }FormMagick uses references to a field object, internally:
if ($fm->validate_field($fieldref) eq "OK")) { }(that's so that FormMagick can easily loop through the fields in a page; you shouldn't need to do that)
If you want to do something with the error messages returned:
my $errors = $fm->validate_field($field);
if (ref $errors) {
foreach my $e (@$errors) {
do_something();
}
} else {
# it's OK
}get_validation_attribute($field)
A tiny little routine which, given a field hashref (as seen in validate_field() will give you the value of the validation attribute from that field.
This was split out to make it easy to have a subclass add validation routines by overriding this function.
$fm->validate_page($number | $name)
This routine allows you to validate a single page worth of fields. It can accept either a page number (counting from zero) or a page name.
This routine returns a hash of errors, with the keys being the names of fields which have errors and the values being the error messages. An empty hash means no errors.
The routine will return undef if it can't figure out what page you want.
Examples:
my %errors = $fm->validate_page(3);
my %errors = $fm->validate_page("CreditCardDetails");
if (%errors) { ... }$fm->validate_all()
This routine goes through all the pages that have been visited (using FormMagick's built-in page stack to keep track of which these are) and runs validate_page() on each of them.
Returns a hash of all errors, and set $self->{errors} when done.
DEVELOPER METHODS
The following methods are probably not of interest to anyone except developers of FormMagick
parse_validation_routine ($validation_routine_name)
parse the name of a validation routine into its name and its parameters. returns a 2-element list, $validator and $arg.
do_validation_routine ($self, $validator, $fielddata, $args)
Runs validation functions with arguments. Looks first for a user routine, then for a builtin, then if it can't find either it just kinda shrugs and says "OK".
Returns "OK" if validation is successful, or the error message returned by the validation routine otherwise.
$fm->call_user_validation_routine($routine, $data, $args)
Calls the user's validation routine, in the calling package (usually main).
$fm->call_fm_validation($routine, $data, $args)
Calls a builtin validation routine in CGI::FormMagick::Validator.
list_error_messages()
prints a list of error messages caused by validation failures
SEE ALSO
The main perldoc for CGI::FormMagick
AUTHOR
Kirrily "Skud" Robert <skud@infotrope.net>
More information about FormMagick may be found at http://sourceforge.net/projects/formmagick/