1Catalyst::Plugin::StatiUcs:e:rSiCmopnlter(i3b)uted PerlCDaotcaulmyesntt:a:tPiloungin::Static::Simple(3)
2
6 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
7
9 package MyApp;
10 use Catalyst qw/ Static::Simple /;
11 MyApp->setup;
12 # that's it; static content is automatically served by Catalyst
13 # from the application's root directory, though you can configure
14 # things or bypass Catalyst entirely in a production environment
15 #
16 # one caveat: the files must be served from an absolute path
17 # (i.e. /images/foo.png)
18
20 The Static::Simple plugin is designed to make serving static content in
21 your application during development quick and easy, without requiring a
22 single line of code from you.
23 This plugin detects static files by looking at the file extension in
25 the URL (such as .css or .png or .js). The plugin uses the lightweight
26 MIME::Types module to map file extensions to IANA-registered MIME
27 types, and will serve your static files with the correct MIME type
28 directly to the browser, without being processed through Catalyst.
29 Note that actions mapped to paths using periods (.) will still operate
31 properly.
32 If the plugin can not find the file, the request is dispatched to your
34 application instead. This means you are responsible for generating a
35 404 error if your applicaton can not process the request:
36 # handled by static::simple, not dispatched to your application
38 /images/exists.png
39 # static::simple will not find the file and let your application
41 # handle the request. You are responsible for generating a file
42 # or returning a 404 error
43 /images/does_not_exist.png
44 Though Static::Simple is designed to work out-of-the-box, you can tweak
46 the operation by adding various configuration options. In a production
47 environment, you will probably want to use your webserver to deliver
48 static content; for an example see "USING WITH APACHE", below.
49
51 By default, Static::Simple will deliver all files having extensions
52 (that is, bits of text following a period (".")), except files having
53 the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
54 and all files without extensions, will be processed through Catalyst.
55 If MIME::Types doesn't recognize an extension, it will be served as
56 "text/plain".
57 To restate: files having the extensions "tmpl", "tt", "tt2", "html",
59 and "xhtml" will not be served statically by default, they will be
60 processed by Catalyst. Thus if you want to use ".html" files from
61 within a Catalyst app as static files, you need to change the
62 configuration of Static::Simple. Note also that files having any other
63 extension will be served statically, so if you're using any other
64 extension for template files, you should also change the configuration.
65 Logging of static files is turned off by default.
67
69 Configuration is completely optional and is specified within
70 "MyApp->config->{static}". If you use any of these options, this
71 module will probably feel less "simple" to you!
72 Enabling request logging
74 Since Catalyst 5.50, logging of static requests is turned off by
75 default; static requests tend to clutter the log output and rarely
76 reveal anything useful. However, if you want to enable logging of
77 static requests, you can do so by setting
78 "MyApp->config->{static}->{logging}" to 1.
79 Forcing directories into static mode
81 Define a list of top-level directories beneath your 'root' directory
82 that should always be served in static mode. Regular expressions may
83 be specified using "qr//".
84 MyApp->config(
86 static => {
87 dirs => [
88 'static',
89 qr/^(images|css)/,
90 ],
91 }
92 );
93 Including additional directories
95 You may specify a list of directories in which to search for your
96 static files. The directories will be searched in order and will return
97 the first file found. Note that your root directory is not
98 automatically added to the search path when you specify an
99 "include_path". You should use "MyApp->config->{root}" to add it.
100 MyApp->config(
102 static => {
103 include_path => [
104 '/path/to/overlay',
105 \&incpath_generator,
106 MyApp->config->{root},
107 ],
108 },
109 );
110 With the above setting, a request for the file "/images/logo.jpg" will
112 search for the following files, returning the first one found:
113 /path/to/overlay/images/logo.jpg
115 /dynamic/path/images/logo.jpg
116 /your/app/home/root/images/logo.jpg
117 The include path can contain a subroutine reference to dynamically
119 return a list of available directories. This method will receive the
120 $c object as a parameter and should return a reference to a list of
121 directories. Errors can be reported using "die()". This method will
122 be called every time a file is requested that appears to be a static
123 file (i.e. it has an extension).
124 For example:
126 sub incpath_generator {
128 my $c = shift;
129 if ( $c->session->{customer_dir} ) {
131 return [ $c->session->{customer_dir} ];
132 } else {
133 die "No customer dir defined.";
134 }
135 }
136 Ignoring certain types of files
138 There are some file types you may not wish to serve as static files.
139 Most important in this category are your raw template files. By
140 default, files with the extensions "tmpl", "tt", "tt2", "html", and
141 "xhtml" will be ignored by Static::Simple in the interest of security.
142 If you wish to define your own extensions to ignore, use the
143 "ignore_extensions" option:
144 MyApp->config(
146 static => {
147 ignore_extensions => [ qw/html asp php/ ],
148 },
149 );
150 Ignoring entire directories
152 To prevent an entire directory from being served statically, you can
153 use the "ignore_dirs" option. This option contains a list of relative
154 directory paths to ignore. If using "include_path", the path will be
155 checked against every included path.
156 MyApp->config(
158 static => {
159 ignore_dirs => [ qw/tmpl css/ ],
160 },
161 );
162 For example, if combined with the above "include_path" setting, this
164 "ignore_dirs" value will ignore the following directories if they
165 exist:
166 /path/to/overlay/tmpl
168 /path/to/overlay/css
169 /dynamic/path/tmpl
170 /dynamic/path/css
171 /your/app/home/root/tmpl
172 /your/app/home/root/css
173 Custom MIME types
175 To override or add to the default MIME types set by the MIME::Types
176 module, you may enter your own extension to MIME type mapping.
177 MyApp->config(
179 static => {
180 mime_types => {
181 jpg => 'image/jpg',
182 png => 'image/png',
183 },
184 },
185 );
186 Compatibility with other plugins
188 Since version 0.12, Static::Simple plays nice with other plugins. It
189 no longer short-circuits the "prepare_action" stage as it was causing
190 too many compatibility issues with other plugins.
191 Debugging information
193 Enable additional debugging information printed in the Catalyst log.
194 This is automatically enabled when running Catalyst in -Debug mode.
195 MyApp->config(
197 static => {
198 debug => 1,
199 },
200 );
201
203 While Static::Simple will work just fine serving files through Catalyst
204 in mod_perl, for increased performance you may wish to have Apache
205 handle the serving of your static files directly. To do this, simply
206 use a dedicated directory for your static files and configure an Apache
207 Location block for that directory This approach is recommended for
208 production installations.
209 <Location /myapp/static>
211 SetHandler default-handler
212 </Location>
213 Using this approach Apache will bypass any handling of these
215 directories through Catalyst. You can leave Static::Simple as part of
216 your application, and it will continue to function on a development
217 server, or using Catalyst's built-in server.
218 In practice, your Catalyst application is probably (i.e. should be)
220 structured in the recommended way (i.e., that generated by
221 bootstrapping the application with the "catalyst.pl" script, with a
222 main directory under which is a "lib/" directory for module files and a
223 "root/" directory for templates and static files). Thus, unless you
224 break up this structure when deploying your app by moving the static
225 files to a different location in your filesystem, you will need to use
226 an Alias directive in Apache to point to the right place. You will then
227 need to add a Directory block to give permission for Apache to serve
228 these files. The final configuration will look something like this:
229 Alias /myapp/static /filesystem/path/to/MyApp/root/static
231 <Directory /filesystem/path/to/MyApp/root/static>
232 allow from all
233 </Directory>
234 <Location /myapp/static>
235 SetHandler default-handler
236 </Location>
237 If you are running in a VirtualHost, you can just set the DocumentRoot
239 location to the location of your root directory; see
240 Catalyst::Engine::Apache2::MP20.
241
243 serve_static_file $file_path
244 Will serve the file located in $file_path statically. This is useful
245 when you need to autogenerate them if they don't exist, or they are
246 stored in a model.
247 package MyApp::Controller::User;
249 sub curr_user_thumb : PathPart("my_thumbnail.png") {
251 my ( $self, $c ) = @_;
252 my $file_path = $c->user->picture_thumbnail_path;
253 $c->serve_static_file($file_path);
254 }
255
257 Static::Simple extends the following steps in the Catalyst process.
258 prepare_action
260 "prepare_action" is used to first check if the request path is a static
261 file. If so, we skip all other "prepare_action" steps to improve
262 performance.
263 dispatch
265 "dispatch" takes the file found during "prepare_action" and writes it
266 to the output.
267 finalize
269 "finalize" serves up final header information and displays any log
270 messages.
271 setup
273 "setup" initializes all default values.
274
276 Catalyst, Catalyst::Plugin::Static,
277 http://www.iana.org/assignments/media-types/
278 <http://www.iana.org/assignments/media-types/>
279
281 Andy Grundman, <andy@hybridized.org>
282
284 Marcus Ramberg, <mramberg@cpan.org>
285 Jesse Sheidlower, <jester@panix.com>
287 Guillermo Roditi, <groditi@cpan.org>
289 Florian Ragwitz, <rafl@debian.org>
291 Tomas Doran, <bobtfish@bobtfish.net>
293 Justin Wheeler (dnm)
295 Matt S Trout, <mst@shadowcat.co.uk>
297
299 The authors of Catalyst::Plugin::Static:
300 Sebastian Riedel
302 Christian Hansen
303 Marcus Ramberg
304 For the include_path code from Template Toolkit:
306 Andy Wardley
308
310 Copyright (c) 2005 - 2009 the Catalyst::Plugin::Static::Simple "AUTHOR"
311 and "CONTRIBUTORS" as listed above.
312
314 This program is free software, you can redistribute it and/or modify it
315 under the same terms as Perl itself.
316perl v5.12.0 2010-02-01Catalyst::Plugin::Static::Simple(3)