1Catalyst::Plugin::StatiUcs:e:rSiCmopnlter(i3b)uted PerlCDaotcaulmyesntt:a:tPiloungin::Static::Simple(3)
2
3
4

NAME

6       Catalyst::Plugin::Static::Simple - Make serving static pages painless.
7

SYNOPSIS

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

DESCRIPTION

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
24       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
30       Note that actions mapped to paths using periods (.) will still operate
31       properly.
32
33       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
37          # handled by static::simple, not dispatched to your application
38          /images/exists.png
39
40          # 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
45       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

DEFAULT BEHAVIOUR

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
58       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
66       Logging of static files is turned off by default.
67

ADVANCED CONFIGURATION

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
73   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
80   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
85           MyApp->config(
86               'Plugin::Static::Simple' => {
87                   dirs => [
88                       'static',
89                       qr/^(images|css)/,
90                   ],
91               }
92           );
93
94   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
101           MyApp->config(
102               'Plugin::Static::Simple' => {
103                   include_path => [
104                       '/path/to/overlay',
105                       \&incpath_generator,
106                       MyApp->config->{root},
107                   ],
108               },
109           );
110
111       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
114           /path/to/overlay/images/logo.jpg
115           /dynamic/path/images/logo.jpg
116           /your/app/home/root/images/logo.jpg
117
118       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
125       For example:
126
127           sub incpath_generator {
128               my $c = shift;
129
130               if ( $c->session->{customer_dir} ) {
131                   return [ $c->session->{customer_dir} ];
132               } else {
133                   die "No customer dir defined.";
134               }
135           }
136
137   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
145           MyApp->config(
146               'Plugin::Static::Simple' => {
147                   ignore_extensions => [ qw/html asp php/ ],
148               },
149           );
150
151   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
157           MyApp->config(
158               'Plugin::Static::Simple' => {
159                   ignore_dirs => [ qw/tmpl css/ ],
160               },
161           );
162
163       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
167           /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
174   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
178           MyApp->config(
179               'Plugin::Static::Simple' => {
180                   mime_types => {
181                       jpg => 'image/jpg',
182                       png => 'image/png',
183                   },
184               },
185           );
186
187   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
194       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
198           MyApp->config(
199               'Plugin::Static::Simple' => {
200                   expires => 3600, # Caching allowed for one hour.
201               },
202           );
203
204   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
209   Debugging information
210       Enable additional debugging information printed in the Catalyst log.
211       This is automatically enabled when running Catalyst in -Debug mode.
212
213           MyApp->config(
214               'Plugin::Static::Simple' => {
215                   debug => 1,
216               },
217           );
218

USING WITH APACHE

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
227           <Location /myapp/static>
228               SetHandler default-handler
229           </Location>
230
231       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
236       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
247           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
255       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

PUBLIC METHODS

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
265           package MyApp::Controller::User;
266
267           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

INTERNAL EXTENDED METHODS

274       Static::Simple extends the following steps in the Catalyst process.
275
276   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
281   dispatch
282       "dispatch" takes the file found during "prepare_action" and writes it
283       to the output.
284
285   finalize
286       "finalize" serves up final header information and displays any log
287       messages.
288
289   setup
290       "setup" initializes all default values.
291

DEPRECATIONS

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
298       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

SEE ALSO

304       Catalyst, Catalyst::Plugin::Static,
305       <http://www.iana.org/assignments/media-types/>
306

AUTHOR

308       Andy Grundman, <andy@hybridized.org>
309

CONTRIBUTORS

311       Marcus Ramberg, <mramberg@cpan.org>
312
313       Jesse Sheidlower, <jester@panix.com>
314
315       Guillermo Roditi, <groditi@cpan.org>
316
317       Florian Ragwitz, <rafl@debian.org>
318
319       Tomas Doran, <bobtfish@bobtfish.net>
320
321       Justin Wheeler (dnm)
322
323       Matt S Trout, <mst@shadowcat.co.uk>
324
325       Toby Corkindale, <tjc@wintrmute.net>
326

THANKS

328       The authors of Catalyst::Plugin::Static:
329
330           Sebastian Riedel
331           Christian Hansen
332           Marcus Ramberg
333
334       For the include_path code from Template Toolkit:
335
336           Andy Wardley
337
339       Copyright (c) 2005 - 2011 the Catalyst::Plugin::Static::Simple "AUTHOR"
340       and "CONTRIBUTORS" as listed above.
341

LICENSE

343       This program is free software, you can redistribute it and/or modify it
344       under the same terms as Perl itself.
345
346
347
348perl v5.34.0                      2022-01-21Catalyst::Plugin::Static::Simple(3)
Impressum