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/ ); |
7 | |
8 | DESCRIPTION |
9 | The Static::Simple plugin is designed to make serving static content in |
10 | your application during development quick and easy, without requiring a |
11 | single line of code from you. |
12 | |
13 | It will detect static files used in your application by looking for file |
14 | extensions in the URI. By default, you can simply load this plugin and |
15 | it will immediately begin serving your static files with the correct |
16 | MIME type. The light-weight MIME::Types module is used to map file |
17 | extensions to IANA-registered MIME types. |
18 | |
19 | Note that actions mapped to paths using periods (.) will still operate |
20 | properly. |
21 | |
22 | You may further tweak the operation by adding configuration options, |
23 | described below. |
24 | |
25 | ADVANCED CONFIGURATION |
26 | Configuration is completely optional and is specified within |
27 | MyApp->config->{static}. If you use any of these options, the module |
28 | will probably feel less "simple" to you! |
29 | |
8cc672a2 |
30 | Aborting request logging |
31 | Since Catalyst 5.50, there has been added support for dropping logging |
32 | for a request. This is enabled by default for static files, as static |
33 | requests tend to clutter the log output. However, if you want logging of |
34 | static requests, you can enable it by setting |
35 | MyApp->config->{static}->{no_logs} to 0. |
36 | |
2268e329 |
37 | Forcing directories into static mode |
38 | Define a list of top-level directories beneath your 'root' directory |
39 | that should always be served in static mode. Regular expressions may be |
40 | specified using qr//. |
41 | |
42 | MyApp->config->{static}->{dirs} = [ |
43 | 'static', |
44 | qr/^(images|css)/, |
45 | ]; |
46 | |
8cc672a2 |
47 | Including additional directories |
2268e329 |
48 | You may specify a list of directories in which to search for your static |
49 | files. The directories will be searched in order and will return the |
50 | first file found. Note that your root directory is not automatically |
51 | added to the search path when you specify an include_path. You should |
52 | use MyApp->config->{root} to add it. |
53 | |
54 | MyApp->config->{static}->{include_path} = [ |
55 | '/path/to/overlay', |
56 | \&incpath_generator, |
57 | MyApp->config->{root} |
58 | ]; |
d6d29b9b |
59 | |
2268e329 |
60 | With the above setting, a request for the file /images/logo.jpg will |
61 | search for the following files, returning the first one found: |
d6d29b9b |
62 | |
2268e329 |
63 | /path/to/overlay/images/logo.jpg |
64 | /dynamic/path/images/logo.jpg |
65 | /your/app/home/root/images/logo.jpg |
d6d29b9b |
66 | |
2268e329 |
67 | The include path can contain a subroutine reference to dynamically |
68 | return a list of available directories. This method will receive the $c |
69 | object as a parameter and should return a reference to a list of |
70 | directories. Errors can be reported using die(). This method will be |
71 | called every time a file is requested that appears to be a static file |
72 | (i.e. it has an extension). |
d6d29b9b |
73 | |
2268e329 |
74 | For example: |
d6d29b9b |
75 | |
2268e329 |
76 | sub incpath_generator { |
77 | my $c = shift; |
d6d29b9b |
78 | |
2268e329 |
79 | if ( $c->session->{customer_dir} ) { |
80 | return [ $c->session->{customer_dir} ]; |
81 | } else { |
82 | die "No customer dir defined."; |
d6d29b9b |
83 | } |
2268e329 |
84 | } |
8cc672a2 |
85 | |
86 | Ignoring certain types of files |
87 | There are some file types you may not wish to serve as static files. |
88 | Most important in this category are your raw template files. By default, |
89 | files with the extensions tt, html, and xhtml will be ignored by |
90 | Static::Simple in the interest of security. If you wish to define your |
91 | own extensions to ignore, use the ignore_extensions option: |
92 | |
93 | MyApp->config->{static}->{ignore_extensions} = [ qw/tt html xhtml/ ]; |
94 | |
95 | Ignoring entire directories |
96 | To prevent an entire directory from being served statically, you can use |
97 | the ignore_dirs option. This option contains a list of relative |
98 | directory paths to ignore. If using include_path, the path will be |
99 | checked against every included path. |
100 | |
101 | MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ]; |
102 | |
103 | For example, if combined with the above include_path setting, this |
104 | ignore_dirs value will ignore the following directories if they exist: |
105 | |
106 | /path/to/overlay/tmpl |
107 | /path/to/overlay/css |
108 | /dynamic/path/tmpl |
109 | /dynamic/path/css |
110 | /your/app/home/root/tmpl |
111 | /your/app/home/root/css |
d6d29b9b |
112 | |
2268e329 |
113 | Custom MIME types |
114 | To override or add to the default MIME types set by the MIME::Types |
115 | module, you may enter your own extension to MIME type mapping. |
d6d29b9b |
116 | |
2268e329 |
117 | MyApp->config->{static}->{mime_types} = { |
118 | jpg => 'image/jpg', |
119 | png => 'image/png', |
120 | }; |
121 | |
122 | Apache integration and performance |
123 | Optionally, when running under mod_perl, Static::Simple can return |
124 | DECLINED on static files to allow Apache to serve the file. A check is |
125 | first done to make sure that Apache's DocumentRoot matches your Catalyst |
126 | root, and that you are not using any custom MIME types or multiple |
127 | roots. To enable the Apache support, you can set the following option. |
128 | |
129 | MyApp->config->{static}->{use_apache} = 1; |
d6d29b9b |
130 | |
2268e329 |
131 | By default this option is disabled because after several benchmarks it |
132 | appears that just serving the file from Catalyst is the better option. |
133 | On a 3K file, Catalyst appears to be around 25% faster, and is 42% |
134 | faster on a 10K file. My benchmarking was done using the following |
135 | 'siege' command, so other benchmarks would be welcome! |
136 | |
137 | siege -u http://server/static/css/10K.css -b -t 1M -c 1 |
138 | |
139 | For best static performance, you should still serve your static files |
140 | directly from Apache by defining a Location block similar to the |
141 | following: |
d6d29b9b |
142 | |
2268e329 |
143 | <Location /static> |
144 | SetHandler default-handler |
145 | </Location> |
d6d29b9b |
146 | |
2268e329 |
147 | Bypassing other plugins |
148 | This plugin checks for a static file in the prepare_action stage. If the |
149 | request is for a static file, it will bypass all remaining |
150 | prepare_action steps. This means that by placing Static::Simple before |
151 | all other plugins, they will not execute when a static file is found. |
152 | This can be helpful by skipping session cookie checks for example. Or, |
153 | if you want some plugins to run even on static files, list them before |
154 | Static::Simple. |
d6d29b9b |
155 | |
2268e329 |
156 | Currently, work done by plugins in any other prepare method will execute |
157 | normally. |
d6d29b9b |
158 | |
2268e329 |
159 | Debugging information |
160 | Enable additional debugging information printed in the Catalyst log. |
161 | This is automatically enabled when running Catalyst in -Debug mode. |
d6d29b9b |
162 | |
2268e329 |
163 | MyApp->config->{static}->{debug} = 1; |
d6d29b9b |
164 | |
165 | SEE ALSO |
166 | Catalyst, Catalyst::Plugin::Static, |
167 | <http://www.iana.org/assignments/media-types/> |
168 | |
169 | AUTHOR |
2268e329 |
170 | Andy Grundman, <andy@hybridized.org> |
d6d29b9b |
171 | |
8cc672a2 |
172 | CONTRIBUTORS |
173 | Marcus Ramberg, <mramberg@cpan.org> |
174 | |
d6d29b9b |
175 | THANKS |
176 | The authors of Catalyst::Plugin::Static: |
177 | |
178 | Sebastian Riedel |
179 | Christian Hansen |
180 | Marcus Ramberg |
181 | |
182 | For the include_path code from Template Toolkit: |
183 | |
184 | Andy Wardley |
185 | |
186 | COPYRIGHT |
187 | This program is free software, you can redistribute it and/or modify it |
188 | under the same terms as Perl itself. |
189 | |