lib/CatalystX/Declare/Keyword/Role.pm

   1 use MooseX::Declare;
   2
   3 class CatalystX::Declare::Keyword::Role
   4     extends MooseX::Declare::Syntax::Keyword::Role {
   5
   6
   7     use aliased 'MooseX::MethodAttributes::Role::Meta::Role';
   8     use aliased 'MooseX::Role::Parameterized::Meta::Role::Parameterizable';
   9     use aliased 'CatalystX::Declare::Keyword::Action',  'ActionKeyword';
  10
  11
  12     around import_symbols_from (Object $ctx) {
  13
  14         $ctx->has_parameter_signature
  15         ? $self->$orig($ctx)
  16         : sprintf('Moose::Role -traits => q(MethodAttributes),')
  17     }
  18
  19     before add_namespace_customizations (Object $ctx, Str $package) {
  20
  21         my $source  = $self->import_symbols_from($ctx);
  22         my @symbols = $self->imported_moose_symbols;
  23
  24         $ctx->add_preamble_code_parts(
  25             'use CLASS',
  26         );
  27     }
  28
  29     after add_namespace_customizations (Object $ctx, Str $package) {
  30
  31         $ctx->add_preamble_code_parts(
  32             sprintf(
  33                 'use %s -traits => q(%s), qw( has )',
  34                 'MooseX::Role::Parameterized',
  35                 'MooseX::MethodAttributes::Role::Meta::Role',
  36             ),
  37         ) if $ctx->has_parameter_signature;
  38     }
  39
  40     around default_inner (@args) {
  41
  42         return [
  43             @{ $self->$orig(@args) },
  44             ActionKeyword->new(identifier => 'action'),
  45             ActionKeyword->new(identifier => 'under'),
  46             ActionKeyword->new(identifier => 'final'),
  47         ];
  48     }
  49 }
  50
  51 __END__
  52
  53 =head1 NAME
  54
  55 CatalystX::Declare::Keyword::Role - Declare Catalyst Controller Roles
  56
  57 =head1 SYNOPSIS
  58
  59     use CatalystX::Declare;
  60
  61     controller_role MyApp::Web::ControllerRole::Foo {
  62
  63         method provided_method { ... }
  64
  65         action foo, under base, is final { ... }
  66
  67         around bar_action (Object $ctx) { ... }
  68     }
  69
  70     controller_role MyApp::Web::ControllerRole::WithParam (Str :$msg!) {
  71
  72         final action message under base {
  73             $ctx->stash(message => $msg);
  74         }
  75     }
  76
  77 =head1 DESCRIPTION
  78
  79 This handler provides the C<controller_role> keyword. It is an extension of the
  80 L<MooseX::Declare::Syntax::Keyword::Role> handler. Like with declared
  81 controllers, the C<method> keyword and the modifiers are provided. For details
  82 on the syntax for action declarations have a look at
  83 L<CatalystX::Declare::Keyword::Action>, which also documents the effects of
  84 method modifiers on actions.
  85
  86 =head2 Parameters
  87
  88 You can use a parameter signature containing named parameters for a role. To
  89 apply the controller role in the L</SYNOPSIS>, you'd use code like this:
  90
  91     controller MyApp::Web::Controller::Hello {
  92         with 'MyApp::Web::ControllerRole::WithParam' => { msg => 'Hello!' };
  93
  94         action base under '/' as '';
  95     }
  96
  97 You can currently only use the parameters in action declarations in the body,
  98 te name, the C<as> path part and the C<under> base action specification:
  99
 100     controller_role Foo (Str :$base, Str :$part) {
 101
 102         action foo under $base as $part { ... }
 103     }
 104
 105 You can specify the parameters either as plain scalar variables or as quoted
 106 strings. The latter is especially useful for more complex path parts:
 107
 108     action foo under $base as "$pathpart/fnord" { ... }
 109
 110 To use it in the action name is rather simple:
 111
 112     final action $foo { ... }
 113
 114 You might want to use the C<as $foo> option to specify a path part instead,
 115 though. Use the dynamic action name possibility only if you are really
 116 concerned with the name of the generated method, not only the path the
 117 action is reachable under.
 118
 119 =head1 SUPERCLASSES
 120
 121 =over
 122
 123 =item L<MooseX::Declare::Syntax::Keyword::Role>
 124
 125 =back
 126
 127 =head1 METHODS
 128
 129 =head2 add_namespace_customizations
 130
 131     Object->add_namespace_customizations (Object $ctx, Str $package)
 132
 133 This hook is called by L<MooseX::Declare> and will set the package up as a role
 134 and apply L<MooseX::MethodAttributes>.
 135
 136 =head2 default_inner
 137
 138     ArrayRef[Object] Object->default_inner ()
 139
 140 Same as L<CatalystX::Declare::Keyword::Class/default_inner>.
 141
 142 =head1 SEE ALSO
 143
 144 =over
 145
 146 =item L<CatalystX::Declare>
 147
 148 =item L<MooseX::Declare/role>
 149
 150 =item L<CatalystX::Declare::Keyword::Action>
 151
 152 =item L<CatalystX::Declare::Keyword::Controller>
 153
 154 =back
 155
 156 =head1 AUTHOR
 157
 158 See L<CatalystX::Declare/AUTHOR> for author information.
 159
 160 =head1 LICENSE
 161
 162 This program is free software; you can redistribute it and/or modify it under
 163 the same terms as perl itself.
 164
 165 =cut