Catalyst::Plugin::StatUserSContributed PerlCatalyst::Plugin::Static::Simple(3)NAMECatalyst::Plugin::Static::Simple - Make serving static pages painless.
SYNOPSIS
package MyApp;
use Catalyst qw/ Static::Simple /;
MyApp->setup;
# that's it; static content is automatically served by Catalyst
# from the application's root directory, though you can configure
# things or bypass Catalyst entirely in a production environment
#
# one caveat: the files must be served from an absolute path
# (i.e. /images/foo.png)
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.
This plugin detects static files by looking at the file extension in
the URL (such as .css or .png or .js). The plugin uses the lightweight
MIME::Types module to map file extensions to IANA-registered MIME
types, and will serve your static files with the correct MIME type
directly to the browser, without being processed through Catalyst.
Note that actions mapped to paths using periods (.) will still operate
properly.
If the plugin can not find the file, the request is dispatched to your
application instead. This means you are responsible for generating a
404 error if your applicaton can not process the request:
# handled by static::simple, not dispatched to your application
/images/exists.png
# static::simple will not find the file and let your application
# handle the request. You are responsible for generating a file
# or returning a 404 error
/images/does_not_exist.png
Though Static::Simple is designed to work out-of-the-box, you can tweak
the operation by adding various configuration options. In a production
environment, you will probably want to use your webserver to deliver
static content; for an example see "USING WITH APACHE", below.
DEFAULT BEHAVIOR
By default, Static::Simple will deliver all files having extensions
(that is, bits of text following a period (".")), except files having
the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
and all files without extensions, will be processed through Catalyst.
If MIME::Types doesn't recognize an extension, it will be served as
"text/plain".
To restate: files having the extensions "tmpl", "tt", "tt2", "html",
and "xhtml" will not be served statically by default, they will be
processed by Catalyst. Thus if you want to use ".html" files from
within a Catalyst app as static files, you need to change the
configuration of Static::Simple. Note also that files having any other
extension will be served statically, so if you're using any other
extension for template files, you should also change the configuration.
Logging of static files is turned off by default.
ADVANCED CONFIGURATION
Configuration is completely optional and is specified within
"MyApp->config->{static}". If you use any of these options, this
module will probably feel less "simple" to you!
Enabling request logging
Since Catalyst 5.50, logging of static requests is turned off by
default; static requests tend to clutter the log output and rarely
reveal anything useful. However, if you want to enable logging of
static requests, you can do so by setting
"MyApp->config->{static}->{logging}" to 1.
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 "tmpl", "tt", "tt2", "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/html asp php/ ],
},
);
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',
},
},
);
Compatibility with other plugins
Since version 0.12, Static::Simple plays nice with other plugins. It
no longer short-circuits the "prepare_action" stage as it was causing
too many compatibility issues with other plugins.
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,
},
);
USING WITH APACHE
While Static::Simple will work just fine serving files through Catalyst
in mod_perl, for increased performance you may wish to have Apache
handle the serving of your static files directly. To do this, simply
use a dedicated directory for your static files and configure an Apache
Location block for that directory This approach is recommended for
production installations.
<Location /myapp/static>
SetHandler default-handler
</Location>
Using this approach Apache will bypass any handling of these
directories through Catalyst. You can leave Static::Simple as part of
your application, and it will continue to function on a development
server, or using Catalyst's built-in server.
In practice, your Catalyst application is probably (i.e. should be)
structured in the recommended way (i.e., that generated by
bootstrapping the application with the "catalyst.pl" script, with a
main directory under which is a "lib/" directory for module files and a
"root/" directory for templates and static files). Thus, unless you
break up this structure when deploying your app by moving the static
files to a different location in your filesystem, you will need to use
an Alias directive in Apache to point to the right place. You will then
need to add a Directory block to give permission for Apache to serve
these files. The final configuration will look something like this:
Alias /myapp/static /filesystem/path/to/MyApp/root/static
<Directory /filesystem/path/to/MyApp/root/static>
allow from all
</Directory>
<Location /myapp/static>
SetHandler default-handler
</Location>
If you are running in a VirtualHost, you can just set the DocumentRoot
location to the location of your root directory; see
Catalyst::Engine::Apache2::MP20.
PUBLIC METHODS
serve_static_file $file_path
Will serve the file located in $file_path statically. This is useful
when you need to autogenerate them if they don't exist, or they are
stored in a model.
package MyApp::Controller::User;
sub curr_user_thumb : PathPart("my_thumbnail.png") {
my ( $self, $c ) = @_;
my $file_path = $c->user->picture_thumbnail_path;
$c->serve_static_file($file_path);
}
INTERNAL EXTENDED METHODS
Static::Simple extends the following steps in the Catalyst process.
prepare_action
"prepare_action" is used to first check if the request path is a static
file. If so, we skip all other "prepare_action" steps to improve
performance.
dispatch
"dispatch" takes the file found during "prepare_action" and writes it
to the output.
finalize
"finalize" serves up final header information and displays any log
messages.
setup
"setup" initializes all default values.
SEE ALSO
Catalyst, Catalyst::Plugin::Static,
http://www.iana.org/assignments/media-types/
<http://www.iana.org/assignments/media-types/>
AUTHOR
Andy Grundman, <andy@hybridized.org>
CONTRIBUTORS
Marcus Ramberg, <mramberg@cpan.org>
Jesse Sheidlower, <jester@panix.com>
Guillermo Roditi, <groditi@cpan.org>
Florian Ragwitz, <rafl@debian.org>
Tomas Doran, <bobtfish@bobtfish.net>
Justin Wheeler (dnm)
Matt S Trout, <mst@shadowcat.co.uk>
THANKS
The authors of Catalyst::Plugin::Static:
Sebastian Riedel
Christian Hansen
Marcus Ramberg
For the include_path code from Template Toolkit:
Andy Wardley
COPYRIGHT
Copyright (c) 2005 - 2009 the Catalyst::Plugin::Static::Simple "AUTHOR"
and "CONTRIBUTORS" as listed above.
LICENSE
This program is free software, you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.12010-02-0Catalyst::Plugin::Static::Simple(3)
