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:
+Note that actions with the C< :Global > attribute are equivalent to
+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).
=back
=head3 Install
-Installation of Catalyst can be a time-consuming effort, due to its
-large number of dependencies. Although most of the frustrations
-associated with this are now ironed out and a simple C<cpan
-Catalyst::Devel> or C<cpan Catalyst::Runtime> are now usually
-straightforward, if you still have problems, you can use 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
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/Model/>
=item * B<MyApp/M/>
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.
+C<M/>, C<V/>, and C<C/>. Though these still work, they are deprecated
+and we now recommend the use of the full names.
=head4 Views
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;
}
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 neaded 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
$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 __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';
}
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, :Local and :Global matches, match at the start of the
+URL path.
+
=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 * Namespace-level (C<:Global>)
-Matches only http://localhost:3000/foo/bar.
+ package MyApp::Controller::Foo;
+ sub foo : Global { }
- package MyApp::Controller::My::Controller;
- sub bar : Path { }
+Matches http://localhost:3000/foo - that is, the action is mapped
+directly to the controller namespace, ignoring the function name.
-By leaving the C<Path> definition empty, it will match on the namespace
-root. The above code matches http://localhost:3000/my/controller.
+C<:Global> is equivalent C<:Local> one level higher in
+the namespace.
-=item * B<Regex>
+ package MyApp::Controller::Root;
+ __PACKAGE__->config->{namespace}='';
+ sub foo : Local { }
- sub bar : Regex('^item(\d+)/order(\d+)$') { }
+Use whichever makes the most sense for your application.
-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. :)
+=item * Changing handler behaviour: eating arguments (C<:Args>)
-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.
+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,
-=item * B<LocalRegex>
+ sub bar :Local
- sub bar : LocalRegex('^widget(\d+)$') { }
+would match any URL starting /foo/bar. To restrict this you can do
-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.
+ sub bar :Local :Args(1)
-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.
+to only match URLs starting /foo/bar/* - with one additional path
+element required after 'bar'.
- package MyApp::Controller::Catalog;
- sub bar : LocalRegex('widget(\d+)$') { }
+NOTE that adding C<:Args(0)> and missing out :Args completely are B<not>
+the same thing.
-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.
+C<:Args(0)> means that no arguments are taken. Thus, the URL and path must
+match precisely.
-=item * B<Top-level> (B<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.
- package MyApp::Controller::Foo;
- sub foo : Global { }
-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:
+=item * Literal match (C<:Path>)
- package MyApp::Controller::Root
- sub foo : Local { }
+C<Path> actions match things starting with a precise specified path,
+and nothing else.
-=item * B<Namespace-Prefixed> (B<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 foo : Local { }
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('foo/bar') { }
-Matches http://localhost:3000/my/controller/foo.
+C<Path> actions B<with> a leading slash ignore their namespace, and
+match from the start of the URL path. Example:
-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.
+ package MyApp::Controller::My::Controller;
+ sub bar : Path('/foo/bar') { }
-Note that actions with the C< :Local > attribute are equivalent to the
-<:Path('action_name') > so sub foo : Local { } is equivalent to -
+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.
+
+Actions with the C<:Local> attribute are similarly equivalent to
+C<:Path('action_name')>:
+
+ sub foo : Local { }
+
+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 Private Actions
+=head4 Built-in special 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. B<Note>: in older Catalyst applications you
-will see C<default : Private> which is roughly speaking equivalent.
+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) >
=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::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.
-=head4 Parameter Processing
+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') { }
+
+ 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
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