1CGI::Ex::Validate(3) User Contributed Perl Documentation CGI::Ex::Validate(3)
2
6 CGI::Ex::Validate - The "Just Right" form validator with javascript in
7 parallel
8
10 use CGI::Ex::Validate;
11 # THE SHORT
13 my $errobj = CGI::Ex::Validate->new->validate($form, $val_hash);
15 # THE LONG
17 my $form = CGI->new;
19 # OR #
20 my $form = CGI::Ex->new; # OR CGI::Ex->get_form;
21 # OR #
22 my $form = {key1 => 'val1', key2 => 'val2'};
23 # simplest
26 my $val_hash = {
27 'group order' => [qw(username email email2)],
28 username => {
29 required => 1,
30 max_len => 30,
31 field => 'username',
32 # field is optional in this case - will use key name
33 },
34 email => {
35 required => 1,
36 max_len => 100,
37 type => 'email',
38 },
39 email2 => {
40 equals => 'email',
41 },
42 };
43 # ordered
45 my $val_hash = {
46 'group order' => [{
47 field => 'username', # field is not optional in this case
48 required => 1,
49 max_len => 30,
50 }, {
51 field => 'email',
52 required => 1,
53 max_len => 100,
54 }, {
55 field => 'email2',
56 equals => 'email',
57 }],
58 };
59 my $vob = CGI::Ex::Validate->new;
62 my $errobj = $vob->validate($form, $val_hash);
63 if ($errobj) {
64 # get errors back in any of several useful ways
65 my $error_heading = $errobj->as_string; # OR "$errobj";
66 my $error_list = $errobj->as_array; # ordered list of what when wrong
67 my $error_hash = $errobj->as_hash; # hash of arrayrefs of errors
68 } else {
69 # the form passed validation
70 }
71 my $js_uri_path = '/js/'; # static or dynamic URI path to find CGI/Ex/validate.js
74 my $form_name = "the_form"; # name of the form to attach javascript to
75 # generate javascript to validate an existing form
77 my $javascript = $vob->generate_js($val_hash, {
78 form_name => $form_name,
79 js_uri_path => $js_uri_path,
80 });
81 # OR let Validate create the form and javascript for you
83 my $form = $vob->generate_form($val_hash, {
84 form_name => $form_name, # will use a random name if not passed
85 js_uri_path => $js_uri_path,
86 });
87
89 CGI::Ex::Validate is one of many validation modules. It aims to have
90 all of the basic data validation functions, avoid adding all of the
91 millions of possible types, while still giving the capability for the
92 developer to add their own types for the rare cases that the basic ones
93 don't suffice. Generally anything more than basic validation probably
94 needs programmatic or data based validation.
95 CGI::Ex::Validate also has full support for providing the same
97 validation in javascript. It provides methods for attaching the
98 javascript to existing forms. This ability is tightly integrated into
99 CGI::Ex::App, but it should be easy to add validation just about
100 anywhere using any type of controller.
101 As opposed to other kitchen sync validation modules, CGI::Ex::Validate
103 offers the simple types of validation, and makes it easy to add your
104 own custom types. Asside from custom and custom_js, all validation
105 markup is declarative.
106
108 "new"
109 Used to instantiate the object. Arguments are either a hash, or
110 hashref, or nothing at all. Keys of the hash become the keys of
111 the object.
112 "get_validation"
114 Uses CGI::Ex::Conf::conf_read to read in the hash. conf_read will
115 all passing a filename or YAML string or a hashref.
116 "get_validation_keys"
118 Takes the validation hashref returned from get_validation. Will
119 return all of the possible keys found in the validation hashref.
120 This can be used to check to see if extra items have been passed to
121 validate. If a second argument contains a form hash is passed,
122 get_validation_keys will only return the keys of groups that were
123 validated.
124 my $key_hashref = $self->get_validation_keys($val_hash);
126 The keys of the hash are the names of the fields.
128 "validate"
130 Arguments are a form hashref or cgi object, a validation hashref or
131 filename, and an optional what_was_validated arrayref (discussed
132 further later on). If a CGI object is passed, CGI::Ex::get_form
133 will be called on that object to turn it into a hashref. If a
134 filename is given for the validation, get_validation will be called
135 on that filename. If the what_was_validated_arrayref is passed -
136 it will be populated (pushed) with the field hashes that were
137 actually validated (anything that was skipped because of
138 validate_if will not be in the array).
139 If the form passes validation, validate will return undef. If it
141 fails validation, it will return a CGI::Ex::Validate::Error object.
142 If the 'raise_error' option has been set, validate will die with a
143 CGI::Ex::validate::Error object as the value.
144 my $err_obj = $self->validate($form, $val_hash);
146 # OR #
148 $self->{raise_error} = 1; # can also be listed in the val_hash
150 eval { $self->validate($form, $val_hash) };
151 if ($@) { my $err_obj = $@; }
152 "generate_form"
154 Takes a validation hash, and additional arguments and generates an
155 HTML form suitable for inclusion in a web based application.
156 my $html = $self->generate_form($val_hash, {
158 form_name => 'my_form',
159 js_uri_path => '/cgi-bin/js', # will be used by generate_js
160 });
161 "generate_js"
163 Works with CGI::Ex::JSONDump.
164 Takes a validation hash, a form name, and an optional javascript
166 uri path and returns Javascript that can be embedded on a page and
167 will perform identical validations as the server side. The form
168 name must be the name of the form that the validation will act upon
169 - the name is used to register an onsubmit function. The
170 javascript uri path is used to embed the locations of javascript
171 source files included with the CGI::Ex distribution.
172 The javascript uri path is highly dependent upon the server
174 configuration and therefore must be configured manually. It may be
175 passed to generate_js, or it may be specified in $JS_URI_PATH.
176 There is one file included with this module that is needed -
177 CGI/Ex/validate.js. When generating the js code, generate_js will
178 look in $JS_URI_PATH_VALIDATE. If this is not set, generate_js
179 will use "$JS_URI_PATH/CGI/Ex/validate.js".
180 my $js = $self->generate_js($val_hash, 'my_form', "/cgi-bin/js")
182 # OR
183 my $js = $self->generate_js($val_hash, {
184 form_name => 'my_form',
185 js_uri_path => '/cgi-bin/js',
186 });
187 # would generate something like the following...
189 <script src="/cgi-bin/js/CGI/Ex/validate.js"></script>
191 ... more js follows ...
192 $CGI::Ex::Validate::JS_URI_PATH = "/stock/js";
194 $self->generate_js($val_hash, 'my_form')
195 # would generate something like the following...
197 <script src="/stock/js/CGI/Ex/validate.js"></script>
199 ... more js follows ...
200 Referencing validate.js can be done in any of several ways. It can
202 be copied to or symlinked to a fixed location in the server's html
203 directory. It can also be printed out by a cgi. The method
204 "->print_js" has been provided in CGI::Ex for printing js files
205 found in the perl hierarchy. See CGI::Ex for more details. The
206 $JS_URI_PATH of "/cgi-bin/js" could contain the following:
207 #!/usr/bin/perl -w
209 use strict;
211 use CGI::Ex;
212 # path_info should contain something like /CGI/Ex/validate.js
214 my $info = $ENV{PATH_INFO} || '';
215 die "Invalid path" if $info !~ m|^(/\w+)+.js$|;
216 $info =~ s|^/+||;
217 CGI::Ex->new->print_js($info);
219 exit;
220 The print_js method in CGI::Ex is designed to cache the javascript
222 in the browser.
223 "->cgix"
225 Returns a CGI::Ex object. Used internally if a CGI object is
226 passed to validate rather than a straight form hash.
227
229 The validation hash may be passed as a hashref or as a filename, or as
230 a YAML document string. Experience has shown it to be better
231 programming to pass in a hashref. If the validation "hash" is a
232 filename or a YAML string, it will be translated into a hash using
233 CGI::Ex::Conf.
234 Keys matching the regex m/^group \s+ (\w+)$/x such as "group onevent"
236 are reserved and are counted as GROUP OPTIONS. Other keys (if any,
237 should be field names that need validation).
238 If the GROUP OPTION 'group validate_if' is set, the validation will
240 only be validated if the conditions of the validate_if are met. If
241 'group validate_if' is not specified, then the validation will proceed.
242 See the validate_if VALIDATION type for more information.
243 Each of the items listed in the validation will be validated. The
245 validation order is determined the following ways:
246 Specify 'group order' arrayref with hashrefs.
248 # order will be (username, password, 'm/\w+_foo/', somethingelse)
249 {
250 'group title' => "User Information",
251 'group order' => [
252 {field => 'username', required => 1},
253 {field => 'password', required => 1},
254 {field => 'm/\w+_foo/', required => 1},
255 ],
256 somethingelse => {required => 1},
257 }
258 Specify 'group order' arrayref with field key names.
260 # order will be (username, password, 'm/\w+_foo/', somethingelse)
261 {
262 'group title' => "User Information",
263 'group order' => [qw(username password), 'm/\w+_foo/'],
264 username => {required => 1},
265 password => {required => 1},
266 'm/\w+_foo/' => {required => 1},
267 somethingelse => {required => 1},
268 }
269 Do nothing - use sorted order.
271 # order will be ('m/\w+_foo/', password, somethingelse, username)
272 {
273 'group title' => "User Information",
274 username => {required => 1},
275 password => {required => 1},
276 'm/\w+_foo/' => {required => 1},
277 somethingelse => {required => 1},
278 }
279 Optionally the 'group order' may contain the word 'OR' as a special
281 keyword. If the item preceding 'OR' fails validation the item after
282 'OR' will be tested instead. If the item preceding 'OR' passes
283 validation the item after 'OR' will not be tested.
284 'group order' => [qw(zip OR postalcode state OR region)],
286 At this time, only "group onevent" submit works with this option.
288 Using OR is not needed if testing for one or more values -- instead you
289 should use min_in_set or max_in_set (OR is still useful for other
290 cases).
291 'zip' => {
293 max_in_set: '1 of zip, postalcode',
294 },
295 'state' => {
296 max_in_set: '1 of state, region',
297 },
298 Each individual field validation hashref will operate on the field
300 contained in the 'field' key. This key may also be a regular
301 expression in the form of 'm/somepattern/'. If a regular expression is
302 used, all keys matching that pattern will be validated. If the field
303 key is not specified, the key from the top level hash will be used.
304 foobar => { # "foobar" is not used as key because field is specified
306 field => 'real_key_name',
307 required => 1,
308 },
309 real_key_name2 => {
310 required => 1,
311 },
312 'm/\w+/' => { # this will apply to all fields matching this regex
313 required => 1,
314 },
315 Each of the individual field validation hashrefs should contain the
317 types listed in VALIDATION TYPES.
318
320 This section lists the available validation types. Multiple instances
321 of the same type may be used for some validation types by adding a
322 number to the type (ie match, match2, match232). Multiple instances
323 are validated in sorted order. Types that allow multiple values are:
324 compare, custom, custom_js, equals, match, required_if, sql,
325 validate_if, and replace (replace is a MODIFICATION TYPE).
326 "compare"
328 Allows for custom comparisons. Available types are >, <, >=, <=,
329 !=, ==, gt, lt, ge, le, ne, and eq. Comparisons also work in the
330 JS.
331 {
333 field => 'my_number',
334 match => 'm/^\d+$/',
335 compare1 => '> 100',
336 compare2 => '< 255',
337 compare3 => '!= 150',
338 }
339 "custom"
341 Custom value - not available in JS. Allows for extra programming
342 types. May be either a boolean value predetermined before calling
343 validate, or may be a coderef that will be called during
344 validation. If coderef is called, it will be passed the field
345 name, the form value for that name, and a reference to the field
346 validation hash. If the custom type returns false the element
347 fails validation and an error is added.
348 {
350 field => 'username',
351 custom => sub {
352 my ($key, $val, $field_val_hash, $checktype, $form) = @_;
353 # do something here
354 return 0;
355 },
356 custom_error => '$name was not valid',
357 }
358 Often it is desirable to specify a different message depending upon
360 the code passed to custom. To use a custom error message simply
361 die with the error message. Note that you will want to add a
362 newline or else perl will add the line number and file for you -
363 CGI::Ex::Validate will remove the trailing newline.
364 {
366 field => 'username',
367 custom => sub {
368 my ($key, $val) = @_;
369 die "Custom error message 1\n" if $val eq '1';
370 die "Custom error message 2\n" if $val eq '2';
371 return 0;
372 },
373 custom_error => '$name default custom error message',
374 }
375 "custom_js"
377 Custom value - only available in JS. Allows for extra programming
378 types. May be a javascript function (if fully declared in
379 javascript), a string containing a javascript function (that will
380 be eval'ed into a real function), a boolean value pre-determined
381 before calling validate, or may be section of javascript that will
382 be eval'ed (the last value of the eval'ed javascript will determine
383 if validation passed). A false response indicates the value did
384 not pass validation. A true response indicates that it did. See
385 the samples/validate_js_0_tests.html page for a sample of usages.
386 {
388 field => 'date',
389 required => 1,
390 match => 'm|^\d\d\d\d/\d\d/\d\d$|',
391 match_error => 'Please enter date in YYYY/MM/DD format',
392 custom_js => "function (args) {
393 var t = new Date();
394 var y = t.getYear()+1900;
395 var m = t.getMonth() + 1;
396 var d = t.getDate();
397 if (m < 10) m = '0'+m;
398 if (d < 10) d = '0'+d;
399 (args.value > ''+y+'/'+m+'/'+d) ? 1 : 0;
400 }",
401 custom_js_error => 'The date was not greater than today.',
402 }
403 Often it is desirable to specify a different message depending upon
405 the function passed to custom_js. To use a custom error message
406 simply throw the error message.
407 {
409 field => 'username',
410 custom_js => 'function (args) {
411 if (args.value == 1) throw "Custom error message 1";
412 if (args.value == 2) throw "Custom error message 2";
413 return 0;
414 }',
415 custom_js_error => '$name default custom error message',
416 }
417 "enum"
419 Allows for checking whether an item matches a set of options. In
420 perl the value may be passed as an arrayref. In the conf or in
421 perl the value may be passed of the options joined with ||.
422 {
424 field => 'password_type',
425 enum => 'plaintext||crypt||md5', # OR enum => [qw(plaintext crypt md5)],
426 }
427 "equals"
429 Allows for comparison of two form elements. Can have an optional
430 !.
431 {
433 field => 'password',
434 equals => 'password_verify',
435 },
436 {
437 field => 'domain1',
438 equals => '!domain2', # make sure the fields are not the same
439 }
440 "had_error"
442 Typically used by a validate_if. Allows for checking if this item
443 has had an error.
444 {
446 field => 'alt_password',
447 validate_if => {field => 'password', had_error => 1},
448 }
449 This is basically the opposite of was_valid.
451 "match"
453 Allows for regular expression comparison. Multiple matches may be
454 concatenated with ||. Available in JS.
455 {
457 field => 'my_ip',
458 match => 'm/^\d{1,3}(\.\d{1,3})3$/',
459 match_2 => '!m/^0\./ || !m/^192\./',
460 }
461 "max_in_set" and "min_in_set"
463 Somewhat like min_values and max_values except that you specify the
464 fields that participate in the count. Also - entries that are not
465 defined or do not have length are not counted. An optional "of"
466 can be placed after the number for human readability.
467 min_in_set => "2 of foo bar baz",
469 # two of the fields foo, bar or baz must be set
470 # same as
471 min_in_set => "2 foo bar baz",
472 # same as
473 min_in_set => "2 OF foo bar baz",
474 validate_if => {field => 'whatever', max_in_set => '0 of whatever'},
476 # only run validation if there were zero occurrences of whatever
477 "max_len and min_len"
479 Allows for check on the length of fields
480 {
482 field => 'site',
483 min_len => 4,
484 max_len => 100,
485 }
486 "max_values" and "min_values"
488 Allows for specifying the maximum number of form elements passed.
489 max_values defaults to 1 (You must explicitly set it higher to
490 allow more than one item by any given name).
491 "required"
493 Requires the form field to have some value. If the field is not
494 present, no other checks will be run and an error will be given.
495 It has been common for code to try "required =" 0> which
497 essentially has no effect - instead use "validate_if ="
498 'fieldname', required => 1>. This results in the fieldname only
499 being required if the fieldname is present.
500 "required_if"
502 Requires the form field if the condition is satisfied. The
503 conditions available are the same as for validate_if. This is
504 somewhat the same as saying:
505 validate_if => 'some_condition',
507 required => 1
508 required_if => 'some_condition',
510 It is different in that other checks will run - whereas validate_if
512 skips all validation if some condition is not met.
513 If a regex is used for the field name, the required_if field will
515 have any match patterns swapped in.
516 {
518 field => 'm/^(\w+)_pass/',
519 required_if => '$1_user',
520 }
521 This example would require the "foobar_pass" field to be set if the
523 "foobar_user" field was passed.
524 "sql"
526 SQL query based - not available in JS. The database handle will be
527 looked for in the value $self->{dbhs}->{foo} if sql_db_type is set
528 to 'foo', otherwise it will default to $self->{dbh}. If
529 $self->{dbhs}->{foo} or $self->{dbh} is a coderef - they will be
530 called and should return a dbh.
531 {
533 field => 'username',
534 sql => 'SELECT COUNT(*) FROM users WHERE username = ?',
535 sql_error_if => 1, # default is 1 - set to 0 to negate result
536 # sql_db_type => 'foo', # will look for a dbh under $self->{dbhs}->{foo}
537 }
538 "type"
540 Allows for more strict type checking. Currently supported types
541 include CC (credit card), EMAIL, DOMAIN, IP, URL, INT, UINT, and
542 NUM. Other types will be added upon request provided we can add a
543 perl and a javascript version (extra types often aren't necessary
544 as the custom and custom_js options give arbitrary checking). If a
545 type checks fails - other compare, custom, or length checks will
546 not be ran.
547 {
549 field => 'credit_card',
550 type => 'CC',
551 }
552 "CC"
554 Simple Luhn-10 check. Note that spaces and dashes are left in
555 place.
556 "EMAIL"
558 Very basic check to see if the value looks like an address.
559 The local part must only contain [\w.~!\#\$%\^&*\-=+?] and the
560 domain must be a domain or ip. If you want full fledged RFC
561 compliant checking consider something like:
562 {
564 field => 'email',
565 custom => sub {
566 my ($key, $val, $fv, $type, $form) = @_;
567 require Mail::Address;
568 my @a = Mail::Address->parse($val);
569 die "Invalid address\n" if @a != 1;
570 return $form->{$key} = $a[0]->address;
571 },
572 }
573 "DOMAIN"
575 Checks for a valid domain name - does no lookup of the domain.
576 For that use a custom sub.
577 "IP"
579 Basic IPv4 check.
580 "URL"
582 Basic check that string matches something resembling an http or
583 https url.
584 "INT"
586 Checks for an integer between -2147483648 and 2147483648
587 "UINT"
589 Checks for an unsigned integer between 0 and 4294967295.
590 "NUM"
592 Checks for something that looks like a number. Scientic
593 notation is not allowed. No range enforced.
594 "validate_if"
596 If validate_if is specified, the field will only be validated if
597 the conditions are met. Works in JS.
598 validate_if => {field => 'name', required => 1, max_len => 30}
600 # Will only validate if the field "name" is present and is less than 30 chars.
601 validate_if => 'name',
603 # SAME as
604 validate_if => {field => 'name', required => 1},
605 validate_if => '! name',
607 # SAME as
608 validate_if => {field => 'name', max_in_set => '0 of name'},
609 validate_if => 'name was_valid',
611 # SAME as
612 validate_if => {field => 'name', was_valid => 1},
613 validate_if => {field => 'country', compare => "eq US"},
615 # only if country's value is equal to US
616 validate_if => {field => 'country', compare => "ne US"},
618 # if country doesn't equal US
619 validate_if => {field => 'password', match => 'm/^md5\([a-z0-9]{20}\)$/'},
621 # if password looks like md5(12345678901234567890)
622 {
624 field => 'm/^(\w+)_pass/',
625 validate_if => '$1_user',
626 required => 1,
627 },
628 {
629 field => 'm/^(\w+)_pass2/',
630 validate_if => '$1_pass',
631 equals => '$1_pass',
632 required => 1,
633 }
634 # will validate foo_pass only if foo_user was present.
636 The validate_if may also contain an arrayref of validation items.
638 So that multiple checks can be run. They will be run in order.
639 validate_if will return true only if all options returned true.
640 validate_if => ['email', 'phone', 'fax']
642 Optionally, if validate_if is an arrayref, it may contain the word
644 'OR' as a special keyword. If the item preceding 'OR' fails
645 validation the item after 'OR' will be tested instead. If the item
646 preceding 'OR' passes validation the item after 'OR' will not be
647 tested.
648 validate_if => [qw(zip OR postalcode)],
650 "was_valid"
652 Typically used by a validate_if. Allows for checking if this item
653 has successfully been validated.
654 {
656 field => 'password2',
657 validate_if => {field => 'password', was_valid => 1},
658 }
659 This is basically the opposite of had_error.
661
663 "field"
664 Specify which field to work on. Key may be a regex in the form
665 'm/\w+_user/'. This key is required in a hashref passed to 'group
666 order'. It can optionally be used with other types to specify a
667 different form element to operate on. On errors, if a non-default
668 error is found, $field will be swapped with the value found in
669 field.
670 The field name may also be a regular expression in the form of
672 'm/somepattern/'. If a regular expression is used, all keys
673 matching that pattern will be validated.
674 "name"
676 Name to use for errors. If a name is not specified, default errors
677 will use "The field $field" as the name. If a non-default error is
678 found, $name will be swapped with this name.
679 "delegate_error"
681 This option allows for any errors generated on a field to delegate
682 to a different field. If the field name was a regex, any patterns
683 will be swapped into the delegate_error value. This option is
684 generally only useful with the as_hash method of the error object
685 (for inline errors).
686 {
688 field => 'zip',
689 match => 'm/^\d{5}/',
690 },
691 {
692 field => 'zip_plus4',
693 match => 'm/^\d{4}/',
694 delegate_error => 'zip',
695 },
696 {
697 field => 'm/^(id_[\d+])_user$/',
698 delegate_error => '$1',
699 },
700 "exclude_js"
702 This allows the cgi to do checking while keeping the checks from
703 being run in JavaScript
704 {
706 field => 'cgi_var',
707 required => 1,
708 exclude_js => 1,
709 }
710 "exclude_cgi"
712 This allows the js to do checking while keeping the checks from
713 being run in the cgi
714 {
716 field => 'js_var',
717 required => 1,
718 exclude_cgi => 1,
719 }
720 "vif_disable"
722 Only functions in javascript. Will mark set the form element to
723 disabled if validate_if fails. It will mark it as enabled if
724 validate_if is successful. This item should normally only be used
725 when onevent includes "change" or "blur".
726
728 The following types will modify the form value before it is processed.
729 They work in both the perl and in javascript as well. The javascript
730 version changes the actual value in the form on appropriate form types.
731 "do_not_trim"
733 By default, validate will trim leading and trailing whitespace from
734 submitted values. Set do_not_trim to 1 to allow it to not trim.
735 {field => 'foo', do_not_trim => 1}
737 "trim_control_chars"
739 Off by default. If set to true, removes characters in the \x00 to
740 \x31 range (Tabs are translated to a single space).
741 {field => 'foo', trim_control_chars => 1}
743 "replace"
745 Pass a swap pattern to change the actual value of the form. Any
746 perl regex can be passed but it is suggested that javascript
747 compatible regexes are used to make generate_js possible.
748 {field => 'foo', replace => 's/(\d{3})(\d{3})(\d{3})/($1) $2-$3/'}
750 "default"
752 Set item to default value if there is no existing value (undefined
753 or zero length string).
754 {field => 'country', default => 'EN'}
756 "to_upper_case" and "to_lower_case"
758 Do what they say they do.
759 "untaint"
761 Requires that the validated field has been also checked with an
762 enum, equals, match, compare, custom, or type check. If the field
763 has been checked and there are no errors - the field is
764 "untainted."
765 This is for use in conjunction with perl's -T switch.
767 "clear_on_error"
769 Clears the form field should a validation error occur. Only
770 supported on the Javascript side (no affect on the server side).
771
773 Failed validation results in an error an error object created via the
774 new_error method. The default error class is CGI::Ex::Validate::Error.
775 The error object has several methods for determining what the errors
777 were.
778 "as_array"
780 Returns an array or arrayref (depending on scalar context) of
781 errors that occurred in the order that they occurred. Individual
782 groups may have a heading and the entire validation will have a
783 heading (the default heading can be changed via the
784 'as_array_title' group option). Each error that occurred is a
785 separate item and are pre-pended with 'as_array_prefix' (which is a
786 group option - default is ' '). The as_array_ options may also be
787 set via a hashref passed to as_array. as_array_title defaults to
788 'Please correct the following items:'.
789 # if this returns the following
791 my $array = $err_obj->as_array;
792 # $array looks like
793 # ['Please correct the following items:', ' error1', ' error2']
794 # then this would return the following
796 my $array = $err_obj->as_array({
797 as_array_prefix => ' - ',
798 as_array_title => 'Something went wrong:',
799 });
800 # $array looks like
801 # ['Something went wrong:', ' - error1', ' - error2']
802 "as_string"
804 Returns values of as_array joined with a newline. This method is
805 used as the stringification for the error object. Values of
806 as_array are joined with 'as_string_join' which defaults to "\n".
807 If 'as_string_header' is set, it will be pre-pended onto the error
808 string. If 'as_string_footer' is set, it will be appended onto the
809 error string.
810 # if this returns the following
812 my $string = $err_obj->as_string;
813 # $string looks like
814 # "Please correct the following items:\n error1\n error2"
815 # then this would return the following
817 my $string = $err_obj->as_string({
818 as_array_prefix => ' - ',
819 as_array_title => 'Something went wrong:',
820 as_string_join => '<br />',
821 as_string_header => '<span class="error">',
822 as_string_footer => '</span>',
823 });
824 # $string looks like
825 # '<span class="error">Something went wrong:<br /> - error1<br /> - error2</span>'
826 "as_hash"
828 Returns a hash or hashref (depending on scalar context) of errors
829 that occurred. Each key is the field name of the form that failed
830 validation with 'as_hash_suffix' added on as a suffix.
831 as_hash_suffix is available as a group option and may also be
832 passed in via a hashref as the only argument to as_hash. The
833 default value is '_error'. The values of the hash are arrayrefs of
834 errors that occurred to that form element.
835 By default as_hash will return the values of the hash as arrayrefs
837 (a list of the errors that occurred to that key). It is possible
838 to also return the values as strings. Three options are available
839 for formatting: 'as_hash_header' which will be pre-pended onto the
840 error string, 'as_hash_footer' which will be appended, and
841 'as_hash_join' which will be used to join the arrayref. The only
842 argument required to force the stringification is 'as_hash_join'.
843 # if this returns the following
845 my $hash = $err_obj->as_hash;
846 # $hash looks like
847 # {key1_error => ['error1', 'error2']}
848 # then this would return the following
850 my $hash = $err_obj->as_hash({
851 as_hash_suffix => '_foo',
852 as_hash_join => '<br />',
853 as_hash_header => '<span class="error">'
854 as_hash_footer => '</span>'
855 });
856 # $hash looks like
857 # {key1_foo => '<span class="error">error1<br />error2</span>'}
858
860 Any key in a validation hash matching the pattern m/^group \s+ (\w+)$/x
861 is considered a group option (the reason that either group or general
862 may be used is that CGI::Ex::Validate used to have the concept of
863 validation groups - these were not commonly used so support has been
864 removed as of the 2.10 release). (the old name of 'general' vs 'group'
865 is still supported but deprecated)
866 "title"
868 Used as a group section heading when as_array or as_string is
869 called by the error object.
870 'group title' => 'Title of errors',
872 "order"
874 Order in which to validate key/value pairs of group.
875 'group order' => [qw(user pass email OR phone)],
877 # OR
879 'group order' => [{
881 field => 'field1',
882 required => 1,
883 }, {
884 field => 'field2',
885 required => 1,
886 }],
887 "fields"
889 Alias for 'group order'.
890 "validate_if"
892 If specified - the entire hashref will only be validated if the
893 "if" conditions are met.
894 'group validate_if => {field => 'email', required => 1},
896 This group would only validate all fields if the email field was
898 present.
899 "raise_error"
901 If raise_error is true, any call to validate that fails validation
902 will die with an error object as the value.
903 "no_extra_fields"
905 If no_extra_fields is true, validate will add errors for any field
906 found in form that does not have a field_val hashref in the
907 validation hash. Default is false. If no_extra_fields is set to
908 'used', it will check for any keys that were not in a group that
909 was validated.
910 An important exception to this is that field_val hashrefs or field
912 names listed in a validate_if or required_if statement will not be
913 included. You must have an explicit entry for each key.
914 "\w+_error"
916 These items allow for an override of the default errors.
917 'group required_error' => '$name is really required',
919 'group max_len_error' => '$name must be shorter than $value characters',
920 # OR #
921 my $self = CGI::Ex::Validate->new({
922 max_len_error => '$name must be shorter than $value characters',
923 });
924 "as_array_title"
926 Used as the section title for all errors that occur, when as_array
927 or as_string is called by the error object.
928 "as_array_prefix"
930 Used as prefix to individual errors that occur, when as_array or
931 as_string is called by the error object. Each individual error
932 will be prefixed with this string. Headings will not be prefixed.
933 Default is ' '.
934 "as_string_join"
936 When as_string is called, the values from as_array will be joined
937 with as_string_join. Default value is "\n".
938 "as_string_header"
940 If set, will be pre-pended onto the string when as_string is
941 called.
942 "as_string_footer"
944 If set, will be pre-pended onto the string when as_string is
945 called.
946 "as_hash_suffix"
948 Added on to key names during the call to as_hash. Default is
949 '_error'.
950 "as_hash_join"
952 By default, as_hash will return hashref values that are errors
953 joined with the default as_hash_join value of <br />. It can also
954 return values that are arrayrefs of the errors. This can be done
955 by setting as_hash_join to a non-true value (for example '')
956 "as_hash_header"
958 If as_hash_join has been set to a true value, as_hash_header may be
959 set to a string that will be pre-pended on to the error string.
960 "as_hash_footer"
962 If as_hash_join has been set to a true value, as_hash_footer may be
963 set to a string that will be postpended on to the error string.
964 "onevent"
966 Defaults to {submit => 1}. This controls when the javascript
967 validation will take place. May be passed any or all or load,
968 submit, change, or blur. Multiple events may be passed in the
969 hash.
970 'group onevent' => {submit => 1, change => 1}',
972 A comma separated string of types may also be passed:
974 'group onevent' => 'submit,change,blur,load',
976 Currently, change and blur will not work for dynamically matched
978 field names such as 'm/\w+/'. Support will be added.
979 "set_hook"
981 Defaults document.validate_set_hook which defaults to nothing. If
982 "group set_hook" or document.validate_set_hook are set to a
983 function, they will be passed the key name of a form element that
984 had a validation error and the error that will be set. If a true
985 value is returned, then validate will not also the inline error.
986 If no value or false is returned (default) the validate will
987 continue setting the inline error. This gives full control over
988 setting inline errors. samples/validate_js_2_onchange.html has a
989 good example of using these hooks.
990 'group set_hook' => "function (args) {
992 alert("Setting error to field "+args.key);
993 }",
994 The args parameter includes key, value, val_hash, and form.
996 The document.validate_set_hook option is probably the better option
998 to use, as it helps to separate display functionality out into your
999 html templates rather than storing too much html logic in your CGI.
1000 "clear_hook"
1002 Similar to set_hook, but called when inline error is cleared. Its
1003 corresponding default is document.validate_clear_hook. The clear
1004 hook is also sampled in samples/validate_js_2_onchange.html
1005 'group clear_hook' => "function (args) {
1007 alert("Clear error on field "+args.key);
1008 }",
1009 The args parameter includes key, val_hash, form, and was_valid.
1011 "no_inline"
1013 If set to true, the javascript validation will not attempt to
1014 generate inline errors when the only "group onevent" type is
1015 "submit". Default is true. Inline errors are independent of
1016 confirm and alert errors.
1017 'group no_inline' => 1,
1019 "no_confirm"
1021 If set to true, the javascript validation will try to use an alert
1022 instead of a confirm to inform the user of errors when one of the
1023 "group onevent" types is "submit". Alert and confirm are
1024 independent or inline errors. Default is false.
1025 'group no_confirm' => 1,
1027 "no_alert"
1029 If set to true, the javascript validation will not show an alert
1030 box when errors occur. Default is false. This option only comes
1031 into play if no_confirm is also set. This option is only in effect
1032 if "group onevent" includes "submit". This option is independent
1033 of inline errors. Although it is possible to turn off all errors
1034 by setting no_inline, no_confirm, and no_alert all to 1, it is
1035 suggested that at least one of the error reporting facilities is
1036 left on.
1037 'group no_alert' => 1,
1039
1041 CGI::Ex::Validate provides for having duplicate validation on the
1042 client side as on the server side. Errors can be shown in any
1043 combination of inline and confirm, inline and alert, inline only,
1044 confirm only, alert only, and none. These combinations are controlled
1045 by the group options no_inline, no_confirm, and no_alert. Javascript
1046 validation can be generated for a page using the "->generate_js" method
1047 of CGI::Ex::Validate.
1048 (Note: It is also possible to store the validation inline with the html
1050 as YAML and have it read in using the HTML conf handler - but this
1051 feature has been deprecated - see the included html samples for how to
1052 do this).
1053 Generate JS will create something similar to the following (based on
1055 your validation):
1056 <script src="/cgi-bin/js/CGI/Ex/validate.js"></script>
1058 <script>
1059 document.validation = {
1060 'group no_confirm': 1,
1061 'group no_alert': 1,
1062 'group onevent': 'change,blur,submit',
1063 'group order': ['username', 'password'],
1064 username: {
1065 required: 1,
1066 max_len: 20
1067 },
1068 password: {
1069 required: 1,
1070 max_len: 30
1071 }
1072 };
1073 if (document.check_form) document.check_form('my_form_name');
1074 </script>
1075 If inline errors are enabled (default), each error that occurs will
1077 attempt to find an html element with its name as the id. For example,
1078 if the field "username" failed validation and created a
1079 "username_error", the javascript would set the html of <span
1080 id="username_error"></span> to the error message.
1081 It is suggested to use something like the following so that you can
1083 have inline javascript validation as well as report validation errors
1084 from the server side as well.
1085 <span class=error id=password_error>[% password_error %]</span><br>
1087 If the javascript fails for some reason, the form should still be able
1089 to submit as normal (fail gracefully).
1090 Additionally, there are two hooks that are called when ever an inline
1092 error is set or cleared. The following hooks are used in
1093 samples/validate_js_2_onchange.html to highlight the row and set an
1094 icon.
1095 document.validate_set_hook = function (args) {
1097 document.getElementById(args.key+'_img').innerHTML
1098 = '<span style="font-weight:bold;color:red">!</span>';
1099 document.getElementById(args.key+'_row').style.background
1100 = '#ffdddd';
1101 };
1102 document.validate_clear_hook = function (args) {
1104 if (args.was_valid) {
1105 document.getElementById(args.key+'_img').innerHTML
1106 = '<span style="font-weight:bold;color:green">+</span>';
1107 document.getElementById(args.key+'_row').style.background
1108 = '#ddffdd';
1109 } else {
1110 document.getElementById(args.key+'_img').innerHTML = '';
1111 document.getElementById(args.key+'_row').style.background = '#fff';
1112 }
1113 };
1114 If you have jquery that looks like:
1116 document.validate_set_hook = function (args) {
1118 $('#'+args.key+'_img').html('<span style="font-weight:bold;color:red">!</span>');
1119 $('#'+args.key+'_row').css('backgroundColor', '#ffdddd');
1120 };
1121 document.validate_clear_hook = function (args) {
1123 if (args.was_valid) {
1124 $('#'+args.key+'_img').html('<span style="font-weight:bold;color:green">+</span>');
1125 $('#'+args.key+'_row').css('backgroundColor', '#ddffdd');
1126 } else {
1127 $('#'+args.key+'_img').html('');
1128 $('#'+args.key+'_row').css('backgroundColor', '#fff');
1129 }
1130 };
1131 These hooks can also be set as "group clear_hook" and "group set_hook"
1133 which are defined further above.
1134 If the confirm option is used ("group onevent" includes submit and
1136 "group no_confirm" is false), the errors will be displayed to the
1137 user. If they choose OK they will be able to try and fix the errors.
1138 If they choose cancel, the form will submit anyway and will rely on
1139 the server to do the validation. This is for fail safety to make sure
1140 that if the javascript didn't validate correctly, the user can still
1141 submit the data.
1142
1144 This module may be distributed under the same terms as Perl itself.
1145
1147 Paul Seamons <perl at seamons dot com>
1148perl v5.30.1 2020-01-29 CGI::Ex::Validate(3)