lib/CatalystX/Declare/Keyword/Controller.pm

   1 use MooseX::Declare;
   2
   3 class CatalystX::Declare::Keyword::Controller
   4     extends CatalystX::Declare::Keyword::Component {
   5
   6     use MooseX::MethodAttributes ();
   7     use aliased 'CatalystX::Declare::Keyword::Action', 'ActionKeyword';
   8     use aliased 'CatalystX::Declare::Controller::RegisterActionRoles';
   9     use aliased 'CatalystX::Declare::Controller::DetermineActionClass';
  10     use aliased 'CatalystX::Declare::Controller::Meta::TypeConstraintMapping';
  11
  12     use Data::Dump qw( pp );
  13
  14
  15     before add_namespace_customizations (Object $ctx, Str $package) {
  16
  17         MooseX::MethodAttributes->init_meta(for_class => $package);
  18
  19         $ctx->add_preamble_code_parts(
  20             ['BEGIN',
  21                 sprintf('Class::MOP::load_class(q(%s))', TypeConstraintMapping),
  22                 sprintf('%s->meta->apply(%s->meta->meta)', TypeConstraintMapping, $package),
  23             ],
  24             sprintf('with qw( %s )', join ' ',
  25                 RegisterActionRoles,
  26                 DetermineActionClass,
  27             ),
  28         );
  29     }
  30
  31     method default_superclasses { 'Catalyst::Controller' }
  32
  33     method auto_make_immutable { 0 }
  34
  35     around default_inner () {
  36
  37         my @modifiers = qw( );
  38
  39         return [
  40             ( grep { my $id = $_->identifier; not grep { $id eq $_ } @modifiers } @{ $self->$orig() || [] } ),
  41             ActionKeyword->new(identifier => 'action'),
  42             ActionKeyword->new(identifier => 'under'),
  43             ActionKeyword->new(identifier => 'final'),
  44         ];
  45     }
  46
  47     method add_with_option_customizations (Object $ctx, $package, ArrayRef $roles, HashRef $options) {
  48
  49         $ctx->add_cleanup_code_parts(
  50             map {
  51                 sprintf('Class::MOP::load_class(%s)', pp "$_"),
  52                 sprintf('%s->meta->apply(%s->meta)', $_, $package),
  53             } @$roles
  54         );
  55
  56         $ctx->add_cleanup_code_parts(
  57             sprintf '%s->meta->make_immutable', $package
  58         ) unless $options->{is}{mutable};
  59     }
  60 }
  61
  62 __END__
  63
  64 =head1 NAME
  65
  66 CatalystX::Declare::Keyword::Controller - Declare Catalyst Controllers
  67
  68 =head1 SYNOPSIS
  69
  70     controller MyApp::Web::Controller::Example
  71        extends MyApp::Web::ControllerBase::CRUD
  72        with    MyApp::Web::ControllerRole::Caching {
  73
  74
  75         $CLASS->config(option_name => 'value');
  76
  77
  78         has attr => (is => 'rw', lazy_build => 1);
  79
  80         method _build_attr { 'Hello World' }
  81
  82
  83         action base as '';
  84
  85         final action site, under base {
  86             $ctx->response->body( $self->attr );
  87         }
  88     }
  89
  90 =head1 DESCRIPTION
  91
  92 This handler module allows the declaration of Catalyst controllers. The
  93 C<controller> keyword is an extension of the
  94 L<CatalystX::Declare::Keyword::Component>, which in turn is an extension
  95 of L<MooseX::Declare/class> with all the
  96 bells and whistles, including C<extends>, C<with>, C<method> and modifier
  97 declarations.
  98
  99 In addition to the keywords and features provided by L<MooseX::Declare>, you
 100 can also specify your controller's actions declaratively. For the whole truth
 101 about the syntax refer to L<CatalystX::Declare::Keyword::Action>.
 102
 103 For controller roles, please see L<CatalystX::Declare::Keyword::Role>. You can
 104 extend controllers with the C<extends> keyword and consume roles via C<with> as
 105 usual.
 106
 107 =head1 SUPERCLASSES
 108
 109 =over
 110
 111 =item L<CatalystX::Declare::Keyword::Component>
 112
 113 =back
 114
 115 =head1 METHODS
 116
 117 These methods are implementation details. Unless you are extending or
 118 developing L<CatalystX::Declare>, you should not be concerned with them.
 119
 120 =head2 add_namespace_customizations
 121
 122     Object->add_namespace_customizations (Object $ctx, Str $package)
 123
 124 This method modifier will initialise the controller with
 125 L<MooseX::MethodAttributes> and add the
 126 L<CatalystX::Declare::Controller::RegisterActionRoles> and
 127 L<CatalystX::Declare::Controller::DetermineActionClass> controller roles
 128 before calling the original.
 129
 130 =head2 default_superclasses
 131
 132     Str Object->default_superclasses ()
 133
 134 Returns L<Catalyst::Controller> as the default superclass for all declared
 135 controllers.
 136
 137 =head2 add_with_option_customizations
 138
 139     Object->add_with_option_customizations (
 140         Object   $ctx,
 141         Str      $package,
 142         ArrayRef $roles,
 143         HashRef  $options,
 144     )
 145
 146 This hook method will be called by L<MooseX::Declare> when C<with> options were
 147 encountered. It will load the specified class and apply them to the controller
 148 one at a time. This will change in the future, and they will be all applied
 149 together.
 150
 151 This method will also add a callback to make the controller immutable to the
 152 cleanup code parts unless C<is mutable> was specified.
 153
 154 =head2 auto_make_immutable
 155
 156     Bool Object->auto_make_immutable ()
 157
 158 Returns C<0>, indicating that L<MooseX::Declare> should not make this class
 159 immutable by itself. We will do that in the L</add_with_option_customizations>
 160 method ourselves.
 161
 162 =head2 default_inner
 163
 164     ArrayRef[Object] Object->default_inner ()
 165
 166 A method modifier around the original. The inner syntax handlers inherited by
 167 L<MooseX::Declare::Syntax::Keyword::Class> are extended with instances of the
 168 L<CatalystX::Declare::Keyword::Action> handler class for the C<action>,
 169 C<under> and C<final> identifiers.
 170
 171 =head1 SEE ALSO
 172
 173 =over
 174
 175 =item L<CatalystX::Declare>
 176
 177 =item L<CatalystX::Declare::Keyword::Action>
 178
 179 =item L<CatalystX::Declare::Keyword::Component>
 180
 181 =item L<MooseX::Declare/class>
 182
 183 =back
 184
 185 =head1 AUTHOR
 186
 187 See L<CatalystX::Declare/AUTHOR> for author information.
 188
 189 =head1 LICENSE
 190
 191 This program is free software; you can redistribute it and/or modify it under
 192 the same terms as perl itself.
 193
 194 =cut