README

   1 NAME
   2     Catalyst::Plugin::Static::Simple - Make serving static pages painless.
   3
   4 SYNOPSIS
   5         use Catalyst;
   6         MyApp->setup( qw/Static::Simple/ );
   7
   8 DESCRIPTION
   9     The Static::Simple plugin is designed to make serving static content in
  10     your application during development quick and easy, without requiring a
  11     single line of code from you.
  12
  13     It will detect static files used in your application by looking for file
  14     extensions in the URI. By default, you can simply load this plugin and
  15     it will immediately begin serving your static files with the correct
  16     MIME type. The light-weight MIME::Types module is used to map file
  17     extensions to IANA-registered MIME types.
  18
  19     Note that actions mapped to paths using periods (.) will still operate
  20     properly.
  21
  22     You may further tweak the operation by adding configuration options,
  23     described below.
  24
  25 ADVANCED CONFIGURATION
  26     Configuration is completely optional and is specified within
  27     MyApp->config->{static}. If you use any of these options, the module
  28     will probably feel less "simple" to you!
  29
  30   Aborting request logging
  31     Since Catalyst 5.50, there has been added support for dropping logging
  32     for a request. This is enabled by default for static files, as static
  33     requests tend to clutter the log output. However, if you want logging of
  34     static requests, you can enable it by setting
  35     MyApp->config->{static}->{no_logs} to 0.
  36
  37   Forcing directories into static mode
  38     Define a list of top-level directories beneath your 'root' directory
  39     that should always be served in static mode. Regular expressions may be
  40     specified using qr//.
  41
  42         MyApp->config->{static}->{dirs} = [
  43             'static',
  44             qr/^(images|css)/,
  45         ];
  46
  47   Including additional directories
  48     You may specify a list of directories in which to search for your static
  49     files. The directories will be searched in order and will return the
  50     first file found. Note that your root directory is not automatically
  51     added to the search path when you specify an include_path. You should
  52     use MyApp->config->{root} to add it.
  53
  54         MyApp->config->{static}->{include_path} = [
  55             '/path/to/overlay',
  56             \&incpath_generator,
  57             MyApp->config->{root}
  58         ];
  59
  60     With the above setting, a request for the file /images/logo.jpg will
  61     search for the following files, returning the first one found:
  62
  63         /path/to/overlay/images/logo.jpg
  64         /dynamic/path/images/logo.jpg
  65         /your/app/home/root/images/logo.jpg
  66
  67     The include path can contain a subroutine reference to dynamically
  68     return a list of available directories. This method will receive the $c
  69     object as a parameter and should return a reference to a list of
  70     directories. Errors can be reported using die(). This method will be
  71     called every time a file is requested that appears to be a static file
  72     (i.e. it has an extension).
  73
  74     For example:
  75
  76         sub incpath_generator {
  77             my $c = shift;
  78
  79             if ( $c->session->{customer_dir} ) {
  80                 return [ $c->session->{customer_dir} ];
  81             } else {
  82                 die "No customer dir defined.";
  83             }
  84         }
  85
  86   Ignoring certain types of files
  87     There are some file types you may not wish to serve as static files.
  88     Most important in this category are your raw template files. By default,
  89     files with the extensions tt, html, and xhtml will be ignored by
  90     Static::Simple in the interest of security. If you wish to define your
  91     own extensions to ignore, use the ignore_extensions option:
  92
  93         MyApp->config->{static}->{ignore_extensions} = [ qw/tt html xhtml/ ];
  94
  95   Ignoring entire directories
  96     To prevent an entire directory from being served statically, you can use
  97     the ignore_dirs option. This option contains a list of relative
  98     directory paths to ignore. If using include_path, the path will be
  99     checked against every included path.
 100
 101         MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
 102
 103     For example, if combined with the above include_path setting, this
 104     ignore_dirs value will ignore the following directories if they exist:
 105
 106         /path/to/overlay/tmpl
 107         /path/to/overlay/css
 108         /dynamic/path/tmpl
 109         /dynamic/path/css
 110         /your/app/home/root/tmpl
 111         /your/app/home/root/css
 112
 113   Custom MIME types
 114     To override or add to the default MIME types set by the MIME::Types
 115     module, you may enter your own extension to MIME type mapping.
 116
 117         MyApp->config->{static}->{mime_types} = {
 118             jpg => 'image/jpg',
 119             png => 'image/png',
 120         };
 121
 122   Apache integration and performance
 123     Optionally, when running under mod_perl, Static::Simple can return
 124     DECLINED on static files to allow Apache to serve the file. A check is
 125     first done to make sure that Apache's DocumentRoot matches your Catalyst
 126     root, and that you are not using any custom MIME types or multiple
 127     roots. To enable the Apache support, you can set the following option.
 128
 129         MyApp->config->{static}->{use_apache} = 1;
 130
 131     By default this option is disabled because after several benchmarks it
 132     appears that just serving the file from Catalyst is the better option.
 133     On a 3K file, Catalyst appears to be around 25% faster, and is 42%
 134     faster on a 10K file. My benchmarking was done using the following
 135     'siege' command, so other benchmarks would be welcome!
 136
 137         siege -u http://server/static/css/10K.css -b -t 1M -c 1
 138
 139     For best static performance, you should still serve your static files
 140     directly from Apache by defining a Location block similar to the
 141     following:
 142
 143         <Location /static>
 144             SetHandler default-handler
 145         </Location>
 146
 147   Bypassing other plugins
 148     This plugin checks for a static file in the prepare_action stage. If the
 149     request is for a static file, it will bypass all remaining
 150     prepare_action steps. This means that by placing Static::Simple before
 151     all other plugins, they will not execute when a static file is found.
 152     This can be helpful by skipping session cookie checks for example. Or,
 153     if you want some plugins to run even on static files, list them before
 154     Static::Simple.
 155
 156     Currently, work done by plugins in any other prepare method will execute
 157     normally.
 158
 159   Debugging information
 160     Enable additional debugging information printed in the Catalyst log.
 161     This is automatically enabled when running Catalyst in -Debug mode.
 162
 163         MyApp->config->{static}->{debug} = 1;
 164
 165 SEE ALSO
 166     Catalyst, Catalyst::Plugin::Static,
 167     <http://www.iana.org/assignments/media-types/>
 168
 169 AUTHOR
 170     Andy Grundman, <andy@hybridized.org>
 171
 172 CONTRIBUTORS
 173     Marcus Ramberg, <mramberg@cpan.org>
 174
 175 THANKS
 176     The authors of Catalyst::Plugin::Static:
 177
 178         Sebastian Riedel
 179         Christian Hansen
 180         Marcus Ramberg
 181
 182     For the include_path code from Template Toolkit:
 183
 184         Andy Wardley
 185
 186 COPYRIGHT
 187     This program is free software, you can redistribute it and/or modify it
 188     under the same terms as Perl itself.
 189