X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=d076b8d5e181782640e69163e82cb275d7aa883a;hb=8f8532e19f5998617f0a05eab528012291168e61;hp=28f43e3b6e4546411d974813dcdc42dd9b47163a;hpb=fc7ec1d96ee55d1bf42af3abce155ecb717b9e2b;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 28f43e3..d076b8d 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -4,21 +4,24 @@ Catalyst::Manual::Cookbook - Cooking with Catalyst =head1 DESCRIPTION -Yummy! +Yummy code like your mum used to bake! =head1 RECIPES =head2 Force debug screen You can force Catalyst to display the debug screen at the end of the request by -placing a die() call in the _end action. +placing a C call in the C action. - __PACKAGE__->action( - '!end' => sub { - my ( $self, $c ) = @_; - die "testing"; - } - ); + sub end : Private { + my ( $self, $c ) = @_; + die "testing"; + } + +If you're tired of removing and adding this all the time, you +can easily add a condition. For example: + + die "Testing" if $c->params->{dump_info}; =head2 Disable statistics @@ -30,7 +33,7 @@ statistics in your debug messages. =head2 Scaffolding Scaffolding is very simple with Catalyst. -Just use Catalyst::Model::CDBI::CRUD as baseclass. +Just use Catalyst::Model::CDBI::CRUD as your base class. # lib/MyApp/Model/CDBI.pm package MyApp::Model::CDBI; @@ -55,24 +58,295 @@ Just use Catalyst::Model::CDBI::CRUD as baseclass. root => '/home/joeuser/myapp/root' ); - __PACKAGE__->action( - 'table' => sub { - my ( $self, $c ) = @_; - $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] ); - $c->forward('MyApp::Model::CDBI::Table'); - } - ); + sub my_table : Global { + my ( $self, $c ) = @_; + $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] ); + $c->forward('MyApp::Model::CDBI::Table'); + } 1; Modify the $c->form() parameters to match your needs, and don't forget to copy the templates. ;) +=head2 Single file upload with Catalyst + +To implement uploads in Catalyst you need to have a HTML form similiar to +this: + +
+ + + +
+ +It's very important not to forget C in form. Uploads will not work without this. + +Catalyst Controller module 'upload' action: + + sub upload : Global { + my ($self, $c) = @_; + + if ( $c->request->parameters->{form_submit} eq 'yes' ) { + + if ( my $upload = $c->request->upload('my_file') ) { + + my $filename = $upload->filename; + my $target = "/tmp/upload/$filename"; + + unless ( $upload->link_to($target) || $upload->copy_to($target) ) { + die( "Failed to copy '$filename' to '$target': $!" ); + } + } + } + + $c->stash->{template} = 'file_upload.html'; + } + +=head2 Multiple file upload with Catalyst + +Code for uploading multiple files from one form needs little changes compared +to single file upload. + +Form goes like this: + +
+ +
+
+
+ +
+ +Controller: + + sub upload : Local { + my ($self, $c) = @_; + + if ( $c->request->parameters->{form_submit} eq 'yes' ) { + + for my $field ( $c->req->upload ) { + + my $filename = $upload->filename; + my $target = "/tmp/upload/$filename"; + + unless ( $upload->link_to($target) || $upload->copy_to($target) ) { + die( "Failed to copy '$filename' to '$target': $!" ); + } + } + } + + $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. + +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. + +=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 + +For both variants you'll need the following code in your MyApp package: + + use Catalyst qw/Session::FastMmap Static Authentication::CDBI/; + + MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users', + user_field => 'email', + password_field => 'password' }); + +'user_class' is a Class::DBI class for your users table. +'user_field' tells which field is used for username lookup (might be +email, first name, surname etc.). +'password_field' is, well, password field in your table and by default +password is stored in plain text. Authentication::CDBI looks for 'user' +and 'password' fields in table, if they're not defined in the config. + +In PostgreSQL, the users table might be something like: + + CREATE TABLE users ( + user_id serial, + name varchar(100), + surname varchar(100), + password varchar(100), + email varchar(100), + primary key(user_id) + ); + +We'll discuss the first variant for now: +1. user:password login/auth without roles + +To log in a user you might use an action like this: + + sub 'login' : Local { + my ($self, $c) = @_; + if ($c->req->params->{username}) { + $c->session_login($c->req->params->{username}, + $c->req->params->{password} ); + if ($c->req->{user}) { + $c->forward('?restricted_area'); + } + } + } + +$c->req->params->{username} and $c->req->params->{password} are html +form parameters from a login form. If login succeeds, then +$c->req->{user} contains the username of the authenticated user. + +If you want to remember the user's login status in between further +requests, then just use the C<$c-Esession_login> method. Catalyst will +create a session id and session cookie and automatically append session +id to all urls. So all you have to do is just check $c->req->{user} +where needed. + +To log out a user, just call $c->session_logout. + +Now let's take a look at the second variant: +2. user:password login/auth with roles + +To use roles you need to add the following parameters to MyApp->config in the 'authentication' section: + + role_class => 'MyApp::M::MyApp::Roles', + user_role_class => 'MyApp::M::MyApp::UserRoles', + user_role_user_field => 'user_id', + user_role_role_field => 'role_id', + +Corresponding tables in PostgreSQL could look like this: + + CREATE TABLE roles ( + role_id serial, + name varchar(100), + primary key(role_id) + ); + + CREATE TABLE user_roles ( + user_role_id serial, + user_id int, + role_id int, + primary key(user_role_id), + foreign key(user_id) references users(user_id), + foreign key(role_id) references roles(role_id) + ); + +The 'roles' table is a list of role names and the 'user_role' table is +used for the user -> role lookup. + +Now if a logged-in user wants to see a location which is allowed only +for people with an 'admin' role, in your controller you can check it +with: + + sub add : Local { + my ($self, $c) = @_; + if ($c->roles(qw/admin/)) { + $c->req->output("Your account has the role 'admin.'"); + } else { + $c->req->output("You're not allowed to be here."); + } + } + +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: + + sub begin : Private { + my ($self, $c) = @_; + unless ($c->req->{user}) { + $c->req->action(undef); ## notice this!! + $c->forward('?login'); + } + } + +Pay attention to $c->req->action(undef). This is needed because of the +way $c->forward works - C to C gets called, but after that +Catalyst will still execute the action defined in the URI (e.g. if you +tried to go to C, then first 'begin' will forward to 'login', but after +that 'add' will nonetheless be executed). So $c->req->action(undef) undefines any +actions that were to be called and forwards the user where we want him/her +to be. + +And this is all you need to do. + + +=head2 How to use Catalyst without mod_perl + +Catalyst applications give optimum performance when run under mod_perl. +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 + +To quote from L: "FastCGI is a language +independent, scalable, extension to CGI that provides high performance +without the limitations of specific server APIs." Web server support +is provided for Apache in the form of C and there is Perl +support in the C module. To convert a CGI Catalyst application +to FastCGI one needs to initialize an C object and loop +while the C method returns zero. The following code shows how +it is done - and it also works as a normal, single-shot CGI script. + + #!/usr/bin/perl + use strict; + use FCGI; + use MyApp; + + my $request = FCGI::Request(); + while ($request->Accept() >= 0) { + MyApp->run; + } + +Any initialization code should be included outside the request-accept +loop. + +There is one little complication, which is that Crun> outputs a +complete HTTP response including the status line (e.g.: +"C"). +FastCGI just wants a set of headers, so the sample code captures the +output and drops the first line if it is an HTTP status line (note: +this may change). + +The Apache C module is provided by a number of Linux +distros and is straightforward to compile for most Unix-like systems. +The module provides a FastCGI Process Manager, which manages FastCGI +scripts. You configure your script as a FastCGI script with the +following Apache configuration directives: + + + AddHandler fastcgi-script fcgi + + +or: + + + SetHandler fastcgi-script + Action fastcgi-script /path/to/fcgi-bin/fcgi-script + + +C provides a number of options for controlling the FastCGI +scripts spawned; it also allows scripts to be run to handle the +authentication, authorization, and access check phases. + +For more information see the FastCGI documentation, the C module +and L. + =head1 AUTHOR Sebastian Riedel, C +Danijel Milicevic C +Viljo Marrandi C +Marcus Ramberg C =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it under -the same terms as Perl itself. +This program is free software, you can redistribute it and/or modify it +under the same terms as Perl itself.