Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Catalyst::Plugin::StatUserSContributed PerlCatalyst::Plugin::Static::Simple(3)

NAME
       Catalyst::Plugin::Static::Simple	- Make serving static pages painless.

SYNOPSIS
	   package MyApp;
	   use Catalyst	qw/ Static::Simple /;
	   MyApp->setup;
	   # that's it;	static content is automatically	served by Catalyst
	   # from the application's root directory, though you can configure
	   # things or bypass Catalyst entirely	in a production	environment
	   #
	   # one caveat: the files must	be served from an absolute path
	   # (i.e. /images/foo.png)

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.

       If the plugin can not find the file, the	request	is dispatched to your
       application instead. This means you are responsible for generating a
       404 error if your applicaton can	not process the	request:

	  # handled by static::simple, not dispatched to your application
	  /images/exists.png

	  # static::simple will	not find the file and let your application
	  # handle the request.	You are	responsible for	generating a file
	  # or returning a 404 error
	  /images/does_not_exist.png

       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	BEHAVIOUR
       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->{Plugin::Static::Simple}".  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->{Plugin::Static::Simple}->{logging}" to 1.

   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(
	       'Plugin::Static::Simple'	=> {
		   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(
	       'Plugin::Static::Simple'	=> {
		   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(
	       'Plugin::Static::Simple'	=> {
		   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(
	       'Plugin::Static::Simple'	=> {
		   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(
	       'Plugin::Static::Simple'	=> {
		   mime_types => {
		       jpg => 'image/jpg',
		       png => 'image/png',
		   },
	       },
	   );

   Controlling caching with Expires header
       The files served	by Static::Simple will have a Last-Modified header
       set, which allows some browsers to cache	them for a while. However if
       you want	to explicitly set an Expires header, such as to	allow proxies
       to cache	your static content, then you can do so	by setting the
       "expires" config	option.

       The value indicates the number of seconds after access time to allow
       caching.	 So a value of zero really means "don't	cache at all", and any
       higher values will keep the file	around for that	long.

	   MyApp->config(
	       'Plugin::Static::Simple'	=> {
		   expires => 3600, # Caching allowed for one hour.
	       },
	   );

   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(
	       'Plugin::Static::Simple'	=> {
		   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 directly. 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 /myapp/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.

       In practice, your Catalyst application is probably (i.e.	should be)
       structured in the recommended way (i.e.,	that generated by
       bootstrapping the application with the "catalyst.pl" script, with a
       main directory under which is a "lib/" directory	for module files and a
       "root/" directory for templates and static files). Thus,	unless you
       break up	this structure when deploying your app by moving the static
       files to	a different location in	your filesystem, you will need to use
       an Alias	directive in Apache to point to	the right place. You will then
       need to add a Directory block to	give permission	for Apache to serve
       these files. The	final configuration will look something	like this:

	   Alias /myapp/static /filesystem/path/to/MyApp/root/static
	   <Directory /filesystem/path/to/MyApp/root/static>
	       allow from all
	   </Directory>
	   <Location /myapp/static>
	       SetHandler default-handler
	   </Location>

       If you are running in a VirtualHost, you	can just set the DocumentRoot
       location	to the location	of your	root directory;	see
       Catalyst::Engine::Apache2::MP20.

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.

DEPRECATIONS
       The old style of	configuration using the	'static' config	key was
       deprecated in version 0.30. A warning will be issued if this is used,
       and the contents	of the config at this key will be merged with the
       newer 'Plugin::Static::Simple' key.

       Be aware	that if	the 'include_path' key under 'static' exists at	all,
       it will be merged with any content of the same key under
       'Plugin::Static::Simple'. Be careful not	to set this to a non-arrayref,
       therefore.

SEE ALSO
       Catalyst, Catalyst::Plugin::Static,
       <http://www.iana.org/assignments/media-types/>

AUTHOR
       Andy Grundman, <andy@hybridized.org>

CONTRIBUTORS
       Marcus Ramberg, <mramberg@cpan.org>

       Jesse Sheidlower, <jester@panix.com>

       Guillermo Roditi, <groditi@cpan.org>

       Florian Ragwitz,	<rafl@debian.org>

       Tomas Doran, <bobtfish@bobtfish.net>

       Justin Wheeler (dnm)

       Matt S Trout, <mst@shadowcat.co.uk>

       Toby Corkindale,	<tjc@wintrmute.net>

THANKS
       The authors of Catalyst::Plugin::Static:

	   Sebastian Riedel
	   Christian Hansen
	   Marcus Ramberg

       For the include_path code from Template Toolkit:

	   Andy	Wardley

COPYRIGHT
       Copyright (c) 2005 - 2011 the Catalyst::Plugin::Static::Simple "AUTHOR"
       and "CONTRIBUTORS" as listed above.

LICENSE
       This program is free software, you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.24.1			  2014-10-2Catalyst::Plugin::Static::Simple(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT BEHAVIOUR | ADVANCED CONFIGURATION | USING WITH APACHE | PUBLIC METHODS | INTERNAL EXTENDED METHODS | DEPRECATIONS | SEE ALSO | AUTHOR | CONTRIBUTORS | THANKS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Catalyst::Plugin::Static::Simple&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help