X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FCookbook.pod;h=2c126d17d12a606b8d0f0a6245189d146dda3767;hb=5c0ff1281ecab26214c9b8279b8fb284385565f3;hp=0ed84d35a1d21a00b46e12ecff0d5b4680e7024e;hpb=145074c2e045b36a52cefcfded0908b91013f9ea;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Cookbook.pod b/lib/Catalyst/Manual/Cookbook.pod index 0ed84d3..2c126d1 100644 --- a/lib/Catalyst/Manual/Cookbook.pod +++ b/lib/Catalyst/Manual/Cookbook.pod @@ -13,12 +13,10 @@ Yummy code like your mum used to bake! You can force Catalyst to display the debug screen at the end of the request by placing a die() call in the _end 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: @@ -60,45 +58,18 @@ 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 Serving static files and CSS as text/css - -If you want to serve static content (like images, txt or CSS) via Catalyst, -then all you need is the plugin Catalyst::Plugin::Static as well as a small -regex to set the MIME type for CSS to text/css. - - # lib/MyApp.pm - package MyApp; - - use strict; - use Catalyst qw/-Debug Static/; - - __PACKAGE__->action( - - '!default' => sub { - my ( $self, $c ) = @_; - $c->serve_static; - }, - - '/^.*\.css$/' => sub { - my ( $self, $c ) = @_; - $c->serve_static('text/css'); - }, - ); - -=head2 Uploads with Catalyst +=head2 Single file upload with Catalyst To implement uploads in Catalyst you need to have a HTML form similiar to this: @@ -114,15 +85,50 @@ if it's not there, uploads just don't work. Catalyst Controller module 'upload' action: - MyApp->action( - - 'upload' => sub { - my ($self, $c) = @_; - if ($c->req->parameters->{form_submit} eq 'yes') { - my $filename = $c->req->parameters->{my_file}; - if ($filename) { - my $fh = $c->req->uploads->{$filename}->{fh}; - open(NEW_FILE, ">/tmp/$filename") or die + sub upload : Global { + my ($self, $c) = @_; + if ($c->req->parameters->{form_submit} eq 'yes') { + my $upload = $c->req->upload('my_file'); + if ($upload->filename) { + my $filename = $upload->filename; + my $fh = $upload->fh; + open(NEW_FILE, ">/tmp/upload/$filename") or die + "Can't open file for writing: $!"; + while ($fh->read(my $buf, 32768)) { + print NEW_FILE $buf; + } + close(NEW_FILE); + } + } + $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->req->parameters->{form_submit} eq 'yes') { + for my $field ($c->req->upload) { + my $upload = $c->req->upload($field); + if ($upload->filename) { + my $filename = $upload->filename; + my $fh = $upload->fh; + open(NEW_FILE, ">/tmp/upload/$filename") or die "Can't open file for writing: $!"; while ($fh->read(my $buf, 32768)) { print NEW_FILE $buf; @@ -130,15 +136,20 @@ Catalyst Controller module 'upload' action: close(NEW_FILE); } } - $c->stash->{template} = 'upload_form.tt'; - $c->forward('MyApp::V::View'); - }, - ); + } + $c->stash->{template} = 'file_upload.html'; + } + +for my $field ($c->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. -If you want to upload bigger files than 1MB, then just add to your Controller -module: +Notice: die'ing might not be what you want to do, when error occurs, but +it works as an example. Better idea would be to store error $! in +$c->stash->{error} and show custom error template displaying this message. - $CGI::Simple::POST_MAX = 1048576000; +For more information about uploads and usable methods look at +C and C. =head2 Authentication with Catalyst::Plugin::Authentication::CDBI @@ -177,25 +188,26 @@ We'll discuss the first variant for now: To log in a user you might use a action like this: - '?login' => sub { + sub 'login' : Local { my ($self, $c) = @_; if ($c->req->params->{username}) { $c->session_login($c->req->params->{username}, - $c->req->params->{password} ); + $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. +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 users login status inbetween further requests, -then just use the $c->session_login method, Catalyst will create a session -id, session cookie and automatically append session id to all urls. So -all you have to do, is just check $c->req->{user} where needed. +If you want to remember the users login status inbetween further +requests, then just use the $c->session_login method, Catalyst will +create a session id, 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 user, just call $c->session_logout. @@ -227,39 +239,40 @@ CREATE TABLE user_roles ( 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. +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 'admin' role then in you controller you can check it with: +Now if a logged in user wants to see a location which is allowed only +for people with 'admin' role then in you controller you can check it +with: - '?add' => sub { + 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 login form, if they try to access restricted areas. If you want to do this controller-wide (if you have one controller for admin section) then it's best to add user check to '!begin' action: - '!begin' => sub { + 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 - forward to login gets called, but after that -Catalyst executes anyway the action defined in the uri (eg. if you tried to -watch /add, then first '!begin' forwards to '?login', but after that -anyway '?add' is executed). So $c->req->action(undef) undefines any +Catalyst executes anyway the action defined in the uri (eg. if you +tried to watch /add, then first 'begin' forwards to 'login', but after +that anyway 'add' is executed). So $c->req->action(undef) undefines any actions that were to be called and forwards user where we want him/her to be. @@ -269,20 +282,20 @@ And this is all you need to do, isn't Catalyst wonderful? =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 are two alternatives to mod_perl that give reasonable -performance: FastCGI and PersistentPerl. +However sometimes mod_perl is not an option, and running under CGI is +just too slow. There are two alternatives to mod_perl that give +reasonable performance: FastCGI and PersistentPerl. 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. +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; @@ -291,27 +304,24 @@ a normal, single-shot CGI script. my $request = FCGI::Request(); while ($request->Accept() >= 0) { - my $output; - { - local(*STDOUT); - open( STDOUT, '>', \$output ); - MyApp->run; - } - $output =~ s!^HTTP/\d+.\d+ \d\d\d.*?\n!!s; - print $output; + MyApp->run; } -Any initialization code should be included outside the request-accept loop. +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: +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 @@ -328,26 +338,27 @@ 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. +For more information see the FastCGI documentation, the C module +and L. B -PersistentPerl (previously known as C) is a persistent Perl -interpreter. After the script is initially run, instead of exiting, the perl -interpreter is kept running. During subsequent runs, this interpreter is used -to handle new executions instead of starting a new perl interpreter each -time. A very fast frontend program contacts the persistent Perl process, which -is usually already running, to do the work and return the results. -PersistentPerl can be used to speed up perl CGI scripts. It also provides an -Apache module so that scripts can be run without the overhead of doing a -fork/exec for each request. +PersistentPerl (previously known as C) is a persistent +Perl interpreter. After the script is initially run, instead of +exiting, the perl interpreter is kept running. During subsequent runs, +this interpreter is used to handle new executions instead of starting +a new perl interpreter each time. A very fast frontend program contacts +the persistent Perl process, which is usually already running, to do +the work and return the results. +PersistentPerl can be used to speed up perl CGI scripts. It also +provides an Apache module so that scripts can be run without the +overhead of doing a fork/exec for each request. -The code for PersistentPerl is simpler than for FastCGI; rather than waiting -in an accept loop the script runs to completion, however variables are not -reinitialized on subsequent runs but maintain their values from the previous -run. +The code for PersistentPerl is simpler than for FastCGI; rather than +waiting in an accept loop the script runs to completion, however +variables are not reinitialized on subsequent runs but maintain their +values from the previous run. #!/usr/bin/perperl @@ -362,13 +373,8 @@ run. # PP-specific initialization code } } - { - local(*STDOUT); - open( STDOUT, '>', \$output ); - MyApp->run; - } - $output =~ s!^HTTP/\d+.\d+ \d\d\d.*?\n!!s; - print $output; + + MyApp->run; For more information see the C documentation. @@ -378,8 +384,9 @@ For more information see the C documentation. 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.