=head2 Force debug screen
-You can force Catalyst to display the debug screen at the end of the
-request by placing a C<die()> call in the C<end> action.
+You can force Catalyst to display the debug screen at the end of the request by
+placing a C<die()> call in the C<end> action.
sub end : Private {
my ( $self, $c ) = @_;
die "forced debug";
}
-If you're tired of removing and adding this all the time, you
-can add a condition in the C<end> action:
+If you're tired of removing and adding this all the time, you can add a
+condition in the C<end> action. For example:
- sub end : Private {
- my ( $self, $c ) = @_;
- die "forced debug" if $c->req->params->{dump_info};
- }
+ 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.
-Then just add to your query string C<"&dump_info=1">, or the like,
-to force debug output.
=head2 Disable statistics
=head2 Scaffolding
Scaffolding is very simple with Catalyst.
-Just use Catalyst::Model::CDBI::CRUD as your base class.
-
- # lib/MyApp/Model/CDBI.pm
- package MyApp::Model::CDBI;
-
- use strict;
- use base 'Catalyst::Model::CDBI::CRUD';
-
- __PACKAGE__->config(
- dsn => 'dbi:SQLite:/tmp/myapp.db',
- relationships => 1
- );
-
- 1;
- # lib/MyApp.pm
- package MyApp;
+The recommended way is to use Catalyst::Helper::Controller::Scaffold.
- use Catalyst 'FormValidator';
+Just install this module, and to scaffold a Class::DBI Model class, do the following:
- __PACKAGE__->config(
- name => 'My Application',
- root => '/home/joeuser/myapp/root'
- );
+./script/myapp_create controller <name> Scaffold <CDBI::Class>Scaffolding
- 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 into the template root. Can't find the templates?
-They were in the CRUD model distribution, so you can do B<look
-Catalyst::Model::CDBI::CRUD> 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
+To implement uploads in Catalyst, you need to have a HTML form similar to
this:
<form action="/upload" method="post" enctype="multipart/form-data">
$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 a few changes:
<input type="submit" value="Send">
</form>
-And in the Controller:
+And in the controller:
sub upload : Local {
my ($self, $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
+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:
$c->session_login($c->req->params->{username},
$c->req->params->{password} );
if ($c->req->{user}) {
- $c->forward('?restricted_area');
+ $c->forward('/restricted_area');
}
}
}
sub add : Local {
my ($self, $c) = @_;
if ($c->roles(qw/admin/)) {
- $c->req->output("Your account has the role 'admin.'");
+ $c->res->output("Your account has the role 'admin.'");
} else {
- $c->req->output("You're not allowed to be here.");
+ $c->res->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:
+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');
}
}
-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.
+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 Pass-through login (and other actions)
-An easy way of having assorted actions that occur during the processing of
-a request that are orthogonal to its actual purpose - logins, silent
+An easy way of having assorted actions that occur during the processing
+of a request that are orthogonal to its actual purpose - logins, silent
commands etc. Provide actions for these, but when they're required for
-something else fill e.g. a form variable __login and have a sub begin like so:
+something else fill e.g. a form variable __login and have a sub begin
+like so:
-sub begin : Private {
- my ($self, $c) = @_;
- foreach my $action (qw/login docommand foo bar whatever/) {
- if ($c->req->params->{"__${action}"}) {
- $c->forward($action);
+ sub begin : Private {
+ my ($self, $c) = @_;
+ foreach my $action (qw/login docommand foo bar whatever/) {
+ if ($c->req->params->{"__${action}"}) {
+ $c->forward($action);
+ }
+ }
}
- }
-}
=head2 How to use Catalyst without mod_perl
just too slow. There's also an alternative to mod_perl that gives
reasonable performance named FastCGI.
-B<Using FastCGI>
+=head3 Using FastCGI
To quote from L<http://www.fastcgi.com/>: "FastCGI is a language
independent, scalable, extension to CGI that provides high performance
For more information see the FastCGI documentation, the C<FCGI> module
and L<http://www.fastcgi.com/>.
-
+
=head2 Serving static content
Serving static content in Catalyst can be somewhat tricky; this recipe
<link rel="icon" href="/static/myapp.ico" type="image/x-icon" />
-
=head3 Common problems
The Static plugin makes use of the C<shared-mime-info> package to
automatically determine MIME types. This package is notoriously
-difficult to install, especially on win32 and OSX. For OSX the easiest
+difficult to install, especially on win32 and OS X. For OS X the easiest
path might be to install Fink, then use C<apt-get install
shared-mime-info>. Restart the server, and everything should be fine.
controller by intercepting requests for the C<root/static> 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; variations, some of
-which could be simpler, are left as an exercise for the reader:
+config for this application under mod_perl 1.x:
<Perl>
use lib qw(/var/www/MyApp/lib);
</LocationMatch>
</VirtualHost>
+And here's a simpler example that'll get you started:
+
+ Alias /static/ "/my/static/files/"
+ <Location "/static">
+ SetHandler none
+ </Location>
+
=head2 Forwarding with arguments
Sometimes you want to pass along arguments when forwarding to another
-action. This can be accomplished by simply setting the arguments before
-the forward:
-
+action. As of version 5.30, arguments can be passed in the call to
+C<forward>; in earlier versions, you can manually set the arguments in
+the Catalyst Request object:
+
+ # version 5.30 and later:
+ $c->forward('/wherever', [qw/arg1 arg2 arg3/]);
+
+ # pre-5.30
$c->req->args([qw/arg1 arg2 arg3/]);
$c->forward('/wherever');
+(See L<Catalyst::Manual::Intro#Flow_Control> for more information on
+passing arguments via C<forward>.)
+
+=head2 Configure your application
+
+You configure your application with the C<config> 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<lib/MyApp.pm>):
+
+ use YAML;
+ # application setup
+ __PACKAGE__->config( YAML::LoadFile(__PACKAGE__->config->{'home'} . '/myapp.yml') );
+ __PACKAGE__->setup;
+
+Now create C<myapp.yml> 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<YAML>.
+
+=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<Some::Other::CDBI::Module::Catalog> is part of your
+Cat app as C<MyApp::M::Catalog>.
+
+=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<end> method to short-circuit
+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<fillform> will probably need to go into this
+C<end> method; see L<Catalyst::Plugin::FillInForm>).
+
+ 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!' );
+
+=head2 Require user logins
+
+It's often useful to restrict access to your application to a set of
+registered users, forcing everyone else to the login page until they're
+signed in.
+
+To implement this in your application make sure you have a customer
+table with username and password fields and a corresponding Model class
+in your Catalyst application, then make the following changes:
+
+=head3 lib/MyApp.pm
+
+ use Catalyst qw/Session::FastMmap Authentication::CDBI/;
+
+ __PACKAGE__->config->{authentication} = {
+ 'user_class' => 'ScratchPad::M::MyDB::Customer',
+ 'user_field' => 'username',
+ 'password_field' => 'password',
+ 'password_hash' => '',
+ };
+
+ sub auto : Private {
+ my ($self, $c) = @_;
+ my $login_path = 'user/login';
+
+ # allow people to actually reach the login page!
+ if ($c->req->path eq $login_path) {
+ return 1;
+ }
+
+ # if we have a user ... we're OK
+ if ( $c->req->user ) {
+ $c->session->{'authed_user'} =
+ MyApp::M::MyDB::Customer->retrieve(
+ 'username' => $c->req->user
+ );
+ }
+
+ # otherwise they're not logged in
+ else {
+ # force the login screen to be shown
+ $c->res->redirect($c->req->base . $login_path);
+ }
+
+ # continue with the processing chain
+ return 1;
+ }
+
+=head3 lib/MyApp/C/User.pm
+
+ sub login : Path('/user/login') {
+ my ($self, $c) = @_;
+
+ # default template
+ $c->stash->{'template'} = "user/login.tt";
+ # default form message
+ $c->stash->{'message'} = 'Please enter your username and password';
+
+ if ( $c->req->param('username') ) {
+ # try to log the user in
+ $c->session_login(
+ $c->req->param('username'),
+ $c->req->param('password'),
+ );
+
+ # if we have a user we're logged in
+ if ( $c->req->user ) {
+ $c->res->redirect('/some/page');
+ }
+
+ # otherwise we failed to login, try again!
+ else {
+ $c->stash->{'message'} =
+ 'Unable to authenticate the login details supplied';
+ }
+ }
+ }
+
+ sub logout : Path('/user/logout') {
+ my ($self, $c) = @_;
+ # logout the session, and remove information we've stashed
+ $c->session_logout;
+ delete $c->session->{'authed_user'};
+
+ # do the 'default' action
+ $c->res->redirect($c->req->base);
+}
+
+
+=head3 root/base/user/login.tt
+
+ [% INCLUDE header.tt %]
+ <form action="/user/login" method="POST" name="login_form">
+ [% message %]<br />
+ <label for="username">username:</label><br />
+ <input type="text" id="username" name="username" /><br />
+
+ <label for="password">password:</label><br />
+ <input type="password" id="password" name="password" /><br />
+
+ <input type="submit" value="log in" name="form_submit" />
+ </form>
+ [% INCLUDE footer.tt %]
+
=head1 AUTHOR
Sebastian Riedel, C<sri@oook.de>
Danijel Milicevic, C<me@danijel.de>
-Viljo Marrandi, C<vilts@yahoo.com>
+Viljo Marrandi, C<vilts@yahoo.com>
Marcus Ramberg, C<mramberg@cpan.org>
-Andy Grundman, C<andy@hybridized.org>
+Jesse Sheidlower, C<jester@panix.com>
+Andy Grundman, C<andy@hybridized.org>
+Chisel Wright, C<pause@herlpacker.co.uk>
=head1 COPYRIGHT
projects / catagits/Catalyst-Runtime.git / blobdiff