local-lib5/man/man3/Catalyst::Plugin::Static::Simple.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Catalyst::Plugin::Static::Simple 3"
 132 .TH Catalyst::Plugin::Static::Simple 3 "2009-11-26" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Catalyst::Plugin::Static::Simple \- Make serving static pages painless.
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 9
 138 \&    package MyApp;
 139 \&    use Catalyst qw/ Static::Simple /;
 140 \&    MyApp\->setup;
 141 \&    # that's it; static content is automatically served by Catalyst
 142 \&    # from the application's root directory, though you can configure
 143 \&    # things or bypass Catalyst entirely in a production environment
 144 \&    #
 145 \&    # one caveat: the files must be served from an absolute path
 146 \&    # (i.e. /images/foo.png)
 147 .Ve
 148 .SH "DESCRIPTION"
 149 .IX Header "DESCRIPTION"
 150 The Static::Simple plugin is designed to make serving static content in
 151 your application during development quick and easy, without requiring a
 152 single line of code from you.
 153 .PP
 154 This plugin detects static files by looking at the file extension in the
 155 \&\s-1URL\s0 (such as \fB.css\fR or \fB.png\fR or \fB.js\fR). The plugin uses the
 156 lightweight MIME::Types module to map file extensions to
 157 IANA-registered \s-1MIME\s0 types, and will serve your static files with the
 158 correct \s-1MIME\s0 type directly to the browser, without being processed
 159 through Catalyst.
 160 .PP
 161 Note that actions mapped to paths using periods (.) will still operate
 162 properly.
 163 .PP
 164 If the plugin can not find the file, the request is dispatched to your
 165 application instead. This means you are responsible for generating a
 166 \&\f(CW404\fR error if your applicaton can not process the request:
 167 .PP
 168 .Vb 2
 169 \&   # handled by static::simple, not dispatched to your application
 170 \&   /images/exists.png
 171 .Ve
 172 .PP
 173 .Vb 4
 174 \&   # static::simple will not find the file and let your application
 175 \&   # handle the request. You are responsible for generating a file
 176 \&   # or returning a 404 error
 177 \&   /images/does_not_exist.png
 178 .Ve
 179 .PP
 180 Though Static::Simple is designed to work out\-of\-the\-box, you can tweak
 181 the operation by adding various configuration options. In a production
 182 environment, you will probably want to use your webserver to deliver
 183 static content; for an example see \*(L"\s-1USING\s0 \s-1WITH\s0 \s-1APACHE\s0\*(R", below.
 184 .SH "DEFAULT BEHAVIOR"
 185 .IX Header "DEFAULT BEHAVIOR"
 186 By default, Static::Simple will deliver all files having extensions
 187 (that is, bits of text following a period (\f(CW\*(C`.\*(C'\fR)), \fIexcept\fR files
 188 having the extensions \f(CW\*(C`tmpl\*(C'\fR, \f(CW\*(C`tt\*(C'\fR, \f(CW\*(C`tt2\*(C'\fR, \f(CW\*(C`html\*(C'\fR, and
 189 \&\f(CW\*(C`xhtml\*(C'\fR. These files, and all files without extensions, will be
 190 processed through Catalyst. If MIME::Types doesn't recognize an
 191 extension, it will be served as \f(CW\*(C`text/plain\*(C'\fR.
 192 .PP
 193 To restate: files having the extensions \f(CW\*(C`tmpl\*(C'\fR, \f(CW\*(C`tt\*(C'\fR, \f(CW\*(C`tt2\*(C'\fR, \f(CW\*(C`html\*(C'\fR,
 194 and \f(CW\*(C`xhtml\*(C'\fR \fIwill not\fR be served statically by default, they will be
 195 processed by Catalyst. Thus if you want to use \f(CW\*(C`.html\*(C'\fR files from
 196 within a Catalyst app as static files, you need to change the
 197 configuration of Static::Simple. Note also that files having any other
 198 extension \fIwill\fR be served statically, so if you're using any other
 199 extension for template files, you should also change the configuration.
 200 .PP
 201 Logging of static files is turned off by default.
 202 .SH "ADVANCED CONFIGURATION"
 203 .IX Header "ADVANCED CONFIGURATION"
 204 Configuration is completely optional and is specified within
 205 \&\f(CW\*(C`MyApp\->config\->{static}\*(C'\fR.  If you use any of these options,
 206 this module will probably feel less \*(L"simple\*(R" to you!
 207 .Sh "Enabling request logging"
 208 .IX Subsection "Enabling request logging"
 209 Since Catalyst 5.50, logging of static requests is turned off by
 210 default; static requests tend to clutter the log output and rarely
 211 reveal anything useful. However, if you want to enable logging of static
 212 requests, you can do so by setting
 213 \&\f(CW\*(C`MyApp\->config\->{static}\->{logging}\*(C'\fR to 1.
 214 .Sh "Forcing directories into static mode"
 215 .IX Subsection "Forcing directories into static mode"
 216 Define a list of top-level directories beneath your 'root' directory
 217 that should always be served in static mode.  Regular expressions may be
 218 specified using \f(CW\*(C`qr//\*(C'\fR.
 219 .PP
 220 .Vb 8
 221 \&    MyApp\->config(
 222 \&        static => {
 223 \&            dirs => [
 224 \&                'static',
 225 \&                qr/^(images|css)/,
 226 \&            ],
 227 \&        }
 228 \&    );
 229 .Ve
 230 .Sh "Including additional directories"
 231 .IX Subsection "Including additional directories"
 232 You may specify a list of directories in which to search for your static
 233 files. The directories will be searched in order and will return the
 234 first file found. Note that your root directory is \fBnot\fR automatically
 235 added to the search path when you specify an \f(CW\*(C`include_path\*(C'\fR. You should
 236 use \f(CW\*(C`MyApp\->config\->{root}\*(C'\fR to add it.
 237 .PP
 238 .Vb 9
 239 \&    MyApp\->config(
 240 \&        static => {
 241 \&            include_path => [
 242 \&                '/path/to/overlay',
 243 \&                \e&incpath_generator,
 244 \&                MyApp\->config\->{root},
 245 \&            ],
 246 \&        },
 247 \&    );
 248 .Ve
 249 .PP
 250 With the above setting, a request for the file \f(CW\*(C`/images/logo.jpg\*(C'\fR will search
 251 for the following files, returning the first one found:
 252 .PP
 253 .Vb 3
 254 \&    /path/to/overlay/images/logo.jpg
 255 \&    /dynamic/path/images/logo.jpg
 256 \&    /your/app/home/root/images/logo.jpg
 257 .Ve
 258 .PP
 259 The include path can contain a subroutine reference to dynamically return a
 260 list of available directories.  This method will receive the \f(CW$c\fR object as a
 261 parameter and should return a reference to a list of directories.  Errors can
 262 be reported using \f(CW\*(C`die()\*(C'\fR.  This method will be called every time a file is
 263 requested that appears to be a static file (i.e. it has an extension).
 264 .PP
 265 For example:
 266 .PP
 267 .Vb 2
 268 \&    sub incpath_generator {
 269 \&        my $c = shift;
 270 .Ve
 271 .PP
 272 .Vb 6
 273 \&        if ( $c\->session\->{customer_dir} ) {
 274 \&            return [ $c\->session\->{customer_dir} ];
 275 \&        } else {
 276 \&            die "No customer dir defined.";
 277 \&        }
 278 \&    }
 279 .Ve
 280 .Sh "Ignoring certain types of files"
 281 .IX Subsection "Ignoring certain types of files"
 282 There are some file types you may not wish to serve as static files.
 283 Most important in this category are your raw template files.  By
 284 default, files with the extensions \f(CW\*(C`tmpl\*(C'\fR, \f(CW\*(C`tt\*(C'\fR, \f(CW\*(C`tt2\*(C'\fR, \f(CW\*(C`html\*(C'\fR, and
 285 \&\f(CW\*(C`xhtml\*(C'\fR will be ignored by Static::Simple in the interest of security.
 286 If you wish to define your own extensions to ignore, use the
 287 \&\f(CW\*(C`ignore_extensions\*(C'\fR option:
 288 .PP
 289 .Vb 5
 290 \&    MyApp\->config(
 291 \&        static => {
 292 \&            ignore_extensions => [ qw/html asp php/ ],
 293 \&        },
 294 \&    );
 295 .Ve
 296 .Sh "Ignoring entire directories"
 297 .IX Subsection "Ignoring entire directories"
 298 To prevent an entire directory from being served statically, you can use
 299 the \f(CW\*(C`ignore_dirs\*(C'\fR option.  This option contains a list of relative
 300 directory paths to ignore.  If using \f(CW\*(C`include_path\*(C'\fR, the path will be
 301 checked against every included path.
 302 .PP
 303 .Vb 5
 304 \&    MyApp\->config(
 305 \&        static => {
 306 \&            ignore_dirs => [ qw/tmpl css/ ],
 307 \&        },
 308 \&    );
 309 .Ve
 310 .PP
 311 For example, if combined with the above \f(CW\*(C`include_path\*(C'\fR setting, this
 312 \&\f(CW\*(C`ignore_dirs\*(C'\fR value will ignore the following directories if they exist:
 313 .PP
 314 .Vb 6
 315 \&    /path/to/overlay/tmpl
 316 \&    /path/to/overlay/css
 317 \&    /dynamic/path/tmpl
 318 \&    /dynamic/path/css
 319 \&    /your/app/home/root/tmpl
 320 \&    /your/app/home/root/css
 321 .Ve
 322 .Sh "Custom \s-1MIME\s0 types"
 323 .IX Subsection "Custom MIME types"
 324 To override or add to the default \s-1MIME\s0 types set by the MIME::Types
 325 module, you may enter your own extension to \s-1MIME\s0 type mapping.
 326 .PP
 327 .Vb 8
 328 \&    MyApp\->config(
 329 \&        static => {
 330 \&            mime_types => {
 331 \&                jpg => 'image/jpg',
 332 \&                png => 'image/png',
 333 \&            },
 334 \&        },
 335 \&    );
 336 .Ve
 337 .Sh "Compatibility with other plugins"
 338 .IX Subsection "Compatibility with other plugins"
 339 Since version 0.12, Static::Simple plays nice with other plugins.  It no
 340 longer short-circuits the \f(CW\*(C`prepare_action\*(C'\fR stage as it was causing too
 341 many compatibility issues with other plugins.
 342 .Sh "Debugging information"
 343 .IX Subsection "Debugging information"
 344 Enable additional debugging information printed in the Catalyst log.  This
 345 is automatically enabled when running Catalyst in \-Debug mode.
 346 .PP
 347 .Vb 5
 348 \&    MyApp\->config(
 349 \&        static => {
 350 \&            debug => 1,
 351 \&        },
 352 \&    );
 353 .Ve
 354 .SH "USING WITH APACHE"
 355 .IX Header "USING WITH APACHE"
 356 While Static::Simple will work just fine serving files through Catalyst
 357 in mod_perl, for increased performance you may wish to have Apache
 358 handle the serving of your static files directly. To do this, simply use
 359 a dedicated directory for your static files and configure an Apache
 360 Location block for that directory  This approach is recommended for
 361 production installations.
 362 .PP
 363 .Vb 3
 364 \&    <Location /myapp/static>
 365 \&        SetHandler default\-handler
 366 \&    </Location>
 367 .Ve
 368 .PP
 369 Using this approach Apache will bypass any handling of these directories
 370 through Catalyst. You can leave Static::Simple as part of your
 371 application, and it will continue to function on a development server,
 372 or using Catalyst's built-in server.
 373 .PP
 374 In practice, your Catalyst application is probably (i.e. should be)
 375 structured in the recommended way (i.e., that generated by bootstrapping
 376 the application with the \f(CW\*(C`catalyst.pl\*(C'\fR script, with a main directory
 377 under which is a \f(CW\*(C`lib/\*(C'\fR directory for module files and a \f(CW\*(C`root/\*(C'\fR
 378 directory for templates and static files). Thus, unless you break up
 379 this structure when deploying your app by moving the static files to a
 380 different location in your filesystem, you will need to use an Alias
 381 directive in Apache to point to the right place. You will then need to
 382 add a Directory block to give permission for Apache to serve these
 383 files. The final configuration will look something like this:
 384 .PP
 385 .Vb 7
 386 \&    Alias /myapp/static /filesystem/path/to/MyApp/root/static
 387 \&    <Directory /filesystem/path/to/MyApp/root/static>
 388 \&        allow from all
 389 \&    </Directory>
 390 \&    <Location /myapp/static>
 391 \&        SetHandler default\-handler
 392 \&    </Location>
 393 .Ve
 394 .PP
 395 If you are running in a VirtualHost, you can just set the DocumentRoot
 396 location to the location of your root directory; see
 397 Catalyst::Engine::Apache2::MP20.
 398 .SH "PUBLIC METHODS"
 399 .IX Header "PUBLIC METHODS"
 400 .ie n .Sh "serve_static_file $file_path"
 401 .el .Sh "serve_static_file \f(CW$file_path\fP"
 402 .IX Subsection "serve_static_file $file_path"
 403 Will serve the file located in \f(CW$file_path\fR statically. This is useful when
 404 you need to  autogenerate them if they don't exist, or they are stored in a model.
 405 .PP
 406 .Vb 1
 407 \&    package MyApp::Controller::User;
 408 .Ve
 409 .PP
 410 .Vb 5
 411 \&    sub curr_user_thumb : PathPart("my_thumbnail.png") {
 412 \&        my ( $self, $c ) = @_;
 413 \&        my $file_path = $c\->user\->picture_thumbnail_path;
 414 \&        $c\->serve_static_file($file_path);
 415 \&    }
 416 .Ve
 417 .SH "INTERNAL EXTENDED METHODS"
 418 .IX Header "INTERNAL EXTENDED METHODS"
 419 Static::Simple extends the following steps in the Catalyst process.
 420 .Sh "prepare_action"
 421 .IX Subsection "prepare_action"
 422 \&\f(CW\*(C`prepare_action\*(C'\fR is used to first check if the request path is a static
 423 file.  If so, we skip all other \f(CW\*(C`prepare_action\*(C'\fR steps to improve
 424 performance.
 425 .Sh "dispatch"
 426 .IX Subsection "dispatch"
 427 \&\f(CW\*(C`dispatch\*(C'\fR takes the file found during \f(CW\*(C`prepare_action\*(C'\fR and writes it
 428 to the output.
 429 .Sh "finalize"
 430 .IX Subsection "finalize"
 431 \&\f(CW\*(C`finalize\*(C'\fR serves up final header information and displays any log
 432 messages.
 433 .Sh "setup"
 434 .IX Subsection "setup"
 435 \&\f(CW\*(C`setup\*(C'\fR initializes all default values.
 436 .SH "SEE ALSO"
 437 .IX Header "SEE ALSO"
 438 Catalyst, Catalyst::Plugin::Static,
 439 <http://www.iana.org/assignments/media\-types/>
 440 .SH "AUTHOR"
 441 .IX Header "AUTHOR"
 442 Andy Grundman, <andy@hybridized.org>
 443 .SH "CONTRIBUTORS"
 444 .IX Header "CONTRIBUTORS"
 445 Marcus Ramberg, <mramberg@cpan.org>
 446 .PP
 447 Jesse Sheidlower, <jester@panix.com>
 448 .PP
 449 Guillermo Roditi, <groditi@cpan.org>
 450 .PP
 451 Florian Ragwitz, <rafl@debian.org>
 452 .PP
 453 Tomas Doran, <bobtfish@bobtfish.net>
 454 .PP
 455 Justin Wheeler (dnm)
 456 .SH "THANKS"
 457 .IX Header "THANKS"
 458 The authors of Catalyst::Plugin::Static:
 459 .PP
 460 .Vb 3
 461 \&    Sebastian Riedel
 462 \&    Christian Hansen
 463 \&    Marcus Ramberg
 464 .Ve
 465 .PP
 466 For the include_path code from Template Toolkit:
 467 .PP
 468 .Vb 1
 469 \&    Andy Wardley
 470 .Ve
 471 .SH "COPYRIGHT"
 472 .IX Header "COPYRIGHT"
 473 Copyright (c) 2005 \- 2009
 474 the Catalyst::Plugin::Static::Simple \*(L"\s-1AUTHOR\s0\*(R" and \*(L"\s-1CONTRIBUTORS\s0\*(R"
 475 as listed above.
 476 .SH "LICENSE"
 477 .IX Header "LICENSE"
 478 This program is free software, you can redistribute it and/or modify it under
 479 the same terms as Perl itself.