Catalyst::Plugin::Static::Simple(3pm)

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           use Catalyst;
10           MyApp->setup( qw/Static::Simple/ );
11           # that's it; static content is automatically served by Catalyst
12           # from the application's root directory, though you can configure
13           # things or bypass Catalyst entirely in a production environment
14           #
15           # one caveat: the files must be served from an absolute path
16           # (ie. /images/foo.png)
17

DESCRIPTION

19       The Static::Simple plugin is designed to make serving static content in
20       your application during development quick and easy, without requiring a
21       single line of code from you.
22
23       This plugin detects static files by looking at the file extension in
24       the URL (such as .css or .png or .js). The plugin uses the lightweight
25       MIME::Types module to map file extensions to IANA-registered MIME
26       types, and will serve your static files with the correct MIME type
27       directly to the browser, without being processed through Catalyst.
28
29       Note that actions mapped to paths using periods (.) will still operate
30       properly.
31
32       Though Static::Simple is designed to work out-of-the-box, you can tweak
33       the operation by adding various configuration options. In a production
34       environment, you will probably want to use your webserver to deliver
35       static content; for an example see "USING WITH APACHE", below.
36

DEFAULT BEHAVIOR

38       By default, Static::Simple will deliver all files having extensions
39       (that is, bits of text following a period (".")), except files having
40       the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
41       and all files without extensions, will be processed through Catalyst.
42       If MIME::Types doesn't recognize an extension, it will be served as
43       "text/plain".
44
45       To restate: files having the extensions "tmpl", "tt", "tt2", "html",
46       and "xhtml" will not be served statically by default, they will be pro‐
47       cessed by Catalyst. Thus if you want to use ".html" files from within a
48       Catalyst app as static files, you need to change the configuration of
49       Static::Simple. Note also that files having any other extension will be
50       served statically, so if you're using any other extension for template
51       files, you should also change the configuration.
52
53       Logging of static files is turned off by default.
54

ADVANCED CONFIGURATION

56       Configuration is completely optional and is specified within
57       "MyApp->config->{static}".  If you use any of these options, this mod‐
58       ule will probably feel less "simple" to you!
59
60       Enabling request logging
61
62       Since Catalyst 5.50, logging of static requests is turned off by
63       default; static requests tend to clutter the log output and rarely
64       reveal anything useful. However, if you want to enable logging of
65       static requests, you can do so by setting "MyApp->con‐
66       fig->{static}->{logging}" to 1.
67
68       Forcing directories into static mode
69
70       Define a list of top-level directories beneath your 'root' directory
71       that should always be served in static mode.  Regular expressions may
72       be specified using "qr//".
73
74           MyApp->config->{static}->{dirs} = [
75               'static',
76               qr/^(images⎪css)/,
77           ];
78
79       Including additional directories
80
81       You may specify a list of directories in which to search for your
82       static files. The directories will be searched in order and will return
83       the first file found. Note that your root directory is not automati‐
84       cally added to the search path when you specify an "include_path". You
85       should use "MyApp->config->{root}" to add it.
86
87           MyApp->config->{static}->{include_path} = [
88               '/path/to/overlay',
89               \&incpath_generator,
90               MyApp->config->{root}
91           ];
92
93       With the above setting, a request for the file "/images/logo.jpg" will
94       search for the following files, returning the first one found:
95
96           /path/to/overlay/images/logo.jpg
97           /dynamic/path/images/logo.jpg
98           /your/app/home/root/images/logo.jpg
99
100       The include path can contain a subroutine reference to dynamically
101       return a list of available directories.  This method will receive the
102       $c object as a parameter and should return a reference to a list of
103       directories.  Errors can be reported using "die()".  This method will
104       be called every time a file is requested that appears to be a static
105       file (i.e. it has an extension).
106
107       For example:
108
109           sub incpath_generator {
110               my $c = shift;
111
112               if ( $c->session->{customer_dir} ) {
113                   return [ $c->session->{customer_dir} ];
114               } else {
115                   die "No customer dir defined.";
116               }
117           }
118
119       Ignoring certain types of files
120
121       There are some file types you may not wish to serve as static files.
122       Most important in this category are your raw template files.  By
123       default, files with the extensions "tmpl", "tt", "tt2", "html", and
124       "xhtml" will be ignored by Static::Simple in the interest of security.
125       If you wish to define your own extensions to ignore, use the
126       "ignore_extensions" option:
127
128           MyApp->config->{static}->{ignore_extensions}
129               = [ qw/html asp php/ ];
130
131       Ignoring entire directories
132
133       To prevent an entire directory from being served statically, you can
134       use the "ignore_dirs" option.  This option contains a list of relative
135       directory paths to ignore.  If using "include_path", the path will be
136       checked against every included path.
137
138           MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
139
140       For example, if combined with the above "include_path" setting, this
141       "ignore_dirs" value will ignore the following directories if they
142       exist:
143
144           /path/to/overlay/tmpl
145           /path/to/overlay/css
146           /dynamic/path/tmpl
147           /dynamic/path/css
148           /your/app/home/root/tmpl
149           /your/app/home/root/css
150
151       Custom MIME types
152
153       To override or add to the default MIME types set by the MIME::Types
154       module, you may enter your own extension to MIME type mapping.
155
156           MyApp->config->{static}->{mime_types} = {
157               jpg => 'image/jpg',
158               png => 'image/png',
159           };
160
161       Compatibility with other plugins
162
163       Since version 0.12, Static::Simple plays nice with other plugins.  It
164       no longer short-circuits the "prepare_action" stage as it was causing
165       too many compatibility issues with other plugins.
166
167       Debugging information
168
169       Enable additional debugging information printed in the Catalyst log.
170       This is automatically enabled when running Catalyst in -Debug mode.
171
172           MyApp->config->{static}->{debug} = 1;
173

