view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    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
    By default, Static::Simple will deliver all files having extensions
    (that is, bits of text following a period (".")), *except* files having
    the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
    and all files without extensions, will be processed through Catalyst. If
    MIME::Types doesn't recognize an extension, it will be served as
    "text/plain".

    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
    Configuration is completely optional and is specified within
    "MyApp->config->{Plugin::Static::Simple}". If you use any of these
    options, this module will probably feel less "simple" to you!

  Enabling request logging
    Since Catalyst 5.50, logging of static requests is turned off by
    default; static requests tend to clutter the log output and rarely
    reveal anything useful. However, if you want to enable logging of static
    requests, you can do so by setting
    "MyApp->config->{Plugin::Static::Simple}->{logging}" to 1.

  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(
            'Plugin::Static::Simple' => {
                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(
            'Plugin::Static::Simple' => {
                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(
            'Plugin::Static::Simple' => {
                ignore_extensions => [ qw/html asp php/ ],
            },
        );

  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(
            'Plugin::Static::Simple' => {
                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(
            'Plugin::Static::Simple' => {
                mime_types => {
                    jpg => 'image/jpg',
                    png => 'image/png',
                },
            },
        );

  Controlling caching with Expires header
    The files served by Static::Simple will have a Last-Modified header set,
    which allows some browsers to cache them for a while. However if you
    want to explicitly set an Expires header, such as to allow proxies to
    cache your static content, then you can do so by setting the "expires"
    config option.

    The value indicates the number of seconds after access time to allow
    caching. So a value of zero really means "don't cache at all", and any
    higher values will keep the file around for that long.

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

  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(
            'Plugin::Static::Simple' => {
                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 directly. 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 /myapp/static>
            SetHandler default-handler