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 my $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);
258 Class::MOP::load_class($class);
260 my $action_args = $self->config->{action_args};
262 %{ $action_args->{'*'} || {} },
263 %{ $action_args->{ $args{name} } || {} },
266 return $class->new({ %extra_args, %args });
270 my ( $self, $c, $name, @attrs ) = @_;
274 foreach my $attr (@attrs) {
276 # Parse out :Foo(bar) into Foo => bar etc (and arrayify)
278 if ( my ( $key, $value ) = ( $attr =~ /^(.*?)(?:\(\s*(.+?)\s*\))?$/ ) )
281 if ( defined $value ) {
282 ( $value =~ s/^'(.*)'$/$1/ ) || ( $value =~ s/^"(.*)"/$1/ );
284 push( @{ $raw_attributes{$key} }, $value );
288 #I know that the original behavior was to ignore action if actions was set
289 # but i actually think this may be a little more sane? we can always remove
290 # the merge behavior quite easily and go back to having actions have
291 # presedence over action by modifying the keys. i honestly think this is
292 # superior while mantaining really high degree of compat
295 $actions = $self->_controller_actions;
297 my $cfg = $self->config;
298 $actions = $self->merge_config_hashes($cfg->{actions}, $cfg->{action});
301 %raw_attributes = ((exists $actions->{'*'} ? %{$actions->{'*'}} : ()),
303 (exists $actions->{$name} ? %{$actions->{$name}} : ()));
306 my %final_attributes;
308 foreach my $key (keys %raw_attributes) {
310 my $raw = $raw_attributes{$key};
312 foreach my $value (ref($raw) eq 'ARRAY' ? @$raw : $raw) {
314 my $meth = "_parse_${key}_attr";
315 if ( my $code = $self->can($meth) ) {
316 ( $key, $value ) = $self->$code( $c, $name, $value );
318 push( @{ $final_attributes{$key} }, $value );
322 return \%final_attributes;
325 sub _parse_Global_attr {
326 my ( $self, $c, $name, $value ) = @_;
327 return $self->_parse_Path_attr( $c, $name, "/$name" );
330 sub _parse_Absolute_attr { shift->_parse_Global_attr(@_); }
332 sub _parse_Local_attr {
333 my ( $self, $c, $name, $value ) = @_;
334 return $self->_parse_Path_attr( $c, $name, $name );
337 sub _parse_Relative_attr { shift->_parse_Local_attr(@_); }
339 sub _parse_Path_attr {
340 my ( $self, $c, $name, $value ) = @_;
341 $value = '' if !defined $value;
342 if ( $value =~ m!^/! ) {
343 return ( 'Path', $value );
345 elsif ( length $value ) {
346 return ( 'Path', join( '/', $self->path_prefix($c), $value ) );
349 return ( 'Path', $self->path_prefix($c) );
353 sub _parse_Regex_attr {
354 my ( $self, $c, $name, $value ) = @_;
355 return ( 'Regex', $value );
358 sub _parse_Regexp_attr { shift->_parse_Regex_attr(@_); }
360 sub _parse_LocalRegex_attr {
361 my ( $self, $c, $name, $value ) = @_;
362 unless ( $value =~ s/^\^// ) { $value = "(?:.*?)$value"; }
364 my $prefix = $self->path_prefix( $c );
365 $prefix .= '/' if length( $prefix );
367 return ( 'Regex', "^${prefix}${value}" );
370 sub _parse_LocalRegexp_attr { shift->_parse_LocalRegex_attr(@_); }
372 sub _parse_Chained_attr {
373 my ($self, $c, $name, $value) = @_;
375 if (defined($value) && length($value)) {
377 $value = '/'.$self->action_namespace($c);
378 } elsif (my ($rel, $rest) = $value =~ /^((?:\.{2}\/)+)(.*)$/) {
379 my @parts = split '/', $self->action_namespace($c);
380 my @levels = split '/', $rel;
382 $value = '/'.join('/', @parts[0 .. $#parts - @levels], $rest);
383 } elsif ($value !~ m/^\//) {
384 my $action_ns = $self->action_namespace($c);
387 $value = '/'.join('/', $action_ns, $value);
389 $value = '/'.$value; # special case namespace '' (root)
396 return Chained => $value;
399 sub _parse_ChainedParent_attr {
400 my ($self, $c, $name, $value) = @_;
401 return $self->_parse_Chained_attr($c, $name, '../'.$name);
404 sub _parse_PathPrefix_attr {
405 my ( $self, $c ) = @_;
406 return PathPart => $self->path_prefix($c);
409 sub _parse_ActionClass_attr {
410 my ( $self, $c, $name, $value ) = @_;
411 my $appname = $self->_application;
412 $value = Catalyst::Utils::resolve_namespace($appname . '::Action', $self->_action_class, $value);
413 return ( 'ActionClass', $value );
416 sub _parse_MyAction_attr {
417 my ( $self, $c, $name, $value ) = @_;
419 my $appclass = Catalyst::Utils::class2appclass($self);
420 $value = "${appclass}::Action::${value}";
422 return ( 'ActionClass', $value );
425 __PACKAGE__->meta->make_immutable;
433 Like any other L<Catalyst::Component>, controllers have a config hash,
434 accessible through $self->config from the controller actions. Some
435 settings are in use by the Catalyst framework:
439 This specifies the internal namespace the controller should be bound
440 to. By default the controller is bound to the URI version of the
441 controller name. For instance controller 'MyApp::Controller::Foo::Bar'
442 will be bound to 'foo/bar'. The default Root controller is an example
443 of setting namespace to '' (the null string).
447 Sets 'path_prefix', as described below.
451 Allows you to set the attributes that the dispatcher creates actions out of.
452 This allows you to do 'rails style routes', or override some of the
453 attribute defintions of actions composed from Roles.
454 You can set arguments globally (for all actions of the controller) and
455 specifically (for a single action).
459 '*' => { Chained => 'base', Args => 0 },
460 base => { Chained => '/', PathPart => '', CaptureArgs => 0 },
464 In the case above every sub in the package would be made into a Chain
465 endpoint with a URI the same as the sub name for each sub, chained
466 to the sub named C<base>. Ergo dispatch to C</example> would call the
467 C<base> method, then the C<example> method.
471 Allows you to set constructor arguments on your actions. You can set arguments
472 globally and specifically (as above).
473 This is particularly useful when using C<ActionRole>s
474 (L<Catalyst::Controller::ActionRole>) and custom C<ActionClass>es.
478 '*' => { globalarg1 => 'hello', globalarg2 => 'goodbye' },
479 'specific_action' => { customarg => 'arg1' },
483 In the case above the action class associated with C<specific_action> would get
484 passed the following arguments, in addition to the normal action constructor
485 arguments, when it is instantiated:
487 (globalarg1 => 'hello', globalarg2 => 'goodbye', customarg => 'arg1')
491 =head2 BUILDARGS ($app, @args)
493 From L<Catalyst::Component::ApplicationAttribute>, stashes the application
494 instance as $self->_application.
496 =head2 $self->action_for('name')
498 Returns the Catalyst::Action object (if any) for a given method name
501 =head2 $self->action_namespace($c)
503 Returns the private namespace for actions in this component. Defaults
504 to a value from the controller name (for
505 e.g. MyApp::Controller::Foo::Bar becomes "foo/bar") or can be
506 overridden from the "namespace" config key.
509 =head2 $self->path_prefix($c)
511 Returns the default path prefix for :PathPrefix, :Local, :LocalRegex and
512 relative :Path actions in this component. Defaults to the action_namespace or
513 can be overridden from the "path" config key.
515 =head2 $self->register_actions($c)
517 Finds all applicable actions for this component, creates
518 Catalyst::Action objects (using $self->create_action) for them and
519 registers them with $c->dispatcher.
521 =head2 $self->get_action_methods()
523 Returns a list of L<Moose::Meta::Method> objects, doing the
524 L<MooseX::MethodAttributes::Role::Meta::Method> role, which are the set of
525 action methods for this package.
527 =head2 $self->register_action_methods($c, @methods)
529 Creates action objects for a set of action methods using C< create_action >,
530 and registers them with the dispatcher.
532 =head2 $self->create_action(%args)
534 Called with a hash of data to be use for construction of a new
535 Catalyst::Action (or appropriate sub/alternative class) object.
537 =head2 $self->_application
541 Returns the application instance stored by C<new()>
545 Catalyst Contributors, see Catalyst.pm
549 This library is free software. You can redistribute it and/or modify
550 it under the same terms as Perl itself.