/ 
Dancer-Plugin-WindowSession-0.02
River stage zero No dependents
/ Dancer::Plugin::WindowSession

NAME

Dancer::Plugin::WindowSession - Manage Per-Browser-Window sessions.

VERSION

version 0.02

SYNOPSIS

use Dancer;
use Dancer::Plugin::WindowSession;

get '/' => sub {
	## Read Session-wide variable
	## (applies to all open browser windows)
	my $username = session 'username';

	## Read Window-Session variable
	## (will be different for every open browser window)
	my $color = window_session 'color';

	## [ return something to the user ]
};


## Assume the user submitted a POST <form>
## with new data, save some variables to the standard session,
## and others to the per-window session.
post 'change_settings' => sub {
	my $username = param 'username';
	my $color = param 'color';

	session 'username' => $username ;
	window_session 'color' => $color ;

	## [ return something to the user ]
};

dance;

######################
### VERY IMPORTANT ###
######################
In all the template files, you must pass-on the 'winsid' CGI variable,
either as part of a URL or as part of a POST <form> varaible.

Using Template::Toolkit templtates:

<a href="some_other_page?winsid=[% winsid | uri %]">Go to some other page</a>

OR

<form method="post">
	<input type="hidden" name="winsid" value="[% winsid|uri %]">
</form>

FUNCTIONS

window_session - Read/Write access to the per-window-session variables. Behaves exactly like Dancer's session keyword.

window_session_id - Returns the per-window-session ID number (if you need to embed it in a URL string).

DESCRIPTION

This module makes it easy to manage per-window session variables (as opposed to browser-wide session variables).

The common use case is when you expect users of your website to have multiple web-browser windows open with your web-site, and for each open window you want to maintain independant set of variables.

IMPLEMENTATION

To use this plugin effectively, be sure to include the winsid value in all URLs and POST forms you have in your templates.

This plugin uses the same session engine configured for your Dancer application (see Dancer::Session).

CONFIGURATION

No configuration options are available, at the moment.

Future version might allow changing the name of the CGI varaible (winsid) to something else.

AUTHOR

Assaf Gordon, <gordon at cshl.edu>

BUGS

Possibly many.

NOTE: If a user copies a URL (containing the winsid value) and pastes it in a new browser window (or sends it to another user) - then both windows will share the same sessions. This can be viewed as a bug (The per-window mechanism does not really guarentee to be a single-window session) or a feature (users can easily share their session state with other users).

Please report any bugs or feature requests to https://github.com/agordon/Dancer-Plugin-WindowSession/issues

SEE ALSO

Dancer, Dancer::Plugin

Example

See working example at: http://winsid.cancan.cshl.edu .

See the eg/ directory for a complete source of the example. Run: perl -I./lib/ eg/example/bin/app.pl then visit http://localhost:3000 .

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Dancer::Plugin::WindowSession

ACKNOWLEDGEMENTS

The implementation was influenced by the UCSC Genome Browser website, which uses the hgsid CGI variable in the same manner.

LICENSE AND COPYRIGHT

Copyright 2012 Assaf Gordon.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.