=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<die()> call in the C<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:
+
+ die "Testing" if $c->params->{dump_info};
=head2 Disable statistics
=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;
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:
+
+ <form action="/upload" method="post" enctype="multipart/form-data">
+ <input type="hidden" name="form_submit" value="yes">
+ <input type="file" name="my_file">
+ <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.
+
+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:
+
+ <form action="/upload" method="post" enctype="multipart/form-data">
+ <input type="hidden" name="form_submit" value="yes">
+ <input type="file" name="file1" size="50"><br>
+ <input type="file" name="file2" size="50"><br>
+ <input type="file" name="file3" size="50"><br>
+ <input type="submit" value="Send">
+ </form>
+
+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';
+ }
+
+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.
+
+For more information about uploads and usable methods look at
+C<Catalyst::Request::Upload> and C<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
+
+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-E<gt>session_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<forward> to C<login> gets called, but after that
+Catalyst will still execute the action defined in the URI (e.g. if you
+tried to go to C</add>, 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<Using FastCGI>
+
+To quote from L<http://www.fastcgi.com/>: "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<mod_fastcgi> and there is Perl
+support in the C<FCGI> module. To convert a CGI Catalyst application
+to FastCGI one needs to initialize an C<FCGI::Request> object and loop
+while the C<Accept> 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 C<MyApp-E<gt>run> outputs a
+complete HTTP response including the status line (e.g.:
+"C<HTTP/1.1 200>").
+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<mod_fastcgi> 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:
+
+ <Location /fcgi-bin>
+ AddHandler fastcgi-script fcgi
+ </Location>
+
+or:
+
+ <Location /fcgi-bin>
+ SetHandler fastcgi-script
+ Action fastcgi-script /path/to/fcgi-bin/fcgi-script
+ </Location>
+
+C<mod_fastcgi> 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<FCGI> module
+and L<http://www.fastcgi.com/>.
+
=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>
=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.
projects / catagits/Catalyst-Runtime.git / blobdiff