README
1NAME
2 Plack::Middleware::AutoRefresh - Reload pages in browsers when files are
3 modified
4
5SYNOPSIS
6 # in app.psgi
7 use Plack::Builder;
8
9 builder {
10 enable 'Plack::Middleware::AutoRefresh',
11 dirs => [ qw/html/ ], filter => qr/\.(swp|bak)/;
12 $app;
13 }
14
15DESCRIPTION
16 Plack::Middleware::AutoRefresh is a middleware component that will
17 reload you web pages in your browser when changes are detected in the
18 source files. It should work with any modern browser that supports
19 JavaScript and multiple browsers simultaneously.
20
21 At this time, this middleware will only work with backend servers that
22 set psgi.nonblocking to true. Servers that are known to work include
23 Plack::Server::AnyEvent and Plack::Server::Coro. You can force a server
24 with the `-s' or `--server' flag to `plackup'.
25
26CONFIGURATION
27 dirs => [ '.' ] # default
28 dirs => [ qw/root share html/ ]
29
30 Specifies the directories to watch for changes. Will watch all files and
31 subdirectories of the specified directories for file modifications, new
32 files, deleted files, new directories and deleted directories.
33
34 filter => qr/\.(swp|bak)$/ # default
35 filter => qr/\.(svn|git)$/
36 filter => sub { shift =~ /\.html$/ }
37
38 Will apply the specified filter to the changed path name. This can be a
39 regular expression or a code ref. Any paths that match the regular
40 expression will be ignored. A code ref will be passed the path as the
41 only argument. Any false return values will be filtered out.
42
43 wait => 5 # default
44
45 Wait indicated the maximum number of seconds that the client should
46 block for while waiting for notifications of changes. Setting this to a
47 lower value will *not* improve response times.
48
49ACKNOWLEDGMENTS
50 This component was inspired by NodeJuice (http://nodeJuice.com/).
51 NodeJuice provides very similar browser refresh functionality by running
52 a standalone proxy between your client and the web application. It is a
53 bit more robust than Plack::Middleware::AutoRefresh as it can handle
54 critical errors in your app (ie, compile errors).
55 Plack::Middleware::AutoRefresh is simpler to setup and is limited to
56 Plack based applications. Some of the original JavaScript was taken from
57 nodeJuice project as well, although it was mostly rewritten prior to
58 release. Thank you to Stephen Blum the author of nodeJuice.
59
60 A huge thank you to the man behind Plack, Tatsuhiko Miyagawa, who help
61 me brainstorm the implementation, explained the inners of the Plack
62 servers, and re-wrote my broken code.
63
64IMPLEMENTATION
65 Plack::Middleware::AutoRefresh accomplishes the browser refresh by
66 inserting a bit (1.2K to be precise) of JavaScript into the (x)html
67 pages your Plack application on the fly. The JavaScript tries to have
68 minimal impact: only one anonymous function and one global flag
69 (window['-plackAutoRefresh-']) are added. The JavaScript will open an
70 Ajax connection back to your Plack server which will block waiting to be
71 notified of changes. When a change notification arrives, the JavaScript
72 will trigger a page reload.
73
74SEE ALSO
75 NodeJuice at http://www.nodejuice.com/.
76
77 Modules used to implement this module AnyEvent::Filesys::Notify.
78
79 And of course, Plack.
80
81BUGS
82 Please report any bugs or suggestions at http://rt.cpan.org/
83
84AUTHOR
85 Mark Grimes, <mgrimes@cpan.org>
86
87COPYRIGHT AND LICENSE
88 Copyright (C) 2010 by Mark Grimes
89
90 This library is free software; you can redistribute it and/or modify it
91 under the same terms as Perl itself, either Perl version 5.8.2 or, at
92 your option, any later version of Perl 5 you may have available.
93
94