USING WITH APACHE

175       While Static::Simple will work just fine serving files through Catalyst
176       in mod_perl, for increased performance, you may wish to have Apache
177       handle the serving of your static files.  To do this, simply use a ded‐
178       icated directory for your static files and configure an Apache Location
179       block for that directory.  This approach is recommended for production
180       installations.
181
182           <Location /static>
183               SetHandler default-handler
184           </Location>
185
186       Using this approach Apache will bypass any handling of these directo‐
187       ries through Catalyst. You can leave Static::Simple as part of your
188       application, and it will continue to function on a development server,
189       or using Catalyst's built-in server.
190

PUBLIC METHODS

192       serve_static_file $file_path
193
194       Will serve the file located in $file_path statically. This is useful
195       when you need to  autogenerate them if they don't exist, or they are
196       stored in a model.
197
198           package MyApp::Controller::User;
199
200           sub curr_user_thumb : PathPart("my_thumbnail.png") {
201               my ( $self, $c ) = @_;
202               my $file_path = $c->user->picture_thumbnail_path;
203               $c->serve_static_file($file_path);
204           }
205

INTERNAL EXTENDED METHODS

207       Static::Simple extends the following steps in the Catalyst process.
208
209       prepare_action
210
211       "prepare_action" is used to first check if the request path is a static
212       file.  If so, we skip all other "prepare_action" steps to improve per‐
213       formance.
214
215       dispatch
216
217       "dispatch" takes the file found during "prepare_action" and writes it
218       to the output.
219
220       finalize
221
222       "finalize" serves up final header information and displays any log mes‐
223       sages.
224
225       setup
226
227       "setup" initializes all default values.
228

AUTHOR

234       Andy Grundman, <andy@hybridized.org>
235

CONTRIBUTORS

237       Marcus Ramberg, <mramberg@cpan.org>
238
239       Jesse Sheidlower, <jester@panix.com>
240
241       Guillermo Roditi, <groditi@cpan.org>
242

THANKS

244       The authors of Catalyst::Plugin::Static:
245
246           Sebastian Riedel
247           Christian Hansen
248           Marcus Ramberg
249
250       For the include_path code from Template Toolkit:
251
252           Andy Wardley
253

COPYRIGHT

255       This program is free software, you can redistribute it and/or modify it
256       under the same terms as Perl itself.
257
258
259
260perl v5.8.8                       2008-03-15Catalyst::Plugin::Static::Simple(3)