NAME

SYNOPSIS

    package MyApp;
    use Catalyst qw/ Static::Simple /;
    MyApp->setup;
    # that's it; static content is automatically served by Catalyst
    # from the application's root directory, though you can configure
    # things or bypass Catalyst entirely in a production environment
    #
    # one caveat: the files must be served from an absolute path
    # (i.e. /images/foo.png)

DESCRIPTION

This plugin detects static files by looking at the file extension in the URL (such as .css or .png or .js). The plugin uses the lightweight MIME::Types module to map file extensions to IANA-registered MIME types, and will serve your static files with the correct MIME type directly to the browser, without being processed through Catalyst.

Note that actions mapped to paths using periods (.) will still operate properly.

If the plugin can not find the file, the request is dispatched to your application instead. This means you are responsible for generating a 404 error if your application can not process the request:

   # handled by static::simple, not dispatched to your application
   /images/exists.png

   # static::simple will not find the file and let your application
   # handle the request. You are responsible for generating a file
   # or returning a 404 error
   /images/does_not_exist.png

Though Static::Simple is designed to work out-of-the-box, you can tweak the operation by adding various configuration options. In a production environment, you will probably want to use your webserver to deliver static content; for an example see "USING WITH APACHE", below.

DEFAULT BEHAVIOUR

To restate: files having the extensions "tmpl", "tt", "tt2", "html", and "xhtml" will not be served statically by default, they will be processed by Catalyst. Thus if you want to use ".html" files from within a Catalyst app as static files, you need to change the configuration of Static::Simple. Note also that files having any other extension will be served statically, so if you're using any other extension for template files, you should also change the configuration.

Logging of static files is turned off by default.

ADVANCED CONFIGURATION

    MyApp->config(
        'Plugin::Static::Simple' => {
            dirs => [
                'static',
                qr/^(images|css)/,
            ],
        }
    );

    MyApp->config(
        'Plugin::Static::Simple' => {
            include_path => [
                '/path/to/overlay',
                \&incpath_generator,
                MyApp->config->{root},
            ],
        },
    );

    /path/to/overlay/images/logo.jpg
    /dynamic/path/images/logo.jpg
    /your/app/home/root/images/logo.jpg

    sub incpath_generator {
        my $c = shift;

        if ( $c->session->{customer_dir} ) {
            return [ $c->session->{customer_dir} ];
        } else {
            die "No customer dir defined.";
        }
    }

    MyApp->config(
        'Plugin::Static::Simple' => {
            ignore_extensions => [ qw/html asp php/ ],
        },
    );

    MyApp->config(
        'Plugin::Static::Simple' => {
            ignore_dirs => [ qw/tmpl css/ ],
        },
    );

    /path/to/overlay/tmpl
    /path/to/overlay/css
    /dynamic/path/tmpl
    /dynamic/path/css
    /your/app/home/root/tmpl
    /your/app/home/root/css

    MyApp->config(
        'Plugin::Static::Simple' => {
            mime_types => {
                jpg => 'image/jpg',
                png => 'image/png',
            },
        },
    );

    MyApp->config(
        'Plugin::Static::Simple' => {
            expires => 3600, # Caching allowed for one hour.
        },
    );

    MyApp->config(
        'Plugin::Static::Simple' => {
            debug => 1,
        },
    );

USING WITH APACHE

    <Location /myapp/static>
        SetHandler default-handler
    </Location>

Using this approach Apache will bypass any handling of these directories through Catalyst. You can leave Static::Simple as part of your application, and it will continue to function on a development server, or using Catalyst's built-in server.

In practice, your Catalyst application is probably (i.e. should be) structured in the recommended way (i.e., that generated by bootstrapping the application with the "catalyst.pl" script, with a main directory under which is a "lib/" directory for module files and a "root/" directory for templates and static files). Thus, unless you break up this structure when deploying your app by moving the static files to a different location in your filesystem, you will need to use an Alias directive in Apache to point to the right place. You will then need to add a Directory block to give permission for Apache to serve these files. The final configuration will look something like this:

    Alias /myapp/static /filesystem/path/to/MyApp/root/static
    <Directory /filesystem/path/to/MyApp/root/static>
        allow from all
    </Directory>
    <Location /myapp/static>
        SetHandler default-handler
    </Location>

If you are running in a VirtualHost, you can just set the DocumentRoot location to the location of your root directory; see Catalyst::Engine::Apache2::MP20.

PUBLIC METHODS

    package MyApp::Controller::User;

    sub curr_user_thumb : PathPart("my_thumbnail.png") {
        my ( $self, $c ) = @_;
        my $file_path = $c->user->picture_thumbnail_path;
        $c->serve_static_file($file_path);
    }

INTERNAL EXTENDED METHODS

DEPRECATIONS

Be aware that if the 'include_path' key under 'static' exists at all, it will be merged with any content of the same key under 'Plugin::Static::Simple'. Be careful not to set this to a non-arrayref, therefore.

SEE ALSO

AUTHOR

CONTRIBUTORS

Jesse Sheidlower, <jester@panix.com>

Guillermo Roditi, <groditi@cpan.org>

Florian Ragwitz, <rafl@debian.org>

Tomas Doran, <bobtfish@bobtfish.net>

Justin Wheeler (dnm)

Matt S Trout, <mst@shadowcat.co.uk>

Toby Corkindale, <tjc@wintrmute.net>

THANKS

    Sebastian Riedel
    Christian Hansen
    Marcus Ramberg

For the include_path code from Template Toolkit:

    Andy Wardley

COPYRIGHT

LICENSE