[Catalyst-commits] r11186 - Catalyst-Plugin-Static-Simple/trunk
rafl at dev.catalyst.perl.org
rafl at dev.catalyst.perl.org
Fri Aug 21 16:19:32 GMT 2009
Author: rafl
Date: 2009-08-21 16:19:30 +0000 (Fri, 21 Aug 2009)
New Revision: 11186
Removed:
Catalyst-Plugin-Static-Simple/trunk/README
Log:
Remove autogenerated README from version control.
Deleted: Catalyst-Plugin-Static-Simple/trunk/README
===================================================================
--- Catalyst-Plugin-Static-Simple/trunk/README 2009-08-21 16:19:22 UTC (rev 11185)
+++ Catalyst-Plugin-Static-Simple/trunk/README 2009-08-21 16:19:30 UTC (rev 11186)
@@ -1,236 +0,0 @@
-NAME
- Catalyst::Plugin::Static::Simple - Make serving static pages painless.
-
-SYNOPSIS
- use Catalyst;
- MyApp->setup( qw/Static::Simple/ );
- # that's it; static content is automatically served by
- # Catalyst, though you can configure things or bypass
- # Catalyst entirely in a production environment
-
-DESCRIPTION
- The Static::Simple plugin is designed to make serving static content in
- your application during development quick and easy, without requiring a
- single line of code from you.
-
- This plugin detects static files by looking at the file extension in the
- URL (such as .css or .png or .js). The plugin uses the lightweight
- MIME::Types module to map file extensions to IANA-registered MIME types,
- and will serve your static files with the correct MIME type directly to
- the browser, without being processed through Catalyst.
-
- Note that actions mapped to paths using periods (.) will still operate
- properly.
-
- Though Static::Simple is designed to work out-of-the-box, you can tweak
- the operation by adding various configuration options. In a production
- environment, you will probably want to use your webserver to deliver
- static content; for an example see "USING WITH APACHE", below.
-
-DEFAULT BEHAVIOR
- By default, Static::Simple will deliver all files having extensions
- (that is, bits of text following a period (".")), *except* files having
- the extensions "tmpl", "tt", "tt2", "html", and "xhtml". These files,
- and all files without extensions, will be processed through Catalyst. If
- MIME::Types doesn't recognize an extension, it will be served as
- "text/plain".
-
- To restate: files having the extensions "tmpl", "tt", "tt2", "html", and
- "xhtml" *will not* be served statically by default, they will be
- processed by Catalyst. Thus if you want to use ".html" files from within
- a Catalyst app as static files, you need to change the configuration of
- Static::Simple. Note also that files having any other extension *will*
- be served statically, so if you're using any other extension for
- template files, you should also change the configuration.
-
- Logging of static files is turned off by default.
-
-ADVANCED CONFIGURATION
- Configuration is completely optional and is specified within
- "MyApp->config->{static}". If you use any of these options, this module
- will probably feel less "simple" to you!
-
- Enabling request logging
- Since Catalyst 5.50, logging of static requests is turned off by
- default; static requests tend to clutter the log output and rarely
- reveal anything useful. However, if you want to enable logging of static
- requests, you can do so by setting "MyApp->config->{static}->{no_logs}"
- to 0.
-
- Forcing directories into static mode
- Define a list of top-level directories beneath your 'root' directory
- that should always be served in static mode. Regular expressions may be
- specified using "qr//".
-
- MyApp->config->{static}->{dirs} = [
- 'static',
- qr/^(images|css)/,
- ];
-
- Including additional directories
- You may specify a list of directories in which to search for your static
- files. The directories will be searched in order and will return the
- first file found. Note that your root directory is not automatically
- added to the search path when you specify an "include_path". You should
- use "MyApp->config->{root}" to add it.
-
- MyApp->config->{static}->{include_path} = [
- '/path/to/overlay',
- \&incpath_generator,
- MyApp->config->{root}
- ];
-
- With the above setting, a request for the file "/images/logo.jpg" will
- search for the following files, returning the first one found:
-
- /path/to/overlay/images/logo.jpg
- /dynamic/path/images/logo.jpg
- /your/app/home/root/images/logo.jpg
-
- The include path can contain a subroutine reference to dynamically
- return a list of available directories. This method will receive the $c
- object as a parameter and should return a reference to a list of
- directories. Errors can be reported using "die()". This method will be
- called every time a file is requested that appears to be a static file
- (i.e. it has an extension).
-
- For example:
-
- sub incpath_generator {
- my $c = shift;
-
- if ( $c->session->{customer_dir} ) {
- return [ $c->session->{customer_dir} ];
- } else {
- die "No customer dir defined.";
- }
- }
-
- Ignoring certain types of files
- There are some file types you may not wish to serve as static files.
- Most important in this category are your raw template files. By default,
- files with the extensions "tmpl", "tt", "tt2", "html", and "xhtml" will
- be ignored by Static::Simple in the interest of security. If you wish to
- define your own extensions to ignore, use the "ignore_extensions"
- option:
-
- MyApp->config->{static}->{ignore_extensions}
- = [ qw/html asp php/ ];
-
- Ignoring entire directories
- To prevent an entire directory from being served statically, you can use
- the "ignore_dirs" option. This option contains a list of relative
- directory paths to ignore. If using "include_path", the path will be
- checked against every included path.
-
- MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
-
- For example, if combined with the above "include_path" setting, this
- "ignore_dirs" value will ignore the following directories if they exist:
-
- /path/to/overlay/tmpl
- /path/to/overlay/css
- /dynamic/path/tmpl
- /dynamic/path/css
- /your/app/home/root/tmpl
- /your/app/home/root/css
-
- Custom MIME types
- To override or add to the default MIME types set by the MIME::Types
- module, you may enter your own extension to MIME type mapping.
-
- MyApp->config->{static}->{mime_types} = {
- jpg => 'image/jpg',
- png => 'image/png',
- };
-
- Compatibility with other plugins
- Since version 0.12, Static::Simple plays nice with other plugins. It no
- longer short-circuits the "prepare_action" stage as it was causing too
- many compatibility issues with other plugins.
-
- Debugging information
- Enable additional debugging information printed in the Catalyst log.
- This is automatically enabled when running Catalyst in -Debug mode.
-
- MyApp->config->{static}->{debug} = 1;
-
-USING WITH APACHE
- While Static::Simple will work just fine serving files through Catalyst
- in mod_perl, for increased performance, you may wish to have Apache
- handle the serving of your static files. To do this, simply use a
- dedicated directory for your static files and configure an Apache
- Location block for that directory. This approach is recommended for
- production installations.
-
- <Location /static>
- SetHandler default-handler
- </Location>
-
- Using this approach Apache will bypass any handling of these directories
- through Catalyst. You can leave Static::Simple as part of your
- application, and it will continue to function on a development server,
- or using Catalyst's built-in server.
-
-PUBLIC METHODS
- serve_static_file $file_path
- Will serve the file located in $file_path statically. This is useful
- when you need to autogenerate them if they don't exist, or they are
- stored in a model.
-
- package MyApp::Controller::User;
-
- sub curr_user_thumb : PathPart("my_thumbnail.png") {
- my ( $self, $c ) = @_;
- my $file_path = $c->user->picture_thumbnail_path;
- $c->serve_static_file($file_path);
- }
-
-INTERNAL EXTENDED METHODS
- Static::Simple extends the following steps in the Catalyst process.
-
- prepare_action
- "prepare_action" is used to first check if the request path is a static
- file. If so, we skip all other "prepare_action" steps to improve
- performance.
-
- dispatch
- "dispatch" takes the file found during "prepare_action" and writes it to
- the output.
-
- finalize
- "finalize" serves up final header information and displays any log
- messages.
-
- setup
- "setup" initializes all default values.
-
-SEE ALSO
- Catalyst, Catalyst::Plugin::Static,
- <http://www.iana.org/assignments/media-types/>
-
-AUTHOR
- Andy Grundman, <andy at hybridized.org>
-
-CONTRIBUTORS
- Marcus Ramberg, <mramberg at cpan.org>
-
- Jesse Sheidlower, <jester at panix.com>
-
- Guillermo Roditi, <groditi at cpan.org>
-
-THANKS
- The authors of Catalyst::Plugin::Static:
-
- Sebastian Riedel
- Christian Hansen
- Marcus Ramberg
-
- For the include_path code from Template Toolkit:
-
- Andy Wardley
-
-COPYRIGHT
- This program is free software, you can redistribute it and/or modify it
- under the same terms as Perl itself.
-
More information about the Catalyst-commits
mailing list