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
   9 =head1 NAME
  10
  11 Catalyst::Component - Catalyst Component Base Class
  12
  13 =head1 SYNOPSIS
  14
  15     # lib/MyApp/Model/Something.pm
  16     package MyApp::Model::Something;
  17
  18     use base 'Catalyst::Component';
  19
  20     __PACKAGE__->config( foo => 'bar' );
  21
  22     sub test {
  23         my $self = shift;
  24         return $self->{foo};
  25     }
  26
  27     sub forward_to_me {
  28         my ( $self, $c ) = @_;
  29         $c->response->output( $self->{foo} );
  30     }
  31
  32     1;
  33
  34     # Methods can be a request step
  35     $c->forward(qw/MyApp::Model::Something forward_to_me/);
  36
  37     # Or just methods
  38     print $c->comp('MyApp::Model::Something')->test;
  39
  40     print $c->comp('MyApp::Model::Something')->{foo};
  41
  42 =head1 DESCRIPTION
  43
  44 This is the universal base class for Catalyst components
  45 (Model/View/Controller).
  46
  47 It provides you with a generic new() for instantiation through Catalyst's
  48 component loader with config() support and a process() method placeholder.
  49
  50 =cut
  51
  52 __PACKAGE__->mk_classdata($_) for qw/_config _plugins/;
  53
  54
  55
  56 sub new {
  57     my ( $self, $c ) = @_;
  58
  59     # Temporary fix, some components does not pass context to constructor
  60     my $arguments = ( ref( $_[-1] ) eq 'HASH' ) ? $_[-1] : {};
  61
  62     return $self->NEXT::new(
  63         $self->merge_config_hashes( $self->config, $arguments ) );
  64 }
  65
  66 sub COMPONENT {
  67     my ( $self, $c ) = @_;
  68
  69     # Temporary fix, some components does not pass context to constructor
  70     my $arguments = ( ref( $_[-1] ) eq 'HASH' ) ? $_[-1] : {};
  71
  72     if ( my $new = $self->NEXT::COMPONENT( $c, $arguments ) ) {
  73         return $new;
  74     }
  75     else {
  76         if ( my $new = $self->new( $c, $arguments ) ) {
  77             return $new;
  78         }
  79         else {
  80             my $class = ref $self || $self;
  81             my $new   = $self->merge_config_hashes(
  82                 $self->config, $arguments );
  83             return bless $new, $class;
  84         }
  85     }
  86 }
  87
  88 sub config {
  89     my $self = shift;
  90     my $config_sub = $self->can('_config');
  91     my $config = $self->$config_sub() || {};
  92     if (@_) {
  93         my $newconfig = { %{@_ > 1 ? {@_} : $_[0]} };
  94         $self->_config(
  95             $self->merge_config_hashes( $config, $newconfig )
  96         );
  97     } else {
  98         # this is a bit of a kludge, required to make
  99         # __PACKAGE__->config->{foo} = 'bar';
 100         # work in a subclass. Calling the Class::Data::Inheritable setter
 101         # will create a new _config method in the current class if it's
 102         # currently inherited from the superclass. So, the can() call will
 103         # return a different subref in that case and that means we know to
 104         # copy and reset the value stored in the class data.
 105
 106         $self->_config( $config );
 107
 108         if ((my $config_sub_now = $self->can('_config')) ne $config_sub) {
 109
 110             $config = $self->merge_config_hashes( $config, {} );
 111             $self->$config_sub_now( $config );
 112         }
 113     }
 114     return $config;
 115 }
 116
 117 sub merge_config_hashes {
 118     my ( $self, $lefthash, $righthash ) = @_;
 119
 120     return Catalyst::Utils::merge_hashes( $lefthash, $righthash );
 121 }
 122
 123 sub process {
 124
 125     Catalyst::Exception->throw( message => ( ref $_[0] || $_[0] )
 126           . " did not override Catalyst::Component::process" );
 127 }
 128
 129 1;
 130
 131 __END__
 132
 133 =head1 METHODS
 134
 135 =head2 new($c, $arguments)
 136
 137 Called by COMPONENT to instantiate the component; should return an object
 138 to be stored in the application's component hash.
 139
 140 =head2 COMPONENT($c, $arguments)
 141
 142 If this method is present (as it is on all Catalyst::Component subclasses,
 143 it is called by Catalyst during setup_components with the application class
 144 as $c and any config entry on the application for this component (for example,
 145 in the case of MyApp::Controller::Foo this would be
 146 MyApp->config->{'Controller::Foo'}). The arguments are expected to be a
 147 hashref and are merged with the __PACKAGE__->config hashref before calling
 148 ->new to instantiate the component.
 149
 150 =head2 $c->config
 151
 152 =head2 $c->config($hashref)
 153
 154 =head2 $c->config($key, $value, ...)
 155
 156 Accessor for this component's config hash. Config values can be set as
 157 key value pair, or you can specify a hashref. In either case the keys
 158 will be merged with any existing config settings. Each component in
 159 a Catalyst application has it's own config hash.
 160
 161 =head2 $c->process()
 162
 163 This is the default method called on a Catalyst component in the dispatcher.
 164 For instance, Views implement this action to render the response body
 165 when you forward to them. The default is an abstract method.
 166
 167 =head2 $c->merge_config_hashes( $hashref, $hashref )
 168
 169 Merges two hashes together recursively, giving right-hand precedence.
 170 Alias for the method in L<Catalyst::Utils>.
 171
 172 =head1 OPTIONAL METHODS
 173
 174 =head2 ACCEPT_CONTEXT($c, @args)
 175
 176 Catalyst components are normally initalized during server startup, either
 177 as a Class or a Instance. However, some components require information about
 178 the current request. To do so, they can implement an ACCEPT_CONTEXT method.
 179
 180 If this method is present, it is called during $c->comp/controller/model/view
 181 with the current $c and any additional args (e.g. $c->model('Foo', qw/bar baz/)
 182 would cause your MyApp::Model::Foo instance's ACCEPT_CONTEXT to be called with
 183 ($c, 'bar', 'baz')) and the return value of this method is returned to the
 184 calling code in the application rather than the component itself.
 185
 186 =head1 SEE ALSO
 187
 188 L<Catalyst>, L<Catalyst::Model>, L<Catalyst::View>, L<Catalyst::Controller>.
 189
 190 =head1 AUTHORS
 191
 192 Catalyst Contributors, see Catalyst.pm
 193
 194 =head1 COPYRIGHT
 195
 196 This program is free software, you can redistribute it and/or modify it under
 197 the same terms as Perl itself.
 198
 199 =cut