Fix capitalization in L<...> so links work in HTML.
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / ExtendingCatalyst.pod
38017482 1=head1 NAME
3Catalyst::Manual::ExtendingCatalyst - Extending The Framework
7This document will provide you with access points, techniques and best
b7c570ac 8practices to extend the L<Catalyst> framework, or to find more elegant
9ways to abstract and use your own code.
38017482 10
b7c570ac 11The design of Catalyst is such that the framework itself should not
12get in your way. There are many entry points to alter or extend
13Catalyst's behaviour, and this can be confusing. This document is
14written to help you understand the possibilities, current practices
15and their consequences.
38017482 16
17Please read the L<BEST PRACTICES> section before deciding on a design,
b7c570ac 18especially if you plan to release your code to CPAN. The Catalyst
19developer and user communities, which B<you are part of>, will benefit
20most if we all work together and coordinate.
22If you are unsure on an implementation or have an idea you would like
23to have RFC'ed, it surely is a good idea to send your questions and
24suggestions to the Catalyst mailing list (See L<Catalyst/SUPPORT>)
25and/or come to the C<#catalyst> channel on the C<>
26network. You might also want to refer to those places for research to
27see if a module doing what you're trying to implement already
28exists. This might give you a solution to your problem or a basis for
38017482 30
b7c570ac 33During Catalyst's early days, it was common to write plugins to
34provide functionality application wide. Since then, Catalyst has
35become a lot more flexible and powerful. It soon became a best
36practice to use some other form of abstraction or interface, to keep
37the scope of its influence as close as possible to where it belongs.
38017482 38
b7c570ac 39For those in a hurry, here's a quick checklist of some fundamental
40points. If you are going to read the whole thing anyway, you can jump
38017482 41forward to L</Namespaces>.
43=head2 Quick Checklist
47=item Use the C<CatalystX::*> namespace if you can!
78170776 49If your extension isn't a Model, View, Controller, Plugin, Engine,
50or Log, it's best to leave it out of the C<Catalyst::> namespace.
51Use <CatalystX::> instead.
38017482 52
53=item Don't make it a plugin unless you have to!
1972ebdd 55A plugin should be careful since it's overriding Catalyst internals.
56If your plugin doesn't really need to muck with the internals, make it a
57base Controller or Model.
38017482 58
fa025310 59Also, if you think you really need a plugin, please instead consider
60using a L<Moose::Role>.
78170776 61
38017482 62=item There's a community. Use it!
b7c570ac 64There are many experienced developers in the Catalyst community,
65there's always the IRC channel and the mailing list to discuss things.
38017482 66
67=item Add tests and documentation!
b7c570ac 69This gives a stable basis for contribution, and even more importantly,
70builds trust. The easiest way is a test application. See
38017482 71L<Catalyst::Manual::Tutorial::Testing> for more information.
75=head2 Namespaces
b7c570ac 77While some core extensions (engines, plugins, etc.) have to be placed
78in the C<Catalyst::*> namespace, the Catalyst core would like to ask
38017482 79developers to use the C<CatalystX::*> namespace if possible.
fa025310 81Please B<do not> invent components which are outside the well
82known C<Model>, C<View>, C<Controller> or C<Plugin> namespaces!
b7c570ac 84When you try to put a base class for a C<Model>, C<View> or
85C<Controller> directly under your C<MyApp> directory as, for example,
86C<MyApp::Controller::Foo>, you will have the problem that Catalyst
87will try to load that base class as a component of your
88application. The solution is simple: Use another namespace. Common
89ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
90as examples.
38017482 91
92=head2 Can it be a simple module?
b7c570ac 94Sometimes you want to use functionality in your application that
95doesn't require the framework at all. Remember that Catalyst is just
96Perl and you always can just C<use> a module. If you have application
97specific code that doesn't need the framework, there is no problem in
98putting it in your C<MyApp::*> namespace. Just don't put it in
99C<Model>, C<Controller> or C<View>, because that would make Catalyst
100try to load them as components.
38017482 101
1972ebdd 102Writing a generic component that only works with Catalyst is wasteful
103of your time. Try writing a plain perl module, and then a small bit
104of glue that integrates it with Catalyst. See
105L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
106module that takes the approach. The advantage here is that your
107"Catalyst" DBIC schema works perfectly outside of Catalyst, making
108testing (and command-line scripts) a breeze. The actual Catalyst
109Model is just a few lines of glue that makes working with the schema
7d36d4ac 112If you want the thinnest interface possible, take a look at
78170776 115=head2 Using Moose roles to apply method modifiers
117Rather than having a complex set of base classes which you have to mixin
400fa4c3 118via multiple inheritance, if your functionality is well structured, then
78170776 119it's possible to use the composability of L<Moose> roles, and method modifiers
fa025310 120to hook onto to provide functionality.
78170776 121
23cf3a36 122These can be applied to your models/views/controllers, and your application
4d719c7e 123class, and shipped to CPAN.
124Please see L<Catalyst::Manual::CatalystAndMoose> for specific information
125about using Roles in combination with Catalyst, and L<Moose::Manual::Roles>
126for more information about roles in general.
78170776 127
38017482 128=head2 Inheritance and overriding methods
433f1ad4 130When overriding a method, keep in mind that some day additional
38017482 131arguments may be provided to the method, if the last parameter is not
132a flat list. It is thus better to override a method by shifting the
133invocant off of C<@_> and assign the rest of the used arguments, so
134you can pass your complete arguments to the original method via C<@_>:
20a4dd98 136 use MRO::Compat; ...
38017482 137
fa025310 138 sub foo {
139 my $self = shift;
140 my ($bar, $baz) = @_; # ... return
141 $self->next::method(@_);
142 }
38017482 143
144If you would do the common
146 my ($self, $foo, $bar) = @_;
148you'd have to use a much uglier construct to ensure that all arguments
149will be passed along and the method is future proof:
151 $self->next::method(@_[ 1 .. $#_ ]);
153=head2 Tests and documentation
b7c570ac 155When you release your module to the CPAN, proper documentation and at
156least a basic test suite (which means more than pod or even just
157C<use_ok>, sorry) gives people a good base to contribute to the
158module. It also shows that you care for your users. If you would like
159your module to become a recommended addition, these things will prove
38017482 160invaluable.
1972ebdd 162If you're just getting started, try using
163L<CatalystX::Starter|CatalystX::Starter> to generate some example
164tests for your module.
38017482 166=head2 Maintenance
b7c570ac 168In planning to release a module to the community (Catalyst or CPAN and
169Perl), you should consider if you have the resources to keep it up to
170date, including fixing bugs and accepting contributions.
38017482 171
b7c570ac 172If you're not sure about this, you can always ask in the proper
173Catalyst or Perl channels if someone else might be interested in the
174project, and would jump in as co-maintainer.
38017482 175
b7c570ac 176A public repository can further ease interaction with the
177community. Even read only access enables people to provide you with
178patches to your current development version. subversion, SVN and SVK,
179are broadly preferred in the Catalyst community.
38017482 180
b7c570ac 181If you're developing a Catalyst extension, please consider asking the
182core team for space in Catalyst's own subversion repository. You can
183get in touch about this via IRC or the Catalyst developers mailing
38017482 185
186=head2 The context object
188Sometimes you want to get a hold of the context object in a component
b7c570ac 189that was created on startup time, where no context existed yet. Often
38017482 190this is about the model reading something out of the stash or other
b7c570ac 191context information (current language, for example).
38017482 192
b7c570ac 193If you use the context object in your component you have tied it to an
194existing request. This means that you might get into problems when
195you try to use the component (e.g. the model - the most common case)
196outside of Catalyst, for example in cronjobs.
38017482 197
b7c570ac 198A stable solution to this problem is to design the Catalyst model
199separately from the underlying model logic. Let's take
200L<Catalyst::Model::DBIC::Schema> as an example. You can create a
38017482 201schema outside of Catalyst that knows nothing about the web. This kind
202of design ensures encapsulation and makes development and maintenance
203a whole lot easier. The you use the aforementioned model to tie your
b7c570ac 204schema to your application. This gives you a C<MyApp::DBIC> (the name
205is of course just an example) model as well as
206C<MyApp::DBIC::TableName> models to access your result sources
209By creating such a thin layer between the actual model and the
210Catalyst application, the schema itself is not at all tied to any
211application and the layer in-between can access the model's API using
212information from the context object.
214A Catalyst component accesses the context object at request time with
38017482 215L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
b7c570ac 219The application has to interact with the extension with some
220configuration. There is of course again more than one way to do it.
38017482 221
222=head2 Attributes
b7c570ac 224You can specify any valid Perl attribute on Catalyst actions you like.
225(See L<attributes/"Syntax of Attribute Lists"> for a description of
226what is valid.) These will be available on the C<Catalyst::Action>
227instance via its C<attributes> accessor. To give an example, this
38017482 229
230 sub foo : Local Bar('Baz') {
231 my ($self, $c) = @_;
bbddff00 232 my $attributes = $self->action_for('foo')->attributes;
b7c570ac 233 $c->res->body($attributes->{Bar}[0] );
38017482 234 }
b7c570ac 236will set the response body to C<Baz>. The values always come in an
237array reference. As you can see, you can use attributes to configure
238your actions. You can specify or alter these attributes via
239L</"Component Configuration">, or even react on them as soon as
240Catalyst encounters them by providing your own L<component base
4307eb1c 241class|/"Component base classes">.
38017482 242
d7823323 243=head2 Component Configuration
38017482 244
b7c570ac 245At creation time, the class configuration of your component (the one
246available via C<$self-E<gt>config>) will be merged with possible
38017482 247configuration settings from the applications configuration (either
6e1417cd 248directly or via config file). This is done by Catalyst, and the
249correctly merged configuration is passed to your component's
250constructor (i.e. the new method).
38017482 251
6e1417cd 252Ergo, if you define an accessor for each configuration value
253that your component takes, then the value will be automatically stored
254in the controller object's hash reference, and available from the
38017482 256
6e1417cd 257The C<config> accessor always only contains the original class configuration
258and you B<MUST NEVER> call $self->config to get your component configuration,
259as the data there is likely to be a subset of the correct config.
38017482 260
6e1417cd 261For example:
bbddff00 262
6e1417cd 263 package MyApp
264 use Moose;
266 extends 'Catalyst';
268 ...
270 __PACKAGE__->config(
271 'Controller::Foo' => { some_value => 'bar' },
272 );
274 ...
bbddff00 275
276 package MyApp::Controller::Foo;
277 use Moose;
278 use namespace::autoclean;
279 BEGIN { extends 'Catalyst::Controller' };
6e1417cd 281 has some_value ( is => 'ro', required => 1 );
283 sub some_method {
284 my $self = shift;
285 return "the value of 'some_value' is " . $self->some_value;
286 }
38017482 287
38017482 288 ...
6e1417cd 289
290 my $controller = $c->controller('Foo');
291 warn $controller->some_value;
292 warn $controller->some_method;
38017482 293
b7c570ac 296This part contains the technical details of various implementation
38017482 297methods. Please read the L</"BEST PRACTICES"> before you start your
298implementation, if you haven't already.
300=head2 Action classes
302Usually, your action objects are of the class L<Catalyst::Action>.
303You can override this with the C<ActionClass> attribute to influence
b7c570ac 304execution and/or dispatching of the action. A widely used example of
305this is L<Catalyst::Action::RenderView>, which is used in every newly
306created Catalyst application in your root controller:
38017482 307
308 sub end : ActionClass('RenderView') { }
b7c570ac 310Usually, you want to override the C<execute> and/or the C<match>
311method. The execute method of the action will naturally call the
312methods code. You can surround this by overriding the method in a
38017482 314
20a4dd98 315 package Catalyst::Action::MyFoo;
bbddff00 316 use Moose;
317 use namespace::autoclean;
20a4dd98 318 use MRO::Compat;
bbddff00 319 extends 'Catalyst::Action';
38017482 320
321 sub execute {
322 my $self = shift;
323 my ($controller, $c, @args) = @_;
38017482 324 # put your 'before' code here
325 my $r = $self->next::method(@_);
326 # put your 'after' code here
38017482 327 return $r;
328 }
38017482 329 1;
20a4dd98 331We are using L<MRO::Compat> to ensure that you have the next::method
332call, from L<Class::C3> (in older perls), or natively (if you are using
333perl 5.10) to re-dispatch to the original C<execute> method in the
334L<Catalyst::Action> class.
38017482 335
b7c570ac 336The Catalyst dispatcher handles an incoming request and, depending
337upon the dispatch type, will call the appropriate target or chain.
338From time to time it asks the actions themselves, or through the
339controller, if they would match the current request. That's what the
340C<match> method does. So by overriding this, you can change on what
341the action will match and add new matching criteria.
38017482 342
b7c570ac 343For example, the action class below will make the action only match on
38017482 345
78170776 346 package Catalyst::Action::OnlyMondays;
bbddff00 347 use Moose;
348 use namespace::autoclean;
20a4dd98 349 use MRO::Compat;
bbddff00 350 extends 'Catalyst::Action';
38017482 351
352 sub match {
353 my $self = shift;
354 return 0 if ( localtime(time) )[6] == 1;
355 return $self->next::method(@_);
b7c570ac 356 }
38017482 357 1;
359And this is how we'd use it:
361 sub foo: Local ActionClass('OnlyMondays') {
362 my ($self, $c) = @_;
363 $c->res->body('I feel motivated!');
364 }
b7c570ac 366If you are using action classes often or have some specific base
367classes that you want to specify more conveniently, you can implement
368a component base class providing an attribute handler.
38017482 369
bbddff00 370It is not possible to use multiple action classes at once, however
371L<Catalyst::Controller::ActionRole> allows you to apply L<Moose Roles|Moose::Role>
372to actions.
374For further information on action classes and roles, please refer to
38017482 375L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
377=head2 Component base classes
b7c570ac 379Many L<Catalyst::Plugin> that were written in Catalyst's early days
380should really have been just controller base classes. With such a
381class, you could provide functionality scoped to a single controller,
382not polluting the global namespace in the context object.
38017482 383
b7c570ac 384You can provide regular Perl methods in a base class as well as
385actions which will be inherited to the subclass. Please refer to
386L</Controllers> for an example of this.
38017482 387
b7c570ac 388You can introduce your own attributes by specifying a handler method
389in the controller base. For example, to use a C<FullClass> attribute
390to specify a fully qualified action class name, you could use the
391following implementation. Note, however, that this functionality is
392already provided via the C<+> prefix for action classes. A simple
38017482 393
394 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
396will use C<MyApp::Action::Bar> as action class.
bbddff00 398 package MyApp::Base::Controller::FullClass;
399 use Moose;
400 use namespace::autoclean;
401 BEGIN { extends 'Catalyst::Controller'; }
38017482 402
403 sub _parse_FullClass_attr {
404 my ($self, $app_class, $action_name, $value, $attrs) = @_;
405 return( ActionClass => $value );
406 }
38017482 407 1;
b7c570ac 409Note that the full line of arguments is only provided for completeness
410sake. We could use this attribute in a subclass like any other
411Catalyst attribute:
38017482 412
413 package MyApp::Controller::Foo;
bbddff00 414 use Moose;
415 use namespace::autoclean;
416 BEGIN { extends 'MyApp::Base::Controller::FullClass'; }
38017482 417
418 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
420 1;
422=head2 Controllers
b7c570ac 424Many things can happen in controllers, and it often improves
425maintainability to abstract some of the code out into reusable base
38017482 426classes.
428You can provide usual Perl methods that will be available via your
b7c570ac 429controller object, or you can even define Catalyst actions which will
430be inherited by the subclasses. Consider this controller base class:
38017482 431
432 package MyApp::Base::Controller::ModelBase;
bbddff00 433 use Moose;
434 use namespace::autoclean;
436 BEGIN { extends 'Catalyst::Controller'; }
38017482 437
438 sub list : Chained('base') PathPart('') Args(0) {
439 my ($self, $c) = @_;
b7c570ac 440 my $model = $c->model( $self->{model_name} );
38017482 441 my $condition = $self->{model_search_condition} || {};
b7c570ac 442 my $attrs = $self->{model_search_attrs} || {};
38017482 443 $c->stash(rs => $model->search($condition, $attrs);
bbddff00 444 }
38017482 445
446 sub load : Chained('base') PathPart('') CaptureArgs(1) {
447 my ($self, $c, $id) = @_;
448 my $model = $c->model( $self->{model_name} );
449 $c->stash(row => $model->find($id));
bbddff00 450 }
38017482 451 1;
b7c570ac 453This example implements two simple actions. The C<list> action chains
454to a (currently non-existent) C<base> action and puts a result-set
455into the stash taking a configured C<model_name> as well as a search
456condition and attributes. This action is a
457L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
458called C< load > is a chain midpoint that takes one argument. It takes
459the value as an ID and loads the row from the configured model. Please
460not that the above code is simplified for clarity. It misses error
461handling, input validation, and probably other things.
38017482 462
b7c570ac 463The class above is not very useful on its own, but we can combine it
464with some custom actions by sub-classing it:
38017482 465
466 package MyApp::Controller::Foo;
bbddff00 467 use Moose;
468 use namespace::autoclean;
470 BEGIN { extends 'MyApp::Base::Controller::ModelBase'; }
38017482 471
b7c570ac 472 __PACKAGE__->config( model_name => 'DB::Foo',
473 model_search_condition=> { is_active => 1 },
474 model_search_attrs => { order_by => 'name' },
475 );
38017482 476
477 sub base : Chained PathPart('foo') CaptureArgs(0) { }
479 sub view : Chained('load') Args(0) {
480 my ($self, $c) = @_;
481 my $row = $c->stash->{row};
b7c570ac 482 $c->res->body(join ': ', $row->name,
483 $row->description); }
38017482 484 1;
b7c570ac 486This class uses the formerly created controller as a base
487class. First, we see the configurations that were used in the parent
488class. Next comes the C<base> action, where everything chains off of.
38017482 489
b7c570ac 490Note that inherited actions act like they were declared in your
491controller itself. You can therefor call them just by their name in
38017482 492C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
493important part of what makes this technique so useful.
b7c570ac 495The new C<view> action ties itself to the C<load> action specified in
496the base class and outputs the loaded row's C<name> and C<description>
497columns. The controller C<MyApp::Controller::Foo> now has these
498publicly available paths:
38017482 499
502=item /foo
b7c570ac 504Will call the controller's C<base>, then the base classes C<list>
38017482 506
507=item /foo/$id/view
b7c570ac 509First, the controller's C<base> will be called, then it will C<load>
510the row with the corresponding C<$id>. After that, C<view> will
511display some fields out of the object.
38017482 512
515=head2 Models and Views
b7c570ac 517If the functionality you'd like to add is really a data-set that you
518want to manipulate, for example internal document types, images,
519files, it might be better suited as a model.
38017482 520
b7c570ac 521The same applies for views. If your code handles representation or
522deals with the applications interface and should be universally
523available, it could be a perfect candidate for a view.
38017482 524
b7c570ac 525Please implement a C<process> method in your views. This method will
526be called by Catalyst if it is asked to forward to a component without
527a specified action. Note that C<process> is B<not a Catalyst action>
528but a simple Perl method.
38017482 529
530You are also encouraged to implement a C<render> method corresponding
531with the one in L<Catalyst::View::TT>. This has proven invaluable,
532because people can use your view for much more fine-grained content
535Here is some example code for a fictional view:
bbddff00 537 package Catalyst::View::MyView;
538 use Moose;
539 use namespace::autoclean;
541 extends 'Catalyst::View';
38017482 542
543 sub process {
544 my ($self, $c) = @_;
38017482 545 my $template = $c->stash->{template};
b7c570ac 546 my $content = $self->render($c, $template, $c->stash);
38017482 547 $c->res->body( $content );
548 }
550 sub render {
551 my ($self, $c, $template, $args) = @_;
b7c570ac 552 # prepare content here
38017482 553 return $content;
554 }
38017482 555 1;
557=head2 Plugins
b7c570ac 559The first thing to say about plugins is that if you're not sure if
560your module should be a plugin, it probably shouldn't. It once was
561common to add features to Catalyst by writing plugins that provide
562accessors to said functionality. As Catalyst grew more popular, it
563became obvious that this qualifies as bad practice.
565By designing your module as a Catalyst plugin, every method you
566implement, import or inherit will be available via your applications
567context object. A plugin pollutes the global namespace, and you
568should be only doing that when you really need to.
570Often, developers design extensions as plugins because they need to
571get hold of the context object. Either to get at the stash or
572request/response objects are the widely spread reasons. It is,
573however, perfectly possible to implement a regular Catalyst component
574(read: model, view or controller) that receives the current context
575object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
577When is a plugin suited to your task? Your code needs to be a
578plugin to act upon or alter specific parts of Catalyst's request
78170776 579lifecycle. If your functionality needs to change some C<prepare_*> or
b7c570ac 580C<finalize_*> stages, you won't get around a plugin.
78170776 582Note, if you just want to hook into such a stage, and run code before,
583or after it, then it is recommended that you use L<Moose>s method modifiers
584to do this.
b7c570ac 586Another valid target for a plugin architecture are things that
587B<really> have to be globally available, like sessions or
590B<Please do not> release Catalyst extensions as plugins only to
591provide some functionality application wide. Design it as a controller
bbddff00 592base class or another better suited technique with a smaller scope, so that
b7c570ac 593your code only influences those parts of the application where it is
594needed, and namespace clashes and conflicts are ruled out.
38017482 595
596The implementation is pretty easy. Your plugin will be inserted in the
597application's inheritance list, above Catalyst itself. You can by this
b7c570ac 598alter Catalyst's request lifecycle behaviour. Every method you
599declare, every import in your package will be available as method on
600the application and the context object. As an example, let's say you
78170776 601want Catalyst to warn you every time uri_for was called without an action
602object as the first parameter, for example to test that all your chained
603uris are generated from actions (a recommended best practice).
604You could do this with this simple
38017482 605implementation (excuse the lame class name, it's just an example):
607 package Catalyst::Plugin::UriforUndefWarning;
608 use strict;
78170776 609 use Scalar::Util qw/blessed/;
20a4dd98 610 use MRO::Compat;
38017482 611
612 sub uri_for {
b7c570ac 613 my $c = shift;
38017482 614 my $uri = $c->next::method(@_);
78170776 615 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
616 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
38017482 617 return $uri;
618 }
620 1;
b7c570ac 622This would override Catalyst's C<uri_for> method and emit a C<warn>
78170776 623log entry containing the arguments to uri_for.
625Please note this is not a practical example, as string URLs are fine for
626static content etc.
628A simple example like this is actually better as a L<Moose> role, for example:
630 package CatalystX::UriforUndefWarning;
631 use Moose::Role;
4d719c7e 632 use namespace::autoclean;
78170776 633
634 after 'uri_for' => sub {
635 my ($c, $arg) = @_;
636 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
637 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
638 return $uri;
fa025310 639 };
bbddff00 640
641Note that Catalyst will load any Moose Roles in the plugin list,
642and apply them to your application class.
38017482 643
644=head2 Factory components with COMPONENT()
b7c570ac 646Every component inheriting from L<Catalyst::Component> contains a
647C<COMPONENT> method. It is used on application startup by
648C<setup_components> to instantiate the component object for the
649Catalyst application. By default, this will merge the components own
650C<config>uration with the application wide overrides and call the
651class' C<new> method to return the component object.
38017482 652
b7c570ac 653You can override this method and do and return whatever you want.
fa025310 654However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
655to the original C<COMPONENT> method to merge the configuration of
20a4dd98 656your component.
38017482 657
658Here is a stub C<COMPONENT> method:
660 package CatalystX::Component::Foo;
bbddff00 661 use Moose;
662 use namespace::autoclean;
664 extends 'Catalyst::Component';
38017482 665
666 sub COMPONENT {
667 my $class = shift;
a70cede4 668 # Note: $app is like $c, but since the application isn't fully
669 # initialized, we don't want to call it $c yet. $config
670 # is a hashref of config options possibly set on this component.
671 my ($app, $config) = @_;
673 # Do things here before instantiation
674 $new = $class->next::method(@_);
675 # Do things to object after instantiation
676 return $new;
38017482 677 }
679The arguments are the class name of the component, the class name of
b7c570ac 680the application instantiating the component, and a hash reference with
681the controller's configuration.
38017482 682
b7c570ac 683You are free to re-bless the object, instantiate a whole other
684component or really do anything compatible with Catalyst's
685expectations on a component.
38017482 686
fa025310 687For more information, please see
38017482 689
bbddff00 690=head2 Applying roles to parts of the framework
692L<CatalystX::RoleApplicator> will allow you to apply Roles to
693the following classes:
697=item Request
699=item Response
701=item Engine
703=item Dispatcher
705=item Stats
709These roles can add new methods to these classes, or wrap preexisting methods.
711The namespace for roles like this is C<Catalyst::TraitFor::XXX::YYYY>.
713For an example of a CPAN component implemented in this manor, see
38017482 716=head1 SEE ALSO
b7c570ac 718L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
38017482 719
bbddff00 720=head1 AUTHORS
38017482 721
bbddff00 722Catalyst Contributors, see
1972ebdd 723
bbddff00 724=head1 COPYRIGHT
38017482 725
bbddff00 726This library is free software. You can redistribute it and/or modify it under
38017482 727the same terms as Perl itself.
bbddff00 731