.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Component 3pm"
.TH Catalyst::Component 3pm "2023-09-28" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Component \- Catalyst Component Base Class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # lib/MyApp/Model/Something.pm
\&    package MyApp::Model::Something;
\&
\&    use base \*(AqCatalyst::Component\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->config( foo => \*(Aqbar\*(Aq );
\&
\&    has foo => (
\&        is => \*(Aqro\*(Aq,
\&    );
\&
\&    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(\*(AqMyApp::Model::Something\*(Aq)\->test;
\&
\&    print $c\->comp(\*(AqMyApp::Model::Something\*(Aq)\->foo;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the universal base class for Catalyst components
(Model/View/Controller).
.PP
It provides you with a generic \fBnew()\fR for component construction through Catalyst's
component loader with \fBconfig()\fR support and a \fBprocess()\fR method placeholder.
.PP
\&\fBNote\fR that calling \f(CW\*(C`$self\->config\*(C'\fR 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!)
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new($app, $arguments)"
.el .SS "new($app, \f(CW$arguments\fP)"
.IX Subsection "new($app, $arguments)"
Called by \s-1COMPONENT\s0 to instantiate the component; should return an object
to be stored in the application's component hash.
.SS "\s-1COMPONENT\s0"
.IX Subsection "COMPONENT"
\&\f(CW\*(C`my $component_instance = $component\->COMPONENT($app, $arguments);\*(C'\fR
.PP
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 \f(CW$app\fR and any config entry on the application for this component (for example,
in the case of MyApp::Controller::Foo this would be
\&\f(CW\*(C`MyApp\->config(\*(AqController::Foo\*(Aq => \e%conf\*(C'\fR).
.PP
The arguments are expected to be a hashref and are merged with the
\&\f(CW\*(C`_\|_PACKAGE_\|_\->config\*(C'\fR hashref before calling \f(CW\*(C`\->new\*(C'\fR
to instantiate the component.
.PP
You can override it in your components to do custom construction, using
something like this:
.PP
.Vb 5
\&  sub COMPONENT {
\&      my ($class, $app, $args) = @_;
\&      $args = $class\->merge_config_hashes($class\->config, $args);
\&      return $class\->new($app, $args);
\&  }
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR Generally when Catalyst starts, it initializes all the components
and passes the hashref present in any configuration information to the
\&\s-1COMPONENT\s0 method.  For example
.PP
.Vb 4
\&    MyApp\->config(
\&      \*(AqModel::Foo\*(Aq => {
\&        bar => \*(Aqbaz\*(Aq,
\&      });
.Ve
.PP
You would expect \s-1COMPONENT\s0 to be called like this \->\s-1COMPONENT\s0( 'MyApp', +{ bar=>'baz'});
.PP
This would happen \s-1ONCE\s0 during setup.
.ie n .SS "$c\->config"
.el .SS "\f(CW$c\fP\->config"
.IX Subsection "$c->config"
.ie n .SS "$c\->config($hashref)"
.el .SS "\f(CW$c\fP\->config($hashref)"
.IX Subsection "$c->config($hashref)"
.ie n .SS "$c\->config($key, $value, ...)"
.el .SS "\f(CW$c\fP\->config($key, \f(CW$value\fP, ...)"
.IX Subsection "$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.
.PP
The component's config hash is merged with any config entry on the
application for this component and passed to \f(CW\*(C`new()\*(C'\fR (as mentioned
above at \*(L"\s-1COMPONENT\*(R"\s0). The recommended practice to access the merged
config is to use a Moose attribute for each config entry on the
receiving component.
.ie n .SS "$c\->\fBprocess()\fP"
.el .SS "\f(CW$c\fP\->\fBprocess()\fP"
.IX Subsection "$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.
.ie n .SS "$c\->merge_config_hashes( $hashref, $hashref )"
.el .SS "\f(CW$c\fP\->merge_config_hashes( \f(CW$hashref\fP, \f(CW$hashref\fP )"
.IX Subsection "$c->merge_config_hashes( $hashref, $hashref )"
Merges two hashes together recursively, giving right-hand precedence.
Alias for the method in Catalyst::Utils.
.ie n .SS "$c\->expand_modules( $setup_component_config )"
.el .SS "\f(CW$c\fP\->expand_modules( \f(CW$setup_component_config\fP )"
.IX Subsection "$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
.SH "OPTIONAL METHODS"
.IX Header "OPTIONAL METHODS"
.ie n .SS "\s-1ACCEPT_CONTEXT\s0($c, @args)"
.el .SS "\s-1ACCEPT_CONTEXT\s0($c, \f(CW@args\fP)"
.IX Subsection "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 \s-1ACCEPT_CONTEXT\s0 method.
.PP
If this method is present, it is called during \f(CW$c\fR\->comp/controller/model/view
with the current \f(CW$c\fR and any additional args (e.g. \f(CW$c\fR\->model('Foo', qw/bar baz/)
would cause your MyApp::Model::Foo instance's \s-1ACCEPT_CONTEXT\s0 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.
.PP
\&\fB\s-1NOTE:\s0\fR All classes that are Catalyst::Components will have a \s-1COMPONENT\s0
method, but classes that are intended to be factories or generators will
have \s-1ACCEPT_CONTEXT.\s0  If you have initialization arguments (such as from
configuration) that you wish to expose to the \s-1ACCEPT_CONTEXT\s0 you should
proxy them in the factory instance.  For example:
.PP
.Vb 1
\&    MyApp::Model::FooFactory;
\&
\&    use Moose;
\&    extends \*(AqCatalyst::Model\*(Aq;
\&
\&    has type => (is=>\*(Aqro\*(Aq, required=>1);
\&
\&    sub ACCEPT_CONTEXT {
\&      my ($self, $c, @args) = @_;
\&      return bless { args=>\e@args }, $self\->type;
\&    }
\&
\&    MyApp::Model::Foo\->meta\->make_immutable;
\&    MyApp::Model::Foo\->config( type => \*(AqType1\*(Aq );
.Ve
.PP
And in a controller:
.PP
.Vb 1
\&    my $type = $c\->model(\*(AqFooFactory\*(Aq, 1,2,3,4): # $type\->isa(\*(AqType1\*(Aq)
.Ve
.PP
\&\fB\s-1NOTE:\s0\fR If you define a \s-1ACCEPT_CONTEXT\s0 method it \s-1MUST\s0 check to see if the
second argument is blessed (is a context) or not (is an application class name) and
it \s-1MUST\s0 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 \s-1ACCEPT_CONTEXT\s0 actually need or use context information
(and there is a school of thought that suggestions doing so is a design error anyway...)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst, Catalyst::Model, Catalyst::View, Catalyst::Controller.
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.