/ 
Catalyst-5.60
/ Catalyst::Plugin::Static::Simple

NAME

Catalyst::Plugin::Static::Simple - Make serving static pages painless.

SYNOPSIS

use Catalyst;
MyApp->setup( qw/Static::Simple/ );

DESCRIPTION

The Static::Simple plugin is designed to make serving static content in your application during development quick and easy, without requiring a single line of code from you.

It will detect static files used in your application by looking for file extensions in the URI. By default, you can simply load this plugin and it will immediately begin serving your static files with the correct MIME type. The light-weight MIME::Types module is used to map file extensions to IANA-registered MIME types.

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

You may further tweak the operation by adding configuration options, described below.

ADVANCED CONFIGURATION

Configuration is completely optional and is specified within MyApp->config->{static}. If you use any of these options, the module will probably feel less "simple" to you!

Aborting request logging

Since Catalyst 5.50, there has been added support for dropping logging for a request. This is enabled by default for static files, as static requests tend to clutter the log output. However, if you want logging of static requests, you can enable it by setting MyApp->config->{static}->{no_logs} to 0.

Forcing directories into static mode

Define a list of top-level directories beneath your 'root' directory that should always be served in static mode. Regular expressions may be specified using qr//.

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

Including additional directories

You may specify a list of directories in which to search for your static files. The directories will be searched in order and will return the first file found. Note that your root directory is not automatically added to the search path when you specify an include_path. You should use MyApp->config->{root} to add it.

MyApp->config->{static}->{include_path} = [
    '/path/to/overlay',
    \&incpath_generator,
    MyApp->config->{root}
];

With the above setting, a request for the file /images/logo.jpg will search for the following files, returning the first one found:

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

The include path can contain a subroutine reference to dynamically return a list of available directories. This method will receive the $c object as a parameter and should return a reference to a list of directories. Errors can be reported using die(). This method will be called every time a file is requested that appears to be a static file (i.e. it has an extension).

For example:

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

Ignoring certain types of files

There are some file types you may not wish to serve as static files. Most important in this category are your raw template files. By default, files with the extensions tmpl, tt, tt2, html, and xhtml will be ignored by Static::Simple in the interest of security. If you wish to define your own extensions to ignore, use the ignore_extensions option:

MyApp->config->{static}->{ignore_extensions} 
    = [ qw/tmpl tt tt2 html xhtml/ ];

Ignoring entire directories

To prevent an entire directory from being served statically, you can use the ignore_dirs option. This option contains a list of relative directory paths to ignore. If using include_path, the path will be checked against every included path.

MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];

For example, if combined with the above include_path setting, this ignore_dirs value will ignore the following directories if they exist:

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

Custom MIME types

To override or add to the default MIME types set by the MIME::Types module, you may enter your own extension to MIME type mapping.

MyApp->config->{static}->{mime_types} = {
    jpg => 'image/jpg',
    png => 'image/png',
};

Compatibility with other plugins

Since version 0.12, Static::Simple plays nice with other plugins. It no longer short-circuits the prepare_action stage as it was causing too many compatibility issues with other plugins.

Debugging information

Enable additional debugging information printed in the Catalyst log. This is automatically enabled when running Catalyst in -Debug mode.

MyApp->config->{static}->{debug} = 1;

USING WITH APACHE

While Static::Simple will work just fine serving files through Catalyst in mod_perl, for increased performance, you may wish to have Apache handle the serving of your static files. To do this, simply use a dedicated directory for your static files and configure an Apache Location block for that directory. This approach is recommended for production installations.

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

INTERNAL EXTENDED METHODS

Static::Simple extends the following steps in the Catalyst process.

prepare_action

prepare_action is used to first check if the request path is a static file. If so, we skip all other prepare_action steps to improve performance.

dispatch

dispatch takes the file found during prepare_action and writes it to the output.

finalize

finalize serves up final header information and displays any log messages.

setup

setup initializes all default values.

SEE ALSO

Catalyst, Catalyst::Plugin::Static, http://www.iana.org/assignments/media-types/

AUTHOR

Andy Grundman, <andy@hybridized.org>

CONTRIBUTORS

Marcus Ramberg, <mramberg@cpan.org>

THANKS

The authors of Catalyst::Plugin::Static:

Sebastian Riedel
Christian Hansen
Marcus Ramberg

For the include_path code from Template Toolkit:

Andy Wardley

COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.