1CGI::Application::PlugiUns:e:rVaCloindtartiebRuMt(e3d)PCeGrIl::DAopcpulmiecnattaitoino:n:Plugin::ValidateRM(3)
2
3
4

NAME

6       CGI::Application::Plugin::ValidateRM - Help validate CGI::Application
7       run modes using Data::FormValidator
8

SYNOPSIS

10        use CGI::Application::Plugin::ValidateRM;
11
12        my  $results = $self->check_rm('form_display','_form_profile') || return $self->check_rm_error_page;
13
14
15        # Optionally, you can pass additional options to HTML::FillInForm->fill()
16        my $results = $self->check_rm('form_display','_form_profile', { fill_password => 0 })
17               || return $self->check_rm_error_page;
18

DESCRIPTION

20       CGI::Application::Plugin::ValidateRM helps to validate web forms when
21       using the CGI::Application framework and the Data::FormValidator
22       module.
23
24   check_rm()
25       Validates a form displayed in a run mode with a "Data::FormValidator"
26       profile, returning the results and possibly an a version of the form
27       page with errors marked on the page.
28
29       In scalar context, it returns simply the Data::FormValidator::Results
30       object which conveniently evaluates to false in a boolean context if
31       there were any missing or invalide fields. This is the recommended
32       calling convention.
33
34       In list context, it returns the results object followed by the error
35       page, if any.  This was the previous recommended syntax, and was used
36       like this:
37
38        my ($results,$err_page) = $self->check_rm('form_display','_form_profile');
39        return $err_page if $err_page;
40
41       The inputs are as follows:
42
43       Return run mode
44           This run mode will be used to generate an error page, with the form
45           re-filled (using HTML::FillInForm) and error messages in the form.
46           This page will be returned as a second output parameter.
47
48           The errors will be passed in as a hash reference, which can then be
49           handed to a templating system for display. Following the above
50           example, the form_display() routine might look like:
51
52            sub form_display {
53               my $self = shift;
54               my $errs = shift;                             # <-- prepared for form reloading
55               my $t = $self->load_tmpl('form_display.html');
56               $t->param($errs) if $errs;                    # <-- Also necessary.
57               # ...
58
59            }
60
61           The fields should be prepared using Data::FormValidator's built-in
62           support for returning error messages as a hash reference.  See the
63           documentation for "msgs" in the Data::FormValidator::Results
64           documentation.
65
66           Returning the errors with a prefix, such as "err_" is recommended.
67           Using "any_errors" is also recommended to make it easy to display a
68           general "we have some errors" message.
69
70           HTML::Template users may want to pass "die_on_bad_params=>0" to the
71           HTML::Template constructor to prevent the presence of the "err_"
72           tokens from triggering an error when the errors are not being
73           displayed.
74
75       Data::FormValidator profile
76           This can either be provided as a hash reference, or as the name of
77           a CGI::Application method that will return such a hash reference.
78
79       HTML::FillInForm options (optional)
80           If desired, you can pass additional options to the HTML::FillInForm
81           fill() method through a hash reference.  See an example above.
82
83       Additional Options
84
85       To control things even more, you can set parameters in your
86       CGI::Application object itself.
87
88       dfv_defaults
89           The value of the 'dfv_defaults' param is optionally used to pass
90           defaults to the Data::FormValidator new() constructor.
91
92             $self->param(dfv_defaults => { filters => ['trim'] })
93
94           By setting this to a hash reference of defaults in your
95           "cgiapp_init" routine in your own super-class, you could make it
96           easy to share some default settings for Data::FormValidator across
97           several forms. Of course, you could also set parameter through an
98           instance script via the PARAMS key.
99
100           Here's an example that I've used:
101
102            sub cgiapp_init {
103                my $self = shift;
104
105                # Set some defaults for DFV unless they already exist.
106                $self->param('dfv_defaults') ||
107                    $self->param('dfv_defaults', {
108                            missing_optional_valid => 1,
109                            filters => 'trim',
110                            msgs => {
111                                any_errors => 'err__',
112                                prefix     => 'err_',
113                                invalid    => 'Invalid',
114                                missing    => 'Missing',
115                                format => '<span class="dfv-errors">%s</span>',
116                            },
117                        });
118            }
119
120           Now all my applications that inherit from a super class with this
121           "cgiapp_init()" routine and have these defaults, so I don't have to
122           add them to every profile.
123
124       dfv_fif_class
125           By default this plugin uses HTML::FillInForm to fill in the forms
126           on the error pages with the given values. This option let's you
127           change that so it uses an HTML::FillInForm compatible class (like a
128           subclass) to do the same work.
129
130               $self->param(dfv_fif_class => 'HTML::FillInForm::SuperDuper');
131
132       dfv_fif_defaults
133           The value of the 'dfv_fif_defaults' param is optionally used to
134           pass defaults to the HTML::FillInForm "fill()" method.
135
136               $self->param(dfv_fif_defaults => {ignore_fields => ['rm']})
137
138           By setting this to a hash reference of defaults in your
139           "cgiapp_init" routine in your own super-class, you could make it
140           easy to share some default settings for HTML::FillInForm across
141           several forms. Of course, you could also set parameter through an
142           instance script via the PARAMS key.
143
144   CGI::Application::Plugin::Forward support
145       Experimental support has been added for
146       CGI::Application::Plugin::Forward, which keeps the current run mode up
147       to date. This would be useful if you were automatically generating a
148       template name based on the run mode name, and you wanted this to work
149       with the form run mode used with ::ValidateRM.
150
151       If we detect that ::Forward is loaded, we will set the current run mode
152       name to be accurate while the error page is being generated, and then
153       set it back to the previous value afterwards. There is a caveat: This
154       currently only works when the run name name is the same as the
155       subroutine name for the form page.  If they differ, the current run
156       mode name inside of the form page will be inaccurate. If this is a
157       problem for you, get in touch to discuss a solution.
158
159   check_rm_error_page()
160       After check_rm() is called this accessor method can be used to retrieve
161       the error page described in the check_rm() docs above. The method has
162       an alias named "dfv_error_page()" if you find that more intuitive.
163
164   dfv_results()
165        $self->dfv_results;
166
167       After "check_rm()" or "validate_rm()" has been called, the DFV results
168       object can also be accessed through this method. I expect this to be
169       most useful to other plugin authors.
170
171   validate_rm()
172       Works like "check_rm" above, but returns the old style $valid hash
173       reference instead of the results object. It's no longer recommended,
174       but still supported.
175

