NAME

Data::FormValidator::Tutorial - Data::FormValidator tutorial

TUTORIAL

D::FV does two types of validation: existence and readability. Existence means that a value exists that should exist. Readability means that a value that exists is intelligible. For example, if a field labeled website has value of s)d--13, then it exists, but it is not readable.

Specification of data validation is done via a hashref which is known as an input profile. Here are the keys which tell D::FV something. In parenthesis is a description of what type of key it is.

• required (existence)

  This field basically does something like this:

  @missing = 
     grep { not defined $formdata{$_} } keys %{$profile{required}} ;
  
  @possibly_valid = 
     grep { defined $formdata{$_} } keys %{$profile{required}} ;

  The fields are only possibly valid. They have to move through a readability test before they can be considered truly valid.

• optional (existence)

• required_regexp (existence)

  This basically says that all fields which match the regular expression are required.

  @missing = 
     grep { not defined $formdata{$_} or $_ =~ /$profile{required_regexp} } 
        keys %formdata;
  
  @possibly_valid = 
     grep { not defined $formdata{$_} and $_ =~ /$profile{required_regexp} } 
        keys %formdata;

• optional_regexp (existence)

  This does the same except says that the fields are optional. Note that a side effect of finding such an optional field will result in a check of the dependencies and dependency_groups parts of the input profile.

• dependencies (existence)

  Only relates to optional fields. Since there are 2 types of ways that optional fields can show up, it has two ways of dealing with them, both shown in this example:

   dependencies   => {
      "cc_no" => [ qw( cc_type cc_exp ) ],
      "pay_type" => {
  	check => [ qw( check_no ) ],
      }
   },

  In the first case, when the cc_no is bound, then the fields cc_type and cc_exp must also be bound. The second one is used when a field is bound but the resulting dependencies vary based on what is bound. This will happen if you have a pull-down menu for pay_type and based on which one is chosen certain dependencies follow.

• dependency_groups (existence)

  This is used to say: "if neither field is filled, then fine, but if either field is filled, then the other must be filled."

  Speaking in terms far too haughty: the dependencies field dictates a uni-directional (hierarchical and asymmetric) dependency between an optional field and the fields which will be required upon fill in. The dependency_groups field dictates a bidirectional (flat and symmetric) dependency between the listed fields.

• defaults (existence - sort of)

  This is a hash reference which contains defaults which should be substituted if the user hasn't filled the fields. So I guess it deals more with non-existence rather than existence. Key is field name and value is default value which will be returned in the list of valid fields.

• filters (neither)

  This is a reference to an array of filters that will be applied to ALL optional or required fields. This can be the name of a built-in filter (trim,digit,etc) or an anonymous subroutine which should take one parameter, the field value and return the (possibly) modified value.

• field_filters (neither)

  Same as above, but it allows selective application of filters to particular fields.

• constraints (readability)

  See manual for details.

• constraint_regexp_map (readability)

  See manual for details.

Given the two tests that this module does, it makes sense that the return data would belong to one of 4 classes:

• exists and is readable

  Returned in $valid position of return array (position 0)

• exists but is not readable

  Returned in $invalid position of return array (position 1)

• should exist but doesn't

  Returned in $missing position of return array (position 1)

  Fields which should exist were specified either as required or as one of the dependencies which kicked in as a result of a bound optional field.

• shouldn't exist but does

  This means that an unrecognized field was bound but no specification of it as required, optional, or dependent was made.

  These are returned in the $unknown array position.

GOTCHAS (provided by William McKee)

• If you use CGI.pm to handle accessing the form data, there's no easy way to send $q to the FormValidator since it wants a hash. There is a little known function Vars() that will do this conversion for you.

  my %fdat = $q->Vars;

• The validated (and untainted??) data comes back in as a hashref. I may be dense but it took me a bit to realize that the first value is a HASHREF, not an arrayref like all the others.

CALL FOR PARTICIPATION (also from William)

Although the module docs are good and my tutorial provides some theoretical background about creating profiles, there is not a clearcut example of actually using this module to check and untaint form data which is then used in a "real" program. That would be a helpful addition to the tutorial.

AUTHOR

T. M. Brannon, <tbone@cpan.org>