Catalyst is an elegant web application framework, extremely flexible
yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
L<Maypole|Maypole>, upon which it was originally based. Its most
-important design philosphy is to provide easy access to all the tools
+important design philosophy is to provide easy access to all the tools
you need to develop web applications, with few restrictions on how you
need to use these tools. However, this does mean that it is always
possible to do things in a different way. Other web frameworks are
I<initially> simpler to use, but achieve this by locking the programmer
into a single set of tools. Catalyst's emphasis on flexibility means
that you have to think more to use it. We view this as a feature. For
-example, this leads to Catalyst being more suited to system integration
+example, this leads to Catalyst being better suited to system integration
tasks than other web frameworks.
=head3 MVC
=item * B<Controller>
Control the whole request phase, check parameters, dispatch actions, flow
-control. Catalyst itself!
+control. This is the meat of where Catalyst works.
=back
With Catalyst you register your actions and address them directly. For
example:
- sub hello : Global {
+ sub hello : Local {
my ( $self, $context ) = @_;
$context->response->body('Hello World!');
}
Now http://localhost:3000/hello prints "Hello World!".
Note that actions with the C< :Local > attribute are equivalent to
-using a C<:Path('/action_name') > attribute (note the leading slash).
-So our action could be equivalently:
+using a C<:Path('action_name') > attribute, so our action could be
+equivalently:
- sub hello : Path('/hello') {
+ sub hi : Path('hello') {
my ( $self, $context ) = @_;
$context->response->body('Hello World!');
}
=item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
-Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
-engines are also available.
+Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Another
+interesting engine is L<Catalyst::Engine::HTTP::Prefork> - available from CPAN
+separately - which will turn the built server into a fully fledged production
+ready server (although you'll probably want to run it behind a front end proxy
+if you end up using it).
+
+=item * PSGI Support
+
+Starting with Catalyst version 5.9 Catalyst ships with L<PSGI> integration
+for even more powerful and flexible testing and deployment options. See
+L<Catalyst::PSGI> for details.
=back
=head3 Install
-Installation of Catalyst can be a time-consuming and frustrating
-effort, due to its large number of dependencies. The easiest way
-to get up and running is to use Matt Trout's C<cat-install>
-script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
-and then install L<Catalyst::Devel>.
+Installation of Catalyst should be straightforward:
- # perl cat-install
+ # perl -MCPAN -e 'install Catalyst::Runtime'
# perl -MCPAN -e 'install Catalyst::Devel'
=head3 Setup
$ cd MyApp
$ script/myapp_create.pl controller Library::Login
+=head4 Frank Speiser's Amazon EC2 Catalyst SDK
+
+There are currently two flavors of publicly available Amazon Machine
+Images (AMI) that include all the elements you'd need to begin
+developing in a fully functional Catalyst environment within
+minutes. See
+L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
+more details.
+
+
=head3 Run
$ script/myapp_server.pl
many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
previously, the general idea is that the View is responsible for the
output of data to the user (typically via a web browser, but a View can
-also generate PDFs or e-mails, for example); the Model is responsible
+also generate PDFs or e-mails, for example); the Model is responsible
for providing data (typically from a relational database); and the
Controller is responsible for interacting with the user and deciding
how user input determines what actions the application takes.
In the world of MVC, there are frequent discussions and disagreements
about the nature of each element - whether certain types of logic
belong in the Model or the Controller, etc. Catalyst's flexibility
-means that this decision is entirely up to you, the programmer;
+means that this decision is entirely up to you, the programmer;
Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
a general discussion of these issues.
common class methods like C<config> and C<new> (constructor).
package MyApp::Controller::Catalog;
+ use Moose;
+ use namespace::autoclean;
- use strict;
- use base 'Catalyst::Controller';
+ BEGIN { extends 'Catalyst::Controller' }
__PACKAGE__->config( foo => 'bar' );
=over 4
-=item * B<MyApp/Model/>
-
-=item * B<MyApp/M/>
+=item * B<MyApp/Model/>
=item * B<MyApp/View/>
-=item * B<MyApp/V/>
-
=item * B<MyApp/Controller/>
-=item * B<MyApp/C/>
-
=back
-In older versions of Catalyst, the recommended practice (and the one
-automatically created by helper scripts) was to name the directories
-C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
-the use of the full names.
-
=head4 Views
To show how to define views, we'll use an already-existing base class for the
script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
-L<DBIx::Class::Schema::Loader> can automaticall load table layouts and
+L<DBIx::Class::Schema::Loader> can automatically load table layouts and
relationships, and convert them into a static schema definition
C<MySchema>, which you can edit later.
sub view : Global {
my ( $self, $c, $id ) = @_;
-
+
$c->stash->{item} = $c->model('MyModel::Foo')->find($id);
}
1;
-
+
sub end : Private {
my ( $self, $c ) = @_;
-
+
$c->stash->{template} ||= 'index.tt';
$c->forward( $c->view('TT') );
}
# in a Controller
sub list : Local {
my ( $self, $c ) = @_;
-
+
$c->stash->{template} = 'list.tt';
-
+
use Some::Outside::Database::Module;
my @records = Some::Outside::Database::Module->search({
artist => 'Led Zeppelin',
});
-
+
$c->stash->{records} = \@records;
}
From a style perspective it's usually considered bad form to make your
model "too smart" about things - it should worry about business logic
and leave the integration details to the controllers. If, however, you
-find that it does not make sense at all to use an auxillary controller
+find that it does not make sense at all to use an auxiliary controller
around the model, and the model's need to access C<$c> cannot be
sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
use base qw/Catalyst::Controller/;
- sub login : Path("login") { }
+ sub sign_in : Path("sign-in") { }
sub new_password : Path("new-password") { }
- sub logout : Path("logout") { }
+ sub sign_out : Path("sign-out") { }
package MyApp::Controller::Catalog;
method instead of returning the model itself, the return value of C<<
$model->ACCEPT_CONTEXT( $c ) >> will be used.
-This means that whenever your model/view/controller needs to talk to C<$c> it
-gets a chance to do this when it's needed.
+This means that whenever your model/view/controller needs to talk to
+C<$c> it gets a chance to do this when it's needed.
A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
with the context object set, or it will return a thin wrapper that contains
C<$c> and delegates to the per-application model object.
-A typical C<ACCEPT_CONTEXT> method could look like this:
-
- sub ACCEPT_CONTEXT {
- my ( $self, $c, @extra_arguments ) = @_;
- bless { %$self, c => $c }, ref($self);
- }
-
-effectively treating $self as a B<prototype object> that gets a new parameter.
-C<@extra_arguments> comes from any trailing arguments to
-C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
-C<< $c->view(...) >> etc).
-
-The life time of this value is B<per usage>, and not per request. To make this
-per request you can use the following technique:
+Generally it's a bad idea to expose the context object (C<$c>) in your
+model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
+to grab the bits of the context object that you need, and provide
+accessors to them in the model. This ensures that C<$c> is only in
+scope where it is needed which reduces maintenance and debugging
+headaches. So, if for example you needed two
+L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
+code, you might do something like this:
+
+ __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
+ sub ACCEPT_CONTEXT {
+ my ( $self, $c, @extra_arguments ) = @_;
+ $self = bless({ %$self,
+ model1_schema => $c->model('Model1')->schema,
+ model2_schema => $c->model('Model2')->schema
+ }, ref($self));
+ return $self;
+ }
+
+This effectively treats $self as a B<prototype object> that gets a new
+parameter. C<@extra_arguments> comes from any trailing arguments to
+C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
+>>, C<< $c->view(...) >> etc).
+
+In a subroutine in the model code, we can then do this:
+
+ sub whatever {
+ my ($self) = @_;
+ my $schema1 = $self->model1_schema;
+ my $schema2 = $self->model2_schema;
+ ...
+ }
+
+Note that we still want the Catalyst models to be a thin wrapper
+around classes that will work independently of the Catalyst
+application to promote reusability of code. Here we might just want
+to grab the $c->model('DB')->schema so as to get the connection
+information from the Catalyst application's configuration for example.
+
+The life time of this value is B<per usage>, and not per request. To
+make this per request you can use the following technique:
Add a field to C<$c>, like C<my_model_instance>. Then write your
C<ACCEPT_CONTEXT> method to look like this:
}
}
+For a similar technique to grab a new component instance on each
+request, see L<Catalyst::Component::InstancePerContext>.
+
=head3 Application Class
In addition to the Model, View, and Controller components, there's a
package MyApp;
use strict;
- use Catalyst qw/-Debug/; # Add other plugins here, e.g.
- # for session support
-
+ use parent qw/Catalyst/;
+ use Catalyst qw/-Debug ConfigLoader Static::Simple/;
MyApp->config(
name => 'My Application',
$c->res->status(404);
$c->res->redirect('http://oook.de');
-=item * L<Catalyst::Config>
+=item * config
$c->config
$c->config->{root};
=head3 Actions
-A Catalyst controller is defined by its actions. An action is a
-subroutine with a special attribute. You've already seen some examples
-of actions in this document. The URL (for example
-http://localhost.3000/foo/bar) consists of two parts, the base
-(http://localhost:3000/ in this example) and the path (foo/bar). Please
-note that the trailing slash after the hostname[:port] always belongs to
-base and not to the action.
+You've already seen some examples of actions in this document:
+subroutines with C<:Path> and C<:Local> attributes attached.
+Here, we explain what actions are and how these attributes affect
+what's happening.
+
+When Catalyst processes a webpage request, it looks for actions to
+take that will deal with the incoming request and produce a response
+such as a webpage. You create these actions for your application by
+writing subroutines within your controller and marking them with
+special attributes. The attributes, the namespace, and the function
+name determine when Catalyst will call the subroutine.
+
+These action subroutines call certain functions to say what response
+the webserver will give to the web request. They can also tell
+Catalyst to run other actions on the request (one example of this is
+called forwarding the request; this is discussed later).
+
+Action subroutines must have a special attribute on to show that they
+are actions - as well as marking when to call them, this shows that
+they take a specific set of arguments and behave in a specific way.
+At startup, Catalyst looks for all the actions in controllers,
+registers them and creates L<Catalyst::Action> objects describing
+them. When requests come in, Catalyst chooses which actions should be
+called to handle the request.
+
+(Occasionally, you might use the action objects directly, but in
+general, when we talk about actions, we're talking about the
+subroutines in your application that do things to process a request.)
+
+You can choose one of several attributes for action subroutines; these
+specify which requests are processed by that subroutine. Catalyst
+will look at the URL it is processing, and the actions that it has
+found, and automatically call the actions it finds that match the
+circumstances of the request.
+
+The URL (for example http://localhost:3000/foo/bar) consists of two
+parts, the base, describing how to connect to the server
+(http://localhost:3000/ in this example) and the path, which the
+server uses to decide what to return (foo/bar). Please note that the
+trailing slash after the hostname[:port] always belongs to base and
+not to the path. Catalyst uses only the path part when trying to find
+actions to process.
+
+Depending on the type of action used, the URLs may match a combination
+of the controller namespace, the arguments passed to the action
+attribute, and the name of the subroutine.
=over 4
+=item * B<Controller namespaces>
+
+The namespace is a modified form of the component's class (package)
+name. This modified class name excludes the parts that have a
+pre-defined meaning in Catalyst ("MyApp::Controller" in the above
+example), replaces "::" with "/", and converts the name to lower case.
+See L</Components> for a full explanation of the pre-defined meaning
+of Catalyst component class names.
+
+=item * B<Overriding the namespace>
+
+Note that C<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the
+current namespace when matching. So:
+
+ package MyApp::Controller::Example;
+
+would normally use 'example' as its namespace for matching, but if
+this is specially overridden with
+
+ __PACKAGE__->config( namespace => 'thing' );
+
+it matches using the namespace 'thing' instead.
+
=item * B<Application Wide Actions>
-Actions which are called at the root level of the application
-(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
-this:
+MyApp::Controller::Root, as created by the catalyst.pl script, will
+typically contain actions which are called for the top level of the
+application (e.g. http://localhost:3000/ ):
package MyApp::Controller::Root;
use base 'Catalyst::Controller';
+
# Sets the actions in this controller to be registered with no prefix
# so they function identically to actions created in MyApp.pm
- __PACKAGE__->config->{namespace} = '';
+
+ __PACKAGE__->config( namespace => '');
+
sub default : Path {
my ( $self, $context ) = @_;
$context->response->status(404);
$context->response->body('404 not found');
}
+
1;
+
+The code
+
+ __PACKAGE__->config( namespace => '' );
+
+makes the controller act as if its namespace is empty. As you'll see
+below, an empty namespace makes many of the URL-matching attributes, such
+as :Path and :Local match at the start of the URL path (i.e. the
+application root).
+
=back
=head4 Action types
-Catalyst supports several types of actions:
+Catalyst supports several types of actions. These mainly correspond
+to ways of matching a URL to an action subroutine. Internally, these
+matching types are implemented by L<Catalyst::DispatchType>-derived
+classes; the documentation there can be helpful in seeing how they
+work.
+
+They will all attempt to match the start of the path. The remainder
+of the path is passed as arguments.
=over 4
-=item * B<Literal> (B<Path> actions)
+=item * Namespace-prefixed (C<:Local>)
package MyApp::Controller::My::Controller;
- sub bar : Path('foo/bar') { }
+ sub foo : Local { }
-Literal C<Path> actions will act relative to their current
-namespace. The above example matches only
-http://localhost:3000/my/controller/foo/bar. If you start your path with
-a forward slash, it will match from the root. Example:
+Matches any URL beginning with> http://localhost:3000/my/controller/foo. The namespace and
+subroutine name together determine the path.
- package MyApp::Controller::My::Controller;
- sub bar : Path('/foo/bar') { }
+=item * Root-level (C<:Global>)
-Matches only http://localhost:3000/foo/bar.
+ package MyApp::Controller::Foo;
- package MyApp::Controller::My::Controller;
- sub bar : Path { }
+ sub bar : Global {
+ my ($self, $c) = @_;
+ $c->res->body(
+ $c->res->body('sub bar in Controller::Foo triggered on a request for '
+ . $c->req->uri));
+ }
-By leaving the C<Path> definition empty, it will match on the namespace
-root. The above code matches http://localhost:3000/my/controller.
+1;
-=item * B<Regex>
+Matches http://localhost:3000/bar - that is, the action is mapped
+directly to the method name, ignoring the controller namespace.
- sub bar : Regex('^item(\d+)/order(\d+)$') { }
+C<:Global> always matches from the application root: it is simply
+shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for
+C<:Path('methodname')>, which takes the controller namespace as described
+above.
-Matches any URL that matches the pattern in the action key, e.g.
-http://localhost:3000/item23/order42. The '' around the regexp is
-optional, but perltidy likes it. :)
+Usage of the C<Global> handler is rare in all but very old Catalyst
+applications (e.g. before Catalyst 5.7). The use cases where C<Global>
+used to make sense are now largely replaced by the C<Chained> dispatch
+type, or by empty C<Path> declarations on an controller action. C<Global>
+is still included in Catalyst for backwards compatibility, although
+legitimate use-cases for it may still exist.
-Regex matches act globally, i.e. without reference to the namespace from
-which it is called, so that a C<bar> method in the
-C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
-form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
-explicitly put this in the regex. To achieve the above, you should
-consider using a C<LocalRegex> action.
+=item * Changing handler behaviour: eating arguments (C<:Args>)
-=item * B<LocalRegex>
+Args is not an action type per se, but an action modifier - it adds a
+match restriction to any action it's provided to, additionally
+requiring as many path parts as are specified for the action to be
+matched. For example, in MyApp::Controller::Foo,
- sub bar : LocalRegex('^widget(\d+)$') { }
+ sub bar :Local
-LocalRegex actions act locally. If you were to use C<bar> in
-C<MyApp::Controller::Catalog>, the above example would match urls like
-http://localhost:3000/catalog/widget23.
+would match any URL starting /foo/bar. To restrict this you can do
-If you omit the "C<^>" from your regex, then it will match any depth
-from the controller and not immediately off of the controller name. The
-following example differs from the above code in that it will match
-http://localhost:3000/catalog/foo/widget23 as well.
+ sub bar :Local :Args(1)
- package MyApp::Controller::Catalog;
- sub bar : LocalRegex('widget(\d+)$') { }
+to only match URLs starting /foo/bar/* - with one additional path
+element required after 'bar'.
-For both LocalRegex and Regex actions, if you use capturing parentheses
-to extract values within the matching URL, those values are available in
-the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
-would capture "23" in the above example, and
-C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
-arguments at the end of your URL, you must use regex action keys. See
-L</URL Path Handling> below.
+NOTE that adding C<:Args(0)> and missing out :Args completely are B<not>
+the same thing.
-=item * B<Top-level> (B<Global>)
+C<:Args(0)> means that no arguments are taken. Thus, the URL and path must
+match precisely.
- package MyApp::Controller::Foo;
- sub foo : Global { }
+No :Args at all means that B<any number> of arguments are taken. Thus, any
+URL that B<starts with> the controller's path will match. Obviously, this means
+you cannot chain from an action that does not specify args, as the next action
+in the chain will be swallowed as an arg to the first!
-Matches http://localhost:3000/foo. The function name is mapped
-directly to the application base. You can provide an equivalent
-function in this case by doing the following:
- package MyApp::Controller::Root
- sub foo : Local { }
+=item * Literal match (C<:Path>)
-=item * B<Namespace-Prefixed> (B<Local>)
+C<Path> actions match things starting with a precise specified path,
+and nothing else.
- package MyApp::Controller::My::Controller;
- sub foo : Local { }
+C<Path> actions without a leading forward slash match a specified path
+relative to their current namespace. This example matches URLs
+starting http://localhost:3000/my/controller/foo/bar :
+
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('foo/bar') { }
+
+C<Path> actions B<with> a leading slash ignore their namespace, and
+match from the start of the URL path. Example:
+
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('/foo/bar') { }
+
+This matches URLs beginning http://localhost:3000/foo/bar.
+
+Empty C<Path> definitions match on the namespace only, exactly like
+C<:Global>.
+
+ package MyApp::Controller::My::Controller;
+ sub bar : Path { }
+
+The above code matches http://localhost:3000/my/controller.
-Matches http://localhost:3000/my/controller/foo.
+Actions with the C<:Local> attribute are similarly equivalent to
+C<:Path('action_name')>:
-This action type indicates that the matching URL must be prefixed with a
-modified form of the component's class (package) name. This modified
-class name excludes the parts that have a pre-defined meaning in
-Catalyst ("MyApp::Controller" in the above example), replaces "::" with
-"/", and converts the name to lower case. See L</Components> for a full
-explanation of the pre-defined meaning of Catalyst component class
-names.
+ sub foo : Local { }
-Note that actions with the C< :Local > attribute are equivalent to the
-<:Path('action_name') > so sub foo : Local { } is equivalent to -
+is equivalent to
sub foo : Path('foo') { }
-=item * B<Chained>
+=item * Pattern-match (C<:Regex> and C<:LocalRegex>)
+
+ package MyApp::Controller::My::Controller;
+ sub bar : Regex('^item(\d+)/order(\d+)$') { }
+
+This matches any URL that matches the pattern in the action key, e.g.
+http://localhost:3000/item23/order42. The '' around the regexp is
+optional, but perltidy likes it. :)
+
+C<:Regex> matches act globally, i.e. without reference to the namespace
+from which they are called. So the above will B<not> match
+http://localhost:3000/my/controller/item23/order42 - use a
+C<:LocalRegex> action instead.
+
+ package MyApp::Controller::My::Controller;
+ sub bar : LocalRegex('^widget(\d+)$') { }
+
+C<:LocalRegex> actions act locally, i.e. the namespace is matched
+first. The above example would match urls like
+http://localhost:3000/my/controller/widget23.
+
+If you omit the "C<^>" from either sort of regex, then it will match any depth
+from the base path:
+
+ package MyApp::Controller::Catalog;
+ sub bar : LocalRegex('widget(\d+)$') { }
+
+This differs from the previous example in that it will match
+http://localhost:3000/my/controller/foo/widget23 - and a number of
+other paths.
+
+For both C<:LocalRegex> and C<:Regex> actions, if you use capturing
+parentheses to extract values within the matching URL, those values
+are available in the C<$c-E<gt>req-E<gt>captures> array. In the above
+example, "widget23" would capture "23" in the above example, and
+C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to
+pass arguments at the end of your URL, you must use regex action
+keys. See L</URL Path Handling> below.
+
+=item * Chained handlers (C<:Chained>)
Catalyst also provides a method to build and dispatch chains of actions,
like
...
}
-to handle a C</catalog/*/item/*> path. For further information about this
-dispatch type, please see L<Catalyst::DispatchType::Chained>.
+to handle a C</catalog/*/item/*> path. Matching actions are called
+one after another - C<catalog()> gets called and handed one path
+element, then C<item()> gets called with another one. For further
+information about this dispatch type, please see
+L<Catalyst::DispatchType::Chained>.
=item * B<Private>
sub foo : Private { }
-Matches no URL, and cannot be executed by requesting a URL that
-corresponds to the action key. Catalyst's :Private attribute is
-exclusive and doesn't work with other attributes (so will not work
-combined with Path or Chained attributes). With the exception of the
-C< index >, C< auto > and C< default > actions, Private actions can
-only be executed from inside a Catalyst application, by calling the
-C<forward> or C<detach> methods:
+This will never match a URL - it provides a private action which can
+be called programmatically from within Catalyst, but is never called
+automatically due to the URL being requested.
+
+Catalyst's C<:Private> attribute is exclusive and doesn't work with other
+attributes (so will not work combined with C<:Path> or C<:Chained>
+attributes, for instance).
+
+Private actions can only be executed explicitly from inside a Catalyst
+application. You might do this in your controllers by calling
+catalyst methods such as C<forward> or C<detach> to fire them:
$c->forward('foo');
# or
$c->detach('foo');
-See L</Flow Control> for a full explanation of C<forward>. Note that, as
-discussed there, when forwarding from another component, you must use
-the absolute path to the method, so that a private C<bar> method in your
-C<MyApp::Controller::Catalog::Order::Process> controller must, if called
-from elsewhere, be reached with
+See L</Flow Control> for a full explanation of how you can pass
+requests on to other actions. Note that, as discussed there, when
+forwarding from another component, you must use the absolute path to
+the method, so that a private C<bar> method in your
+C<MyApp::Controller::Catalog::Order::Process> controller must, if
+called from elsewhere, be reached with
C<$c-E<gt>forward('/catalog/order/process/bar')>.
-=item * B<Args>
-
-Args is not an action type per se, but an action modifier - it adds a
-match restriction to any action it's provided to, requiring only as many
-path parts as are specified for the action to be valid - for example in
-MyApp::Controller::Foo,
-
- sub bar :Local
-
-would match any URL starting /foo/bar/. To restrict this you can do
-
- sub bar :Local :Args(1)
-
-to only match /foo/bar/*/
-
=back
-B<Note:> After seeing these examples, you probably wonder what the point
-is of defining names for regex and path actions. Every public action is
-also a private one, so you have one unified way of addressing components
-in your C<forward>s.
+B<Note:> After seeing these examples, you probably wonder what the
+point is of defining subroutine names for regex and path
+actions. However, every public action is also a private one with a
+path corresponding to its namespace and subroutine name, so you have
+one unified way of addressing components in your C<forward>s.
+
+=head4 Built-in special actions
-=head4 Built-in Private Actions
+If present, the special actions C< index >, C< auto >, C<begin>,
+C<end> and C< default > are called at certain points in the request
+cycle.
In response to specific application states, Catalyst will automatically
-call these built-in private actions in your application class:
+call these built-in actions in your application class:
=over 4
=item * B<default : Path>
-Called when no other action matches. Could be used, for example, for
-displaying a generic frontpage for the main app, or an error page for
-individual controllers.
+This is called when no other action matches. It could be used, for
+example, for displaying a generic frontpage for the main app, or an
+error page for individual controllers. B<Note>: in older Catalyst
+applications you will see C<default : Private> which is roughly
+speaking equivalent.
=item * B<index : Path : Args (0) >
as a static entry point to a controller, e.g. to have a static welcome
page. Note that it's also weighted higher than Path. Actually the sub
name C<index> can be called anything you want. The sub attributes are
-what determines the behaviour of the action.
+what determines the behaviour of the action. B<Note>: in older
+Catalyst applications, you will see C<index : Private> used, which is
+roughly speaking equivalent.
=item * B<begin : Private>
-Called at the beginning of a request, before any matching actions are
-called.
+Called at the beginning of a request, once the controller that will
+run has been identified, but before any URL-matching actions are
+called. Catalyst will call the C<begin> function in the controller
+which contains the action matching the URL.
=item * B<end : Private>
-Called at the end of a request, after all matching actions are called.
+Called at the end of a request, after all URL-matching actions are called.
+Catalyst will call the C<end> function in the controller
+which contains the action matching the URL.
+
+=item * B<auto : Private>
+
+In addition to the normal built-in actions, you have a special action
+for making chains, C<auto>. C<auto> actions will be run after any
+C<begin>, but before your URL-matching action is processed. Unlike the other
+built-ins, multiple C<auto> actions can be called; they will be
+called in turn, starting with the application class and going through
+to the most specific class.
=back
=head4 Built-in actions in controllers/autochaining
- Package MyApp::Controller::Foo;
+ package MyApp::Controller::Foo;
sub begin : Private { }
sub default : Path { }
- sub auto : Private { }
-
-You can define built-in private actions within your controllers as
-well. The actions will override the ones in less-specific controllers,
-or your application class. In other words, for each of the three
-built-in private actions, only one will be run in any request
-cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
-run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
-and C<MyApp::Controller::Catalog::Order::begin> would override this in
+ sub end : Path { }
+
+You can define built-in actions within your controllers as well as on
+your application class. In other words, for each of the three built-in
+actions above, only one will be run in any request cycle. Thus, if
+C<MyApp::Controller::Catalog::begin> exists, it will be run in place
+of C<MyApp::begin> if you're in the C<catalog> namespace, and
+C<MyApp::Controller::Catalog::Order::begin> would override this in
turn.
-=over 4
-
-=item * B<auto : Private>
-
-In addition to the normal built-in actions, you have a special action
-for making chains, C<auto>. Such C<auto> actions will be run after any
-C<begin>, but before your action is processed. Unlike the other
-built-ins, C<auto> actions I<do not> override each other; they will be
-called in turn, starting with the application class and going through to
-the I<most> specific class. I<This is the reverse of the order in which
-the normal built-ins override each other>.
+ sub auto : Private { }
-=back
+C<auto>, however, doesn't override like this: providing they exist,
+C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and
+C<MyApp::Catalog::Order::auto> would be called in turn.
Here are some examples of the order in which the various built-ins
would be called:
=item for a request for C</foo/foo>
- MyApp::begin
- MyApp::auto
+ MyApp::Controller::Foo::auto
MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
- MyApp::end
+ MyApp::Controller::Foo::end
=item for a request for C</foo/bar/foo>
MyApp::Controller::Foo::Bar::begin
- MyApp::auto
MyApp::Controller::Foo::auto
MyApp::Controller::Foo::Bar::auto
MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
false
MyApp::Controller::Foo::Bar::begin
- MyApp::auto
+ MyApp::Controller::Foo::auto # returns false, skips some calls:
+ # MyApp::Controller::Foo::Bar::auto - never called
+ # MyApp::Controller::Foo::Bar::foo - never called
MyApp::Controller::Foo::Bar::end
+You can also C<die> in the auto action; in that case, the request will
+go straight to the finalize stage, without processing further
+actions. So in the above example, C<MyApp::Controller::Foo::Bar::end>
+is skipped as well.
+
=back
-An example of why one might use this is an authentication action: you
-could set up a C<auto> action to handle authentication in your
+An example of why one might use C<auto> is an authentication action:
+you could set up a C<auto> action to handle authentication in your
application class (which will always be called first), and if
-authentication fails, returning 0 would skip any remaining methods
-for that URL.
+authentication fails, returning 0 would skip any remaining methods for
+that URL.
B<Note:> Looking at it another way, C<auto> actions have to return a
-true value to continue processing! You can also C<die> in the auto
-action; in that case, the request will go straight to the finalize
-stage, without processing further actions.
+true value to continue processing!
=head4 URL Path Handling
-You can pass variable arguments as part of the URL path, separated with
-forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
-must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
-where C<$bar> and C<$baz> may vary:
+You can pass arguments as part of the URL path, separated with forward
+slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
+must be used. For example, suppose you want to handle
+C</foo/$bar/$baz>, where C<$bar> and C<$baz> may vary:
sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
sub boo : Path('foo/boo') { .. }
sub hoo : Path('foo/boo/hoo') { .. }
-Catalyst matches actions in most specific to least specific order:
+Catalyst matches actions in most specific to least specific order - that is, whatever matches the most pieces of the path wins:
/foo/boo/hoo
/foo/boo
So Catalyst would never mistakenly dispatch the first two URLs to the
'^foo$' action.
-If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
-still match a URL containing arguments, however the arguments won't be
-available via C<@_>.
+If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
+still match a URL containing arguments; however the arguments won't be
+available via C<@_>, because the Regex will 'eat' them.
+
+Beware! If you write two matchers, that match the same path, with the
+same specificity (that is, they match the same quantity of the path),
+there's no guarantee which will actually get called. Non-regex
+matchers get tried first, followed by regex ones, but if you have, for
+instance:
+
+ package MyApp::Controller::Root;
+
+ sub match1 :Path('/a/b') { }
-=head4 Parameter Processing
+ package MyApp::Controller::A;
+
+ sub b :Local { } # Matches /a/b
+
+then Catalyst will call the one it finds first. In summary, Don't Do
+This.
+
+=head4 Query Parameter Processing
Parameters passed in the URL query string are handled with methods in
the L<Catalyst::Request> class. The C<param> method is functionally
my $current_page = $c->req->param('page') || 1;
# multiple values for single parameter name
- my @values = $c->req->param('scrolling_list');
+ my @values = $c->req->param('scrolling_list');
# DFV requires a CGI.pm-like input hash
my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
# now $c->req->args is back to what it was before
}
- sub check_message : Private {
- my ( $self, $c ) = @_;
- my $first_argument = $c->req->args->[0]; # now = 'test1'
+ sub check_message : Action {
+ my ( $self, $c, $first_argument ) = @_;
+ my $also_first_argument = $c->req->args->[0]; # now = 'test1'
# do something...
}
$c->forward('/my/controller/action');
$c->forward('/default'); # calls default in main application
-Here are some examples of how to forward to classes and methods.
+You can also forward to classes and methods.
sub hello : Global {
my ( $self, $c ) = @_;
- $c->forward(qw/MyApp::Model::Hello say_hello/);
+ $c->forward(qw/MyApp::View:Hello say_hello/);
}
sub bye : Global {
$c->forward('MyApp::Model::Hello'); # no method: will try 'process'
}
- package MyApp::Model::Hello;
+ package MyApp::View::Hello;
sub say_hello {
my ( $self, $c ) = @_;
$c->res->body('Goodbye World!');
}
+This mechanism is used by L<Catalyst::Action::RenderView> to forward
+to the C<process> method in a view class.
+
+It should be noted that whilst forward is useful, it is not the only way
+of calling other code in Catalyst. Forward just gives you stats in the debug
+screen, wraps the code you're calling in an exception handler and localises
+C<< $c->request->args >>.
+
+If you don't want or need these features then it's perfectly acceptable
+(and faster) to do something like this:
+
+ sub hello : Global {
+ my ( $self, $c ) = @_;
+ $c->stash->{message} = 'Hello World!';
+ $self->check_message( $c, 'test1' );
+ }
+
+ sub check_message {
+ my ( $self, $c, $first_argument ) = @_;
+ # do something...
+ }
+
Note that C<forward> returns to the calling action and continues
processing after the action finishes. If you want all further processing
in the calling action to stop, use C<detach> instead, which will execute
Catalyst will automatically try to call process() if you omit the
method.
-
=head3 Testing
Catalyst has a built-in http server for testing or local
comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
invaluable tool.
-For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
+For more testing ideas, see L<Catalyst::Manual::Tutorial::08_Testing>.
Have fun!
http://lists.scsys.co.uk/mailman/listinfo/catalyst
http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
-=head1 AUTHOR
+Wiki:
+
+ http://dev.catalystframework.org/wiki
-Sebastian Riedel, C<sri@oook.de>
-David Naughton, C<naughton@umn.edu>
-Marcus Ramberg, C<mramberg@cpan.org>
-Jesse Sheidlower, C<jester@panix.com>
-Danijel Milicevic, C<me@danijel.de>
-Kieren Diment, C<kd@totaldatasolution.com>
-Yuval Kogman, C<nothingmuch@woobling.org>
+FAQ:
+
+ http://dev.catalystframework.org/wiki/faq
+
+=head1 AUTHORS
+
+Catalyst Contributors, see Catalyst.pm
=head1 COPYRIGHT
-This program is free software. You can redistribute it and/or modify it
-under the same terms as Perl itself.
+This library is free software. You can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut
projects / catagits/Catalyst-Manual.git / blobdiff