1Catalyst::Component(3)User Contributed Perl DocumentationCatalyst::Component(3)
2
3
4

NAME

6       Catalyst::Component - Catalyst Component Base Class
7

SYNOPSIS

9           # lib/MyApp/Model/Something.pm
10           package MyApp::Model::Something;
11
12           use base 'Catalyst::Component';
13
14           __PACKAGE__->config( foo => 'bar' );
15
16           has foo => (
17               is => 'ro',
18           );
19
20           sub test {
21               my $self = shift;
22               return $self->foo;
23           }
24
25           sub forward_to_me {
26               my ( $self, $c ) = @_;
27               $c->response->output( $self->foo );
28           }
29
30           1;
31
32           # Methods can be a request step
33           $c->forward(qw/MyApp::Model::Something forward_to_me/);
34
35           # Or just methods
36           print $c->comp('MyApp::Model::Something')->test;
37
38           print $c->comp('MyApp::Model::Something')->foo;
39

DESCRIPTION

41       This is the universal base class for Catalyst components
42       (Model/View/Controller).
43
44       It provides you with a generic new() for component construction through
45       Catalyst's component loader with config() support and a process()
46       method placeholder.
47
48       Note that calling "$self->config" inside a component is strongly not
49       recommended - the correctly merged config should have already been
50       passed to the constructor and stored in attributes - accessing the
51       config accessor directly from an instance is likely to get the wrong
52       values (as it only holds the class wide config, not things loaded from
53       the config file!)
54

METHODS

56   new($app, $arguments)
57       Called by COMPONENT to instantiate the component; should return an
58       object to be stored in the application's component hash.
59
60   COMPONENT
61       "my $component_instance = $component->COMPONENT($app, $arguments);"
62
63       If this method is present (as it is on all Catalyst::Component
64       subclasses), it is called by Catalyst during setup_components with the
65       application class as $app and any config entry on the application for
66       this component (for example, in the case of MyApp::Controller::Foo this
67       would be "MyApp->config('Controller::Foo' => \%conf").
68
69       The arguments are expected to be a hashref and are merged with the
70       "__PACKAGE__->config" hashref before calling "->new" to instantiate the
71       component.
72
73       You can override it in your components to do custom construction, using
74       something like this:
75
76         sub COMPONENT {
77             my ($class, $app, $args) = @_;
78             $args = $class->merge_config_hashes($class->config, $args);
79             return $class->new($app, $args);
80         }
81
82       NOTE: Generally when Catalyst starts, it initializes all the components
83       and passes the hashref present in any configuration information to the
84       COMPONENT method.  For example
85
86           MyApp->config(
87             'Model::Foo' => {
88               bar => 'baz',
89             });
90
91       You would expect COMPONENT to be called like this ->COMPONENT( 'MyApp',
92       +{ bar=>'baz'});
93
94       This would happen ONCE during setup.
95
96   $c->config
97   $c->config($hashref)
98   $c->config($key, $value, ...)
99       Accessor for this component's config hash. Config values can be set as
100       key value pair, or you can specify a hashref. In either case the keys
101       will be merged with any existing config settings. Each component in a
102       Catalyst application has its own config hash.
103
104       The component's config hash is merged with any config entry on the
105       application for this component and passed to "new()" (as mentioned
106       above at "COMPONENT"). The recommended practice to access the merged
107       config is to use a Moose attribute for each config entry on the
108       receiving component.
109
110   $c->process()
111       This is the default method called on a Catalyst component in the
112       dispatcher.  For instance, Views implement this action to render the
113       response body when you forward to them. The default is an abstract
114       method.
115
116   $c->merge_config_hashes( $hashref, $hashref )
117       Merges two hashes together recursively, giving right-hand precedence.
118       Alias for the method in Catalyst::Utils.
119
120   $c->expand_modules( $setup_component_config )
121       Return a list of extra components that this component has created. By
122       default, it just looks for a list of inner packages of this component
123

OPTIONAL METHODS

125   ACCEPT_CONTEXT($c, @args)
126       Catalyst components are normally initialized during server startup,
127       either as a Class or a Instance. However, some components require
128       information about the current request. To do so, they can implement an
129       ACCEPT_CONTEXT method.
130
131       If this method is present, it is called during
132       $c->comp/controller/model/view with the current $c and any additional
133       args (e.g. $c->model('Foo', qw/bar baz/) would cause your
134       MyApp::Model::Foo instance's ACCEPT_CONTEXT to be called with ($c,
135       'bar', 'baz')) and the return value of this method is returned to the
136       calling code in the application rather than the component itself.
137
138       NOTE: All classes that are Catalyst::Components will have a COMPONENT
139       method, but classes that are intended to be factories or generators
140       will have ACCEPT_CONTEXT.  If you have initialization arguments (such
141       as from configuration) that you wish to expose to the ACCEPT_CONTEXT
142       you should proxy them in the factory instance.  For example:
143
144           MyApp::Model::FooFactory;
145
146           use Moose;
147           extends 'Catalyst::Model';
148
149           has type => (is=>'ro', required=>1);
150
151           sub ACCEPT_CONTEXT {
152             my ($self, $c, @args) = @_;
153             return bless { args=>\@args }, $self->type;
154           }
155
156           MyApp::Model::Foo->meta->make_immutable;
157           MyApp::Model::Foo->config( type => 'Type1' );
158
159       And in a controller:
160
161           my $type = $c->model('FooFactory', 1,2,3,4): # $type->isa('Type1')
162
163       NOTE: If you define a ACCEPT_CONTEXT method it MUST check to see if the
164       second argument is blessed (is a context) or not (is an application
165       class name) and it MUST return something valid for the case when the
166       scope is application.  This is required because a component maybe be
167       called from the application scope even if it requires a context and you
168       must prevent errors from being issued if this happens.  Remember not
169       all components that ACCEPT_CONTEXT actually need or use context
170       information (and there is a school of thought that suggestions doing so
171       is a design error anyway...)
172

SEE ALSO

174       Catalyst, Catalyst::Model, Catalyst::View, Catalyst::Controller.
175

AUTHORS

177       Catalyst Contributors, see Catalyst.pm
178
180       This library is free software. You can redistribute it and/or modify it
181       under the same terms as Perl itself.
182
183
184
185perl v5.30.0                      2019-07-26            Catalyst::Component(3)
Impressum