2 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
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
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.
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.
22 Note that actions mapped to paths using periods (.) will still operate
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.
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
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.
46 Logging of static files is turned off by default.
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!
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}"
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//".
65 MyApp->config->{static}->{dirs} = [
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.
77 MyApp->config->{static}->{include_path} = [
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:
86 /path/to/overlay/images/logo.jpg
87 /dynamic/path/images/logo.jpg
88 /your/app/home/root/images/logo.jpg
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).
99 sub incpath_generator {
102 if ( $c->session->{customer_dir} ) {
103 return [ $c->session->{customer_dir} ];
105 die "No customer dir defined.";
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"
117 MyApp->config->{static}->{ignore_extensions}
118 = [ qw/html asp php/ ];
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.
126 MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
128 For example, if combined with the above "include_path" setting, this
129 "ignore_dirs" value will ignore the following directories if they exist:
131 /path/to/overlay/tmpl
135 /your/app/home/root/tmpl
136 /your/app/home/root/css
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.
142 MyApp->config->{static}->{mime_types} = {
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.
152 Debugging information
153 Enable additional debugging information printed in the Catalyst log.
154 This is automatically enabled when running Catalyst in -Debug mode.
156 MyApp->config->{static}->{debug} = 1;
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.
167 SetHandler default-handler
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.
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
181 package MyApp::Controller::User;
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);
189 INTERNAL EXTENDED METHODS
190 Static::Simple extends the following steps in the Catalyst process.
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
198 "dispatch" takes the file found during "prepare_action" and writes it to
202 "finalize" serves up final header information and displays any log
206 "setup" initializes all default values.
209 Catalyst, Catalyst::Plugin::Static,
210 <http://www.iana.org/assignments/media-types/>
213 Andy Grundman, <andy@hybridized.org>
216 Marcus Ramberg, <mramberg@cpan.org>
218 Jesse Sheidlower, <jester@panix.com>
220 Guillermo Roditi, <groditi@cpan.org>
223 The authors of Catalyst::Plugin::Static:
229 For the include_path code from Template Toolkit:
234 This program is free software, you can redistribute it and/or modify it
235 under the same terms as Perl itself.