Cataly...onRole(3pm)

💖 Catalyst::Controller::ActionRole — the manual page, but make it make sense 💖

okay bestie, gather round, because this is Catalyst::Controller::ActionRole (a 3pm manual page, iykyk) and it's the module that lets you slap Moose roles onto your action instances. also. um. it's DEPRECATED. we'll get to that. deep breaths. 🫶

---

✨ VERSION ✨

version 0.17 — that's the one, no cap.

---

🌸 SYNOPSIS 🌸

package MyApp::Controller::Foo;

use Moose;
use namespace::autoclean;

BEGIN { extends 'Catalyst::Controller::ActionRole' }

sub bar : Local Does('Moo') { ... }

look at that little Does('Moo') sitting there being iconic. that's the whole vibe. 💅

---

🦋 DESCRIPTION 🦋

so this module lets you apply Moose::Roles to the Catalyst::Actions that belong to your different controller methods. yes. exactly that. obsessed.

to make it happen, there's a Does attribute. it takes an argument, and that argument decides which role is gonna get applied. here's how it reads the vibe:

• if the argument starts with "+", it's treated as the full name of the role. periodt.
• if it starts with "~", then your application's name gets prepended, followed by "::ActionRole::". so like, name-tag time.
• if it has neither "+" nor "~" in front, the role name gets searched for in @INC following the rules for role prefix searching. we have a whole section on that, don't worry.

now — and this is the good part — you can also apply roles to every single action in a controller without typing Does into every single action definition. queen behavior honestly:

package MyApp::Controller::Bar

use Moose;
use namespace::autoclean;

BEGIN { extends 'Catalyst::Controller::ActionRole' }

__PACKAGE__->config(
    action_roles => ['Foo', '~Bar'],
);

# Has Catalyst::ActionRole::Foo and MyApp::ActionRole::Bar applied.
#
# If MyApp::ActionRole::Foo exists and is loadable, it will take
# precedence over Catalyst::ActionRole::Foo.
#
# If MyApp::ActionRole::Bar exists and is loadable, it will be loaded,
# but even if it doesn't exist Catalyst::ActionRole::Bar will not be loaded.
sub moo : Local { ... }

read those comments again bestie, they matter. MyApp::ActionRole::Foo can steal the spotlight from Catalyst::ActionRole::Foo if it exists and loads. and for ~Bar? if MyApp::ActionRole::Bar exists and is loadable it loads — but if it doesn't exist, Catalyst::ActionRole::Bar will not be loaded. that's the rule. no wiggle room. 🎀

also! you can apply roles to selected actions without writing Does, using "action" in Catalyst::Controller and configuring it with "action_args" in Catalyst::Controller. fancy:

package MyApp::Controller::Baz;

use Moose;
use namespace::autoclean;

BEGIN { extends 'Catalyst::Controller::ActionRole' }

__PACKAGE__->config(
    action_roles => [qw( Foo )],
    action       => {
        some_action    => { Does => [qw( ~Bar )] },
        another_action => { Does => [qw( +MyActionRole::Baz )] },
    },
    action_args  => {
        another_action => { customarg => 'arg1' },
    }
);

# has Catalyst::ActionRole::Foo and MyApp::ActionRole::Bar applied
sub some_action : Local { ... }

# has Catalyst::ActionRole::Foo and MyActionRole::Baz applied
# and associated action class would get additional arguments passed
sub another_action : Local { ... }

see how some_action picked up Catalyst::ActionRole::Foo and MyApp::ActionRole::Bar? and another_action got Catalyst::ActionRole::Foo and MyActionRole::Baz, plus its associated action class gets extra arguments passed to it. multi-tasking. main character energy fr fr. ✨

---

👑 ATTRIBUTES 👑

💜 _action_role_prefix

this class attribute stores an array reference of role prefixes — these are what get searched when a role name isn't prefixed with "+" or "~". it defaults to [ 'Catalyst::ActionRole::' ]. go read "role prefix searching" if you want the full tea.

💜 _action_roles

this attribute stores an array reference of role names that get applied to every action of this controller. you can set it by passing an "action_roles" argument to the constructor. and the same expansions that happen for "Does" happen here too. same energy, different door. 🚪✨

---

💅 METHODS 💅

🌈 gather_action_roles(%action_args)

gathers the list of roles to apply to an action with the given %action_args. that's it. that's the method. it gathers. it's giving collector. 🧺

---

😭 DEPRECATION NOTICE 😭

okay so. as of version 5.90013, Catalyst merged this whole functionality into the core Catalyst::Controller. so like —

do not use this for new development, bestie. the recommendation is to switch to the core controller as soon as practical. it's not a vibe emergency, but it is a vibe deadline. 🕰️

---

🧚 ROLE PREFIX SEARCHING 🧚

when you specify a role with no prefix, it gets looked up under a set of role prefixes. the first prefix is always "MyApp::ActionRole::" — with "MyApp" swapped out for whatever your app is actually called, obviously, don't be weird about it. the prefixes that come after that one are pulled from the "_action_role_prefix" attribute. lineup order matters, the first match wins the crown. 👑

---

🌸 AUTHOR 🌸

Florian Ragwitz <rafl@debian.org>

---

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2009 by Florian Ragwitz.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

⭐ CONTRIBUTORS ⭐

• Karen Etheridge <ether@cpan.org>
• Tomas Doran <bobtfish@bobtfish.net>
• Hans Dieter Pearcey <hdp@weftsoar.net>
• Alex J. G. BurzyXski <ajgb@ajgb.net>
• Jason Kohles <email@jasonkohles.com>
• William King <william.king@quentustech.com>
• NAKAGAWA Masaki <masaki.nakagawa@gmail.com>
• Joenio Costa <joenio@cpan.org>
• John Napiorkowski <jjnapiork@cpan.org>

---

and that's the whole page, bestie!! 🫶 this beauty ships with perl v5.30.3 and the page itself is dated 2020-09-27 — so yeah, it's a little vintage, but vintage is literally just iconic with a timestamp. mwah. 💖✨🎀🦋