=head1 DESCRIPTION
This section of the manual describes the reusable action system in
-Catalyst, how they work, descriptions of some existing ones, and how to
-write your own. Reusable actions are attributes on Catalyst methods
-that allow you to decorate your method with functions running before or
-after the method call. This can be used to implement commonly used
-action patterns, while still leaving you full freedom to customize them.
+Catalyst, how such actions work, descriptions of some existing ones, and
+how to write your own. Reusable actions are attributes on Catalyst
+methods that allow you to decorate your method with functions running
+before or after the method call. This can be used to implement commonly
+used action patterns, while still leaving you full freedom to customize
+them.
=head1 USING ACTIONS
-This is pretty simple. It works just like the normal dispatch attributes
-you are used to, like Local or Private:
+This is pretty simple. Actions work just like the normal dispatch
+attributes you are used to, like Local or Private:
sub Hello :Local :ActionClass('SayBefore') {
$c->res->output( 'Hello '.$c->stash->{what} );
In this example, we expect the SayBefore action to magically populate
stash with something relevant before C<Hello> is run. In the next
-section we'll show you how to implement it. If you want it in another
-namespace than Catalyst::Action you can prefix the action name with a
-'+', for instance '+Foo::SayBefore', or if you just want it under your
-application namespace instead, use MyAction, like MyAction('SayBefore').
+section we'll show you how to implement it. If you want it in a
+namespace other than Catalyst::Action you can prefix the action name
+with a '+', for instance '+Foo::SayBefore', or if you just want it under
+your application namespace instead, use MyAction, like
+MyAction('SayBefore').
=head1 WRITING YOUR OWN ACTIONS
=head1 ACTION ROLES
-You can only have one action class per action, which can be somewhat inflexible.
+You can only have one action class per action, which can be somewhat
+inflexible.
The solution to this is to use L<Catalyst::Controller::ActionRole>, which
would make the example above look like this:
$c->stash->{what} = 'world';
};
- after 'extecute' => sub {
+ after 'execute' => sub {
my ( $self, $controller, $c, $test ) = @_;
$c->stash->{foo} = 'bar';
};
=head1 DESCRIPTION
-Since version 5.8 the core of Catalyst is based on L<Moose>. Although
+Since version 5.8, the core of Catalyst is based on L<Moose>. Although
the developers went through great lengths to allow for a seamless
transition, there are still a few things to keep in mind when trying
to exploit the power of L<Moose> in your Catalyst application.
This document provides you with a short overview of common caveats and
-best practices to use L<Moose>-based classes within Catalyst.
+best practices for using L<Moose>-based classes within Catalyst.
=head1 THE CONTEXT CLASS
=head1 NAME
-Catalyst::Manual::Component - Reuseable components for Catalyst applications.
+Catalyst::Manual::Component - Reuseable components for Catalyst applications
=head1 DESCRIPTION
are not distributed with Catalyst but should be available from CPAN.
They typically require additional modules from CPAN.
-This list may well be outdated by the time you read this and some
-plugins may be deprecated or now part of core L<Catalyst>. Be sure to
-check the Catalyst:: and CatalystX:: namespaces for additional components and consult
-the mailing list ( L<http://dev.catalyst.perl.org/wiki/Support> ) for
-advice on the current status or preferred use of your chosen
-plugin/framework.
+This list may well be outdated by the time you read this, and some
+plugins may be deprecated, or, conversely, may now part of core
+L<Catalyst>. Be sure to check the Catalyst:: and CatalystX:: namespaces
+for additional components, and consult the mailing list (
+L<http://dev.catalyst.perl.org/wiki/Support> ) for advice on the current
+status or preferred use of your chosen plugin/framework.
=head1 PLUGINS
C<Catalyst::Plugin::Authentication::Credential::XXX> and
C<Catalyst::Plugin::Authentication::Store::XXX> namespaces.
-These plugins are still useable, however they have mostly been
-replaced with new modules in the new namespace which will work together.
+These plugins are still usable, but they have mostly been replaced with
+new modules in the new namespace which will work together.
=head3 Available Credential modules:
=head4 L<Catalyst::Authentication::Credential::FBConnect>
-Allows you to authenticate facebook users using the FBConnect API.
+Allows you to authenticate Facebook users using the FBConnect API.
=head4 L<Catalyst::Authentication::Credential::Flickr>
=head4 L<Catalyst::Authentication::Credential::OAuth>
-Allows you to authenticate users using their login on other websites supporting
-the OAuth protocol.
+Allows you to authenticate users using their login on other websites
+supporting the OAuth protocol.
=head4 L<Catalyst::Authentication::Credential::OpenID>
-Allows you to authenticate users using their login on other websites supporting
-the OpenID protocol.
+Allows you to authenticate users using their login on other websites
+supporting the OpenID protocol.
=head4 L<Catalyst::Authentication::Credential::Password>
=head4 L<Catalyst::Authentication::Credential::RPX>
-Allows you to autheticate users using the RPX protocol.
+Allows you to authenticate users using the RPX protocol.
=head4 L<Catalyst::Authentication::Credential::Remote>
-Allows you to authenticate users in Catalyst which have already been
-authenticated by your web server - this is useful for authenticating
+Allows you to authenticate users in Catalyst that have already been
+authenticated by your web server. This is useful for authenticating
users with SSL Client certificates, and using NTLM or any other
authentication protocol natively supported by your web server.
=head4 L<Catalyst::Authentication::Credential::Testing>
-Allows you to set the same password for all users, which is useful
-when you want to test logging in as multiple users / types of user,
-without having to mock things, or set all users passwords in your
-test suite.
+Allows you to set the same password for all users, which is useful when
+you want to test logging in as multiple users or multiple types of user,
+without having to mock things, or set all users' passwords in your test
+suite.
=head4 L<Catalyst::Authentication::Credential::Authen::Simple>
Allows any of the L<Authen::Simple> family of modules to be used
to authenticate users in Catalyst.
-=head3 LAvailable Store modules:
+=head3 Available Store modules:
=head4 L<Catalyst::Authentication::Store::DBIx::Class>
=head4 L<Catalyst::Authentication::Store::Htpasswd>
-Uses L<Authen::Htpasswd> to let your application use C<.htpasswd> files for its
-authentication storage.
+Uses L<Authen::Htpasswd> to let your application use C<.htpasswd> files
+for its authentication storage.
=head4 L<Catalyst::Authentication::Store::AuthTkt>
=head4 L<Catalyst::Authentication::Store::Htpasswd>
-Allows you to use an apache htpassed type file to authenticate users from.
+Allows you to use an Apache htpasswd type file to authenticate users.
=head4 L<Catalyst::Authentication::Store::KiokuDB>
-Authenticate users stored as objects in the L<KiokuDB> object graph storage
-engine system.
+Authenticate users stored as objects in the L<KiokuDB> object graph
+storage engine system.
=head4 L<Catalyst::Authentication::Store::LDAP>
=head4 L<Catalyst::Authentication::Store::Null>
-The Null store is a transparent store where any supplied user data is accepted.
-This is mainly useful for remotely authenticating credentials (e.g. OpenID) which
-may not be tied to any local storage.
+The Null store is a transparent store where any supplied user data is
+accepted. This is mainly useful for remotely authenticating credentials
+(e.g. OpenID) which may not be tied to any local storage.
=head4 L<Catalyst::Authentication::Store::RDBO>
=head4 L<Catalyst::Authentication::Store::Tangram>
-Allows access to authentication information stored in a database via a L<Tangram> class.
+Allows access to authentication information stored in a database via a
+L<Tangram> class.
=head4 L<Catalyst::Authentication::Store::DBIx::Class>
-Allows access to authentication information stored in a database via a L<DBIx::Class> class.
+Allows access to authentication information stored in a database via a
+L<DBIx::Class> class.
=head4 L<Catalyst::Authentication::Store::Jifty::DBI>
=head2 L<Catalyst::Plugin::Authorization::Roles>
-L<Catalyst::Plugin::Authorization::Roles> provides role based authorization
-for Catalyst based on L<Catalyst::Plugin::Authentication>.
+L<Catalyst::Plugin::Authorization::Roles> provides role-based
+authorization for Catalyst based on L<Catalyst::Plugin::Authentication>.
=head2 L<Catalyst::Plugin::AutoSession>
=head2 L<Catalyst::Plugin::Prototype>
-A plugin for the Prototype JavaScript library. This Plugin allows you to
+A plugin for the Prototype JavaScript library. This plugin allows you to
easily implement AJAX functionality without actually knowing Javascript.
=head2 L<Catalyst::Plugin::Redirect>
=head1 Basics
These recipes cover some basic stuff that is worth knowing for
-catalyst developers.
+Catalyst developers.
=head2 Delivering a Custom Error Page
your C<use Catalyst> statement . However, you can also enable it using
environment variable, so you can (for example) get debug info without
modifying your application scripts. Just set C<CATALYST_DEBUG> or
-C<E<lt>MYAPPE<gt>_DEBUG> to a true value.
+C<E<lt>MYAPP<gt>_DEBUG> to a true value.
=head2 Sessions
package MyApp::Controller::Foo;
use Moose;
use namespace::autoclean;
- BEGIN { extends 'Catalyst::Controller';
+ BEGIN { extends 'Catalyst::Controller' };
## Write data into the session
sub add_item : Local {
=head1 Skipping your VCS's directories
-Catalyst uses Module::Pluggable to load Models, Views and Controllers.
+Catalyst uses Module::Pluggable to load Models, Views, and Controllers.
Module::Pluggable will scan through all directories and load modules
it finds. Sometimes you might want to skip some of these directories,
for example when your version control system makes a subdirectory with
source control systems. Here is the configuration you need to add
their directories to the list to skip.
-You can make catalyst skip these directories using the Catalyst config:
+You can make Catalyst skip these directories using the Catalyst config:
# Configure the application
__PACKAGE__->config(
=head1 Users and Access Control
-Most multiuser, and some single user web applications require that
+Most multiuser, and some single-user web applications require that
users identify themselves, and the application is often required to
define those roles. The recipes below describe some ways of doing
this.
=item Authorization
Making sure the user only accesses functions you want them to
-access. This is done by checking the verified users data against your
+access. This is done by checking the verified user's data against your
internal list of groups, or allowed persons for the current page.
=back
A Storage backend contains the actual data representing the users. It
is queried by the credential verifiers. Updating the store is not done
-within this system, you will need to do it yourself.
+within this system; you will need to do it yourself.
Examples:
- DBIC - Storage using a database.
+ DBIC - Storage using a database via DBIx::Class.
Minimal - Storage using a simple hash (for testing).
=head3 User objects
A User object is created by either the storage backend or the
-credential verifier, and filled with the retrieved user information.
+credential verifier, and is filled with the retrieved user information.
Examples:
=head3 ACL authorization
ACL stands for Access Control List. The ACL plugin allows you to
-regulate access on a path by path basis, by listing which users, or
+regulate access on a path-by-path basis, by listing which users, or
roles, have access to which paths.
=head3 Roles authorization
=head3 Checking roles
-Role checking is done by using the C<< $c->check_user_roles >> method,
-this will check using the currently logged in user (via C<< $c->user
+Role checking is done by using the C<< $c->check_user_roles >> method.
+This will check using the currently logged-in user (via C<< $c->user
>>). You pass it the name of a role to check, and it returns true if
the user is a member.
=head3 Using authentication in a testing environment
-Ideally, to write tests for authentication/authorization code one
-would first set up a test database with known data, then use
+Ideally, to write tests for authentication/authorization code one would
+first set up a test database with known data, then use
L<Test::WWW::Mechanize::Catalyst> to simulate a user logging
-in. Unfortunately the former can be rather awkward, which is why it's
-a good thing that the authentication framework is so flexible.
+in. Unfortunately this can be rather awkward, which is why it's a good
+thing that the authentication framework is so flexible.
Instead of using a test database, one can simply change the
authentication store to something a bit easier to deal with in a
modifying one's database, which can be problematic if one forgets to
use the testing instead of production database.
-Alternatively, if you want to authenticate real users, but not have to worry about
-their passwords, you can use L<Catalyst::Authentication::Credential::Testing>
-to force all users to authenticate with a global password.
+Alternatively, if you want to authenticate real users, but not have to
+worry about their passwords, you can use
+L<Catalyst::Authentication::Credential::Testing> to force all users to
+authenticate with a global password.
=head3 More information
=head3 Introduction
Authorization is the step that comes after
-authentication. Authentication establishes that the user agent is
-really representing the user we think it's representing, and then
-authorization determines what this user is allowed to do.
+authentication. Authentication establishes that the user agent is really
+representing the user we think it's representing, and then authorization
+determines what this user is allowed to do.
=head3 Role Based Access Control
Under role based access control each user is allowed to perform any
number of roles. For example, at a zoo no one but specially trained
-personnel can enter the moose cage (Mynd you, møøse bites kan be
+personnel can enter the moose cage (Mynd you, møøse bites kan be
pretty nasti!). For example:
package Zoo::Controller::MooseCage;
the moose, which is a very dangerous thing. We need to restrict this
action, so that only a qualified moose feeder can perform that action.
-The Authorization::Roles plugin let's us perform role based access
+The Authorization::Roles plugin lets us perform role based access
control checks. Let's load it:
use parent qw/Catalyst/;
Checking for roles all the time can be tedious and error prone.
-The Authorization::ACL plugin let's us declare where we'd like checks
+The Authorization::ACL plugin lets us declare where we'd like checks
to be done automatically for us.
For example, we may want to completely block out anyone who isn't a
clean up in your C<end> private action instead.
Also, it's important to note that if you restrict access to "/" then
-C<end>, C<default>, etc will also be restricted.
+C<end>, C<default>, etc. will also be restricted.
MyApp->acl_allow_root_internals;
write a simple component in Catalyst that slurps in an outside Model:
package MyApp::Model::DB;
+
use base qw/Catalyst::Model::DBIC::Schema/;
+
__PACKAGE__->config(
schema_class => 'Some::DBIC::Schema',
connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}];
);
+
1;
and that's it! Now C<Some::DBIC::Schema> is part of your
=head2 Create accessors to preload static data once per server instance
When you have data that you want to load just once from the model at
-server load instead of for each request, use mk_group_accessors to
+startup, instead of for each request, use mk_group_accessors to
create accessors and tie them to resultsets in your package that
-inherits from DBIx::Class::Schema
+inherits from DBIx::Class::Schema:
package My::Schema;
use base qw/DBIx::Class::Schema/;
and now in the controller, you can now access any of these without a
per-request fetch:
- $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAMEn;
+ $c->stash->{something} = $c->model('My::Schema')->schema->ACCESSORNAME;
=head2 XMLRPC
-Unlike SOAP, XMLRPC is a very simple (and imo elegant) web-services
+Unlike SOAP, XMLRPC is a very simple (and elegant) web-services
protocol, exchanging small XML messages like these:
Request:
=head1 Views
Views pertain to the display of your application. As with models,
-catalyst is uncommonly flexible. The recipes below are just a start.
+Catalyst is uncommonly flexible. The recipes below are just a start.
=head2 Catalyst::View::TT
The Catalyst subversion repository can be found at:
svn: http://dev.catalyst.perl.org/repos/Catalyst
- browser: ttp://dev.catalyst.perl.org/svnweb/Catalyst
+ browser: http://dev.catalyst.perl.org/svnweb/Catalyst
and the git repository can be found at:
write: catagits@git.shadowcat.co.uk:PROJECTNAME
browser: https://git.shadowcat.co.uk/gitweb/gitweb.cgi
-=head2 New Catalyst extensions
+=head2 New Catalyst Extensions
As Catalyst is deliberately designed for extension, there is an ecosystem of
-several hundred Catalyst extensions which can be found on CPAN.
+several hundred Catalyst extensions that can be found on CPAN.
-See L<Catalyst::Manual::ExtendingCatalyst> for more information on how to extend
-Catalyst in various ways and how to write CPANable components for Catalyst which
-can be reused in many applications.
+See L<Catalyst::Manual::ExtendingCatalyst> for more information on how
+to extend Catalyst in various ways and how to write CPANable components
+for Catalyst which can be reused in many applications.
-It is recommended to post a request for comments to the Catalyst mailing list,
-or ask around in the #catalyst irc channel before starting to implement something,
-as another member of the community is likely to have example or prototype code that
-you can reuse, and members of the community and core team are happy to advise on
-the best way to implement a generic solution to a particular problem.
+It is recommended to post a request for comments to the Catalyst mailing
+list, or ask around in the #catalyst IRC channel before starting to
+implement something, as another member of the community is likely to
+have example or prototype code that you can reuse, and members of the
+community and core team are happy to advise on the best way to implement
+a generic solution to a particular problem.
-This could save you duplicate work, and will help you produce a betetr thought out
-and designed extension.
+This could save you duplicate work, and will help you produce a better
+thought out and designed extension.
=head1 AUTHORS
projects / catagits/Catalyst-Manual.git / commitdiff