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 application 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->{Plugin::Static::Simple}". If you use any of these
71 options, this 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->{Plugin::Static::Simple}->{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 'Plugin::Static::Simple' => {
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 'Plugin::Static::Simple' => {
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 be
122 called every time a file is requested that appears to be a static file
123 (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 'Plugin::Static::Simple' => {
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 'Plugin::Static::Simple' => {
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 'Plugin::Static::Simple' => {
180 mime_types => {
181 jpg => 'image/jpg',
182 png => 'image/png',
183 },
184 },
185 );
186 Controlling caching with Expires header
188 The files served by Static::Simple will have a Last-Modified header
189 set, which allows some browsers to cache them for a while. However if
190 you want to explicitly set an Expires header, such as to allow proxies
191 to cache your static content, then you can do so by setting the
192 "expires" config option.
193 The value indicates the number of seconds after access time to allow
195 caching. So a value of zero really means "don't cache at all", and any
196 higher values will keep the file around for that long.
197 MyApp->config(
199 'Plugin::Static::Simple' => {
200 expires => 3600, # Caching allowed for one hour.
201 },
202 );
203 Compatibility with other plugins
205 Since version 0.12, Static::Simple plays nice with other plugins. It
206 no longer short-circuits the "prepare_action" stage as it was causing
207 too many compatibility issues with other plugins.
208 Debugging information
210 Enable additional debugging information printed in the Catalyst log.
211 This is automatically enabled when running Catalyst in -Debug mode.
212 MyApp->config(
214 'Plugin::Static::Simple' => {
215 debug => 1,
216 },
217 );
218
220 While Static::Simple will work just fine serving files through Catalyst
221 in mod_perl, for increased performance you may wish to have Apache
222 handle the serving of your static files directly. To do this, simply
223 use a dedicated directory for your static files and configure an Apache
224 Location block for that directory This approach is recommended for
225 production installations.
226 <Location /myapp/static>
228 SetHandler default-handler
229 </Location>
230 Using this approach Apache will bypass any handling of these
232 directories through Catalyst. You can leave Static::Simple as part of
233 your application, and it will continue to function on a development
234 server, or using Catalyst's built-in server.
235 In practice, your Catalyst application is probably (i.e. should be)
237 structured in the recommended way (i.e., that generated by
238 bootstrapping the application with the "catalyst.pl" script, with a
239 main directory under which is a "lib/" directory for module files and a
240 "root/" directory for templates and static files). Thus, unless you
241 break up this structure when deploying your app by moving the static
242 files to a different location in your filesystem, you will need to use
243 an Alias directive in Apache to point to the right place. You will then
244 need to add a Directory block to give permission for Apache to serve
245 these files. The final configuration will look something like this:
246 Alias /myapp/static /filesystem/path/to/MyApp/root/static
248 <Directory /filesystem/path/to/MyApp/root/static>
249 allow from all
250 </Directory>
251 <Location /myapp/static>
252 SetHandler default-handler
253 </Location>
254 If you are running in a VirtualHost, you can just set the DocumentRoot
256 location to the location of your root directory; see
257 Catalyst::Engine::Apache2::MP20.
258
260 serve_static_file $file_path
261 Will serve the file located in $file_path statically. This is useful
262 when you need to autogenerate them if they don't exist, or they are
263 stored in a model.
264 package MyApp::Controller::User;
266 sub curr_user_thumb : PathPart("my_thumbnail.png") {
268 my ( $self, $c ) = @_;
269 my $file_path = $c->user->picture_thumbnail_path;
270 $c->serve_static_file($file_path);
271 }
272
274 Static::Simple extends the following steps in the Catalyst process.
275 prepare_action
277 "prepare_action" is used to first check if the request path is a static
278 file. If so, we skip all other "prepare_action" steps to improve
279 performance.
280 dispatch
282 "dispatch" takes the file found during "prepare_action" and writes it
283 to the output.
284 finalize
286 "finalize" serves up final header information and displays any log
287 messages.
288 setup
290 "setup" initializes all default values.
291
293 The old style of configuration using the 'static' config key was
294 deprecated in version 0.30. A warning will be issued if this is used,
295 and the contents of the config at this key will be merged with the
296 newer 'Plugin::Static::Simple' key.
297 Be aware that if the 'include_path' key under 'static' exists at all,
299 it will be merged with any content of the same key under
300 'Plugin::Static::Simple'. Be careful not to set this to a non-arrayref,
301 therefore.
302
304 Catalyst, Catalyst::Plugin::Static,
305 <http://www.iana.org/assignments/media-types/>
306
308 Andy Grundman, <andy@hybridized.org>
309
311 Marcus Ramberg, <mramberg@cpan.org>
312 Jesse Sheidlower, <jester@panix.com>
314 Guillermo Roditi, <groditi@cpan.org>
316 Florian Ragwitz, <rafl@debian.org>
318 Tomas Doran, <bobtfish@bobtfish.net>
320 Justin Wheeler (dnm)
322 Matt S Trout, <mst@shadowcat.co.uk>
324 Toby Corkindale, <tjc@wintrmute.net>
326
328 The authors of Catalyst::Plugin::Static:
329 Sebastian Riedel
331 Christian Hansen
332 Marcus Ramberg
333 For the include_path code from Template Toolkit:
335 Andy Wardley
337
339 Copyright (c) 2005 - 2011 the Catalyst::Plugin::Static::Simple "AUTHOR"
340 and "CONTRIBUTORS" as listed above.
341
343 This program is free software, you can redistribute it and/or modify it
344 under the same terms as Perl itself.
345perl v5.36.0 2023-01-20Catalyst::Plugin::Static::Simple(3)