/ 
Plack-Middleware-AutoRefresh-0.08
River stage zero No dependents
/ Plack::Middleware::AutoRefresh

NAME

Plack::Middleware::AutoRefresh - Reload pages in browsers when files are modified

SYNOPSIS

# in app.psgi
use Plack::Builder;

builder {
    enable 'Plack::Middleware::AutoRefresh',
           dirs => [ qw/html/ ], filter => qr/\.(swp|bak)/;
    $app;
}

DESCRIPTION

Plack::Middleware::AutoRefresh is a middleware component that will reload you web pages in your browser when changes are detected in the source files. It should work with any modern browser that supports JavaScript and multiple browsers simultaneously.

At this time, this middleware will only work with backend servers that set psgi.nonblocking to true. Servers that are known to work include Plack::Server::AnyEvent and Plack::Server::Coro. You can force a server with the -s or --server flag to plackup.

CONFIGURATION

dirs => [ '.' ]                     # default
dirs => [ qw/root share html/ ]

Specifies the directories to watch for changes. Will watch all files and subdirectories of the specified directories for file modifications, new files, deleted files, new directories and deleted directories.

filter => qr/\.(swp|bak)$/           # default
filter => qr/\.(svn|git)$/
filter => sub { shift =~ /\.html$/ }

Will apply the specified filter to the changed path name. This can be a regular expression or a code ref. Any paths that match the regular expression will be ignored. A code ref will be passed the path as the only argument. Any false return values will be filtered out.

wait => 5                           # default

Wait indicated the maximum number of seconds that the client should block for while waiting for notifications of changes. Setting this to a lower value will not improve response times.

ACKNOWLEDGMENTS

This component was inspired by NodeJuice (http://nodeJuice.com/). NodeJuice provides very similar browser refresh functionality by running a standalone proxy between your client and the web application. It is a bit more robust than Plack::Middleware::AutoRefresh as it can handle critical errors in your app (ie, compile errors). Plack::Middleware::AutoRefresh is simpler to setup and is limited to Plack based applications. Some of the original JavaScript was taken from nodeJuice project as well, although it was mostly rewritten prior to release. Thank you to Stephen Blum the author of nodeJuice.

A huge thank you to the man behind Plack, Tatsuhiko Miyagawa, who help me brainstorm the implementation, explained the inners of the Plack servers, and re-wrote my broken code.

IMPLEMENTATION

Plack::Middleware::AutoRefresh accomplishes the browser refresh by inserting a bit (1.2K to be precise) of JavaScript into the (x)html pages your Plack application on the fly. The JavaScript tries to have minimal impact: only one anonymous function and one global flag (window['-plackAutoRefresh-']) are added. The JavaScript will open an Ajax connection back to your Plack server which will block waiting to be notified of changes. When a change notification arrives, the JavaScript will trigger a page reload.

SEE ALSO

NodeJuice at http://www.nodejuice.com/.

Modules used to implement this module AnyEvent::Filesys::Notify.

And of course, Plack.

BUGS

Please report any bugs or suggestions at http://rt.cpan.org/

AUTHOR

Mark Grimes, <mgrimes@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Mark Grimes

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.