Debian Codegraph @

README

raw
1 NAME
2 FormValidator::Simple - validation with simple chains of constraints
3
4 SYNOPSIS
5 my $query = CGI->new;
6 $query->param( param1 => 'ABCD' );
7 $query->param( param2 => 12345 );
8 $query->param( mail1 => '[email protected]' );
9 $query->param( mail2 => '[email protected]' );
10 $query->param( year => 2005 );
11 $query->param( month => 11 );
12 $query->param( day => 27 );
13
14 my $result = FormValidator::Simple->check( $query => [
15 param1 => ['NOT_BLANK', 'ASCII', ['LENGTH', 2, 5]],
16 param2 => ['NOT_BLANK', 'INT' ],
17 mail1 => ['NOT_BLANK', 'EMAIL_LOOSE'],
18 mail2 => ['NOT_BLANK', 'EMAIL_LOOSE'],
19 { mails => ['mail1', 'mail2' ] } => ['DUPLICATION'],
20 { date => ['year', 'month', 'day'] } => ['DATE'],
21 ] );
22
23 if ( $result->has_error ) {
24 my $tt = Template->new({ INCLUDE_PATH => './tmpl' });
25 $tt->process('template.html', { result => $result });
26 }
27
28 template example
29
30 [% IF result.has_error %]
31 <p>Found Input Error</p>
32 <ul>
33
34 [% IF result.missing('param1') %]
35 <li>param1 is blank.</li>
36 [% END %]
37
38 [% IF result.invalid('param1') %]
39 <li>param1 is invalid.</li>
40 [% END %]
41
42 [% IF result.invalid('param1', 'ASCII') %]
43 <li>param1 needs ascii code.</li>
44 [% END %]
45
46 [% IF result.invalid('param1', 'LENGTH') %]
47 <li>input into param1 with characters that's length should be between two and five. </li>
48 [% END %]
49
50 </ul>
51 [% END %]
52
53 example2
54
55 [% IF result.has_error %]
56 <ul>
57 [% FOREACH key IN result.error %]
58 [% FOREACH type IN result.error(key) %]
59 <li>invalid: [% key %] - [% type %]</li>
60 [% END %]
61 [% END %]
62 </ul>
63 [% END %]
64
65 DESCRIPTION
66 This module provides you a sweet way of form data validation with simple
67 constraints chains. You can write constraints on single line for each
68 input data.
69
70 This idea is based on Sledge::Plugin::Validator, and most of validation
71 code is borrowed from this plugin.
72
73 (Sledge is a MVC web application framework: http://sl.edge.jp [Japanese]
74 )
75
76 The result object this module returns behaves like
77 Data::FormValidator::Results.
78
79 HOW TO SET PROFILE
80 FormValidator::Simple->check( $q => [
81 #profile
82 ] );
83
84 Use 'check' method.
85
86 A hash reference includes input data, or an object of some class that
87 has a method named 'param', for example CGI, is needed as first
88 argument.
89
90 And set profile as array reference into second argument. Profile
91 consists of some pairs of input data and constraints.
92
93 my $q = CGI->new;
94 $q->param( param1 => 'hoge' );
95
96 FormValidator::Simple->check( $q => [
97 param1 => [ ['NOT_BLANK'], ['LENGTH', 4, 10] ],
98 ] );
99
100 In this case, param1 is the name of a form element. and the array ref "[
101 ['NOT_BLANK']... ]" is a constraints chain.
102
103 Write constraints chain as arrayref, and you can set some constraints
104 into it. In the last example, two constraints 'NOT_BLANK', and 'LENGTH'
105 are set. Each constraints is should be set as arrayref, but in case the
106 constraint has no argument, it can be written as scalar text.
107
108 FormValidator::Simple->check( $q => [
109 param1 => [ 'NOT_BLANK', ['LENGTH', 4, 10] ],
110 ] );
111
112 Now, in this sample 'NOT_BLANK' constraint is not an arrayref, but
113 'LENGTH' isn't. Because 'LENGTH' has two arguments, 4 and 10.
114
115 MULTIPLE DATA VALIDATION
116 When you want to check about multiple input data, do like this.
117
118 my $q = CGI->new;
119 $q->param( mail1 => '[email protected]' );
120 $q->param( mail2 => '[email protected]' );
121
122 my $result = FormValidator::Simple->check( $q => [
123 { mails => ['mail1', 'mail2'] } => [ 'DUPLICATION' ],
124 ] )
125
126 [% IF result.invalid('mails') %]
127 <p>mail1 and mail2 aren't same.</p>
128 [% END %]
129
130 and here's an another example.
131
132 my $q = CGI->new;
133 $q->param( year => 2005 );
134 $q->param( month => 12 );
135 $q->param( day => 27 );
136
137 my $result = FormValidator::Simple->check( $q => [
138 { date => ['year', 'month', 'day'] } => [ 'DATE' ],
139 ] );
140
141 [% IF result.invalid('date') %]
142 <p>Set correct date.</p>
143 [% END %]
144
145 FLEXIBLE VALIDATION
146 my $valid = FormValidator::Simple->new();
147
148 $valid->check( $q => [
149 param1 => [qw/NOT_BLANK ASCII/, [qw/LENGTH 4 10/] ],
150 ] );
151
152 $valid->check( $q => [
153 param2 => [qw/NOT_BLANK/],
154 ] );
155
156 my $results = $valid->results;
157
158 if ( found some error... ) {
159 $results->set_invalid('param3' => 'MY_ERROR');
160 }
161
162 template example
163
164 [% IF results.invalid('param1') %]
165 ...
166 [% END %]
167 [% IF results.invalid('param2') %]
168 ...
169 [% END %]
170 [% IF results.invalid('param3', 'MY_ERROR') %]
171 ...
172 [% END %]
173
174 HOW TO SET OPTIONS
175 Option setting is needed by some validation, especially in plugins.
176
177 You can set them in two ways.
178
179 FormValidator::Simple->set_option(
180 dbic_base_class => 'MyProj::Model::DBIC',
181 charset => 'euc',
182 );
183
184 or
185
186 $valid = FormValidator::Simple->new(
187 dbic_base_class => 'MyProj::Model::DBIC',
188 charset => 'euc',
189 );
190
191 $valid->check(...)
192
193 VALIDATION COMMANDS
194 You can use follow variety validations. and each validations can be used
195 as negative validation with 'NOT_' prefix.
196
197 FormValidator::Simple->check( $q => [
198 param1 => [ 'INT', ['LENGTH', 4, 10] ],
199 param2 => [ 'NOT_INT', ['NOT_LENGTH', 4, 10] ],
200 ] );
201
202 SP check if the data has space or not.
203
204 INT check if the data is integer or not.
205
206 UINT
207 unsigined integer check. for example, if -1234 is input, the
208 validation judges it invalid.
209
210 DECIMAL
211 $q->param( 'num1' => '123.45678' );
212
213 my $result = FormValidator::Simple->check( $q => [
214 num1 => [ ['DECIMAL', 3, 5] ],
215 ] );
216
217 each numbers (3,5) mean maximum digits before/after '.'
218
219 ASCII
220 check is the data consists of only ascii code.
221
222 LENGTH
223 check the length of the data.
224
225 my $result = FormValidator::Simple->check( $q => [
226 param1 => [ ['LENGTH', 4] ],
227 ] );
228
229 check if the length of the data is 4 or not.
230
231 my $result = FormValidator::Simple->check( $q => [
232 param1 => [ ['LENGTH', 4, 10] ],
233 ] );
234
235 when you set two arguments, it checks if the length of data is in
236 the range between 4 and 10.
237
238 HTTP_URL
239 verify it is a http(s)-url
240
241 my $result = FormValidator::Simple->check( $q => [
242 param1 => [ 'HTTP_URL' ],
243 ] );
244
245 SELECTED_AT_LEAST
246 verify the quantity of selected parameters is counted over allowed
247 minimum.
248
249 <input type="checkbox" name="hobby" value="music" /> Music
250 <input type="checkbox" name="hobby" value="movie" /> Movie
251 <input type="checkbox" name="hobby" value="game" /> Game
252
253 my $result = FormValidator::Simple->check( $q => [
254 hobby => ['NOT_BLANK', ['SELECTED_AT_LEAST', 2] ],
255 ] );
256
257 REGEX
258 check with regular expression.
259
260 my $result = FormValidator::Simple->check( $q => [
261 param1 => [ ['REGEX', qr/^hoge$/ ] ],
262 ] );
263
264 DUPLICATION
265 check if the two data are same or not.
266
267 my $result = FormValidator::Simple->check( $q => [
268 { duplication_check => ['param1', 'param2'] } => [ 'DUPLICATION' ],
269 ] );
270
271 EMAIL
272 check with Email::Valid.
273
274 EMAIL_MX
275 check with Email::Valid, including mx check.
276
277 EMAIL_LOOSE
278 check with Email::Valid::Loose.
279
280 EMAIL_LOOSE_MX
281 check with Email::Valid::Loose, including mx check.
282
283 DATE
284 check with Date::Calc
285
286 my $result = FormValidator::Simple->check( $q => [
287 { date => [qw/year month day/] } => [ 'DATE' ]
288 ] );
289
290 TIME
291 check with Date::Calc
292
293 my $result = FormValidator::Simple->check( $q => [
294 { time => [qw/hour min sec/] } => ['TIME'],
295 ] );
296
297 DATETIME
298 check with Date::Calc
299
300 my $result = FormValidator::Simple->check( $q => [
301 { datetime => [qw/year month day hour min sec/] } => ['DATETIME']
302 ] );
303
304 DATETIME_STRPTIME
305 check with DateTime::Format::Strptime.
306
307 my $q = CGI->new;
308 $q->param( datetime => '2006-04-26T19:09:21+0900' );
309
310 my $result = FormValidator::Simple->check( $q => [
311 datetime => [ [ 'DATETIME_STRPTIME', '%Y-%m-%dT%T%z' ] ],
312 ] );
313
314 DATETIME_FORMAT
315 check with DateTime::Format::***. for example,
316 DateTime::Format::HTTP, DateTime::Format::Mail,
317 DateTime::Format::MySQL and etc.
318
319 my $q = CGI->new;
320 $q->param( datetime => '2004-04-26 19:09:21' );
321
322 my $result = FormValidator::Simple->check( $q => [
323 datetime => [ [qw/DATETIME_FORMAT MySQL/] ],
324 ] );
325
326 GREATER_THAN
327 numeric comparison
328
329 my $result = FormValidator::Simple->check( $q => [
330 age => [ ['GREATER_THAN', 25] ],
331 ] );
332
333 LESS_THAN
334 numeric comparison
335
336 my $result = FormValidator::Simple->check( $q => [
337 age => [ ['LESS_THAN', 25] ],
338 ] );
339
340 EQUAL_TO
341 numeric comparison
342
343 my $result = FormValidator::Simple->check( $q => [
344 age => [ ['EQUAL_TO', 25] ],
345 ] );
346
347 BETWEEN
348 numeric comparison
349
350 my $result = FormValidator::Simple->check( $q => [
351 age => [ ['BETWEEN', 20, 25] ],
352 ] );
353
354 ANY check if there is not blank data in multiple data.
355
356 my $result = FormValidator::Simple->check( $q => [
357 { some_data => [qw/param1 param2 param3/] } => ['ANY']
358 ] );
359
360 IN_ARRAY
361 check if the food ordered is in menu
362
363 my $result = FormValidator::Simple->check( $q => [
364 food => [ ['IN_ARRAY', qw/noodle soba spaghetti/] ],
365 ] };
366
367 HOW TO LOAD PLUGINS
368 use FormValidator::Simple qw/Japanese CreditCard/;
369
370 FormValidator::Simple::Plugin::Japanese,
371 FormValidator::Simple::Plugin::CreditCard are loaded.
372
373 or use 'load_plugin' method.
374
375 use FormValidator::Simple;
376 FormValidator::Simple->load_plugin('FormValidator::Simple::Plugin::CreditCard');
377
378 MESSAGE HANDLING
379 You can custom your own message with key and type.
380
381 [% IF result.has_error %]
382 [% FOREACH key IN result.error %]
383 [% FOREACH type IN result.error(key) %]
384 <p>error message:[% type %] - [% key %]</p>
385 [% END %]
386 [% END %]
387 [% END %]
388
389 And you can also set messages configuration before. You can prepare
390 configuration as hash reference.
391
392 FormValidator::Simple->set_messages( {
393 action1 => {
394 name => {
395 NOT_BLANK => 'input name!',
396 LENGTH => 'input name (length should be between 0 and 10)!',
397 },
398 email => {
399 DEFAULT => 'input correct email address!',
400 },
401 },
402 } );
403
404 or a YAML file.
405
406 # messages.yml
407 DEFAULT:
408 name:
409 DEFAULT: name is invalid!
410 action1:
411 name:
412 NOT_BLANK: input name!
413 LENGTH: input name(length should be between 0 and 10)!
414 email:
415 DEFAULT: input correct email address!
416 action2:
417 name:
418 DEFAULT: ...
419
420 # in your perl-script, set the file's path.
421 FormValidator::Simple->set_messages('messages.yml');
422
423 DEFAULT is a special type. If it can't find setting for indicated
424 validation-type, it uses message set for DEFAULT.
425
426 after setting, execute check(),
427
428 my $result = FormValidator::Simple->check( $q => [
429 name => [qw/NOT_BLANK/, [qw/LENGTH 0 10/] ],
430 email => [qw/NOT_BLANK EMAIL_LOOSE/, [qw/LENGTH 0 20/] ],
431 ] );
432
433 # matching result and messages for indicated action.
434 my $messages = $result->messages('action1');
435
436 foreach my $message ( @$messages ) {
437 print $message, "\n";
438 }
439
440 When it can't find indicated action, name, and type, it searches proper
441 message from DEFAULT action. If in template file,
442
443 [% IF result.has_error %]
444 [% FOREACH msg IN result.messages('action1') %]
445 <p>[% msg %]</p>
446 [% END %]
447 [% END %]
448
449 you can set each message format.
450
451 FormValidator::Simple->set_message_format('<p>%s</p>');
452 my $result = FormValidator::Simple->check( $q => [
453 ...profile
454 ] );
455
456 [% IF result.has_error %]
457 [% result.messages('action1').join("\n") %]
458 [% END %]
459
460 RESULT HANDLING
461 See FormValidator::Simple::Results
462
463 SEE ALSO
464 Data::FormValidator
465
466 http://sl.edge.jp/ (Japanese)
467
468 http://sourceforge.jp/projects/sledge
469
470 AUTHOR
471 Lyo Kato <[email protected]>
472
473 COPYRIGHT AND LICENSE
474 This library is free software. You can redistribute it and/or modify it
475 under the same terms as perl itself.
476