[Copy to clipboard] [ - ]
CODE:
Action types
Catalyst supports several types of actions:
Literal (Path actions)
package MyApp::Controller::My::Controller;
sub bar : Path('foo/bar') { }
Literal 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:
package MyApp::Controller::My::Controller;
sub bar : Path('/foo/bar') { }
Matches only http://localhost:3000/foo/bar.
package MyApp::Controller::My::Controller;
sub bar : Path { }
By leaving the Path definition empty, it will match on the namespace root. The above code matches http://localhost:3000/my/controller.
Regex
sub bar : Regex('^item(\d+)/order(\d+)$') { }
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. :)
Regex matches act globally, i.e. without reference to the namespace from which it is called, so that a bar method in the MyApp::Controller::Catalog::Order::Process namespace won't match any form of bar, Catalog, Order, or Process unless you explicitly put this in the regex. To achieve the above, you should consider using a LocalRegex action.
LocalRegex
sub bar : LocalRegex('^widget(\d+)$') { }
LocalRegex actions act locally. If you were to use bar in MyApp::Controller::Catalog, the above example would match urls like http://localhost:3000/catalog/widget23.
If you omit the ``^'' 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.
package MyApp::Controller::Catalog;
sub bar : LocalRegex('widget(\d+)$') { }
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->req->captures array. In the above example, ``widget23'' would capture ``23'' in the above example, and $c->req->captures->[0] would be ``23''. If you want to pass arguments at the end of your URL, you must use regex action keys. See URL Path Handling below.
Top-level (Global)
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:
package MyApp::Controller::Root
sub foo : Local { }
Namespace-Prefixed (Local)
package MyApp::Controller::My::Controller;
sub foo : Local { }
Matches http://localhost:3000/my/controller/foo.
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 Components for a full explanation of the pre-defined meaning of Catalyst component class names.
Chained
Catalyst also provides a method to build and dispatch chains of actions, like
sub catalog : Chained : CaptureArgs(1) {
my ( $self, $c, $arg ) = @_;
...
}
sub item : Chained('catalog') : Args(1) {
my ( $self, $c, $arg ) = @_;
...
}
to handle a /catalog/*/item/* path. For further information about this dispatch type, please see the Catalyst::DispatchType::Chained manpage.
Private
sub foo : Private { }
Matches no URL, and cannot be executed by requesting a URL that corresponds to the action key. Private actions can be executed only inside a Catalyst application, by calling the forward method:
$c->forward('foo');
See Flow Control for a full explanation of forward. Note that, as discussed there, when forwarding from another component, you must use the absolute path to the method, so that a private bar method in your MyApp::Controller::Catalog::Order::Process controller must, if called from elsewhere, be reached with $c->forward('/catalog/order/process/bar').
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/*/
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 forwards.
Built-in Private Actions
In response to specific application states, Catalyst will automatically call these built-in private actions in your application class:
default : Private
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.
If default isn't acting how you would expect, look at using a Literal Path action (with an empty path string). The difference is that Path takes arguments relative from the namespace and default always takes arguments relative from the root, regardless of what controller it's in. Indeed, this is now the recommended way of handling default situations; the default private controller should be considered deprecated.
index : Private
index is much like default except that it takes no arguments and it is weighted slightly higher in the matching process. It is useful 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.
begin : Private
Called at the beginning of a request, before any matching actions are called.
end : Private
Called at the end of a request, after all matching actions are called.
Built-in actions in controllers/autochaining
Package MyApp::Controller::Foo;
sub begin : Private { }
sub default : Private { }
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 MyApp::Controller::Catalog::begin exists, it will be run in place of MyApp::begin if you're in the catalog namespace, and MyApp::Controller::Catalog::Order::begin would override this in turn.
auto : Private
In addition to the normal built-in actions, you have a special action for making chains, auto. Such auto actions will be run after any begin, but before your action is processed. Unlike the other built-ins, auto actions do not override each other; they will be called in turn, starting with the application class and going through to the most specific class. This is the reverse of the order in which the normal built-ins override each other.
Here are some examples of the order in which the various built-ins would be called:
for a request for /foo/foo
MyApp::begin
MyApp::auto
MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
MyApp::end
for a request for /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
MyApp::Controller::Foo::Bar::end
The auto action is also distinguished by the fact that you can break out of the processing chain by returning 0. If an auto action returns 0, any remaining actions will be skipped, except for end. So, for the request above, if the first auto returns false, the chain would look like this:
for a request for /foo/bar/foo where first auto returns false
MyApp::Controller::Foo::Bar::begin
MyApp::auto
MyApp::Controller::Foo::Bar::end
An example of why one might use this is an authentication action: you could set up a 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.
Note: Looking at it another way, auto actions have to return a true value to continue processing! You can also die in the auto action; in that case, the request will go straight to the finalize stage, without processing further actions.
