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 . ref($meta) . " for "
188 . " cannot support register_actions." )
189 unless $meta->can('get_nearest_methods_with_attributes');
190 my @methods = $meta->get_nearest_methods_with_attributes;
192 # actions specified via config are also action_methods
196 $meta->find_method_by_name($_)
197 || confess( sprintf 'Action "%s" is not available from controller %s',
199 } keys %{ $self->_controller_actions }
201 return uniq @methods;
205 sub register_actions {
206 my ( $self, $c ) = @_;
207 $self->register_action_methods( $c, $self->get_action_methods );
210 sub register_action_methods {
211 my ( $self, $c, @methods ) = @_;
212 my $class = $self->catalyst_component_name;
213 #this is still not correct for some reason.
214 my $namespace = $self->action_namespace($c);
217 if (!blessed($self) && $self eq $c && scalar(@methods)) {
218 my @really_bad_methods = grep { ! /^_(DISPATCH|BEGIN|AUTO|ACTION|END)$/ } map { $_->name } @methods;
219 if (scalar(@really_bad_methods)) {
220 $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.");
224 foreach my $method (@methods) {
225 my $name = $method->name;
226 # Horrible hack! All method metaclasses should have an attributes
227 # method, core Moose bug - see r13354.
228 my $attributes = $method->can('attributes') ? $method->attributes : [];
229 my $attrs = $self->_parse_attrs( $c, $name, @{ $attributes } );
230 if ( $attrs->{Private} && ( keys %$attrs > 1 ) ) {
231 $c->log->debug( 'Bad action definition "'
232 . join( ' ', @{ $attributes } )
233 . qq/" for "$class->$name"/ )
237 my $reverse = $namespace ? "${namespace}/${name}" : $name;
238 my $action = $self->create_action(
240 code => $method->body,
242 namespace => $namespace,
244 attributes => $attrs,
247 $c->dispatcher->register( $c, $action );
255 my $class = (exists $args{attributes}{ActionClass}
256 ? $args{attributes}{ActionClass}[0]
257 : $self->_action_class);
259 Class::MOP::load_class($class);
267 my $class = $self->action_class(%args);
268 my $action_args = $self->config->{action_args};
271 %{ $action_args->{'*'} || {} },
272 %{ $action_args->{ $args{name} } || {} },
275 return $class->new({ %extra_args, %args });
279 my ( $self, $c, $name, @attrs ) = @_;
283 foreach my $attr (@attrs) {
285 # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
287 if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)\s*\))?$/ ) )
290 if ( defined $value ) {
291 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
293 push( @{ $raw_attributes{$key} }, $value );
299 $actions = $self->_controller_actions;
301 my $cfg = $self->config;
302 $actions = $self->merge_config_hashes($cfg->{actions}, $cfg->{action});
305 %raw_attributes = ((exists $actions->{'*'} ? %{$actions->{'*'}} : ()),
307 (exists $actions->{$name} ? %{$actions->{$name}} : ()));
310 my %final_attributes;
312 foreach my $key (keys %raw_attributes) {
314 my $raw = $raw_attributes{$key};
316 foreach my $value (ref($raw) eq 'ARRAY' ? @$raw : $raw) {
318 my $meth = "_parse_${key}_attr";
319 if ( my $code = $self->can($meth) ) {
320 ( $key, $value ) = $self->$code( $c, $name, $value );
322 push( @{ $final_attributes{$key} }, $value );
326 return \%final_attributes;
329 sub _parse_Global_attr {
330 my ( $self, $c, $name, $value ) = @_;
331 return $self->_parse_Path_attr( $c, $name, "/$name" );
334 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
336 sub _parse_Local_attr {
337 my ( $self, $c, $name, $value ) = @_;
338 return $self->_parse_Path_attr( $c, $name, $name );
341 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
343 sub _parse_Path_attr {
344 my ( $self, $c, $name, $value ) = @_;
345 $value = '' if !defined $value;
346 if ( $value =~ m!^/! ) {
347 return ( 'Path', $value );
349 elsif ( length $value ) {
350 return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
353 return ( 'Path', $self->path_prefix($c) );
357 sub _parse_Regex_attr {
358 my ( $self, $c, $name, $value ) = @_;
359 return ( 'Regex', $value );
362 sub _parse_Regexp_attr { shift->_parse_Regex_attr(@_); }
364 sub _parse_LocalRegex_attr {
365 my ( $self, $c, $name, $value ) = @_;
366 unless ( $value =~ s/^\^// ) { $value = "(?:.*?)$value"; }
368 my $prefix = $self->path_prefix( $c );
369 $prefix .= '/' if length( $prefix );
371 return ( 'Regex', "^${prefix}${value}" );
374 sub _parse_LocalRegexp_attr { shift->_parse_LocalRegex_attr(@_); }
376 sub _parse_Chained_attr {
377 my ($self, $c, $name, $value) = @_;
379 if (defined($value) && length($value)) {
381 $value = '/'.$self->action_namespace($c);
382 } elsif (my ($rel, $rest) = $value =~ /^((?:\.{2}\/)+)(.*)$/) {
383 my @parts = split '/', $self->action_namespace($c);
384 my @levels = split '/', $rel;
386 $value = '/'.join('/', @parts[0 .. $#parts - @levels], $rest);
387 } elsif ($value !~ m/^\//) {
388 my $action_ns = $self->action_namespace($c);
391 $value = '/'.join('/', $action_ns, $value);
393 $value = '/'.$value; # special case namespace '' (root)
400 return Chained => $value;
403 sub _parse_ChainedParent_attr {
404 my ($self, $c, $name, $value) = @_;
405 return $self->_parse_Chained_attr($c, $name, '../'.$name);
408 sub _parse_PathPrefix_attr {
409 my ( $self, $c ) = @_;
410 return PathPart => $self->path_prefix($c);
413 sub _parse_ActionClass_attr {
414 my ( $self, $c, $name, $value ) = @_;
415 my $appname = $self->_application;
416 $value = Catalyst::Utils::resolve_namespace($appname . '::Action', $self->_action_class, $value);
417 return ( 'ActionClass', $value );
420 sub _parse_MyAction_attr {
421 my ( $self, $c, $name, $value ) = @_;
423 my $appclass = Catalyst::Utils::class2appclass($self);
424 $value = "${appclass}::Action::${value}";
426 return ( 'ActionClass', $value );
429 __PACKAGE__->meta->make_immutable;
437 Like any other L<Catalyst::Component>, controllers have a config hash,
438 accessible through $self->config from the controller actions. Some
439 settings are in use by the Catalyst framework:
443 This specifies the internal namespace the controller should be bound
444 to. By default the controller is bound to the URI version of the
445 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
446 will be bound to 'foo/bar'. The default Root controller is an example
447 of setting namespace to '' (the null string).
451 Sets 'path_prefix', as described below.
455 Allows you to set the attributes that the dispatcher creates actions out of.
456 This allows you to do 'rails style routes', or override some of the
457 attribute defintions of actions composed from Roles.
458 You can set arguments globally (for all actions of the controller) and
459 specifically (for a single action).
463 '*' => { Chained => 'base', Args => 0 },
464 base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
468 In the case above every sub in the package would be made into a Chain
469 endpoint with a URI the same as the sub name for each sub, chained
470 to the sub named C<base>. Ergo dispatch to C</example> would call the
471 C<base> method, then the C<example> method.
475 Allows you to set constructor arguments on your actions. You can set arguments
476 globally and specifically (as above).
477 This is particularly useful when using C<ActionRole>s
478 (L<Catalyst::Controller::ActionRole>) and custom C<ActionClass>es.
482 '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
483 'specific_action' => { customarg => 'arg1' },
487 In the case above the action class associated with C<specific_action> would get
488 passed the following arguments, in addition to the normal action constructor
489 arguments, when it is instantiated:
491 (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
495 =head2 BUILDARGS ($app, @args)
497 From L<Catalyst::Component::ApplicationAttribute>, stashes the application
498 instance as $self->_application.
500 =head2 $self->action_for('name')
502 Returns the Catalyst::Action object (if any) for a given method name
505 =head2 $self->action_namespace($c)
507 Returns the private namespace for actions in this component. Defaults
508 to a value from the controller name (for
509 e.g. MyApp::Controller::Foo::Bar becomes "foo/bar") or can be
510 overridden from the "namespace" config key.
513 =head2 $self->path_prefix($c)
515 Returns the default path prefix for :PathPrefix, :Local, :LocalRegex and
516 relative :Path actions in this component. Defaults to the action_namespace or
517 can be overridden from the "path" config key.
519 =head2 $self->register_actions($c)
521 Finds all applicable actions for this component, creates
522 Catalyst::Action objects (using $self->create_action) for them and
523 registers them with $c->dispatcher.
525 =head2 $self->get_action_methods()
527 Returns a list of L<Moose::Meta::Method> objects, doing the
528 L<MooseX::MethodAttributes::Role::Meta::Method> role, which are the set of
529 action methods for this package.
531 =head2 $self->register_action_methods($c, @methods)
533 Creates action objects for a set of action methods using C< create_action >,
534 and registers them with the dispatcher.
536 =head2 $self->action_class(%args)
538 Used when a controller is creating an action to determine the correct base
541 =head2 $self->create_action(%args)
543 Called with a hash of data to be use for construction of a new
544 Catalyst::Action (or appropriate sub/alternative class) object.
546 =head2 $self->_application
550 Returns the application instance stored by C<new()>
554 Catalyst Contributors, see Catalyst.pm
558 This library is free software. You can redistribute it and/or modify
559 it under the same terms as Perl itself.