EXAMPLE

177       In a CGI::Application module:
178
179        # This is the run mode that will be validated. Notice that it accepts
180        # some errors to be passed in, and on to the template system.
181        sub form_display {
182               my $self = shift;
183               my $errs = shift;
184
185               my $t = $self->load_tmpl('page.html');
186
187               $t->param($errs) if $errs;
188               return $t->output;
189        }
190
191        sub form_process {
192               my $self = shift;
193
194               use CGI::Application::Plugin::ValidateRM (qw/check_rm/);
195               my ($results, $err_page) = $self->check_rm('form_display','_form_profile');
196               return $err_page if $err_page;
197
198               #..  do something with DFV $results object now
199
200               my $t = $self->load_tmpl('success.html');
201               return $t->output;
202
203        }
204
205        sub _form_profile {
206               return {
207                       required => 'email',
208                       msgs => {
209                               any_errors => 'some_errors',
210                               prefix => 'err_',
211                       },
212               };
213        }
214
215       In page.html:
216
217        <!-- tmpl_if some_errors -->
218               <h3>Some fields below are missing or invalid</h3>
219        <!-- /tmpl_if -->
220        <form>
221               <input type="text" name="email"> <!-- tmpl_var err_email -->
222        </form>
223

SEE ALSO

225       CGI::Application, Data::FormValidator, HTML::FillInForm, perl(1)
226

AUTHOR

228       Mark Stosberg <mark@summersault.com>
229

MAILING LIST

231       If you have any questions, comments, bug reports or feature
232       suggestions, post them to the support mailing list! This the
233       Data::FormValidator list.  To join the mailing list, visit
234       <http://lists.sourceforge.net/lists/listinfo/cascade-dataform>
235

LICENSE

237       Copyright (C) 2003-2005 Mark Stosberg <mark@summersault.com>
238
239       This module is free software; you can redistribute it and/or modify it
240       under the terms of either:
241
242       a) the GNU General Public License as published by the Free Software
243       Foundation; either version 1, or (at your option) any later version,
244
245       or
246
247       b) the "Artistic License"
248
249       This program is distributed in the hope that it will be useful, but
250       WITHOUT ANY WARRANTY; without even the implied warranty of
251       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
252       GNU General Public License or the Artistic License for more details.
253
254       For a copy of the GNU General Public License along with this program;
255       if not, write to the Free Software Foundation, Inc., 59 Temple Place,
256       Suite 330, Boston, MA 02111-1307 USA
257
258
259
260perl v5.32.0                      2020-0C7G-I2:8:Application::Plugin::ValidateRM(3)
Impressum