Commit | Line | Data |
cb93c9d7 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Actions - Catalyst Reusable Actions |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This section of the manual describes the reusable action system in |
8 | Catalyst, how they work, descriptions of some existing ones, and how to |
9 | write your own. Reusable actions are attributes on Catalyst methods |
10 | that allow you to decorate your method with functions running before or |
11 | after the method call. This can be used to implement commonly used |
12 | action patterns, while still leaving you full freedom to customize them. |
13 | |
14 | =head1 USING ACTIONS |
15 | |
16 | This is pretty simple. It works just like the normal dispatch attributes |
17 | you are used to, like Local or Private: |
18 | |
19 | sub Hello :Local :ActionClass('SayBefore') { |
20 | $c->res->output( 'Hello '.$c->stash->{what} ); |
21 | } |
22 | |
23 | In this example, we expect the SayBefore action to magically populate |
24 | stash with something relevant before C<Hello> is run. In the next |
25 | section we'll show you how to implement it. If you want it in another |
26 | namespace than Catalyst::Action you can prefix the action name with a |
27 | '+', for instance '+Foo::SayBefore', or if you just want it under your |
28 | application namespace instead, use MyAction, like MyAction('SayBefore'). |
29 | |
30 | =head1 WRITING YOUR OWN ACTIONS |
31 | |
32 | Implementing the action itself is almost as easy. Just use |
33 | L<Catalyst::Action> as a base class and decorate the C<execute> call in |
34 | the Action class: |
35 | |
bbddff00 |
36 | package Catalyst::Action::MyAction; |
37 | use Moose; |
38 | use namespace::autoclean; |
39 | |
40 | extends 'Catalyst::Action'; |
41 | |
42 | before 'execute' => sub { |
43 | my ( $self, $controller, $c, $test ) = @_; |
44 | $c->stash->{what} = 'world'; |
45 | }; |
46 | |
47 | after 'extecute' => sub { |
48 | my ( $self, $controller, $c, $test ) = @_; |
49 | $c->stash->{foo} = 'bar'; |
50 | }; |
51 | |
52 | __PACKAGE__->meta->make_immutable; |
53 | |
54 | Pretty simple, huh? |
cb93c9d7 |
55 | |
bbddff00 |
56 | =head1 ACTION ROLES |
cb93c9d7 |
57 | |
bbddff00 |
58 | You can only have one action class per action, which can be somewhat inflexible. |
59 | |
60 | The solution to this is to use L<Catalyst::Controller::ActionRole>, which |
61 | would make the example above look like this: |
62 | |
63 | package Catalyst::ActionRole::MyActionRole; |
64 | use Moose::Role; |
65 | |
66 | before 'execute' => sub { |
67 | my ( $self, $controller, $c, $test ) = @_; |
cb93c9d7 |
68 | $c->stash->{what} = 'world'; |
cb93c9d7 |
69 | }; |
70 | |
bbddff00 |
71 | after 'extecute' => sub { |
72 | my ( $self, $controller, $c, $test ) = @_; |
73 | $c->stash->{foo} = 'bar'; |
74 | }; |
75 | |
cb93c9d7 |
76 | 1; |
77 | |
bbddff00 |
78 | and this would be used in a controller like this: |
cb93c9d7 |
79 | |
bbddff00 |
80 | package MyApp::Controller::Foo; |
81 | use Moose; |
82 | use namespace::autoclean; |
83 | BEGIN { extends 'Catalyst::Controller::ActionRole'; } |
84 | |
85 | sub foo : Does('MyActionRole') { |
86 | my ($self, $c) = @_; |
87 | } |
88 | |
89 | 1; |
90 | |
91 | =head1 EXAMPLE ACTIONS |
cb93c9d7 |
92 | |
93 | =head2 Catalyst::Action::RenderView |
94 | |
95 | This is meant to decorate end actions. It's similar in operation to |
96 | L<Catalyst::Plugin::DefaultEnd>, but allows you to decide on an action |
97 | level rather than on an application level where it should be run. |
98 | |
bbddff00 |
99 | =head2 Catalyst::Action::REST |
100 | |
101 | Provides additional syntax for dispatching based upon the HTTP method |
102 | of the request. |
cb93c9d7 |
103 | |
bbddff00 |
104 | =head1 EXAMPLE ACTIONROLES |
105 | |
106 | =head2 Catalyst::ActionRole::ACL |
107 | |
108 | Provides ACLs for role membership by decorating your actions. |
109 | |
110 | =head1 AUTHORS |
111 | |
112 | Catalyst Contributors, see Catalyst.pm |
cb93c9d7 |
113 | |
114 | =head1 COPYRIGHT |
115 | |
bbddff00 |
116 | This library is free software. You can redistribute it and/or modify it under |
117 | the same terms as Perl itself. |
118 | |
119 | =cut |