Commit | Line | Data |
d6d29b9b |
1 | NAME |
2 | Catalyst::Plugin::Static::Simple - Make serving static pages painless. |
3 | |
4 | SYNOPSIS |
5 | use Catalyst; |
6 | MyApp->setup( qw/Static::Simple/ ); |
99ce134b |
7 | # that's it; static content is automatically served by |
8 | # Catalyst, though you can configure things or bypass |
9 | # Catalyst entirely in a production environment |
d6d29b9b |
10 | |
11 | DESCRIPTION |
12 | The Static::Simple plugin is designed to make serving static content in |
13 | your application during development quick and easy, without requiring a |
14 | single line of code from you. |
15 | |
99ce134b |
16 | This plugin detects static files by looking at the file extension in the |
17 | URL (such as .css or .png or .js). The plugin uses the lightweight |
18 | MIME::Types module to map file extensions to IANA-registered MIME types, |
19 | and will serve your static files with the correct MIME type directly to |
20 | the browser, without being processed through Catalyst. |
d6d29b9b |
21 | |
22 | Note that actions mapped to paths using periods (.) will still operate |
23 | properly. |
24 | |
99ce134b |
25 | Though Static::Simple is designed to work out-of-the-box, you can tweak |
26 | the operation by adding various configuration options. In a production |
27 | environment, you will probably want to use your webserver to deliver |
28 | static content; for an example see "USING WITH APACHE", below. |
29 | |
30 | DEFAULT BEHAVIOR |
31 | By default, Static::Simple will deliver all files having extensions |
32 | (that is, bits of text following a period (".")), *except* files having |
33 | the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files, |
34 | and all files without extensions, will be processed through Catalyst. If |
35 | MIME::Types doesn't recognize an extension, it will be served as |
36 | "text/plain". |
37 | |
38 | To restate: files having the extensions "tmpl", "tt", "tt2", "html", and |
39 | "xhtml" *will not* be served statically by default, they will be |
40 | processed by Catalyst. Thus if you want to use ".html" files from within |
41 | a Catalyst app as static files, you need to change the configuration of |
42 | Static::Simple. Note also that files having any other extension *will* |
43 | be served statically, so if you're using any other extension for |
44 | template files, you should also change the configuration. |
45 | |
46 | Logging of static files is turned off by default. |
d6d29b9b |
47 | |
48 | ADVANCED CONFIGURATION |
49 | Configuration is completely optional and is specified within |
99ce134b |
50 | "MyApp->config->{static}". If you use any of these options, this module |
d6d29b9b |
51 | will probably feel less "simple" to you! |
52 | |
99ce134b |
53 | Enabling request logging |
54 | Since Catalyst 5.50, logging of static requests is turned off by |
55 | default; static requests tend to clutter the log output and rarely |
56 | reveal anything useful. However, if you want to enable logging of static |
57 | requests, you can do so by setting "MyApp->config->{static}->{no_logs}" |
58 | to 0. |
8cc672a2 |
59 | |
2268e329 |
60 | Forcing directories into static mode |
61 | Define a list of top-level directories beneath your 'root' directory |
62 | that should always be served in static mode. Regular expressions may be |
99ce134b |
63 | specified using "qr//". |
2268e329 |
64 | |
65 | MyApp->config->{static}->{dirs} = [ |
66 | 'static', |
67 | qr/^(images|css)/, |
68 | ]; |
69 | |
8cc672a2 |
70 | Including additional directories |
2268e329 |
71 | You may specify a list of directories in which to search for your static |
72 | files. The directories will be searched in order and will return the |
73 | first file found. Note that your root directory is not automatically |
99ce134b |
74 | added to the search path when you specify an "include_path". You should |
75 | use "MyApp->config->{root}" to add it. |
2268e329 |
76 | |
77 | MyApp->config->{static}->{include_path} = [ |
78 | '/path/to/overlay', |
79 | \&incpath_generator, |
80 | MyApp->config->{root} |
81 | ]; |
d6d29b9b |
82 | |
99ce134b |
83 | With the above setting, a request for the file "/images/logo.jpg" will |
2268e329 |
84 | search for the following files, returning the first one found: |
d6d29b9b |
85 | |
2268e329 |
86 | /path/to/overlay/images/logo.jpg |
87 | /dynamic/path/images/logo.jpg |
88 | /your/app/home/root/images/logo.jpg |
d6d29b9b |
89 | |
2268e329 |
90 | The include path can contain a subroutine reference to dynamically |
91 | return a list of available directories. This method will receive the $c |
92 | object as a parameter and should return a reference to a list of |
99ce134b |
93 | directories. Errors can be reported using "die()". This method will be |
2268e329 |
94 | called every time a file is requested that appears to be a static file |
95 | (i.e. it has an extension). |
d6d29b9b |
96 | |
2268e329 |
97 | For example: |
d6d29b9b |
98 | |
2268e329 |
99 | sub incpath_generator { |
100 | my $c = shift; |
d6d29b9b |
101 | |
2268e329 |
102 | if ( $c->session->{customer_dir} ) { |
103 | return [ $c->session->{customer_dir} ]; |
104 | } else { |
105 | die "No customer dir defined."; |
d6d29b9b |
106 | } |
2268e329 |
107 | } |
8cc672a2 |
108 | |
109 | Ignoring certain types of files |
110 | There are some file types you may not wish to serve as static files. |
111 | Most important in this category are your raw template files. By default, |
99ce134b |
112 | files with the extensions "tmpl", "tt", "tt2", "html", and "xhtml" will |
113 | be ignored by Static::Simple in the interest of security. If you wish to |
114 | define your own extensions to ignore, use the "ignore_extensions" |
115 | option: |
8cc672a2 |
116 | |
99ce134b |
117 | MyApp->config->{static}->{ignore_extensions} |
118 | = [ qw/html asp php/ ]; |
8cc672a2 |
119 | |
120 | Ignoring entire directories |
121 | To prevent an entire directory from being served statically, you can use |
99ce134b |
122 | the "ignore_dirs" option. This option contains a list of relative |
123 | directory paths to ignore. If using "include_path", the path will be |
8cc672a2 |
124 | checked against every included path. |
125 | |
126 | MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ]; |
127 | |
99ce134b |
128 | For example, if combined with the above "include_path" setting, this |
129 | "ignore_dirs" value will ignore the following directories if they exist: |
8cc672a2 |
130 | |
131 | /path/to/overlay/tmpl |
132 | /path/to/overlay/css |
133 | /dynamic/path/tmpl |
134 | /dynamic/path/css |
135 | /your/app/home/root/tmpl |
136 | /your/app/home/root/css |
d6d29b9b |
137 | |
2268e329 |
138 | Custom MIME types |
139 | To override or add to the default MIME types set by the MIME::Types |
140 | module, you may enter your own extension to MIME type mapping. |
d6d29b9b |
141 | |
2268e329 |
142 | MyApp->config->{static}->{mime_types} = { |
143 | jpg => 'image/jpg', |
144 | png => 'image/png', |
145 | }; |
146 | |
99ce134b |
147 | Compatibility with other plugins |
148 | Since version 0.12, Static::Simple plays nice with other plugins. It no |
149 | longer short-circuits the "prepare_action" stage as it was causing too |
150 | many compatibility issues with other plugins. |
2268e329 |
151 | |
99ce134b |
152 | Debugging information |
153 | Enable additional debugging information printed in the Catalyst log. |
154 | This is automatically enabled when running Catalyst in -Debug mode. |
2268e329 |
155 | |
99ce134b |
156 | MyApp->config->{static}->{debug} = 1; |
157 | |
158 | USING WITH APACHE |
159 | While Static::Simple will work just fine serving files through Catalyst |
160 | in mod_perl, for increased performance, you may wish to have Apache |
161 | handle the serving of your static files. To do this, simply use a |
162 | dedicated directory for your static files and configure an Apache |
163 | Location block for that directory. This approach is recommended for |
164 | production installations. |
d6d29b9b |
165 | |
2268e329 |
166 | <Location /static> |
167 | SetHandler default-handler |
168 | </Location> |
d6d29b9b |
169 | |
99ce134b |
170 | Using this approach Apache will bypass any handling of these directories |
171 | through Catalyst. You can leave Static::Simple as part of your |
172 | application, and it will continue to function on a development server, |
173 | or using Catalyst's built-in server. |
d6d29b9b |
174 | |
6cc495c4 |
175 | PUBLIC METHODS |
176 | serve_static_file $file_path |
177 | Will serve the file located in $file_path statically. This is useful |
178 | when you need to autogenerate them if they don't exist, or they are |
179 | stored in a model. |
180 | |
181 | package MyApp::Controller::User; |
182 | |
183 | sub curr_user_thumb : PathPart("my_thumbnail.png") { |
184 | my ( $self, $c ) = @_; |
185 | my $file_path = $c->user->picture_thumbnail_path; |
186 | $c->serve_static_file($file_path); |
187 | } |
188 | |
99ce134b |
189 | INTERNAL EXTENDED METHODS |
190 | Static::Simple extends the following steps in the Catalyst process. |
d6d29b9b |
191 | |
99ce134b |
192 | prepare_action |
193 | "prepare_action" is used to first check if the request path is a static |
194 | file. If so, we skip all other "prepare_action" steps to improve |
195 | performance. |
d6d29b9b |
196 | |
99ce134b |
197 | dispatch |
198 | "dispatch" takes the file found during "prepare_action" and writes it to |
199 | the output. |
200 | |
201 | finalize |
202 | "finalize" serves up final header information and displays any log |
203 | messages. |
204 | |
205 | setup |
206 | "setup" initializes all default values. |
d6d29b9b |
207 | |
208 | SEE ALSO |
209 | Catalyst, Catalyst::Plugin::Static, |
210 | <http://www.iana.org/assignments/media-types/> |
211 | |
212 | AUTHOR |
2268e329 |
213 | Andy Grundman, <andy@hybridized.org> |
d6d29b9b |
214 | |
8cc672a2 |
215 | CONTRIBUTORS |
6cc495c4 |
216 | Marcus Ramberg, <mramberg@cpan.org> |
217 | |
218 | Jesse Sheidlower, <jester@panix.com> |
219 | |
220 | Guillermo Roditi, <groditi@cpan.org> |
8cc672a2 |
221 | |
d6d29b9b |
222 | THANKS |
223 | The authors of Catalyst::Plugin::Static: |
224 | |
225 | Sebastian Riedel |
226 | Christian Hansen |
227 | Marcus Ramberg |
228 | |
229 | For the include_path code from Template Toolkit: |
230 | |
231 | Andy Wardley |
232 | |
233 | COPYRIGHT |
234 | This program is free software, you can redistribute it and/or modify it |
235 | under the same terms as Perl itself. |
236 | |