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     Forcing directories into static mode
  31         Define a list of top-level directories beneath your 'root' directory
  32         that should always be served in static mode. Regular expressions may
  33         be specified using qr//.
  34
  35             MyApp->config->{static}->{dirs} = [
  36                 'static',
  37                 qr/^(images|css)/,
  38             ];
  39
  40     Including additional directories (experimental!)
  41         You may specify a list of directories in which to search for your
  42         static files. The directories will be searched in order and will
  43         return the first file found. Note that your root directory is not
  44         automatically added to the search path when you specify an
  45         include_path. You should use MyApp->config->{root} to add it.
  46
  47             MyApp->config->{static}->{include_path} = [
  48                 '/path/to/overlay',
  49                 \&incpath_generator,
  50                 MyApp->config->{root}
  51             ];
  52
  53         With the above setting, a request for the file /images/logo.jpg will
  54         search for the following files, returning the first one found:
  55
  56             /path/to/overlay/images/logo.jpg
  57             /dynamic/path/images/logo.jpg
  58             /your/app/home/root/images/logo.jpg
  59
  60         The include path can contain a subroutine reference to dynamically
  61         return a list of available directories. This method will receive the
  62         $c object as a parameter and should return a reference to a list of
  63         directories. Errors can be reported using die(). This method will be
  64         called every time a file is requested that appears to be a static
  65         file (i.e. it has an extension).
  66
  67         For example:
  68
  69             sub incpath_generator {
  70                 my $c = shift;
  71
  72                 if ( $c->session->{customer_dir} ) {
  73                     return [ $c->session->{customer_dir} ];
  74                 } else {
  75                     die "No customer dir defined.";
  76                 }
  77             }
  78
  79     Custom MIME types
  80         To override or add to the default MIME types set by the MIME::Types
  81         module, you may enter your own extension to MIME type mapping.
  82
  83             MyApp->config->{static}->{mime_types} = {
  84                 jpg => 'image/jpg',
  85                 png => 'image/png',
  86             };
  87
  88     Apache integration and performance
  89         Optionally, when running under mod_perl, Static::Simple can return
  90         DECLINED on static files to allow Apache to serve the file. A check
  91         is first done to make sure that Apache's DocumentRoot matches your
  92         Catalyst root, and that you are not using any custom MIME types or
  93         multiple roots. To enable the Apache support, you can set the
  94         following option.
  95
  96             MyApp->config->{static}->{use_apache} = 1;
  97
  98         By default this option is disabled because after several benchmarks
  99         it appears that just serving the file from Catalyst is the better
 100         option. On a 3K file, Catalyst appears to be around 25% faster, and
 101         is 42% faster on a 10K file. My benchmarking was done using the
 102         following 'siege' command, so other benchmarks would be welcome!
 103
 104             siege -u http://server/static/css/10K.css b -t 1M -c 1
 105
 106         For best static performance, you should still serve your static
 107         files directly from Apache by defining a Location block similar to
 108         the following:
 109
 110             <Location /static>
 111                 SetHandler default-handler
 112             </Location>
 113
 114     Debugging information
 115         Enable additional debugging information printed in the Catalyst log.
 116         This is automatically enabled when running Catalyst in -Debug mode.
 117
 118             MyApp->config->{static}->{debug} = 1;
 119
 120 SEE ALSO
 121     Catalyst, Catalyst::Plugin::Static,
 122     <http://www.iana.org/assignments/media-types/>
 123
 124 AUTHOR
 125     Andy Grundman, "andy@hybridized.org"
 126
 127 THANKS
 128     The authors of Catalyst::Plugin::Static:
 129
 130         Sebastian Riedel
 131         Christian Hansen
 132         Marcus Ramberg
 133
 134     For the include_path code from Template Toolkit:
 135
 136         Andy Wardley
 137
 138 COPYRIGHT
 139     This program is free software, you can redistribute it and/or modify it
 140     under the same terms as Perl itself.
 141