=head1 SYNOPSIS

use Dancer2::Plugin::Deferred;

get '/defer' => sub { deferred error => "Klaatu barada nikto"; redirect '/later'; }

get '/later' => sub { template 'later'; }

in template 'later.tt'

<% IF deferred.error %>

<% END %>

=head1 DESCRIPTION

This L plugin provides a method for deferring a one-time message across a redirect. It is similar to "flash" messages, but without the race conditions that can result from multiple tabs in a browser or from AJAX requests. It is similar in design to L, but adapted for Dancer2.

It works by creating a unique message ID within the session that holds deferred data. The message ID is automatically added as a query parameter to redirection requests. It's sort of like a session within a session, but tied to a request rather than global to the browser. (It will even chain across multiple redirects.)

When a template is rendered, a pre-template hook retrieves the data and deletes it from the session. Alternatively, the data can be retrieved manually (which will also automatically delete the data.)

Alternatively, the message ID parameters can be retrieved and used to construct a hyperlink for a message to be retrieved later. In this case, the message is preserved past the template hook. (The template should be sure not to render the message if not desired.)

=head1 USAGE

=head2 deferred

deferred $key => $value; $value = deferred $key; # also deletes $key

This function works just like C or C, except that it lasts only for the current request and across any redirects. Data is deleted if accessed. If a key is set to an undefined value, the key is deleted from the deferred data hash.

=head2 all_deferred

template 'index', { deferred => all_deferred };

This function returns all the deferred data as a hash reference and deletes the stored data. This is called automatically in the C hook, but is available if someone wants to have manual control.

=head2 deferred_param

template 'index' => { link => uri_for( '/other', { deferred_param } ) };

This function returns the parameter key and value used to propagate the message to another request. Using this function toggles the C variable to true to ensure the message remains to be retrieved by the link.

=head1 CONFIGURATION

=head1 SEE ALSO

=head1 ACKNOWLEDGMENTS

Thank you to mst for explaining why L does what it does and putting up with my dumb ideas along the way.