lib/Catalyst/Component.pm

   1 package Catalyst::Component;
   2
   3 use strict;
   4 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
   5 use NEXT;
   6 use Catalyst::Utils;
   7
   8 __PACKAGE__->mk_classdata($_) for qw/_config _plugins/;
   9
  10 =head1 NAME
  11
  12 Catalyst::Component - Catalyst Component Base Class
  13
  14 =head1 SYNOPSIS
  15
  16     # lib/MyApp/Model/Something.pm
  17     package MyApp::Model::Something;
  18
  19     use base 'Catalyst::Component';
  20
  21     __PACKAGE__->config( foo => 'bar' );
  22
  23     sub test {
  24         my $self = shift;
  25         return $self->{foo};
  26     }
  27
  28     sub forward_to_me {
  29         my ( $self, $c ) = @_;
  30         $c->response->output( $self->{foo} );
  31     }
  32
  33     1;
  34
  35     # Methods can be a request step
  36     $c->forward(qw/MyApp::Model::Something forward_to_me/);
  37
  38     # Or just methods
  39     print $c->comp('MyApp::Model::Something')->test;
  40
  41     print $c->comp('MyApp::Model::Something')->{foo};
  42
  43 =head1 DESCRIPTION
  44
  45 This is the universal base class for Catalyst components
  46 (Model/View/Controller).
  47
  48 It provides you with a generic new() for instantiation through Catalyst's
  49 component loader with config() support and a process() method placeholder.
  50
  51 =head1 METHODS
  52
  53 =head2 new($c, $arguments)
  54
  55 Called by COMPONENT to instantiate the component; should return an object
  56 to be stored in the application's component hash.
  57
  58 =cut
  59
  60 sub new {
  61     my ( $self, $c ) = @_;
  62
  63     # Temporary fix, some components does not pass context to constructor
  64     my $arguments = ( ref( $_[-1] ) eq 'HASH' ) ? $_[-1] : {};
  65
  66     return $self->NEXT::new( $self->merge_config_hashes( $self->config, $arguments ) );
  67 }
  68
  69 =head2 COMPONENT($c, $arguments)
  70
  71 If this method is present (as it is on all Catalyst::Component subclasses,
  72 it is called by Catalyst during setup_components with the application class
  73 as $c and any config entry on the application for this component (for example,
  74 in the case of MyApp::Controller::Foo this would be
  75 MyApp->config->{'Controller::Foo'}). The arguments are expected to be a hashref
  76 and are merged with the __PACKAGE__->config hashref before calling ->new to
  77 instantiate the component.
  78
  79 =cut
  80
  81 sub COMPONENT {
  82     my ( $self, $c ) = @_;
  83
  84     # Temporary fix, some components does not pass context to constructor
  85     my $arguments = ( ref( $_[-1] ) eq 'HASH' ) ? $_[-1] : {};
  86
  87     if ( my $new = $self->NEXT::COMPONENT( $c, $arguments ) ) {
  88         return $new;
  89     }
  90     else {
  91         if ( my $new = $self->new( $c, $arguments ) ) {
  92             return $new;
  93         }
  94         else {
  95             my $class = ref $self || $self;
  96             my $new   = $self->merge_config_hashes( $self->config, $arguments );
  97             return bless $new, $class;
  98         }
  99     }
 100 }
 101
 102 # remember to leave blank lines between the consecutive =head2's
 103 # otherwise the pod tools don't recognize the subsequent =head2s
 104
 105 =head2 $c->config
 106
 107 =head2 $c->config($hashref)
 108
 109 =head2 $c->config($key, $value, ...)
 110
 111 =cut
 112
 113 sub config {
 114     my $self = shift;
 115     my $config = $self->_config;
 116     unless ($config) {
 117         $self->_config( $config = {} );
 118     }
 119     if (@_) {
 120         my $newconfig = { %{@_ > 1 ? {@_} : $_[0]} };
 121         $self->_config(
 122             $self->merge_config_hashes( $config, $newconfig )
 123         );
 124     }
 125     return $config;
 126 }
 127
 128 =head2 $c->process()
 129
 130 =cut
 131
 132 sub process {
 133
 134     Catalyst::Exception->throw( message => ( ref $_[0] || $_[0] )
 135           . " did not override Catalyst::Component::process" );
 136 }
 137
 138 =head2 $c->merge_config_hashes( $hashref, $hashref )
 139
 140 Merges two hashes together recursively, giving right-hand precedence.
 141
 142 =cut
 143
 144 sub merge_config_hashes {
 145     my ( $self, $lefthash, $righthash ) = @_;
 146
 147     return Catalyst::Utils::merge_hashes( $lefthash, $righthash );
 148 }
 149
 150 =head1 OPTIONAL METHODS
 151
 152 =head2 ACCEPT_CONTEXT($c, @args)
 153
 154 Catalyst components are normally initalized during server startup, either
 155 as a Class or a Instance. However, some components require information about
 156 the current request. To do so, they can implement an ACCEPT_CONTEXT method.
 157
 158 If this method is present, it is called during $c->comp/controller/model/view
 159 with the current $c and any additional args (e.g. $c->model('Foo', qw/bar baz/)
 160 would cause your MyApp::Model::Foo instance's ACCEPT_CONTEXT to be called with
 161 ($c, 'bar', 'baz')) and the return value of this method is returned to the
 162 calling code in the application rather than the component itself.
 163
 164 =head1 SEE ALSO
 165
 166 L<Catalyst>, L<Catalyst::Model>, L<Catalyst::View>, L<Catalyst::Controller>.
 167
 168 =head1 AUTHOR
 169
 170 Sebastian Riedel, C<sri@cpan.org>
 171 Marcus Ramberg, C<mramberg@cpan.org>
 172 Matt S Trout, C<mst@shadowcatsystems.co.uk>
 173
 174 =head1 COPYRIGHT
 175
 176 This program is free software, you can redistribute it and/or modify it under
 177 the same terms as Perl itself.
 178
 179 =cut
 180
 181 1;