added entry for serving static files with apache.

[catagits/Catalyst-Runtime.git] / lib / Catalyst / Manual / Cookbook.pod

diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod
index 820f5f8..af8d13e 100644 (file)
--- a/lib/Catalyst/Manual/Cookbook.pod
+++ b/lib/Catalyst/Manual/Cookbook.pod
@@ -80,7 +80,9 @@ 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
+=head2 File uploads
+
+=head3 Single file upload with Catalyst
 
 To implement uploads in Catalyst you need to have a HTML form similiar to
 this:
@@ -115,7 +117,7 @@ Catalyst Controller module 'upload' action:
         $c->stash->{template} = 'file_upload.html';
     }
 
-=head2 Multiple file upload with Catalyst
+=head3 Multiple file upload with Catalyst
 
 Code for uploading multiple files from one form needs a few changes:
 
@@ -317,7 +319,7 @@ However sometimes mod_perl is not an option, and running under CGI is
 just too slow.  There's also an alternative to mod_perl that gives
 reasonable performance named FastCGI.
 
-B<Using FastCGI>
+=head3 Using FastCGI
 
 To quote from L<http://www.fastcgi.com/>: "FastCGI is a language 
 independent, scalable, extension to CGI that provides high performance 
@@ -520,14 +522,110 @@ the Catalyst Request object:
 (See L<Catalyst::Manual::Intro#Flow_Control> for more information on
 passing arguments via C<forward>.)
 
+=head2 Configure your application
+
+You configure your application with the C<config> method in your
+application class. This can be hard-coded, or brought in from a
+separate configuration file.
+
+=head3 Using YAML
+
+YAML is a method for creating flexible and readable configuration
+files. It's a great way to keep your Catalyst application configuration
+in one easy-to-understand location.
+
+In your application class (e.g. C<lib/MyApp.pm>):
+
+  use YAML;
+  # application setup
+  __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') );
+  __PACKAGE__->setup;
+
+Now create C<myapp.yml> in your application home:
+
+  --- #YAML:1.0
+  # DO NOT USE TABS FOR INDENTATION OR label/value SEPARATION!!!
+  name:     MyApp
+
+  # authentication; perldoc Catalyst::Plugin::Authentication::CDBI
+  authentication:
+    user_class:           'MyApp::M::MyDB::Customer'
+    user_field:           'username'
+    password_field:       'password'
+    password_hash:        'md5'
+    role_class:           'MyApp::M::MyDB::Role'
+    user_role_class:      'MyApp::M::MyDB::PersonRole'
+    user_role_user_field: 'person'
+
+  # session; perldoc Catalyst::Plugin::Session::FastMmap
+  session:
+    expires:        '3600'
+    rewrite:        '0'
+    storage:        '/tmp/myapp.session'
+
+  # emails; perldoc Catalyst::Plugin::Email
+  # this passes options as an array :(
+  email:
+    - SMTP
+    - localhost
+
+This is equivalent to:
+
+  # configure base package
+  __PACKAGE__->config( name => MyApp );
+  # configure authentication
+  __PACKAGE__->config->{authentication} = {
+    user_class => 'MyApp::M::MyDB::Customer',
+    ...
+  };
+  # configure sessions
+  __PACKAGE__->config->{session} = {
+    expires => 3600,
+    ...
+  };
+  # configure email sending
+  __PACKAGE__->config->{email} = [qw/SMTP localhost/];
+
+See also L<YAML>.
+
+=head2 Using existing CDBI (etc.) classes with Catalyst
+
+Many people have existing Model classes that they would like to use with
+Catalyst (or, conversely, they want to write Catalyst models that can be
+used outside of Catalyst, e.g.  in a cron job). It's trivial to write a
+simple component in Catalyst that slurps in an outside Model:
+
+    package MyApp::M::Catalog;
+    use base qw/Catalyst::Base Some::Other::CDBI::Module::Catalog/;
+    1;
+
+and that's it! Now C<Some::Other::CDBI::Module::Catalog> is part of your
+Cat app as C<MyApp::M::Catalog>.
+
+=head1 Serving static files with Apache.
+
+When deploying your application it's a waste to serve static files 
+with Catalyst. Instead, set up something like this:
+
+    Alias /static/ "/my/static/files/"
+    <Location "/static">
+    SetHandler none
+    </Location>
+
+To match the location of your static files. 
+
+
+=cut
+
 =head1 AUTHOR
 
 Sebastian Riedel, C<sri@oook.de>
 Danijel Milicevic, C<me@danijel.de>
 Viljo Marrandi, C<vilts@yahoo.com>  
-Marcus Ramberg, C<mramberg@cpan.org>  
+Marcus Ramberg, C<mramberg@cpan.org>
+Jesse Sheidlower, C<jester@panix.com>
 Andy Grundman, C<andy@hybridized.org> 
-Marcus Ramberg C<mramberg@cpan.org>
+Chisel Wright, C<pause@herlpacker.co.uk>
 
 =head1 COPYRIGHT