NAME
wallflower - Sorry I can't dance, I'm hanging on to my friend's purse
VERSION
version 1.003
SYNOPSIS
wallflower [options] [arguments]OPTIONS AND ARGUMENTS
In typical Getopt::Long fashion, all options can be abbreviated as long as the shorter version is unambiguous.
Required options
--application <app> Pathname of the .psgi Plack application fileOther options
--destination <path> Directory for saving generated files
--directory <path> (default: current dir), must exist
--environment <name> Plack environment for running the application,
usually development, deployment, or test
(default: deployment)
--index <filename> Name of index file for URLs ending in /
(default: index.html)
--follow Do/don't follow links in (X)HTML and CSS pages
--no-follow (default = follow)
--filter Arguments are files containing lists of URLs
--files
-F
--host <hostname> * Process URLs with one of these hostnames in
addition to hostame-less ones and ones using
localhost (default is only hostame-less and
localhost ones), can include * as a wildcard,
like *.example.com
--quiet Don't display URLs as they're processed
--include <path> * Library paths to add to @INC, delimited with your
--INC <path> * OS' path separator ($Config::Config{path_sep})
--help Print a short help summary and exit
--manual Print the full manual page and exit
--tutorial Print the tutorial and exitOptions marked with * can be repeated as necessary.
Arguments
Arguments are either URLs or (if --filter is specified) files containing URLs (one per line) or lines containing only spaces or where the first non-space is a #. If no arguments are present, / (or standard input if --filter is specified) is used instead.
DESCRIPTION
wallflower turns your Plack application into a static (read-only) web site.
While this isn't suitable for all applications, it makes sense for many uses. Most web sites are largely static. With no way for the site's users to update its content (via forms, comments, etc) the only changes to the web site come from sources that you control (including the database) and that are accessible in your development environment.
Using a web framework like Dancer (or any other) for a static web site is very useful, because it lets you use all the features of the framework on that site. Think of it as extreme caching.
A possible dataflow would be processing forms on your development server (maybe to update a local database), then publish as static pages a subset of all the URLs the application supports.
Turning that application into a real static site (a set of pages to upload to a static web server) is just a matter of generating all possible URLs for the static site and saving the corresponding pages to files.
wallflower does just that. It reads a list of URLs, strips off any query strings, issues HTTP GET requests for each in turn and saves the response body to a file with a name derived from the request pathinfo, under the directory specified by the --destination option.
Note that wallflower is not meant for use as an offline browsing tool: among other things, it doesn't rewrite link URLs to match the pathnames of the saved pages.
EXAMPLE
The web site created by dancer -a mywebapp is the perfect example.
The complete list of URLs needed to view the site is:
/
/404.html
/500.html
/css/error.css
/css/style.css
/favicon.ico
/images/perldancer-bg.jpg
/images/perldancer.jpg
/javascripts/jquery.jsPassing this list to wallflower gives the following result:
$ wallflower -a bin/app.pl -d /tmp -F urls.txt
200 / => /tmp/output/index.html [5367]
200 /404.html => /tmp/output/404.html [499]
200 /500.html => /tmp/output/500.html [510]
200 /css/error.css => /tmp/output/css/error.css [1210]
200 /css/style.css => /tmp/output/css/style.css [2850]
404 /favicon.ico
404 /images/perldancer-bg.jpg
404 /images/perldancer.jpg
200 /javascripts/jquery.js => /tmp/output/javascripts/jquery.js [248235]Note that URLs with a path ending in a / are considered directories and have the default index filename appended, and that wallflower will behave unpredictably if the site contains pages accessible through URLs ending both in foo and foo/. This is arguably a bug, but it's unclear where to fix it, or if it can be fixed at all. See "URI SEMANTICS COMPARED TO DIRECTORY SEMANTICS" in Wallflower::Tutorial for background on this.
Any URL returning a status other than 200 will be logged, but not saved. URLs returning a 301 status (moved) are followed.
Only the path component is used to fetch the response, so URLs pointing to other sites will likely return a 404 (or fetch the local page if it exists in the application).
ACKNOWLEDGEMENTS
wallflower started as a neat idea in a discussion between Marc Chantreux, Alexis Sukrieh, Franck Cuny and myself in the hallway of OSDC.fr (http://osdc.fr/) 2010, after Alexis' talk about Dancer.
Because a good pun should never be wasted, a first version of the program has been included in Dancer since version 1.3000_01. Since it wasn't maintained, it has been removed in version 1.3110, after the first release of App::Wallflower.
The idea for App::Wallflower owes a lot to Vincent Pit who, while I was talking about wallflower and Dancer with Marc on IRC in January 2011, noted that this file generation scheme had nothing to do with Dancer and much more with Plack.
wallflower treats all Plack applications equally, even if the first version of the program was targetting Dancer only.
AUTHOR
Philippe Bruhat (BooK) <book@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Philippe Bruhat (BooK).
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.