From: Florian Ragwitz Date: Fri, 21 Aug 2009 16:19:30 +0000 (+0000) Subject: Remove autogenerated README from version control. X-Git-Tag: v0.22~1 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Plugin-Static-Simple.git;a=commitdiff_plain;h=f52523864271eaf96c7a2edba983eb7f5c5058c6 Remove autogenerated README from version control. --- diff --git a/README b/README deleted file mode 100644 index 65e7141..0000000 --- a/README +++ /dev/null @@ -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. - - - SetHandler default-handler - - - 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, - - -AUTHOR - Andy Grundman, - -CONTRIBUTORS - Marcus Ramberg, - - Jesse Sheidlower, - - Guillermo Roditi, - -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. -