Debian Codegraph @

README

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