| 1 |
NAME |
| 2 |
CGI::Application::Plugin::FormState - Store Form State without Hidden |
| 3 |
Fields |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 0.12 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
FormState is just a temporary stash that you can use for storing and |
| 10 |
retrieving private parameters in your multi-page form. |
| 11 |
|
| 12 |
use CGI::Application::Plugin::FormState; |
| 13 |
|
| 14 |
my $form = <<EOF; |
| 15 |
<form action="app.cgi"> |
| 16 |
<input type="hidden" name="run_mode" value="form_process_runmode"> |
| 17 |
<input type="hidden" name="cap_form_state" value="<tmpl_var cap_form_state>"> |
| 18 |
... |
| 19 |
</form> |
| 20 |
EOF |
| 21 |
|
| 22 |
sub form_display_runmode { |
| 23 |
my $self = shift; |
| 24 |
|
| 25 |
# Store some parameters |
| 26 |
$self->form_state->param('name' => 'Road Runner'); |
| 27 |
$self->form_state->param('occupation' => 'Having Fun'); |
| 28 |
|
| 29 |
my $t = $self->load_tmpl(scalarref => \$form); |
| 30 |
return $t->output; |
| 31 |
|
| 32 |
} |
| 33 |
|
| 34 |
sub form_process_runmode { |
| 35 |
my $self = shift; |
| 36 |
|
| 37 |
# Retrieve some parameters |
| 38 |
print $self->form_state->param('name'); # 'Road Runner' |
| 39 |
print $self->form_state->param('occupation'); # 'Having Fun' |
| 40 |
} |
| 41 |
|
| 42 |
EXAMPLE |
| 43 |
This is a more complete example, using |
| 44 |
CGI::Application::Plugin::ValidateRM. |
| 45 |
|
| 46 |
use CGI::Application::Plugin::Session; |
| 47 |
use CGI::Application::Plugin::FormState; |
| 48 |
use CGI::Application::Plugin::ValidateRM; |
| 49 |
|
| 50 |
my $form = <<EOF; |
| 51 |
<form action="app.cgi"> |
| 52 |
<input type="hidden" name="run_mode" value="my_form_process"> |
| 53 |
<input type="hidden" name="cap_form_state" value="<tmpl_var cap_form_state>"> |
| 54 |
... |
| 55 |
</form> |
| 56 |
EOF |
| 57 |
|
| 58 |
sub my_form_display { |
| 59 |
my $self = shift; |
| 60 |
my $errs = shift; |
| 61 |
my $t = $self->load_tmpl(scalarref => \$form); |
| 62 |
|
| 63 |
# Stash some data into it |
| 64 |
$self->form_state->param('name' => 'Wile E. Coyote'); |
| 65 |
$self->form_state->param('occupation' => 'Mining Engineer'); |
| 66 |
|
| 67 |
# Normal ValidateRM error handling |
| 68 |
$t->param($errs) if $errs; |
| 69 |
return $t->output; |
| 70 |
} |
| 71 |
|
| 72 |
sub my_form_process { |
| 73 |
my $self; |
| 74 |
|
| 75 |
# Normal ValidateRM validation |
| 76 |
my ($results, $err_page) = $self->check_rm('my_form_display','_my_form_profile'); |
| 77 |
return $err_page if $err_page; |
| 78 |
|
| 79 |
# The data from the submitted form |
| 80 |
my $params = $self->dfv_results; |
| 81 |
|
| 82 |
$params->{'name'} = $self->form_state->param('name'); # 'Wile E. Coyote' |
| 83 |
$params->{'occupation'} = $self->form_state->param('occupation'); # 'Mining Engineer' |
| 84 |
|
| 85 |
# Now do something interesting with $params |
| 86 |
# ... |
| 87 |
|
| 88 |
my $t = $self->load_tmpl('success.html'); |
| 89 |
return $t->output; |
| 90 |
} |
| 91 |
|
| 92 |
# Standard ValiateRM profile |
| 93 |
sub _my_form_profile { |
| 94 |
return { |
| 95 |
required => 'email', |
| 96 |
msgs => { |
| 97 |
any_errors => 'some_errors', |
| 98 |
prefix => 'err_', |
| 99 |
}, |
| 100 |
}; |
| 101 |
} |
| 102 |
|
| 103 |
DESCRIPTION |
| 104 |
"CGI::Application::Plugin::FormState" provides a temporary storage area |
| 105 |
within the user's session for storing form-related data. |
| 106 |
|
| 107 |
The main use of this is for multi-page forms. Instead of using hidden |
| 108 |
fields to store data related to the form, you store and retrieve values |
| 109 |
from the form state. |
| 110 |
|
| 111 |
In the first instance of your app: |
| 112 |
|
| 113 |
$self->form_state->param('some_name' => 'some_value'); |
| 114 |
$self->form_state->param('some_other_name' => 'some_other_value'); |
| 115 |
|
| 116 |
And later, in a different instance of your app: |
| 117 |
|
| 118 |
$val1 = $self->form_state->param('some_name'); |
| 119 |
$val2 = $self->form_state->param('some_other_name'); |
| 120 |
|
| 121 |
To connect the first instance and the second, you put a single hidden |
| 122 |
field in your template: |
| 123 |
|
| 124 |
<input type="hidden" name="cap_form_state" value="<tmpl_var my_storage_name>"> |
| 125 |
|
| 126 |
You don't have to worry about creating the template param |
| 127 |
"cap_form_state"; it is added automatically to your template parameters |
| 128 |
via the "load_tmpl" hook. |
| 129 |
|
| 130 |
If you want to use a parameter other than "cap_form_state" you can do so |
| 131 |
via the "name" parameter to "form_state-"config>. |
| 132 |
|
| 133 |
If you're skeptical about whether all this abstraction is a good idea, |
| 134 |
see "MOTIVATION", below. |
| 135 |
|
| 136 |
PRESERVING FORM STATE ACROSS REDIRECTS |
| 137 |
You can include the form_state hash in a link: |
| 138 |
|
| 139 |
my $link = '/app.cgi?rm=list&cap_form_state=' . $self->form_state->id; |
| 140 |
|
| 141 |
If you use CGI::Application::Plugin::Redirect, you can easily create |
| 142 |
redirect this way: |
| 143 |
|
| 144 |
$self->redirect('/app.cgi?rm=list&cap_form_state=' . $self->form_state->id); |
| 145 |
|
| 146 |
If you also use CGI::Application::Plugin::LinkIntegrity it is as simple |
| 147 |
as: |
| 148 |
|
| 149 |
$self->redirect($self->link('/app.cgi', 'rm' => 'list', 'cap_form_state' => $self->form_state->id)); |
| 150 |
|
| 151 |
Or, in the case of a link to the currently running app: |
| 152 |
|
| 153 |
$self->redirect($self->self_link('rm' => 'list', 'cap_form_state' => $self->form_state->id)); |
| 154 |
|
| 155 |
IMPLEMENTATION |
| 156 |
When you call "$self->form_state" for the first time, a top-level key is |
| 157 |
created in the user's session. This key contains a random, hard-to-guess |
| 158 |
element. It might look something like: |
| 159 |
|
| 160 |
form_state_cap_form_state_84eb13cfed01764d9c401219faa56d53 |
| 161 |
|
| 162 |
All data you place in the form state with "param" is stored in the |
| 163 |
user's session under this key. |
| 164 |
|
| 165 |
You pass the name of this key on to the next instance of your |
| 166 |
application by means of a hidden field in your form: |
| 167 |
|
| 168 |
<input type="hidden" name="cap_form_state" value="<tmpl_var cap_form_state>"> |
| 169 |
|
| 170 |
You manually put this hidden field in your template. The template |
| 171 |
parameter "cap_form_state" is automatically added to your template |
| 172 |
parameters via the "load_tmpl" hook. It contains the random, |
| 173 |
hard-to-guess portion (e.g. "84eb13cfed01764d9c401219faa56d53"). When |
| 174 |
the template is filled, the hidden field will look something like this: |
| 175 |
|
| 176 |
<input type="hidden" name="cap_form_state" value="84eb13cfed01764d9c401219faa56d53"> |
| 177 |
|
| 178 |
Since all values are stored on the server in the user's session, the |
| 179 |
user can't tamper with any of them. |
| 180 |
|
| 181 |
To keep old form_data from cluttering up the user's session, the system |
| 182 |
uses CGI::Session's "expire" feature to expire old form state keys after |
| 183 |
a reasonable amount of time has passed (2 days by default). |
| 184 |
|
| 185 |
You can manually delete a form state storage by calling: |
| 186 |
|
| 187 |
$self->form_state->delete; |
| 188 |
|
| 189 |
METHODS |
| 190 |
config(%options) |
| 191 |
Sets defaults for the plugin. |
| 192 |
|
| 193 |
Calling config is purely optional, since the defaults should be fine |
| 194 |
most purposes. |
| 195 |
|
| 196 |
$self->form_state->config('name' => 'storage_names', 'expires' => '3d') |
| 197 |
|
| 198 |
The following options are allowed: |
| 199 |
|
| 200 |
name |
| 201 |
Sets the name of the default form state storage. This name is |
| 202 |
used for the key in the user's session, for the name of hidden |
| 203 |
form field, and the template parameter used to fill the hidden |
| 204 |
form field. So if you set the "name" to "foo": |
| 205 |
|
| 206 |
$self->form_state_config('name' => 'foo'); |
| 207 |
|
| 208 |
then the hidden field in your template should look like this: |
| 209 |
|
| 210 |
<input type="hidden" name="foo" value="<tmpl_var foo>"> |
| 211 |
|
| 212 |
and the key in the user's session would look something like |
| 213 |
this: |
| 214 |
|
| 215 |
form_state_foo_84eb13cfed01764d9c401219faa56d53 |
| 216 |
|
| 217 |
expires |
| 218 |
Indicates when form state storage keys should expire and |
| 219 |
disappear from the user's session. Uses the same format as |
| 220 |
CGI::Session's "expire". Defaults to 2 days ('2d'). To cancel |
| 221 |
expiration and make the form state last as long as the user's |
| 222 |
session does, use: |
| 223 |
|
| 224 |
$self->form_state_config('expires' => 0); |
| 225 |
|
| 226 |
param |
| 227 |
Read and set values in the form state storage. It acts like the |
| 228 |
"param" method typically does in modules such as CGI, |
| 229 |
CGI::Application, CGI::Session, "HTML::Template" etc. |
| 230 |
|
| 231 |
# set a value |
| 232 |
$self->form_state->param('some_name' => 'some_value'); |
| 233 |
|
| 234 |
# retrieve a value |
| 235 |
my $val = $self->form_state->param('some_name'); |
| 236 |
|
| 237 |
# set multiple values |
| 238 |
$self->form_state->param( |
| 239 |
'some_name' => 'some_value', |
| 240 |
'some_other_name' => 'some_other_value', |
| 241 |
); |
| 242 |
|
| 243 |
# retrive the names of all the keys |
| 244 |
my @keys = $self->form_state->param; |
| 245 |
|
| 246 |
clear_params |
| 247 |
Clear all of the values in the form state storage: |
| 248 |
|
| 249 |
$self->form_state->param('name' => 'Road Runner'); |
| 250 |
$self->form_state->clear_params; |
| 251 |
print $self->form_state->param('name'); # undef |
| 252 |
|
| 253 |
delete |
| 254 |
Deletes the form_state storage from the user's session. |
| 255 |
|
| 256 |
id Returns the current value of the storage param - the "hard to guess" |
| 257 |
portion of the session key. |
| 258 |
|
| 259 |
my $id = $self->form_state->id; |
| 260 |
|
| 261 |
name |
| 262 |
Returns the current name being used for storage. Defaults to |
| 263 |
"cap_form_state". |
| 264 |
|
| 265 |
my $name = $self->form_state->name; |
| 266 |
|
| 267 |
session_key |
| 268 |
Returns the full key used for storage in the user's session. |
| 269 |
|
| 270 |
my $key = $self->form_state->session_key; |
| 271 |
|
| 272 |
# Get the full form state hash |
| 273 |
my $data = $self->session->param($key); |
| 274 |
|
| 275 |
The following can be used to debug the form_state data: |
| 276 |
|
| 277 |
use Data::Dumper; |
| 278 |
print STDERR Dumper $self->session->param($self->form_state->session_key); |
| 279 |
|
| 280 |
MOTIVATION |
| 281 |
Why not just use hidden fields? |
| 282 |
Hidden fields are not secure. The end user could save a local copy of |
| 283 |
your form, change the hidden fields and tamper with your app's form |
| 284 |
state. |
| 285 |
|
| 286 |
Why not just use the user's session? |
| 287 |
With "CGI::Application::Plugin::FormState" the data is associated with a |
| 288 |
particular instance of a form, not with the user. If the user gives up |
| 289 |
halfway through your multi-page form, you don't want their session to be |
| 290 |
cluttered up with the incomplete form state data. |
| 291 |
|
| 292 |
If a user opens up your application in two browser windows (both sharing |
| 293 |
the same user session), each window should have it's own independent |
| 294 |
form state. |
| 295 |
|
| 296 |
For instance, in an email application the user might have one window |
| 297 |
open for the inbox and another open for the outbox. If you store the |
| 298 |
value of "current_mailbox" in the user's session, then one of these |
| 299 |
windows will go to the wrong mailbox. |
| 300 |
|
| 301 |
Finally, the user's session probably sticks around longer than the form |
| 302 |
state should. |
| 303 |
|
| 304 |
AUTHOR |
| 305 |
Michael Graham, "<[email protected]>" |
| 306 |
|
| 307 |
BUGS |
| 308 |
Please report any bugs or feature requests to |
| 309 |
"[email protected]", or through the web |
| 310 |
interface at <http://rt.cpan.org>. I will be notified, and then you'll |
| 311 |
automatically be notified of progress on your bug as I make changes. |
| 312 |
|
| 313 |
ACKNOWLEDGEMENTS |
| 314 |
Thanks to Richard Dice and Cees Hek for helping me sort out the issues |
| 315 |
with this approach. |
| 316 |
|
| 317 |
The informative error message text used for when this module is loaded |
| 318 |
before your app actually @ISA "CGI::Application" object was stolen from |
| 319 |
Cees's CGI::Application::Plugin::TT module. |
| 320 |
|
| 321 |
COPYRIGHT & LICENSE |
| 322 |
Copyright 2005 Michael Graham, All Rights Reserved. |
| 323 |
|
| 324 |
This program is free software; you can redistribute it and/or modify it |
| 325 |
under the same terms as Perl itself. |
| 326 |
|