From: Jesse Sheidlower <jester@panix.com>
Date: Wed, 6 Jul 2005 17:23:23 +0000 (+0000)
Subject: fixed borked Cookbook merge
X-Git-Tag: 5.7099_04~1267
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=379ca3717901cf0a7502ed10443cfe9329a379e4

fixed borked Cookbook merge
---

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index 573a8ff..820f5f8 100644
--- a/lib/Catalyst/Manual/Cookbook.pod
+++ b/lib/Catalyst/Manual/Cookbook.pod
@@ -18,10 +18,17 @@ placing a C<die()> call in the C<end> action.
          die "forced debug";
      }
 
-If you're tired of removing and adding this all the time, you
-can easily add a condition. For example:
+If you're tired of removing and adding this all the time, you can add a
+condition in the C<end> action. For example:
+
+    sub end : Private {  
+        my ( $self, $c ) = @_;  
+        die "forced debug" if $c->req->params->{dump_info};  
+    }  
+
+Then just add to your query string C<"&dump_info=1">, or the like, to
+force debug output.
 
-  die "force debug" if $c->req->params->{dump_info};
 
 =head2 Disable statistics
 
@@ -66,10 +73,12 @@ Just use Catalyst::Model::CDBI::CRUD as your base class.
 
     1;
 
-Modify the $c->form() parameters to match your needs, and don't forget to copy
-the templates into the template root. Can't find the templates? They were in the
-CRUD model distribution, so you can do B<look Catalyst::Model::CDBI::CRUD> from 
-the CPAN shell to find them.
+Modify the C<$c-E<gt>form()> parameters to match your needs, and don't
+forget to copy the templates into the template root. Can't find the
+templates?  They were in the CRUD model distribution, so you can do
+B<look Catalyst::Model::CDBI::CRUD> from the CPAN shell to find them.
+
+Other Scaffolding modules are in development at the time of writing.
 
 =head2 Single file upload with Catalyst
 
@@ -82,7 +91,8 @@ this:
       <input type="submit" value="Send">
     </form>
 
-It's very important not to forget C<enctype="multipart/form-data"> in form. Uploads will not work without this.
+It's very important not to forget C<enctype="multipart/form-data"> in
+the form.
 
 Catalyst Controller module 'upload' action:
 
@@ -107,10 +117,9 @@ Catalyst Controller module 'upload' action:
 
 =head2 Multiple file upload with Catalyst
 
-Code for uploading multiple files from one form needs little changes compared
-to single file upload.
+Code for uploading multiple files from one form needs a few changes:
 
-Form goes like this:
+The form should have this basic structure:
 
     <form action="/upload" method="post" enctype="multipart/form-data">
       <input type="hidden" name="form_submit" value="yes">
@@ -120,7 +129,7 @@ Form goes like this:
       <input type="submit" value="Send">
     </form>
 
-Controller:
+And in the controller:
 
     sub upload : Local {
         my ($self, $c) = @_;
@@ -142,22 +151,23 @@ Controller:
         $c->stash->{template} = 'file_upload.html';
     }
 
-C<for my $field ($c-E<gt>req->upload)> loops automatically over all file input
-fields and gets input names. After that is basic file saving code, just like in
-single file upload.
+C<for my $field ($c-E<gt>req->upload)> loops automatically over all file
+input fields and gets input names. After that is basic file saving code,
+just like in single file upload.
 
-Notice: C<die>ing might not be what you want to do, when an error occurs, but
-it works as an example. A better idea would be to store error C<$!> in
-$c->stash->{error} and show a custom error template displaying this message.
+Notice: C<die>ing might not be what you want to do, when an error
+occurs, but it works as an example. A better idea would be to store
+error C<$!> in $c->stash->{error} and show a custom error template
+displaying this message.
 
 For more information about uploads and usable methods look at
-C<Catalyst::Request::Upload> and C<Catalyst::Request>.
+L<Catalyst::Request::Upload> and L<Catalyst::Request>.
 
 =head2 Authentication with Catalyst::Plugin::Authentication::CDBI
 
 There are (at least) two ways to implement authentication with this plugin:
 1) only checking username and password;
-2) checking username, password and the roles the user has
+2) checking username, password, and the roles the user has
 
 For both variants you'll need the following code in your MyApp package:
 
@@ -362,7 +372,138 @@ authentication, authorization, and access check phases.
 For more information see the FastCGI documentation, the C<FCGI> module 
 and L<http://www.fastcgi.com/>.
  
