root/lang/perl/FormValidator-LazyWay/trunk/lib/FormValidator/LazyWay/JA.pod @ 35113

Revision 35113, 13.8 kB (checked in by vkgtaro, 4 years ago)

filter, fix についてドキュメント追記。

Line 
1=encoding utf-8
2
3=head1 NAME
4
5FormValidator::LazyWay - フォーム検証用モジュール
6
7=head1 SYNOPSIS
8
9    use strict;
10    use warnings;
11    use Data::Dumper;
12    use CGI;
13    use FormValidator::LazyWay;
14   
15    my $config = {
16        'setting' => {
17            'strict' => {
18                'email'    => { 'rule' => [ 'Email#email' ] },
19                'password' => {
20                    'rule' => [
21                        {   'String#length' => {
22                                'min' => '4',
23                                'max' => '12'
24                            }
25                        },
26                        'String#ascii'
27                    ]
28                }
29            }
30        },
31        'lang'   => 'ja',
32        'labels' => {
33            'ja' => {
34                'email'    => 'メールアドレス',
35                'password' => 'パスワード'
36            }
37        },
38        'rules' => [ 'Email', 'String' ]
39    };
40   
41    my $fv  = FormValidator::LazyWay->new(config => $config);
42    my $cgi = new CGI( { password => 'e' } );
43    my $res = $fv->check( $cgi, { required => [qw/email password/], } );
44   
45    if ( $res->has_error ) {
46        print Dumper $res->error_message;
47        # output 
48        #$VAR1 = {
49        #  'email' => 'メールアドレスが空です。',
50        #  'password' => 'パスワードには4文字以上12文字以下が使用できます。'
51        #};
52    }
53    else {
54   
55        # OK!
56        print Dumper $res->valid;
57    }
58   
59
60=head1 DESCRIPTION
61
62このモジュールはまだ開発段階ですので、仕様が変更される恐れがあります。
63
64フォーム検証用モジュールL<FormValidator::LazyWay>は各フォームごとではなく、アプリケーション全体で使用する目的で作成しております。
65フォームごとに検証ルールを設定するのではなく、フィールド名ごとに検証ルールを設定することにより、よりDRYなコードを書くことのお手伝いをします。
66
67また、検証用モジュールごとに、検証内容を設定することができます。その情報を元に、エラーメッセージを作成するので、
68エラーメッセージを考える手間も短縮できるようになっています。
69
70=head1 QUICK START
71
72簡単な問い合わせフォームを例を基に、使い方の説明をいたします。
73
74=head2 コンフィグ設定
75
76今回はYAMLで設定ファイルを作成しています。
77使用するのは、このデータをハッシュにしたデータですので、あなたの好きな方法をご利用下さい。
78
79rulesで指定されているのは、使用する検証用モジュール名です。
80詳細は L<FormValidator::LazyWay::Rule::Email> L<FormValidator::LazyWay::Rule::String> をご確認下さい。
81
82    rules :
83        - Email
84        - String
85    lang : ja
86    setting :
87        strict :
88            email :
89                rule :
90                    - Email#email
91            message :
92                rule :
93                    - String#length :
94                        min : 1
95                        max : 500
96            user_key :
97                rule :
98                    - String#length :
99                        min : 4
100                        max : 12
101                    - String#ascii
102    labels :
103        ja :
104            email    : メールアドレス
105            message  : お問い合わせ内容
106            user_key : ユーザID
107
108=head2 準備
109
110設定ファイルから取り出したデータを、newの引数として渡すだけです。これで準備完了です。
111
112    use FormValidator::LazyWay;
113    use YAML::Syck;
114    use FindBin;
115    use File::Spec;
116
117    my $conf_file = File::Spec->catfile( $FindBin::Bin, 'conf/inquery-sample.yml' );
118    my $config = LoadFile($conf_file);
119    my $fv = FormValidator::LazyWay->new( config => $config );
120
121=head2 検証フィールドの設定
122
123検証フィールドの設定をおこないます。そのフィールドが必須の場合は、required ,
124あってもなくても良い場合は、optional に設定します。
125
126    my $cgi = new CGI() ;
127
128    my $res = $fv->check( $cgi , {
129        required => [qw/email message/],
130        optional => [qw/user_key/],
131    });
132
133    # 検証がエラーだった場合
134    if( $res->has_error ) {
135        warn Dumper $res->error_message;
136    }
137    else {
138        # 検証がうまくいった場合
139        warn Dumper $res->valid;
140    }
141
142=head2 実行結果
143
144=over
145
146=item 正常なデータで試した際
147 
148    my $cgi = new CGI( { email => 'tomohiro.teranishi@gmail.com' , use_key => 'tomyhero' , message => 'うごきません' } ) ;
149
150$res->valid の中身が dump されます。
151
152    $VAR1 = {
153        'email' => 'tomohiro.teranishi@gmail.com',
154        'message' => 'うごきません'
155    };
156
157
158=item 必要なデータが足らない場合
159 
160    my $cgi = new CGI( { message => 'うごきません' } ) ;
161
162$res->error_message には以下のデータが格納されます。
163
164    $VAR1 = {
165        'email' => 'メールアドレスが空です。'
166    };
167
168=item フォーマットが間違ってる場合
169
170    my $cgi = new CGI( { email => 'email' , use_key => 'tom' , message => 'うごかないよ！'  } ) ;
171
172$res->error_message には以下のデータが格納されます。
173
174    $VAR1 = {
175        'email' => 'メールアドレスにはメールアドレスの書式が使用できます。'
176    };
177
178=back
179
180=head1 設定の説明
181
182=head2 rules
183
184使用する設定のモジュールを指定します。指定していない、検証ルールを実行しようとするとエラーになるので、ご注意ください。
185
186指定の際には、FormValidator::LazyWay::Rule:: の部分は省略できます。
187また、独自で作成した検証モジュールの場合は、頭に+をつけることで、指定することができます。
188
189 rules :
190    - String
191    - +OreOre::Rule
192
193=head2 lang
194
195デフォルトで使用する言語を設定します。値のデフォルトはenです。
196
197 lang : ja
198
199=head2 langs
200
201使用する言語をすべて指定します。複数の言語を使用するサイトの際に設定します。
202複数の言語を使用しない場合は、設定する必要はありません。
203
204 langs :
205    - ja
206    - en
207
208
209=head2 setting
210
211検証ルールなどを、フィールド名にマッピングさせます。
212    以下のような、フォーマットになります。
213
214 レベル :
215    フィールド名 :
216        設定名 :
217            設定名ごとに定義された設定
218
219=over
220
221=item レベル
222
223同じフィールド名で、違う検証モジュールを指定できるように、レベルという仕組みがあります。
224何も設定しなければ、strict という検証ルールが読み込まれます。
225
226例えばemailというフィールドがあった場合に、登録時のフォームでは strict レベルの検証ルールを、
227検索時にはlooseレベルの検証ルールを使用したい場合など、そうした際に使用することになります。
228
229 setting :
230    stcit :
231        email :
232            rule :
233                - Email#email
234    loose :
235        email :
236            rule :
237                - Email#much_alias
238 
239登録フォームでは、strict なので指定をする必要なく実行できます。
240
241    my $res = $fv->check( $cgi , { required => [qw/email/] } );
242
243検索フォームでは、loose を使用するので、level の設定を使って使用します。
244
245    my $res = $fv->check( $cgi , { required => [qw/email/] , level => { email => 'loose' }   } );
246
247また、特別にスペシャルレベルが二つあります。
248一つめは regex_map というスペシャルレベルです。
249このレベルを使用すると、正規表現をフィールド名に使用することができます。
250
251 setting :
252    regexp_map :
253        '_id$' :
254            rule :
255                - Number#integer
256    strict :
257        foo_id :
258            rule :
259                - Email#email
260       
261このようにセットすることにより、_idで終わるすべてのフィールドは、Number#integerの検証ルールが適応されます。
262ただし、他のレベルの設定の方が強い仕様になっており、strict で foo_idを設定した場合、そちら側を優先的に反映させます。
263
264二つめは merge というスペシャルレベルです。
265このレベルを使用すると、複数の項目をマージした結果を検証に使用することが出来るようになります。
266
267  merge:
268    date:
269      format: "%04d-%02d-%02d"
270      fields:
271        - year
272        - month
273        - day
274  strict:
275    date:
276      rule:
277        - DateTime#date
278
279このようにセットすることにより、year, month, day を format に従って入
280力内容をマージして date と言う項目を作ります。
281この date という項目にはその他の通常の項目と同じように検証することが出
282来ます。
283
284=item フィールド名
285
286フィールド名を指定します。
287
288=item 設定名
289
290現在 rule, filter, fix という設定名があり、この配下には各々のモジュールの設定を書くことができます。
291
292=over
293
294=item rule
295
296フィールドと、検証用モジュールのマッピングをする設定です。以下のように、配列で、検証用モジュールを複数指定することができます。
297また、検証用モジュールは、引数を設定することができます。 検証用モジュール名は、rules で指定したナマエと、関数名を # でつなぐことにより設定できます。
298
299 rule :
300    - String#length :
301        min : 4
302        max : 12
303    - String#ascii
304    - +OreOre#rule
305
306=item filter
307
308検証用モジュールにかける前に入力された内容を変化させることができる設定です。
309以下の例では utf8 で入力された内容を decode して String#length にかかります。
310String#length は入力された内容の長さを検証しますが、この場合だと日本語でも1文字を1文字として検証されます。
311（LazyWay 内部は flagged utf-8 で保たれるような設計になっています。
312　入力内容が flagged utf-8 であればこのフィルタは不要です。）
313
314  name :
315    rule :
316      - String#length:
317          min : 4
318          max : 12
319    filter :
320      - Encode#decode:
321          encoding: utf8
322
323=item fix
324
325検証が完了した後に入力された内容をオブジェクトなどに変化させます。
326以下の例では DateTime#date の検証を経て、入力された内容を DateTime オブジェクトにします。
327L<FormValidator::LazyWay::Result>オブジェクトの valid メソッドで取り出すときにはオブジェクトになっているはずです。
328（fix という名前は妥当？）
329
330  date:
331    rule:
332      - DateTime#date
333    fix:
334      - DateTime#format:
335          - '%Y-%m-%d'
336
337=back
338
339=back
340
341=head2 labels
342
343フィールド名の表示名を設定します。
344
345 labels :
346    email     : メールアドレス
347    user_name : ユーザ名
348    user_id   : ユーザーID
349
350=head2 messages
351
352検証モジュール自身に設定されている、メッセージに内容を上書きするのに使用できます。
353特に問題ない場合は、使用する必要はありません。言語ごとに指定することができ、
354rule_messageで、大枠のレイアウト、 rule で、各検証モジュールのメッセージを上書きすることができます。
355
356    messages :
357        ja :
358            rule_message : __field__には__rule__が使用できます。
359            rule :
360                Email#email  : メイルアドレス
361                String#length : $_[min]文字以上で、$_[max]文字以下
362
363
364=head1 Profile
365
366check()メソッドの二つ目の引数に入るデータを、profile と呼びます。
367
368=head2 required
369
370必須項目を指定します。ここで指定されたフィールド名が存在しない場合、missing エラーになります。
371
372 my $profile
373    = {
374        required => [qw/email name/],
375    }
376
377=head2 optional
378
379必須ではなく、あってもなくても良いフィールド名を指定します。
380
381 my $profile
382    = {
383        optional => [qw/zip/],
384    }
385
386=head2 defaults
387
388フィールド名が空欄だった場合、デフォルト値を設定いたします。requiredのチェックより先に、
389デフォルト値を設定しますので、defaultsを設定した場合、入力がなくても、必須条件を満たすことができます。
390
391 my $profile
392    = {
393        required => [qw/email name/],
394        defaults => {
395            email => 'tomohiro.teranishi@gmail.com',
396            name => 'Tomohiro',
397        },
398    }
399
400
401=head2 want_array
402
403一つのフィールドに対して、複数の値が送られてきた場合、１つ目以外を無視するのですが、この設定をした場合、
404複数のフィールドの値を取得することができます。また、配列の参照として取得することができます。
405
406 my $profile
407    = {
408        required => [qw/email name/],
409        optional => [qw/hobby/],
410        want_array => [qw/hobby/],
411    }
412
413=head2 lang
414
415言語設定を指定することができます。ここで指定する言語は、設定のlangsで指定されている必要があります。
416
417 my $profile
418    = {
419        required => [qw/email name/],
420        lang => 'ja',
421    }
422
423=head2 level
424
425検証レベルを変更したい場合に使用します。レベルとフィールド名とのマッピングは、設定にて定義している必要があります。
426
427 my $profile
428    = {
429        required => [qw/email name/],
430        level => {
431            email => 'loose',
432            name  => 'special',
433        }
434    }
435
436=head1 結果
437
438L<FormValidator::LazyWay::Result>オブジェクトを戻り値として取得することができます。そちらを参照してください。
439
440=head1 AUTHOR
441
442Tomohiro Teranishi <tomohiro.teranishi@gmail.com>
443
444=cut
445
Note: See TracBrowser for help on using the browser.