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