| Catalyst::Plugin::Static::Simple - Make serving static pages painless. |
Catalyst::Plugin::Static::Simple - Make serving static pages painless.
use Catalyst;
MyApp->setup( qw/Static::Simple/ );
# 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
# (ie. /images/foo.png)
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 the MIME::Types manpage 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.
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.
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 the MIME::Types manpage 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.
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!
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.
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)/,
];
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 C</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<$c> object as a
parameter and should return a reference to a list of directories. Errors can
be reported using C<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.";
}
}
=head2 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/ ];
=head2 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 C<include_path> setting, this
C<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
To override or add to the default MIME types set by the the MIME::Types manpage module, you may enter your own extension to MIME type mapping.
MyApp->config->{static}->{mime_types} = {
jpg => 'image/jpg',
png => 'image/png',
};
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.
Enable additional debugging information printed in the Catalyst log. This is automatically enabled when running Catalyst in -Debug mode.
MyApp->config->{static}->{debug} = 1;
=head1 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. 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 /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.
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);
}
Static::Simple extends the following steps in the Catalyst process.
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 takes the file found during prepare_action and writes it
to the output.
finalize serves up final header information and displays any log
messages.
setup initializes all default values.
Catalyst, the Catalyst::Plugin::Static manpage, http://www.iana.org/assignments/media-types/
Andy Grundman, <andy@hybridized.org>
Marcus Ramberg, <mramberg@cpan.org>
Jesse Sheidlower, <jester@panix.com>
Guillermo Roditi, <groditi@cpan.org>
The authors of Catalyst::Plugin::Static:
Sebastian Riedel
Christian Hansen
Marcus Ramberg
For the include_path code from Template Toolkit:
Andy Wardley
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
| Catalyst::Plugin::Static::Simple - Make serving static pages painless. |