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 tt, 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/tt 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',
       };

 Apache integration and performance
   Optionally, when running under mod_perl, Static::Simple can return
   DECLINED on static files to allow Apache to serve the file. A check is
   first done to make sure that Apache's DocumentRoot matches your Catalyst
   root, and that you are not using any custom MIME types or multiple
   roots. To enable the Apache support, you can set the following option.

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

   By default this option is disabled because after several benchmarks it
   appears that just serving the file from Catalyst is the better option.
   On a 3K file, Catalyst appears to be around 25% faster, and is 42%
   faster on a 10K file. My benchmarking was done using the following
   'siege' command, so other benchmarks would be welcome!

       siege -u http://server/static/css/10K.css -b -t 1M -c 1

   For best static performance, you should still serve your static files
   directly from Apache by defining a Location block similar to the
   following:

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

 Bypassing other plugins
   This plugin checks for a static file in the prepare_action stage. If the
   request is for a static file, it will bypass all remaining
   prepare_action steps. This means that by placing Static::Simple before
   all other plugins, they will not execute when a static file is found.
   This can be helpful by skipping session cookie checks for example. Or,
   if you want some plugins to run even on static files, list them before
   Static::Simple.

   Currently, work done by plugins in any other prepare method will execute
   normally.

 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;

SEE ALSO
   Catalyst, Catalyst::Plugin::Static,
   <http://www.iana.org/assignments/media-types/>

AUTHOR
   Andy Grundman, <[email protected]>

CONTRIBUTORS
   Marcus Ramberg, <[email protected]>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.