lib/Catalyst/Manual/Actions.pod

   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 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.
  14
  15 =head1 USING ACTIONS
  16
  17 This is pretty simple. Actions work just like the normal dispatch
  18 attributes you are used to, like Local or Private:
  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
  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').
  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
  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 'execute' => sub {
  50       my ( $self, $controller, $c, $test ) = @_;
  51       $c->stash->{foo} = 'bar';
  52   };
  53
  54   __PACKAGE__->meta->make_immutable;
  55
  56 Pretty simple, huh?
  57
  58 =head1 ACTION ROLES
  59
  60 You can only have one action class per action, which can be somewhat
  61 inflexible.
  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 ) = @_;
  71     $c->stash->{what} = 'world';
  72   };
  73
  74   after 'execute' => sub {
  75       my ( $self, $controller, $c, $test ) = @_;
  76       $c->stash->{foo} = 'bar';
  77   };
  78
  79   1;
  80
  81 and this would be used in a controller like this:
  82
  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
  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
 102 =head2 Catalyst::Action::REST
 103
 104 Provides additional syntax for dispatching based upon the HTTP method
 105 of the request.
 106
 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
 116
 117 =head1 COPYRIGHT
 118
 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