1CGI::Application::PlugiUns:e:rVaCloindtartiebRuMt(e3d)PCeGrIl::DAopcpulmiecnattaitoino:n:Plugin::ValidateRM(3)
2
6 CGI::Application::Plugin::ValidateRM - Help validate CGI::Application
7 run modes using Data::FormValidator
8
10 use CGI::Application::Plugin::ValidateRM;
11 my $results = $self->check_rm('form_display','_form_profile') || return $self->check_rm_error_page;
13 # 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
20 CGI::Application::Plugin::ValidateRM helps to validate web forms when
21 using the CGI::Application framework and the Data::FormValidator
22 module.
23 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 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 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 my ($results,$err_page) = $self->check_rm('form_display','_form_profile');
39 return $err_page if $err_page;
40 The inputs are as follows:
42 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 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 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 }
60 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 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 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 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 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 Additional Options
84 To control things even more, you can set parameters in your
86 CGI::Application object itself.
87 dfv_defaults
89 The value of the 'dfv_defaults' param is optionally used to pass
90 defaults to the Data::FormValidator new() constructor.
91 $self->param(dfv_defaults => { filters => ['trim'] })
93 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 Here's an example that I've used:
101 sub cgiapp_init {
103 my $self = shift;
104 # 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 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 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 $self->param(dfv_fif_class => 'HTML::FillInForm::SuperDuper');
131 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 $self->param(dfv_fif_defaults => {ignore_fields => ['rm']})
137 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 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 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 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 dfv_results()
165 $self->dfv_results;
166 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 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
177 In a CGI::Application module:
178 # 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 my $t = $self->load_tmpl('page.html');
186 $t->param($errs) if $errs;
188 return $t->output;
189 }
190 sub form_process {
192 my $self = shift;
193 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 #.. do something with DFV $results object now
199 my $t = $self->load_tmpl('success.html');
201 return $t->output;
202 }
204 sub _form_profile {
206 return {
207 required => 'email',
208 msgs => {
209 any_errors => 'some_errors',
210 prefix => 'err_',
211 },
212 };
213 }
214 In page.html:
216 <!-- 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
225 CGI::Application, Data::FormValidator, HTML::FillInForm, perl(1)
226
228 Mark Stosberg <mark@summersault.com>
229
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
237 Copyright (C) 2003-2005 Mark Stosberg <mark@summersault.com>
238 This module is free software; you can redistribute it and/or modify it
240 under the terms of either:
241 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 or
246 b) the "Artistic License"
248 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 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
257perl v5.30.1 2020-0C1G-I2:9:Application::Plugin::ValidateRM(3)