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 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
  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?
  55
  56 =head1 ACTION ROLES
  57
  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 ) = @_;
  68     $c->stash->{what} = 'world';
  69   };
  70
  71   after 'extecute' => sub {
  72       my ( $self, $controller, $c, $test ) = @_;
  73       $c->stash->{foo} = 'bar';
  74   };
  75
  76   1;
  77
  78 and this would be used in a controller like this:
  79
  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
  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
  99 =head2 Catalyst::Action::REST
 100
 101 Provides additional syntax for dispatching based upon the HTTP method
 102 of the request.
 103
 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
 113
 114 =head1 COPYRIGHT
 115
 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