/ 
App-Wallflower-1.001
River stage one • 1 direct dependent • 1 total dependent
/ wallflower

NAME

wallflower - Sorry I can't dance, I'm hanging on to my friend's purse

SYNOPSIS

wallflower [options]

OPTIONS

--application <app>        Name of the .psgi application file
--destination <path>       Destination directory for the static files

--environment <name>       Plack environment (default: deployment)
--index       <filename>   Default name for index file (default: index.html)
--no-follow                Do not follow links in HTML and CSS pages
--filter                   Consider arguments as files containing URL
--quiet                    Do not show progress
--include     <path>       Library paths to include

--help                     Print a short online help and exit
--manual                   Print the full manual page and exit

DESCRIPTION

wallflower turns your Plack application into a static web site.

While not suitable for all applications, there are a number of use cases where this makes sense. Most web sites are in essence static. Without a way for users to update information on the site (via forms, comments, etc) the only changes in 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 actually makes a lot of sense, just because it gives you access to all the features of the framework for that site. Think of it as extreme caching.

So, forms could be processed on your development server (e.g. to update a local database), and the pages to be published would be a subset of all the URL that the application supports.

Turning such an 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 URL for the static site and saving them to files.

wallflower does exactly that. It reads a list of URL, strips them from their query strings, turn them into GET requests and saves the response body to a file whose name matches the request pathinfo.

wallflower is not a generic offline browsing tool.

COMMAND-LINE OPTIONS

In typical Getopt::Long fashion, all options can be shortened, so long as the shortened version is unambiguous.

  • --application application

    The path to the Plack application to run. This option is required.

  • --destination path, --directory path

    The directory where files will be saved. This option is required, and the directory must exist.

  • --environment name

    Define the Plack environment to run the application in. The default environment is deployment.

  • --index filename

    The default name for index files when fetching a URL ending with a /. The default is index.html.

  • --no-follow, --follow

    Disables or enables following links in HTML, XHTML, and CSS pages. The default option is to follow links.

  • --filter, --files

    Behave as a filter: all remaining arguments on the command-line are considered as files containing URL to process (one per line). If no arguments are provided, will read from standard input.

    The normal behaviour (without --filter) is to consider the remaining arguments as a list of URL. If no arguments are provided, assume the only URL is /.

  • --quiet

    Hide all output.

  • --include <path>, -INC <path>

    Library paths to include. This option can be repeated.

  • --help

    Print a short online help and exit.

  • --manual

    Print the full manual page and exit.

EXAMPLE

The web site created by dancer -a mywebapp is the perfect example.

The complete list of URL 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.js

Passing 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 URL with a path ending with a / or a name without an extension will be considered to be a directory, and have the default index filename appended.

Any URL resulting in a status different than 200 will be logged, but not saved.

Only the path section is used to fetch the response, which means that URL that pointing to other sites will likely result in 404 (or point to a page that exist in the application, and therefore fetch the local response).

AUTHOR

Philippe Bruhat (BooK)

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.

COPYRIGHT

Copyright 2010-2012 Philippe Bruhat (BooK), all rights reserved.

LICENSE

This program is free software and is published under the same terms as Perl itself.