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 | |
2268e329 |
30 | Forcing directories into static mode |
31 | Define a list of top-level directories beneath your 'root' directory |
32 | that should always be served in static mode. Regular expressions may be |
33 | specified using qr//. |
34 | |
35 | MyApp->config->{static}->{dirs} = [ |
36 | 'static', |
37 | qr/^(images|css)/, |
38 | ]; |
39 | |
40 | Including additional directories (experimental!) |
41 | You may specify a list of directories in which to search for your static |
42 | files. The directories will be searched in order and will return the |
43 | first file found. Note that your root directory is not automatically |
44 | added to the search path when you specify an include_path. You should |
45 | use MyApp->config->{root} to add it. |
46 | |
47 | MyApp->config->{static}->{include_path} = [ |
48 | '/path/to/overlay', |
49 | \&incpath_generator, |
50 | MyApp->config->{root} |
51 | ]; |
d6d29b9b |
52 | |
2268e329 |
53 | With the above setting, a request for the file /images/logo.jpg will |
54 | search for the following files, returning the first one found: |
d6d29b9b |
55 | |
2268e329 |
56 | /path/to/overlay/images/logo.jpg |
57 | /dynamic/path/images/logo.jpg |
58 | /your/app/home/root/images/logo.jpg |
d6d29b9b |
59 | |
2268e329 |
60 | The include path can contain a subroutine reference to dynamically |
61 | return a list of available directories. This method will receive the $c |
62 | object as a parameter and should return a reference to a list of |
63 | directories. Errors can be reported using die(). This method will be |
64 | called every time a file is requested that appears to be a static file |
65 | (i.e. it has an extension). |
d6d29b9b |
66 | |
2268e329 |
67 | For example: |
d6d29b9b |
68 | |
2268e329 |
69 | sub incpath_generator { |
70 | my $c = shift; |
d6d29b9b |
71 | |
2268e329 |
72 | if ( $c->session->{customer_dir} ) { |
73 | return [ $c->session->{customer_dir} ]; |
74 | } else { |
75 | die "No customer dir defined."; |
d6d29b9b |
76 | } |
2268e329 |
77 | } |
d6d29b9b |
78 | |
2268e329 |
79 | Custom MIME types |
80 | To override or add to the default MIME types set by the MIME::Types |
81 | module, you may enter your own extension to MIME type mapping. |
d6d29b9b |
82 | |
2268e329 |
83 | MyApp->config->{static}->{mime_types} = { |
84 | jpg => 'image/jpg', |
85 | png => 'image/png', |
86 | }; |
87 | |
88 | Apache integration and performance |
89 | Optionally, when running under mod_perl, Static::Simple can return |
90 | DECLINED on static files to allow Apache to serve the file. A check is |
91 | first done to make sure that Apache's DocumentRoot matches your Catalyst |
92 | root, and that you are not using any custom MIME types or multiple |
93 | roots. To enable the Apache support, you can set the following option. |
94 | |
95 | MyApp->config->{static}->{use_apache} = 1; |
d6d29b9b |
96 | |
2268e329 |
97 | By default this option is disabled because after several benchmarks it |
98 | appears that just serving the file from Catalyst is the better option. |
99 | On a 3K file, Catalyst appears to be around 25% faster, and is 42% |
100 | faster on a 10K file. My benchmarking was done using the following |
101 | 'siege' command, so other benchmarks would be welcome! |
102 | |
103 | siege -u http://server/static/css/10K.css -b -t 1M -c 1 |
104 | |
105 | For best static performance, you should still serve your static files |
106 | directly from Apache by defining a Location block similar to the |
107 | following: |
d6d29b9b |
108 | |
2268e329 |
109 | <Location /static> |
110 | SetHandler default-handler |
111 | </Location> |
d6d29b9b |
112 | |
2268e329 |
113 | Bypassing other plugins |
114 | This plugin checks for a static file in the prepare_action stage. If the |
115 | request is for a static file, it will bypass all remaining |
116 | prepare_action steps. This means that by placing Static::Simple before |
117 | all other plugins, they will not execute when a static file is found. |
118 | This can be helpful by skipping session cookie checks for example. Or, |
119 | if you want some plugins to run even on static files, list them before |
120 | Static::Simple. |
d6d29b9b |
121 | |
2268e329 |
122 | Currently, work done by plugins in any other prepare method will execute |
123 | normally. |
d6d29b9b |
124 | |
2268e329 |
125 | Debugging information |
126 | Enable additional debugging information printed in the Catalyst log. |
127 | This is automatically enabled when running Catalyst in -Debug mode. |
d6d29b9b |
128 | |
2268e329 |
129 | MyApp->config->{static}->{debug} = 1; |
d6d29b9b |
130 | |
131 | SEE ALSO |
132 | Catalyst, Catalyst::Plugin::Static, |
133 | <http://www.iana.org/assignments/media-types/> |
134 | |
135 | AUTHOR |
2268e329 |
136 | Andy Grundman, <andy@hybridized.org> |
d6d29b9b |
137 | |
138 | THANKS |
139 | The authors of Catalyst::Plugin::Static: |
140 | |
141 | Sebastian Riedel |
142 | Christian Hansen |
143 | Marcus Ramberg |
144 | |
145 | For the include_path code from Template Toolkit: |
146 | |
147 | Andy Wardley |
148 | |
149 | COPYRIGHT |
150 | This program is free software, you can redistribute it and/or modify it |
151 | under the same terms as Perl itself. |
152 | |