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( 'Action "'
199 . '" is not available from controller '
201 } keys %{ $self->_controller_actions }
203 return uniq @methods;
207 sub register_actions {
208 my ( $self, $c ) = @_;
209 $self->register_action_methods( $c, $self->get_action_methods );
212 sub register_action_methods {
213 my ( $self, $c, @methods ) = @_;
214 my $class = $self->catalyst_component_name;
215 #this is still not correct for some reason.
216 my $namespace = $self->action_namespace($c);
219 if (!blessed($self) && $self eq $c && scalar(@methods)) {
220 my @really_bad_methods = grep { ! /^_(DISPATCH|BEGIN|AUTO|ACTION|END)$/ } map { $_->name } @methods;
221 if (scalar(@really_bad_methods)) {
222 $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.");
226 foreach my $method (@methods) {
227 my $name = $method->name;
228 # Horrible hack! All method metaclasses should have an attributes
229 # method, core Moose bug - see r13354.
230 my $attributes = $method->can('attributes') ? $method->attributes : [];
231 my $attrs = $self->_parse_attrs( $c, $name, @{ $attributes } );
232 if ( $attrs->{Private} && ( keys %$attrs > 1 ) ) {
233 $c->log->debug( 'Bad action definition "'
234 . join( ' ', @{ $attributes } )
235 . qq/" for "$class->$name"/ )
239 my $reverse = $namespace ? "${namespace}/${name}" : $name;
240 my $action = $self->create_action(
242 code => $method->body,
244 namespace => $namespace,
246 attributes => $attrs,
249 $c->dispatcher->register( $c, $action );
257 my $class = (exists $args{attributes}{ActionClass}
258 ? $args{attributes}{ActionClass}[0]
259 : $self->_action_class);
261 Class::MOP::load_class($class);
269 my $class = $self->action_class(%args);
270 my $action_args = $self->config->{action_args};
273 %{ $action_args->{'*'} || {} },
274 %{ $action_args->{ $args{name} } || {} },
277 return $class->new({ %extra_args, %args });
281 my ( $self, $c, $name, @attrs ) = @_;
285 foreach my $attr (@attrs) {
287 # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
289 if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)\s*\))?$/ ) )
292 if ( defined $value ) {
293 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
295 push( @{ $raw_attributes{$key} }, $value );
301 $actions = $self->_controller_actions;
303 my $cfg = $self->config;
304 $actions = $self->merge_config_hashes($cfg->{actions}, $cfg->{action});
307 %raw_attributes = ((exists $actions->{'*'} ? %{$actions->{'*'}} : ()),
309 (exists $actions->{$name} ? %{$actions->{$name}} : ()));
312 my %final_attributes;
314 foreach my $key (keys %raw_attributes) {
316 my $raw = $raw_attributes{$key};
318 foreach my $value (ref($raw) eq 'ARRAY' ? @$raw : $raw) {
320 my $meth = "_parse_${key}_attr";
321 if ( my $code = $self->can($meth) ) {
322 ( $key, $value ) = $self->$code( $c, $name, $value );
324 push( @{ $final_attributes{$key} }, $value );
328 return \%final_attributes;
331 sub _parse_Global_attr {
332 my ( $self, $c, $name, $value ) = @_;
333 return $self->_parse_Path_attr( $c, $name, "/$name" );
336 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
338 sub _parse_Local_attr {
339 my ( $self, $c, $name, $value ) = @_;
340 return $self->_parse_Path_attr( $c, $name, $name );
343 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
345 sub _parse_Path_attr {
346 my ( $self, $c, $name, $value ) = @_;
347 $value = '' if !defined $value;
348 if ( $value =~ m!^/! ) {
349 return ( 'Path', $value );
351 elsif ( length $value ) {
352 return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
355 return ( 'Path', $self->path_prefix($c) );
359 sub _parse_Regex_attr {
360 my ( $self, $c, $name, $value ) = @_;
361 return ( 'Regex', $value );
364 sub _parse_Regexp_attr { shift->_parse_Regex_attr(@_); }
366 sub _parse_LocalRegex_attr {
367 my ( $self, $c, $name, $value ) = @_;
368 unless ( $value =~ s/^\^// ) { $value = "(?:.*?)$value"; }
370 my $prefix = $self->path_prefix( $c );
371 $prefix .= '/' if length( $prefix );
373 return ( 'Regex', "^${prefix}${value}" );
376 sub _parse_LocalRegexp_attr { shift->_parse_LocalRegex_attr(@_); }
378 sub _parse_Chained_attr {
379 my ($self, $c, $name, $value) = @_;
381 if (defined($value) && length($value)) {
383 $value = '/'.$self->action_namespace($c);
384 } elsif (my ($rel, $rest) = $value =~ /^((?:\.{2}\/)+)(.*)$/) {
385 my @parts = split '/', $self->action_namespace($c);
386 my @levels = split '/', $rel;
388 $value = '/'.join('/', @parts[0 .. $#parts - @levels], $rest);
389 } elsif ($value !~ m/^\//) {
390 my $action_ns = $self->action_namespace($c);
393 $value = '/'.join('/', $action_ns, $value);
395 $value = '/'.$value; # special case namespace '' (root)
402 return Chained => $value;
405 sub _parse_ChainedParent_attr {
406 my ($self, $c, $name, $value) = @_;
407 return $self->_parse_Chained_attr($c, $name, '../'.$name);
410 sub _parse_PathPrefix_attr {
411 my ( $self, $c ) = @_;
412 return PathPart => $self->path_prefix($c);
415 sub _parse_ActionClass_attr {
416 my ( $self, $c, $name, $value ) = @_;
417 my $appname = $self->_application;
418 $value = Catalyst::Utils::resolve_namespace($appname . '::Action', $self->_action_class, $value);
419 return ( 'ActionClass', $value );
422 sub _parse_MyAction_attr {
423 my ( $self, $c, $name, $value ) = @_;
425 my $appclass = Catalyst::Utils::class2appclass($self);
426 $value = "${appclass}::Action::${value}";
428 return ( 'ActionClass', $value );
431 __PACKAGE__->meta->make_immutable;
439 Like any other L<Catalyst::Component>, controllers have a config hash,
440 accessible through $self->config from the controller actions. Some
441 settings are in use by the Catalyst framework:
445 This specifies the internal namespace the controller should be bound
446 to. By default the controller is bound to the URI version of the
447 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
448 will be bound to 'foo/bar'. The default Root controller is an example
449 of setting namespace to '' (the null string).
453 Sets 'path_prefix', as described below.
457 Allows you to set the attributes that the dispatcher creates actions out of.
458 This allows you to do 'rails style routes', or override some of the
459 attribute defintions of actions composed from Roles.
460 You can set arguments globally (for all actions of the controller) and
461 specifically (for a single action).
465 '*' => { Chained => 'base', Args => 0 },
466 base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
470 In the case above every sub in the package would be made into a Chain
471 endpoint with a URI the same as the sub name for each sub, chained
472 to the sub named C<base>. Ergo dispatch to C</example> would call the
473 C<base> method, then the C<example> method.
477 Allows you to set constructor arguments on your actions. You can set arguments
478 globally and specifically (as above).
479 This is particularly useful when using C<ActionRole>s
480 (L<Catalyst::Controller::ActionRole>) and custom C<ActionClass>es.
484 '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
485 'specific_action' => { customarg => 'arg1' },
489 In the case above the action class associated with C<specific_action> would get
490 passed the following arguments, in addition to the normal action constructor
491 arguments, when it is instantiated:
493 (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
497 =head2 BUILDARGS ($app, @args)
499 From L<Catalyst::Component::ApplicationAttribute>, stashes the application
500 instance as $self->_application.
502 =head2 $self->action_for('name')
504 Returns the Catalyst::Action object (if any) for a given method name
507 =head2 $self->action_namespace($c)
509 Returns the private namespace for actions in this component. Defaults
510 to a value from the controller name (for
511 e.g. MyApp::Controller::Foo::Bar becomes "foo/bar") or can be
512 overridden from the "namespace" config key.
515 =head2 $self->path_prefix($c)
517 Returns the default path prefix for :PathPrefix, :Local, :LocalRegex and
518 relative :Path actions in this component. Defaults to the action_namespace or
519 can be overridden from the "path" config key.
521 =head2 $self->register_actions($c)
523 Finds all applicable actions for this component, creates
524 Catalyst::Action objects (using $self->create_action) for them and
525 registers them with $c->dispatcher.
527 =head2 $self->get_action_methods()
529 Returns a list of L<Moose::Meta::Method> objects, doing the
530 L<MooseX::MethodAttributes::Role::Meta::Method> role, which are the set of
531 action methods for this package.
533 =head2 $self->register_action_methods($c, @methods)
535 Creates action objects for a set of action methods using C< create_action >,
536 and registers them with the dispatcher.
538 =head2 $self->action_class(%args)
540 Used when a controller is creating an action to determine the correct base
543 =head2 $self->create_action(%args)
545 Called with a hash of data to be use for construction of a new
546 Catalyst::Action (or appropriate sub/alternative class) object.
548 =head2 $self->_application
552 Returns the application instance stored by C<new()>
556 Catalyst Contributors, see Catalyst.pm
560 This library is free software. You can redistribute it and/or modify
561 it under the same terms as Perl itself.