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 be
  33     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 static
  42     files. The directories will be searched in order and will return the
  43     first file found. Note that your root directory is not automatically
  44     added to the search path when you specify an include_path. You should
  45     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 $c
  62     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 file
  65     (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 is
  91     first done to make sure that Apache's DocumentRoot matches your Catalyst
  92     root, and that you are not using any custom MIME types or multiple
  93     roots. To enable the Apache support, you can set the following option.
  94
  95         MyApp->config->{static}->{use_apache} = 1;
  96
  97     By default this option is disabled because after several benchmarks it
  98     appears that just serving the file from Catalyst is the better option.
  99     On a 3K file, Catalyst appears to be around 25% faster, and is 42%
 100     faster on a 10K file. My benchmarking was done using the following
 101     'siege' command, so other benchmarks would be welcome!
 102
 103         siege -u http://server/static/css/10K.css -b -t 1M -c 1
 104
 105     For best static performance, you should still serve your static files
 106     directly from Apache by defining a Location block similar to the
 107     following:
 108
 109         <Location /static>
 110             SetHandler default-handler
 111         </Location>
 112
 113   Bypassing other plugins
 114     This plugin checks for a static file in the prepare_action stage. If the
 115     request is for a static file, it will bypass all remaining
 116     prepare_action steps. This means that by placing Static::Simple before
 117     all other plugins, they will not execute when a static file is found.
 118     This can be helpful by skipping session cookie checks for example. Or,
 119     if you want some plugins to run even on static files, list them before
 120     Static::Simple.
 121
 122     Currently, work done by plugins in any other prepare method will execute
 123     normally.
 124
 125   Debugging information
 126     Enable additional debugging information printed in the Catalyst log.
 127     This is automatically enabled when running Catalyst in -Debug mode.
 128
 129         MyApp->config->{static}->{debug} = 1;
 130
 131 SEE ALSO
 132     Catalyst, Catalyst::Plugin::Static,
 133     <http://www.iana.org/assignments/media-types/>
 134
 135 AUTHOR
 136     Andy Grundman, <andy@hybridized.org>
 137
 138 THANKS
 139     The authors of Catalyst::Plugin::Static:
 140
 141         Sebastian Riedel
 142         Christian Hansen
 143         Marcus Ramberg
 144
 145     For the include_path code from Template Toolkit:
 146
 147         Andy Wardley
 148
 149 COPYRIGHT
 150     This program is free software, you can redistribute it and/or modify it
 151     under the same terms as Perl itself.
 152