CGI::FormMagick::Validator

	Skill level: Developer
	Risk of inconsistencies with Koozali SME Server methodology, upgrades & functionality is high. One must be knowledgeable about how changes impact their Koozali SME Server. Significant risk of irreversible harm.

NAME

      CGI::FormMagick::Validator - validate data from FormMagick forms

In a root terminal you can do the command below if you want to display the up-to-date content

perldoc CGI::FormMagick::Validator

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:

CGI::FormMagick::Validator::Basic

CGI::FormMagick::Validator::Length

CGI::FormMagick::Validator::Network

CGI::FormMagick::Validator::Geography

CGI::FormMagick::Validator::Business

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_routine" is equivalent to "my_routine()".

You MUST put a comma or a space between routine names, eg "my_routine, my_other_routine" OR "my_routine my_other_routine".

You MUST put a comma between args to a routine, eg "my_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

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

AUTHOR

Kirrily "Skud" Robert <skud@infotrope.net>

More information about FormMagick may be found at http://sourceforge.net/projects/formmagick/