-=head2 Forwarding with a parameter
+=head2 Serving static content
+
+Serving static content in Catalyst can be somewhat tricky; this recipe
+shows one possible solution. Using this recipe will serve all static
+content through Catalyst when developing with the built-in HTTP::Daemon
+server, and will make it easy to use Apache to serve the content when
+your app goes into production.
+
+Static content is best served from a single directory within your root
+directory. Having many different directories such as C<root/css> and
+C<root/images> requires more code to manage, because you must separately
+identify each static directory--if you decide to add a C<root/js>
+directory, you'll need to change your code to account for it. In
+contrast, keeping all static directories as subdirectories of a main
+C<root/static> directory makes things much easier to manager. Here's an
+example of a typical root directory structure:
+
+    root/
+    root/content.tt
+    root/controller/stuff.tt
+    root/header.tt
+    root/static/
+    root/static/css/main.css
+    root/static/images/logo.jpg
+    root/static/js/code.js
+
+
+All static content lives under C<root/static> with everything else being
+Template Toolkit files. Now you can identify the static content by
+matching C<static> from within Catalyst.
+
+=head3 Serving with HTTP::Daemon (myapp_server.pl)
+
+To serve these files under the standalone server, we first must load the
+Static plugin. Install L<Catalyst::Plugin::Static> if it's not already
+installed.
+
+In your main application class (MyApp.pm), load the plugin:
+
+    use Catalyst qw/-Debug FormValidator Static OtherPlugin/;
+
+You will also need to make sure your end method does I<not> forward
+static content to the view, perhaps like this:
+
+    sub end : Private {
+        my ( $self, $c ) = @_;
+
+        $c->forward( 'MyApp::V::TT' ) 
+          unless ( $c->res->body || !$c->stash->{template} );
+    }
+
+This code will only forward to the view if a template has been
+previously defined by a controller and if there is not already data in
+C<$c-E<gt>res-E<gt>body>.
+
+Next, create a controller to handle requests for the /static path. Use
+the Helper to save time. This command will create a stub controller as
+C<lib/MyApp/C/Static.pm>.
+
+    $ script/myapp_create.pl controller Static
+
+Edit the file and add the following methods:
+
+    # serve all files under /static as static files
+    sub default : Path('/static') {
+        my ( $self, $c ) = @_;
+    
+        # Optional, allow the browser to cache the content
+        $c->res->headers->header( 'Cache-Control' => 'max-age=86400' );
+
+        $c->serve_static; # from Catalyst::Plugin::Static
+    }
+
+    # also handle requests for /favicon.ico
+    sub favicon : Path('/favicon.ico') {
+        my ( $self, $c ) = @_;
+    
+        $c->serve_static;
+    }
+
+You can also define a different icon for the browser to use instead of
+favicon.ico by using this in your HTML header:
+
+    <link rel="icon" href="/static/myapp.ico" type="image/x-icon" />
+
+=head3 Common problems
+
+The Static plugin makes use of the C<shared-mime-info> package to
+automatically determine MIME types. This package is notoriously
+difficult to install, especially on win32 and OSX. For OSX the easiest
+path might be to install Fink, then use C<apt-get install
+shared-mime-info>. Restart the server, and everything should be fine.
+
+Make sure you are using the latest version (>= 0.16) for best
+results. If you are having errors serving CSS files, or if they get
+served as text/plain instead of text/css, you may have an outdated
+shared-mime-info version. You may also wish to simply use the following
+code in your Static controller:
+
+    if ($c->req->path =~ /css$/i) {
+        $c->serve_static( "text/css" );
+    } else {
+        $c->serve_static;
+    }
+
+=head3 Serving with Apache
+
+When using Apache, you can completely bypass Catalyst and the Static
+controller by intercepting requests for the C<root/static> path at the
+server level. All that is required is to define a DocumentRoot and add a
+separate Location block for your static content. Here is a complete
+config for this application under mod_perl 1.x; variations, some of
+which could be simpler, are left as an exercise for the reader:
+
+    <Perl>
+        use lib qw(/var/www/MyApp/lib);
+    </Perl>
+    PerlModule MyApp
+    
+    <VirtualHost *>
+        ServerName myapp.example.com
+        DocumentRoot /var/www/MyApp/root
+        <Location />
+            SetHandler perl-script
+            PerlHandler MyApp
+        </Location>
+        <LocationMatch "/(static|favicon.ico)">
+            SetHandler default-handler
+        </LocationMatch>
+    </VirtualHost>
+
+=head2 Forwarding with arguments
 
 Sometimes you want to pass along arguments when forwarding to another
 action. As of version 5.30, arguments can be passed in the call to
@@ -382,8 +523,10 @@ passing arguments via C<forward>.)
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@oook.de>
-Danijel Milicevic C<me@danijel.de>
-Viljo Marrandi C<vilts@yahoo.com>
+Danijel Milicevic, C<me@danijel.de>
+Viljo Marrandi, C<vilts@yahoo.com>  
+Marcus Ramberg, C<mramberg@cpan.org>  
+Andy Grundman, C<andy@hybridized.org> 
 Marcus Ramberg C<mramberg@cpan.org>
 
 =head1 COPYRIGHT