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         # that's it; static content is automatically served by
   8         # Catalyst, though you can configure things or bypass
   9         # Catalyst entirely in a production environment
  10
  11 DESCRIPTION
  12     The Static::Simple plugin is designed to make serving static content in
  13     your application during development quick and easy, without requiring a
  14     single line of code from you.
  15
  16     This plugin detects static files by looking at the file extension in the
  17     URL (such as .css or .png or .js). The plugin uses the lightweight
  18     MIME::Types module to map file extensions to IANA-registered MIME types,
  19     and will serve your static files with the correct MIME type directly to
  20     the browser, without being processed through Catalyst.
  21
  22     Note that actions mapped to paths using periods (.) will still operate
  23     properly.
  24
  25     Though Static::Simple is designed to work out-of-the-box, you can tweak
  26     the operation by adding various configuration options. In a production
  27     environment, you will probably want to use your webserver to deliver
  28     static content; for an example see "USING WITH APACHE", below.
  29
  30 DEFAULT BEHAVIOR
  31     By default, Static::Simple will deliver all files having extensions
  32     (that is, bits of text following a period (".")), *except* files having
  33     the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
  34     and all files without extensions, will be processed through Catalyst. If
  35     MIME::Types doesn't recognize an extension, it will be served as
  36     "text/plain".
  37
  38     To restate: files having the extensions "tmpl", "tt", "tt2", "html", and
  39     "xhtml" *will not* be served statically by default, they will be
  40     processed by Catalyst. Thus if you want to use ".html" files from within
  41     a Catalyst app as static files, you need to change the configuration of
  42     Static::Simple. Note also that files having any other extension *will*
  43     be served statically, so if you're using any other extension for
  44     template files, you should also change the configuration.
  45
  46     Logging of static files is turned off by default.
  47
  48 ADVANCED CONFIGURATION
  49     Configuration is completely optional and is specified within
  50     "MyApp->config->{static}". If you use any of these options, this module
  51     will probably feel less "simple" to you!
  52
  53   Enabling request logging
  54     Since Catalyst 5.50, logging of static requests is turned off by
  55     default; static requests tend to clutter the log output and rarely
  56     reveal anything useful. However, if you want to enable logging of static
  57     requests, you can do so by setting "MyApp->config->{static}->{no_logs}"
  58     to 0.
  59
  60   Forcing directories into static mode
  61     Define a list of top-level directories beneath your 'root' directory
  62     that should always be served in static mode. Regular expressions may be
  63     specified using "qr//".
  64
  65         MyApp->config->{static}->{dirs} = [
  66             'static',
  67             qr/^(images|css)/,
  68         ];
  69
  70   Including additional directories
  71     You may specify a list of directories in which to search for your static
  72     files. The directories will be searched in order and will return the
  73     first file found. Note that your root directory is not automatically
  74     added to the search path when you specify an "include_path". You should
  75     use "MyApp->config->{root}" to add it.
  76
  77         MyApp->config->{static}->{include_path} = [
  78             '/path/to/overlay',
  79             \&incpath_generator,
  80             MyApp->config->{root}
  81         ];
  82
  83     With the above setting, a request for the file "/images/logo.jpg" will
  84     search for the following files, returning the first one found:
  85
  86         /path/to/overlay/images/logo.jpg
  87         /dynamic/path/images/logo.jpg
  88         /your/app/home/root/images/logo.jpg
  89
  90     The include path can contain a subroutine reference to dynamically
  91     return a list of available directories. This method will receive the $c
  92     object as a parameter and should return a reference to a list of
  93     directories. Errors can be reported using "die()". This method will be
  94     called every time a file is requested that appears to be a static file
  95     (i.e. it has an extension).
  96
  97     For example:
  98
  99         sub incpath_generator {
 100             my $c = shift;
 101
 102             if ( $c->session->{customer_dir} ) {
 103                 return [ $c->session->{customer_dir} ];
 104             } else {
 105                 die "No customer dir defined.";
 106             }
 107         }
 108
 109   Ignoring certain types of files
 110     There are some file types you may not wish to serve as static files.
 111     Most important in this category are your raw template files. By default,
 112     files with the extensions "tmpl", "tt", "tt2", "html", and "xhtml" will
 113     be ignored by Static::Simple in the interest of security. If you wish to
 114     define your own extensions to ignore, use the "ignore_extensions"
 115     option:
 116
 117         MyApp->config->{static}->{ignore_extensions}
 118             = [ qw/html asp php/ ];
 119
 120   Ignoring entire directories
 121     To prevent an entire directory from being served statically, you can use
 122     the "ignore_dirs" option. This option contains a list of relative
 123     directory paths to ignore. If using "include_path", the path will be
 124     checked against every included path.
 125
 126         MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
 127
 128     For example, if combined with the above "include_path" setting, this
 129     "ignore_dirs" value will ignore the following directories if they exist:
 130
 131         /path/to/overlay/tmpl
 132         /path/to/overlay/css
 133         /dynamic/path/tmpl
 134         /dynamic/path/css
 135         /your/app/home/root/tmpl
 136         /your/app/home/root/css
 137
 138   Custom MIME types
 139     To override or add to the default MIME types set by the MIME::Types
 140     module, you may enter your own extension to MIME type mapping.
 141
 142         MyApp->config->{static}->{mime_types} = {
 143             jpg => 'image/jpg',
 144             png => 'image/png',
 145         };
 146
 147   Compatibility with other plugins
 148     Since version 0.12, Static::Simple plays nice with other plugins. It no
 149     longer short-circuits the "prepare_action" stage as it was causing too
 150     many compatibility issues with other plugins.
 151
 152   Debugging information
 153     Enable additional debugging information printed in the Catalyst log.
 154     This is automatically enabled when running Catalyst in -Debug mode.
 155
 156         MyApp->config->{static}->{debug} = 1;
 157
 158 USING WITH APACHE
 159     While Static::Simple will work just fine serving files through Catalyst
 160     in mod_perl, for increased performance, you may wish to have Apache
 161     handle the serving of your static files. To do this, simply use a
 162     dedicated directory for your static files and configure an Apache
 163     Location block for that directory. This approach is recommended for
 164     production installations.
 165
 166         <Location /static>
 167             SetHandler default-handler
 168         </Location>
 169
 170     Using this approach Apache will bypass any handling of these directories
 171     through Catalyst. You can leave Static::Simple as part of your
 172     application, and it will continue to function on a development server,
 173     or using Catalyst's built-in server.
 174
 175 PUBLIC METHODS
 176   serve_static_file $file_path
 177     Will serve the file located in $file_path statically. This is useful
 178     when you need to autogenerate them if they don't exist, or they are
 179     stored in a model.
 180
 181         package MyApp::Controller::User;
 182
 183         sub curr_user_thumb : PathPart("my_thumbnail.png") {
 184             my ( $self, $c ) = @_;
 185             my $file_path = $c->user->picture_thumbnail_path;
 186             $c->serve_static_file($file_path);
 187         }
 188
 189 INTERNAL EXTENDED METHODS
 190     Static::Simple extends the following steps in the Catalyst process.
 191
 192   prepare_action
 193     "prepare_action" is used to first check if the request path is a static
 194     file. If so, we skip all other "prepare_action" steps to improve
 195     performance.
 196
 197   dispatch
 198     "dispatch" takes the file found during "prepare_action" and writes it to
 199     the output.
 200
 201   finalize
 202     "finalize" serves up final header information and displays any log
 203     messages.
 204
 205   setup
 206     "setup" initializes all default values.
 207
 208 SEE ALSO
 209     Catalyst, Catalyst::Plugin::Static,
 210     <http://www.iana.org/assignments/media-types/>
 211
 212 AUTHOR
 213     Andy Grundman, <andy@hybridized.org>
 214
 215 CONTRIBUTORS
 216     Marcus Ramberg, <mramberg@cpan.org>
 217
 218     Jesse Sheidlower, <jester@panix.com>
 219
 220     Guillermo Roditi, <groditi@cpan.org>
 221
 222 THANKS
 223     The authors of Catalyst::Plugin::Static:
 224
 225         Sebastian Riedel
 226         Christian Hansen
 227         Marcus Ramberg
 228
 229     For the include_path code from Template Toolkit:
 230
 231         Andy Wardley
 232
 233 COPYRIGHT
 234     This program is free software, you can redistribute it and/or modify it
 235     under the same terms as Perl itself.
 236