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::SayBefore;
  37
  38   use base 'Catalyst::Action';
  39
  40   sub execute {
  41     my $self = shift;
  42     my ( $controller, $c, $test ) = @_;
  43     $c->stash->{what} = 'world';
  44     $self->next::method( @_ );
  45   };
  46
  47   1;
  48
  49 If you want to do something after the action, just put it after the
  50 C<execute> call. Pretty simple, huh?
  51
  52 =head1 ACTIONS
  53
  54 =head2 Catalyst::Action::RenderView
  55
  56 This is meant to decorate end actions. It's similar in operation to
  57 L<Catalyst::Plugin::DefaultEnd>, but allows you to decide on an action
  58 level rather than on an application level where it should be run.
  59
  60 =head1 AUTHOR
  61
  62 The Catalyst Core Team - see http://catalyst.perl.org/
  63
  64 =head1 COPYRIGHT
  65
  66 This program is free software. You can redistribute it and/or modify it
  67 under the same terms as Perl itself.