X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=7d7c103e9d4cb5071f2f1f3bc960d76608cb0755;hb=9bee7d3734adfe39c748712670ced0f2b5c90f84;hp=573a8ff0a22195982c88551a4f6b09d5be792a3f;hpb=eff5f524553d82eb1672709248a6a2fdaaf0b089;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 573a8ff..7d7c103 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -18,10 +18,17 @@ placing a C call in the C 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 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,12 +73,16 @@ 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 from -the CPAN shell to find them. +Modify the C<$c-Eform()> 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 from the CPAN shell to find them. + +Other Scaffolding modules are in development at the time of writing. + +=head2 File uploads -=head2 Single file upload with Catalyst +=head3 Single file upload with Catalyst To implement uploads in Catalyst you need to have a HTML form similiar to this: @@ -82,7 +93,8 @@ this: -It's very important not to forget C in form. Uploads will not work without this. +It's very important not to forget C in +the form. Catalyst Controller module 'upload' action: @@ -105,12 +117,11 @@ 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 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:
@@ -120,7 +131,7 @@ Form goes like this:
-Controller: +And in the controller: sub upload : Local { my ($self, $c) = @_; @@ -142,22 +153,23 @@ Controller: $c->stash->{template} = 'file_upload.html'; } -Creq->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. +Creq->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: Cing 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: Cing 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 and C. +L and L. =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: @@ -196,7 +208,7 @@ To log in a user you might use an action like this: $c->session_login($c->req->params->{username}, $c->req->params->{password} ); if ($c->req->{user}) { - $c->forward('?restricted_area'); + $c->forward('/restricted_area'); } } } @@ -263,13 +275,13 @@ with: One thing you might need is to forward non-authenticated users to a login form if they try to access restricted areas. If you want to do this controller-wide (if you have one controller for your admin section) then it's -best to add a user check to a '!begin' action: +best to add a user check to a 'begin' action: sub begin : Private { my ($self, $c) = @_; unless ($c->req->{user}) { $c->req->action(undef); ## notice this!! - $c->forward('?login'); + $c->forward('/user/login'); } } @@ -307,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 +=head3 Using FastCGI To quote from L: "FastCGI is a language independent, scalable, extension to CGI that provides high performance @@ -362,7 +374,144 @@ authentication, authorization, and access check phases. For more information see the FastCGI documentation, the C module and L. -=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 and +C requires more code to manage, because you must separately +identify each static directory--if you decide to add a C +directory, you'll need to change your code to account for it. In +contrast, keeping all static directories as subdirectories of a main +C 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 with everything else being +Template Toolkit files. Now you can identify the static content by +matching C 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 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 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-Eres-Ebody>. + +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. + + $ 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: + + + +=head3 Common problems + +The Static plugin makes use of the C 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. 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 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: + + + use lib qw(/var/www/MyApp/lib); + + PerlModule MyApp + + + ServerName myapp.example.com + DocumentRoot /var/www/MyApp/root + + SetHandler perl-script + PerlHandler MyApp + + + SetHandler default-handler + + + +And here's a simpler example that'll get you started: + + Alias /static/ "/my/static/files/" + + SetHandler none + + +=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 @@ -379,12 +528,133 @@ the Catalyst Request object: (See L for more information on passing arguments via C.) +=head2 Configure your application + +You configure your application with the C 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): + + use YAML; + # application setup + __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') ); + __PACKAGE__->setup; + +Now create C 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. + +=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 is part of your +Cat app as C. + +=head2 Delivering a Custom Error Page + +By default, Catalyst will display its own error page whenever it +encounters an error in your application. When running under C<-Debug> +mode, the error page is a useful screen including the error message and +a full Data::Dumper output of the C<$c> context object. When not in +C<-Debug>, users see a simple "Please come back later" screen. + +To use a custom error page, use a special C method to short-circut +the error processing. The following is an example; you might want to +adjust it further depending on the needs of your application (for +example, any calls to C will probably need to go into this +C method; see L). + + sub end : Private { + my ( $self, $c ) = @_; + + if ( scalar @{ $c->error } ) { + $c->stash->{errors} = $c->error; + $c->stash->{template} = 'errors.tt'; + $c->forward('MyApp::View::TT'); + $c->{error} = []; + } + + return 1 if $c->response->status =~ /^3\d\d$/; + return 1 if $c->response->body; + + unless ( $c->response->content_type ) { + $c->response->content_type('text/html; charset=utf-8'); + } + + $c->forward('MyApp::View::TT'); + } + +You can manually set errors in your code to trigger this page by calling + + $c->error( 'You broke me!' ); + =head1 AUTHOR Sebastian Riedel, C -Danijel Milicevic C -Viljo Marrandi C -Marcus Ramberg C +Danijel Milicevic, C +Viljo Marrandi, C +Marcus Ramberg, C +Jesse Sheidlower, C +Andy Grundman, C +Chisel Wright, C =head1 COPYRIGHT