1 package Catalyst::Controller;
4 use Moose::Util qw/find_meta/;
5 use List::MoreUtils qw/uniq/;
6 use namespace::clean -except => 'meta';
8 BEGIN { extends qw/Catalyst::Component MooseX::MethodAttributes::Inheritable/; }
10 use MooseX::MethodAttributes;
11 use Catalyst::Exception;
14 with 'Catalyst::Component::ApplicationAttribute';
21 predicate => 'has_path_prefix',
24 has action_namespace =>
28 init_arg => 'namespace',
29 predicate => 'has_action_namespace',
34 accessor => '_controller_actions',
40 my ($self, $args) = @_;
41 my $action = delete $args->{action} || {};
42 my $actions = delete $args->{actions} || {};
43 my $attr_value = $self->merge_config_hashes($actions, $action);
44 $self->_controller_actions($attr_value);
51 Catalyst::Controller - Catalyst Controller base class
55 package MyApp::Controller::Search
56 use base qw/Catalyst::Controller/;
59 my ($self,$c,@args) = @_;
61 } # Dispatches to /search/foo
65 Controllers are where the actions in the Catalyst framework
66 reside. Each action is represented by a function with an attribute to
67 identify what kind of action it is. See the L<Catalyst::Dispatcher>
68 for more info about how Catalyst dispatches to actions.
72 #I think both of these could be attributes. doesn't really seem like they need
73 #to ble class data. i think that attributes +default would work just fine
74 __PACKAGE__->mk_classdata($_) for qw/_dispatch_steps _action_class/;
76 __PACKAGE__->_dispatch_steps( [qw/_BEGIN _AUTO _ACTION/] );
77 __PACKAGE__->_action_class('Catalyst::Action');
80 sub _DISPATCH : Private {
81 my ( $self, $c ) = @_;
83 foreach my $disp ( @{ $self->_dispatch_steps } ) {
84 last unless $c->forward($disp);
90 sub _BEGIN : Private {
91 my ( $self, $c ) = @_;
92 my $begin = ( $c->get_actions( 'begin', $c->namespace ) )[-1];
93 return 1 unless $begin;
94 $begin->dispatch( $c );
95 return !@{ $c->error };
99 my ( $self, $c ) = @_;
100 my @auto = $c->get_actions( 'auto', $c->namespace );
101 foreach my $auto (@auto) {
102 $auto->dispatch( $c );
103 return 0 unless $c->state;
108 sub _ACTION : Private {
109 my ( $self, $c ) = @_;
111 && $c->action->can('execute')
112 && defined $c->req->action )
114 $c->action->dispatch( $c );
116 return !@{ $c->error };
120 my ( $self, $c ) = @_;
121 my $end = ( $c->get_actions( 'end', $c->namespace ) )[-1];
122 return 1 unless $end;
123 $end->dispatch( $c );
124 return !@{ $c->error };
128 my ( $self, $name ) = @_;
129 my $app = ($self->isa('Catalyst') ? $self : $self->_application);
130 return $app->dispatcher->get_action($name, $self->action_namespace);
133 #my opinion is that this whole sub really should be a builder method, not
134 #something that happens on every call. Anyone else disagree?? -- groditi
135 ## -- apparently this is all just waiting for app/ctx split
136 around action_namespace => sub {
138 my ( $self, $c ) = @_;
140 my $class = ref($self) || $self;
141 my $appclass = ref($c) || $c;
143 return $self->$orig if $self->has_action_namespace;
145 return $class->config->{namespace} if exists $class->config->{namespace};
150 $case_s = $appclass->config->{case_sensitive};
152 if ($self->isa('Catalyst')) {
153 $case_s = $class->config->{case_sensitive};
156 $case_s = ref($self->_application)->config->{case_sensitive};
158 confess("Can't figure out case_sensitive setting");
163 my $namespace = Catalyst::Utils::class2prefix($self->catalyst_component_name, $case_s) || '';
164 $self->$orig($namespace) if ref($self);
168 #Once again, this is probably better written as a builder method
169 around path_prefix => sub {
173 return $self->$orig if $self->has_path_prefix;
175 return $self->config->{path} if exists $self->config->{path};
177 my $namespace = $self->action_namespace(@_);
178 $self->$orig($namespace) if ref($self);
182 sub get_action_methods {
184 my $meta = find_meta($self) || confess("No metaclass setup for $self");
186 sprintf "Metaclass %s for %s cannot support register_actions.",
187 ref $meta, $meta->name,
188 ) unless $meta->can('get_nearest_methods_with_attributes');
189 my @methods = $meta->get_nearest_methods_with_attributes;
191 # actions specified via config are also action_methods
195 $meta->find_method_by_name($_)
196 || confess( sprintf 'Action "%s" is not available from controller %s',
198 } keys %{ $self->_controller_actions }
200 return uniq @methods;
204 sub register_actions {
205 my ( $self, $c ) = @_;
206 $self->register_action_methods( $c, $self->get_action_methods );
209 sub register_action_methods {
210 my ( $self, $c, @methods ) = @_;
211 my $class = $self->catalyst_component_name;
212 #this is still not correct for some reason.
213 my $namespace = $self->action_namespace($c);
216 if (!blessed($self) && $self eq $c && scalar(@methods)) {
217 my @really_bad_methods = grep { ! /^_(DISPATCH|BEGIN|AUTO|ACTION|END)$/ } map { $_->name } @methods;
218 if (scalar(@really_bad_methods)) {
219 $c->log->warn("Action methods (" . join(', ', @really_bad_methods) . ") found defined in your application class, $self. This is deprecated, please move them into a Root controller.");
223 foreach my $method (@methods) {
224 my $name = $method->name;
225 # Horrible hack! All method metaclasses should have an attributes
226 # method, core Moose bug - see r13354.
227 my $attributes = $method->can('attributes') ? $method->attributes : [];
228 my $attrs = $self->_parse_attrs( $c, $name, @{ $attributes } );
229 if ( $attrs->{Private} && ( keys %$attrs > 1 ) ) {
230 $c->log->debug( 'Bad action definition "'
231 . join( ' ', @{ $attributes } )
232 . qq/" for "$class->$name"/ )
236 my $reverse = $namespace ? "${namespace}/${name}" : $name;
237 my $action = $self->create_action(
239 code => $method->body,
241 namespace => $namespace,
243 attributes => $attrs,
246 $c->dispatcher->register( $c, $action );
254 my $class = (exists $args{attributes}{ActionClass}
255 ? $args{attributes}{ActionClass}[0]
256 : $self->_action_class);
258 Class::MOP::load_class($class);
266 my $class = $self->action_class(%args);
267 my $action_args = $self->config->{action_args};
270 %{ $action_args->{'*'} || {} },
271 %{ $action_args->{ $args{name} } || {} },
274 return $class->new({ %extra_args, %args });
278 my ( $self, $c, $name, @attrs ) = @_;
282 foreach my $attr (@attrs) {
284 # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
286 if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)\s*\))?$/ ) )
289 if ( defined $value ) {
290 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
292 push( @{ $raw_attributes{$key} }, $value );
298 $actions = $self->_controller_actions;
300 my $cfg = $self->config;
301 $actions = $self->merge_config_hashes($cfg->{actions}, $cfg->{action});
304 %raw_attributes = ((exists $actions->{'*'} ? %{$actions->{'*'}} : ()),
306 (exists $actions->{$name} ? %{$actions->{$name}} : ()));
309 my %final_attributes;
311 foreach my $key (keys %raw_attributes) {
313 my $raw = $raw_attributes{$key};
315 foreach my $value (ref($raw) eq 'ARRAY' ? @$raw : $raw) {
317 my $meth = "_parse_${key}_attr";
318 if ( my $code = $self->can($meth) ) {
319 ( $key, $value ) = $self->$code( $c, $name, $value );
321 push( @{ $final_attributes{$key} }, $value );
325 return \%final_attributes;
328 sub _parse_Global_attr {
329 my ( $self, $c, $name, $value ) = @_;
330 return $self->_parse_Path_attr( $c, $name, "/$name" );
333 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
335 sub _parse_Local_attr {
336 my ( $self, $c, $name, $value ) = @_;
337 return $self->_parse_Path_attr( $c, $name, $name );
340 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
342 sub _parse_Path_attr {
343 my ( $self, $c, $name, $value ) = @_;
344 $value = '' if !defined $value;
345 if ( $value =~ m!^/! ) {
346 return ( 'Path', $value );
348 elsif ( length $value ) {
349 return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
352 return ( 'Path', $self->path_prefix($c) );
356 sub _parse_Regex_attr {
357 my ( $self, $c, $name, $value ) = @_;
358 return ( 'Regex', $value );
361 sub _parse_Regexp_attr { shift->_parse_Regex_attr(@_); }
363 sub _parse_LocalRegex_attr {
364 my ( $self, $c, $name, $value ) = @_;
365 unless ( $value =~ s/^\^// ) { $value = "(?:.*?)$value"; }
367 my $prefix = $self->path_prefix( $c );
368 $prefix .= '/' if length( $prefix );
370 return ( 'Regex', "^${prefix}${value}" );
373 sub _parse_LocalRegexp_attr { shift->_parse_LocalRegex_attr(@_); }
375 sub _parse_Chained_attr {
376 my ($self, $c, $name, $value) = @_;
378 if (defined($value) && length($value)) {
380 $value = '/'.$self->action_namespace($c);
381 } elsif (my ($rel, $rest) = $value =~ /^((?:\.{2}\/)+)(.*)$/) {
382 my @parts = split '/', $self->action_namespace($c);
383 my @levels = split '/', $rel;
385 $value = '/'.join('/', @parts[0 .. $#parts - @levels], $rest);
386 } elsif ($value !~ m/^\//) {
387 my $action_ns = $self->action_namespace($c);
390 $value = '/'.join('/', $action_ns, $value);
392 $value = '/'.$value; # special case namespace '' (root)
399 return Chained => $value;
402 sub _parse_ChainedParent_attr {
403 my ($self, $c, $name, $value) = @_;
404 return $self->_parse_Chained_attr($c, $name, '../'.$name);
407 sub _parse_PathPrefix_attr {
408 my ( $self, $c ) = @_;
409 return PathPart => $self->path_prefix($c);
412 sub _parse_ActionClass_attr {
413 my ( $self, $c, $name, $value ) = @_;
414 my $appname = $self->_application;
415 $value = Catalyst::Utils::resolve_namespace($appname . '::Action', $self->_action_class, $value);
416 return ( 'ActionClass', $value );
419 sub _parse_MyAction_attr {
420 my ( $self, $c, $name, $value ) = @_;
422 my $appclass = Catalyst::Utils::class2appclass($self);
423 $value = "${appclass}::Action::${value}";
425 return ( 'ActionClass', $value );
428 __PACKAGE__->meta->make_immutable;
436 Like any other L<Catalyst::Component>, controllers have a config hash,
437 accessible through $self->config from the controller actions. Some
438 settings are in use by the Catalyst framework:
442 This specifies the internal namespace the controller should be bound
443 to. By default the controller is bound to the URI version of the
444 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
445 will be bound to 'foo/bar'. The default Root controller is an example
446 of setting namespace to '' (the null string).
450 Sets 'path_prefix', as described below.
454 Allows you to set the attributes that the dispatcher creates actions out of.
455 This allows you to do 'rails style routes', or override some of the
456 attribute defintions of actions composed from Roles.
457 You can set arguments globally (for all actions of the controller) and
458 specifically (for a single action).
462 '*' => { Chained => 'base', Args => 0 },
463 base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
467 In the case above every sub in the package would be made into a Chain
468 endpoint with a URI the same as the sub name for each sub, chained
469 to the sub named C<base>. Ergo dispatch to C</example> would call the
470 C<base> method, then the C<example> method.
474 Allows you to set constructor arguments on your actions. You can set arguments
475 globally and specifically (as above).
476 This is particularly useful when using C<ActionRole>s
477 (L<Catalyst::Controller::ActionRole>) and custom C<ActionClass>es.
481 '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
482 'specific_action' => { customarg => 'arg1' },
486 In the case above the action class associated with C<specific_action> would get
487 passed the following arguments, in addition to the normal action constructor
488 arguments, when it is instantiated:
490 (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
494 =head2 BUILDARGS ($app, @args)
496 From L<Catalyst::Component::ApplicationAttribute>, stashes the application
497 instance as $self->_application.
499 =head2 $self->action_for('name')
501 Returns the Catalyst::Action object (if any) for a given method name
504 =head2 $self->action_namespace($c)
506 Returns the private namespace for actions in this component. Defaults
507 to a value from the controller name (for
508 e.g. MyApp::Controller::Foo::Bar becomes "foo/bar") or can be
509 overridden from the "namespace" config key.
512 =head2 $self->path_prefix($c)
514 Returns the default path prefix for :PathPrefix, :Local, :LocalRegex and
515 relative :Path actions in this component. Defaults to the action_namespace or
516 can be overridden from the "path" config key.
518 =head2 $self->register_actions($c)
520 Finds all applicable actions for this component, creates
521 Catalyst::Action objects (using $self->create_action) for them and
522 registers them with $c->dispatcher.
524 =head2 $self->get_action_methods()
526 Returns a list of L<Moose::Meta::Method> objects, doing the
527 L<MooseX::MethodAttributes::Role::Meta::Method> role, which are the set of
528 action methods for this package.
530 =head2 $self->register_action_methods($c, @methods)
532 Creates action objects for a set of action methods using C< create_action >,
533 and registers them with the dispatcher.
535 =head2 $self->action_class(%args)
537 Used when a controller is creating an action to determine the correct base
540 =head2 $self->create_action(%args)
542 Called with a hash of data to be use for construction of a new
543 Catalyst::Action (or appropriate sub/alternative class) object.
545 =head2 $self->_application
549 Returns the application instance stored by C<new()>
553 Catalyst Contributors, see Catalyst.pm
557 This library is free software. You can redistribute it and/or modify
558 it under the same terms as Perl itself.