Provided by: libcatalyst-perl_5.90115-1_all bug

NAME

       Catalyst::Component - Catalyst Component Base Class

SYNOPSIS

           # lib/MyApp/Model/Something.pm
           package MyApp::Model::Something;

           use base 'Catalyst::Component';

           __PACKAGE__->config( foo => 'bar' );

           has foo => (
               is => 'ro',
           );

           sub test {
               my $self = shift;
               return $self->foo;
           }

           sub forward_to_me {
               my ( $self, $c ) = @_;
               $c->response->output( $self->foo );
           }

           1;

           # Methods can be a request step
           $c->forward(qw/MyApp::Model::Something forward_to_me/);

           # Or just methods
           print $c->comp('MyApp::Model::Something')->test;

           print $c->comp('MyApp::Model::Something')->foo;

DESCRIPTION

       This is the universal base class for Catalyst components (Model/View/Controller).

       It provides you with a generic new() for component construction through Catalyst's
       component loader with config() support and a process() method placeholder.

       Note that calling "$self->config" inside a component is strongly not recommended - the
       correctly merged config should have already been passed to the constructor and stored in
       attributes - accessing the config accessor directly from an instance is likely to get the
       wrong values (as it only holds the class wide config, not things loaded from the config
       file!)

METHODS

   new($app, $arguments)
       Called by COMPONENT to instantiate the component; should return an object to be stored in
       the application's component hash.

   COMPONENT
       "my $component_instance = $component->COMPONENT($app, $arguments);"

       If this method is present (as it is on all Catalyst::Component subclasses), it is called
       by Catalyst during setup_components with the application class as $app and any config
       entry on the application for this component (for example, in the case of
       MyApp::Controller::Foo this would be "MyApp->config('Controller::Foo' => \%conf").

       The arguments are expected to be a hashref and are merged with the "__PACKAGE__->config"
       hashref before calling "->new" to instantiate the component.

       You can override it in your components to do custom construction, using something like
       this:

         sub COMPONENT {
             my ($class, $app, $args) = @_;
             $args = $class->merge_config_hashes($class->config, $args);
             return $class->new($app, $args);
         }

       NOTE: Generally when Catalyst starts, it initializes all the components and passes the
       hashref present in any configuration information to the COMPONENT method.  For example

           MyApp->config(
             'Model::Foo' => {
               bar => 'baz',
             });

       You would expect COMPONENT to be called like this ->COMPONENT( 'MyApp', +{ bar=>'baz'});

       This would happen ONCE during setup.

   $c->config
   $c->config($hashref)
   $c->config($key, $value, ...)
       Accessor for this component's config hash. Config values can be set as key value pair, or
       you can specify a hashref. In either case the keys will be merged with any existing config
       settings. Each component in a Catalyst application has its own config hash.

       The component's config hash is merged with any config entry on the application for this
       component and passed to "new()" (as mentioned above at "COMPONENT"). The recommended
       practice to access the merged config is to use a Moose attribute for each config entry on
       the receiving component.

   $c->process()
       This is the default method called on a Catalyst component in the dispatcher.  For
       instance, Views implement this action to render the response body when you forward to
       them. The default is an abstract method.

   $c->merge_config_hashes( $hashref, $hashref )
       Merges two hashes together recursively, giving right-hand precedence.  Alias for the
       method in Catalyst::Utils.

   $c->expand_modules( $setup_component_config )
       Return a list of extra components that this component has created. By default, it just
       looks for a list of inner packages of this component

OPTIONAL METHODS

   ACCEPT_CONTEXT($c, @args)
       Catalyst components are normally initialized during server startup, either as a Class or a
       Instance. However, some components require information about the current request. To do
       so, they can implement an ACCEPT_CONTEXT method.

       If this method is present, it is called during $c->comp/controller/model/view with the
       current $c and any additional args (e.g. $c->model('Foo', qw/bar baz/) would cause your
       MyApp::Model::Foo instance's ACCEPT_CONTEXT to be called with ($c, 'bar', 'baz')) and the
       return value of this method is returned to the calling code in the application rather than
       the component itself.

       NOTE: All classes that are Catalyst::Components will have a COMPONENT method, but classes
       that are intended to be factories or generators will have ACCEPT_CONTEXT.  If you have
       initialization arguments (such as from configuration) that you wish to expose to the
       ACCEPT_CONTEXT you should proxy them in the factory instance.  For example:

           MyApp::Model::FooFactory;

           use Moose;
           extends 'Catalyst::Model';

           has type => (is=>'ro', required=>1);

           sub ACCEPT_CONTEXT {
             my ($self, $c, @args) = @_;
             return bless { args=>\@args }, $self->type;
           }

           MyApp::Model::Foo->meta->make_immutable;
           MyApp::Model::Foo->config( type => 'Type1' );

       And in a controller:

           my $type = $c->model('FooFactory', 1,2,3,4): # $type->isa('Type1')

       NOTE: If you define a ACCEPT_CONTEXT method it MUST check to see if the second argument is
       blessed (is a context) or not (is an application class name) and it MUST return something
       valid for the case when the scope is application.  This is required because a component
       maybe be called from the application scope even if it requires a context and you must
       prevent errors from being issued if this happens.  Remember not all components that
       ACCEPT_CONTEXT actually need or use context information (and there is a school of thought
       that suggestions doing so is a design error anyway...)

SEE ALSO

       Catalyst, Catalyst::Model, Catalyst::View, Catalyst::Controller.

AUTHORS

       Catalyst Contributors, see Catalyst.pm

COPYRIGHT

       This library is free software. You can redistribute it and/or modify it under the same
       terms as Perl itself.