view release on metacpan or  search on metacpan

bin/wallflower  view on Meta::CPAN

 --no-follow                (default = follow)

 --filter                   Arguments are files containing lists of URLs
 --files                    (if no file is given, read from standard input)
 -F

 --url         <url>        URL of the production site. If the URL has
                            a path component, the application will be
                            "mounted" there.

 --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. The hostname used in the
                            --url option is automatically added to the list,

 --errors                   Show URLs that returned a non-200 status code
 --verbose                  Show URLs that returned a 200 status code
 --quiet                    Disable both --errors and --verbose
                            (which are enabled by default)

 --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 exit
 --version                  Print wallflower version information and exit

Options marked with * can be repeated as necessary.

=head2 Arguments

Arguments are either URLs or (if I<--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
I<--filter> is specified) is used instead.

=head1 DESCRIPTION

B<wallflower> turns your L<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 L<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 I<extreme caching>.

A possible dataflow would be processing forms on your development server
(maybe to update a local database), then I<publish> as static pages
a I<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.

B<wallflower> does just that. It reads a list of URLs, strips off
any query strings, issues HTTP C<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 B<--destination> option.

Note that B<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.

=head1 EXAMPLE

The web site created by C<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.js

Passing this list to B<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 C</> are considered directories
and have the default I<index> filename appended, and that wallflower will
behave unpredictably if the site contains pages accessible through URLs
ending both in F<foo> and F<foo/>. This is arguably a bug, but it's
unclear where to fix it, or if it can be fixed at all. See
L<Wallflower::Tutorial/URI SEMANTICS COMPARED TO DIRECTORY SEMANTICS> for
background on this.

Any response with a status other than C<200> will be logged,
but not saved. Responses with a C<301> status (moved) are followed.

B<wallflower> sends the C<If-Modified-Since> header if the target
file for a given URL already exists in the destination directory.
If the application replies with a C<304> status, the file is not
modified. If the 304 response contains a C<Content-Type> header
and I<--follow> is enabled, the file will be searched for more
links to follow.

With the I<--host> option, it's possible to indicate to B<wallflower>
that some fully qualified URL should also be processed via the application.