3 Catalyst::Manual::Cookbook - Cooking with Catalyst
7 Yummy code like your mum used to bake!
11 =head2 Force debug screen
13 You can force Catalyst to display the debug screen at the end of the request by
14 placing a die() call in the _end action.
18 my ( $self, $c ) = @_;
23 =head2 Disable statistics
25 Just add this line to your application class if you don't want those nifty
26 statistics in your debug messages.
28 sub Catalyst::Log::info { }
32 Scaffolding is very simple with Catalyst.
33 Just use Catalyst::Model::CDBI::CRUD as baseclass.
35 # lib/MyApp/Model/CDBI.pm
36 package MyApp::Model::CDBI;
39 use base 'Catalyst::Model::CDBI::CRUD';
42 dsn => 'dbi:SQLite:/tmp/myapp.db',
51 use Catalyst 'FormValidator';
54 name => 'My Application',
55 root => '/home/joeuser/myapp/root'
60 my ( $self, $c ) = @_;
61 $c->form( optional => [ MyApp::Model::CDBI::Table->columns ] );
62 $c->forward('MyApp::Model::CDBI::Table');
68 Modify the $c->form() parameters to match your needs, and don't forget to copy
71 =head2 Serving static files and CSS as text/css
73 If you want to serve static content (like images, txt or CSS) via Catalyst,
74 then all you need is the plugin Catalyst::Plugin::Static as well as a small
75 regex to set the MIME type for CSS to text/css.
81 use Catalyst qw/-Debug Static/;
86 my ( $self, $c ) = @_;
90 '/^.*\.css$/' => sub {
91 my ( $self, $c ) = @_;
92 $c->serve_static('text/css');
96 =head2 Uploads with Catalyst
98 To implement uploads in Catalyst you need to have a HTML form similiar to
101 <form action="/upload" method="post" enctype="multipart/form-data">
102 <input type="hidden" name="form_submit" value="yes">
103 <input type="file" name="my_file">
104 <input type="submit" value="Send">
107 It's very important not to forget enctype="multipart/form-data" in form,
108 if it's not there, uploads just don't work.
110 Catalyst Controller module 'upload' action:
116 if ($c->req->parameters->{form_submit} eq 'yes') {
117 my $filename = $c->req->parameters->{my_file};
119 my $fh = $c->req->uploads->{$filename}->{fh};
120 open(NEW_FILE, ">/tmp/$filename") or die
121 "Can't open file for writing: $!";
122 while ($fh->read(my $buf, 32768)) {
128 $c->stash->{template} = 'upload_form.tt';
129 $c->forward('MyApp::V::View');
133 If you want to upload bigger files than 1MB, then just add to your Controller
136 $CGI::Simple::POST_MAX = 1048576000;
138 =head2 Authentication with Catalyst::Plugin::Authentication::CDBI
140 There are (at least) two ways to implement authentication with this plugin:
141 1) only checking username and password
142 2) checking username, password and the roles the user has
144 For both variants you'll need the following code in your MyApp package:
146 use Catalyst qw/Session::FastMmap Static Authentication::CDBI/;
148 MyApp->config( authentication => { user_class => 'MyApp::M::MyApp::Users',
149 user_field => 'email',
150 password_field => 'password' });
152 'user_class' is a Class::DBI class for your users table.
153 'user_field' tells which field is used for username lookup (might be
154 email, first name, surname etc).
155 'password_field' is, well, password field in your table and by default
156 password is stored in plain text. Authentication::CDBI looks for 'user'
157 and 'password' fields in table, if they're not defined in the config.
159 In PostgreSQL users table might be something like:
164 surname varchar(100),
165 password varchar(100),
170 We'll discuss the first variant for now:
171 1. user:password login / auth without roles
173 To log in a user you might use a action like this:
177 if ($c->req->params->{username}) {
178 $c->session_login($c->req->params->{username},
179 $c->req->params->{password} );
180 if ($c->req->{user}) {
181 $c->forward('?restricted_area');
186 $c->req->params->{username} and $c->req->params->{password} are html
187 form parameters from a login form. If login succeeds, then $c->req->{user}
188 contains the username of the authenticated user.
190 If you want to remember the users login status inbetween further requests,
191 then just use the $c->session_login method, Catalyst will create a session
192 id, session cookie and automatically append session id to all urls. So
193 all you have to do, is just check $c->req->{user} where needed.
195 To log out user, just call $c->session_logout.
197 Now lets take a look at the second variant:
198 2. user:password login / auth with roles
200 To use roles you need to add to MyApp->config in the 'authentication'
201 section following parameters:
203 role_class => 'MyApp::M::MyApp::Roles',
204 user_role_class => 'MyApp::M::MyApp::UserRoles',
205 user_role_user_field => 'user_id',
206 user_role_role_field => 'role_id',
208 Corresponding tables in PostgreSQL could look like this:
216 CREATE TABLE user_roles (
220 primary key(user_role_id),
221 foreign key(user_id) references users(user_id),
222 foreign key(role_id) references roles(role_id)
225 The 'roles' table is a list of role names and the 'user_role' table is used for
226 the user -> role lookup.
228 Now if a logged in user wants to see a location which is allowed only for
229 people with 'admin' role then in you controller you can check it with:
233 if ($c->roles(qw/admin/)) {
234 $c->req->output("Your account has the role 'admin.'");
236 $c->req->output("You're not allowed to be here");
240 One thing you might need is to forward non-authenticated users to login
241 form, if they try to access restricted areas. If you want to do this
242 controller-wide (if you have one controller for admin section) then it's
243 best to add user check to '!begin' action:
247 unless ($c->req->{user}) {
248 $c->req->action(undef); ## notice this!!
249 $c->forward('?login');
253 Pay attention to $c->req->action(undef). This is needed, because of the
254 way $c->forward works - forward to login gets called, but after that
255 Catalyst executes anyway the action defined in the uri (eg. if you tried to
256 watch /add, then first '!begin' forwards to '?login', but after that
257 anyway '?add' is executed). So $c->req->action(undef) undefines any
258 actions that were to be called and forwards user where we want him/her
261 And this is all you need to do, isn't Catalyst wonderful?
265 Sebastian Riedel, C<sri@oook.de>
266 Danijel Milicevic C<me@danijel.de>
267 Viljo Marrandi C<vilts@yahoo.com>
271 This program is free software, you can redistribute it and/or modify it under
272 the same terms as Perl itself.