README.mkdn
1# NAME
2
3Dancer2::Plugin::Deferred - Defer messages or data across redirections
4
5# VERSION
6
7version 0.008000
8
9# SYNOPSIS
10
11```perl
12use Dancer2::Plugin::Deferred;
13
14get '/defer' => sub {
15 deferred error => "Klaatu barada nikto";
16 redirect '/later';
17};
18
19get '/later' => sub {
20 template 'later';
21};
22
23# in template 'later.tt'
24<% IF deferred.error %>
25<div class="error"><% deferred.error %></div>
26<% END %>
27```
28
29# DESCRIPTION
30
31This [Dancer2](https://metacpan.org/pod/Dancer2) plugin provides a method for deferring a one-time message across
32a redirect. It is similar to "flash" messages, but without the race conditions
33that can result from multiple tabs in a browser or from AJAX requests. It is
34similar in design to [Catalyst::Plugin::StatusMessage](https://metacpan.org/pod/Catalyst::Plugin::StatusMessage), but adapted for Dancer2.
35
36It works by creating a unique message ID within the session that holds deferred
37data. The message ID is automatically added as a query parameter to redirection
38requests. It's sort of like a session within a session, but tied to a request
39rather than global to the browser. (It will even chain across multiple
40redirects.)
41
42When a template is rendered, a pre-template hook retrieves the data and
43deletes it from the session. Alternatively, the data can be retrieved manually
44(which will also automatically delete the data.)
45
46Alternatively, the message ID parameters can be retrieved and used to
47construct a hyperlink for a message to be retrieved later. In this case,
48the message is preserved past the template hook. (The template should be
49sure not to render the message if not desired.)
50
51# USAGE
52
53## deferred
54
55```perl
56deferred $key => $value;
57$value = deferred $key; # also deletes $key
58```
59
60This function works just like `var` or `session`, except that it lasts only
61for the current request and across any redirects. Data is deleted if accessed.
62If a key is set to an undefined value, the key is deleted from the deferred
63data hash.
64
65## all\_deferred
66
67```perl
68template 'index', { deferred => all_deferred };
69```
70
71This function returns all the deferred data as a hash reference and deletes
72the stored data. This is called automatically in the `before_template_render`
73hook, but is available if someone wants to have manual control.
74
75## deferred\_param
76
77```perl
78template 'index' => { link => uri_for( '/other', { deferred_param } ) };
79```
80
81This function returns the parameter key and value used to propagate the
82message to another request. Using this function toggles the `var_keep_key`
83variable to true to ensure the message remains to be retrieved by the link.
84
85# CONFIGURATION
86
87# SEE ALSO
88
89# ACKNOWLEDGMENTS
90
91Thank you to mst for explaining why [Catalyst::Plugin::StatusMessages](https://metacpan.org/pod/Catalyst::Plugin::StatusMessages) does
92what it does and putting up with my dumb ideas along the way.
93
94# AUTHORS
95
96- David Golden <dagolden@cpan.org>
97- Yanick Champoux <yanick@cpan.org> [](http://coderwall.com/yanick)
98- Deluxaran <deluxaran@cpan.org>
99
100# COPYRIGHT AND LICENSE
101
102This software is Copyright (c) 2020, 2018, 2016 by David Golden.
103
104This is free software, licensed under:
105
106```
107The Apache License, Version 2.0, January 2004
108```
109
README.pod
1=head1 SYNOPSIS
2
3 use Dancer2::Plugin::Deferred;
4
5 get '/defer' => sub {
6 deferred error => "Klaatu barada nikto";
7 redirect '/later';
8 }
9
10 get '/later' => sub {
11 template 'later';
12 }
13
14 # in template 'later.tt'
15 <% IF deferred.error %>
16 <div class="error"><% deferred.error %></div>
17 <% END %>
18
19=head1 DESCRIPTION
20
21This L<Dancer2> plugin provides a method for deferring a one-time message across
22a redirect. It is similar to "flash" messages, but without the race conditions
23that can result from multiple tabs in a browser or from AJAX requests. It is
24similar in design to L<Catalyst::Plugin::StatusMessage>, but adapted for Dancer2.
25
26It works by creating a unique message ID within the session that holds deferred
27data. The message ID is automatically added as a query parameter to redirection
28requests. It's sort of like a session within a session, but tied to a request
29rather than global to the browser. (It will even chain across multiple
30redirects.)
31
32When a template is rendered, a pre-template hook retrieves the data and
33deletes it from the session. Alternatively, the data can be retrieved manually
34(which will also automatically delete the data.)
35
36Alternatively, the message ID parameters can be retrieved and used to
37construct a hyperlink for a message to be retrieved later. In this case,
38the message is preserved past the template hook. (The template should be
39sure not to render the message if not desired.)
40
41=head1 USAGE
42
43=head2 deferred
44
45 deferred $key => $value;
46 $value = deferred $key; # also deletes $key
47
48This function works just like C<var> or C<session>, except that it lasts only
49for the current request and across any redirects. Data is deleted if accessed.
50If a key is set to an undefined value, the key is deleted from the deferred
51data hash.
52
53=head2 all_deferred
54
55 template 'index', { deferred => all_deferred };
56
57This function returns all the deferred data as a hash reference and deletes
58the stored data. This is called automatically in the C<before_template_render>
59hook, but is available if someone wants to have manual control.
60
61=head2 deferred_param
62
63 template 'index' => { link => uri_for( '/other', { deferred_param } ) };
64
65This function returns the parameter key and value used to propagate the
66message to another request. Using this function toggles the C<var_keep_key>
67variable to true to ensure the message remains to be retrieved by the link.
68
69=head1 CONFIGURATION
70
71=head1 SEE ALSO
72
73=head1 ACKNOWLEDGMENTS
74
75Thank you to mst for explaining why L<Catalyst::Plugin::StatusMessages> does
76what it does and putting up with my dumb ideas along the way.
77
78
){kind=link}