This file is indexed.

/usr/share/perl5/Catalyst/Manual/ExtendingCatalyst.pod is in libcatalyst-manual-perl 5.9007-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
=head1 NAME

Catalyst::Manual::ExtendingCatalyst - Extending The Framework

=head1 DESCRIPTION

This document will provide you with access points, techniques and best
practices to extend the L<Catalyst> framework, or to find more elegant
ways to abstract and use your own code.

The design of Catalyst is such that the framework itself should not
get in your way. There are many entry points to alter or extend
Catalyst's behaviour, and this can be confusing. This document is
written to help you understand the possibilities, current practices
and their consequences.

Please read the L<BEST PRACTICES> section before deciding on a design,
especially if you plan to release your code to CPAN. The Catalyst
developer and user communities, which B<you are part of>, will benefit
most if we all work together and coordinate.

If you are unsure on an implementation or have an idea you would like
to have RFC'ed, it surely is a good idea to send your questions and
suggestions to the Catalyst mailing list (See L<Catalyst/SUPPORT>)
and/or come to the C<#catalyst> channel on the C<irc.perl.org>
network. You might also want to refer to those places for research to
see if a module doing what you're trying to implement already
exists. This might give you a solution to your problem or a basis for
starting.

=head1 BEST PRACTICES

During Catalyst's early days, it was common to write plugins to
provide functionality application wide. Since then, Catalyst has
become a lot more flexible and powerful. It soon became a best
practice to use some other form of abstraction or interface, to keep
the scope of its influence as close as possible to where it belongs.

For those in a hurry, here's a quick checklist of some fundamental
points. If you are going to read the whole thing anyway, you can jump
forward to L</Namespaces>.

=head2 Quick Checklist

=over

=item Use the C<CatalystX::*> namespace if you can!

If your extension isn't a Model, View, Controller, Plugin, Engine,
or Log, it's best to leave it out of the C<Catalyst::> namespace.
Use <CatalystX::> instead.

=item Don't make it a plugin unless you have to!

A plugin should be careful since it's overriding Catalyst internals.
If your plugin doesn't really need to muck with the internals, make it a
base Controller or Model.

Also, if you think you really need a plugin, please instead consider
using a L<Moose::Role>.

=item There's a community. Use it!

There are many experienced developers in the Catalyst community,
there's always the IRC channel and the mailing list to discuss things.

=item Add tests and documentation!

This gives a stable basis for contribution, and even more importantly,
builds trust. The easiest way is a test application. See
L<Catalyst::Manual::Tutorial::Testing> for more information.

=back

=head2 Namespaces

While some core extensions (engines, plugins, etc.) have to be placed
in the C<Catalyst::*> namespace, the Catalyst core would like to ask
developers to use the C<CatalystX::*> namespace if possible.

Please B<do not> invent components which are outside the well
known C<Model>, C<View>, C<Controller> or C<Plugin> namespaces!

When you try to put a base class for a C<Model>, C<View> or
C<Controller> directly under your C<MyApp> directory as, for example,
C<MyApp::Controller::Foo>, you will have the problem that Catalyst
will try to load that base class as a component of your
application. The solution is simple: Use another namespace. Common
ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
as examples.

=head2 Can it be a simple module?

Sometimes you want to use functionality in your application that
doesn't require the framework at all. Remember that Catalyst is just
Perl and you always can just C<use> a module. If you have application
specific code that doesn't need the framework, there is no problem in
putting it in your C<MyApp::*> namespace. Just don't put it in
C<Model>, C<Controller> or C<View>, because that would make Catalyst
try to load them as components.

Writing a generic component that only works with Catalyst is wasteful
of your time.  Try writing a plain perl module, and then a small bit
of glue that integrates it with Catalyst.  See
L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
module that takes the approach.  The advantage here is that your
"Catalyst" DBIC schema works perfectly outside of Catalyst, making
testing (and command-line scripts) a breeze.  The actual Catalyst
Model is just a few lines of glue that makes working with the schema
convenient.

If you want the thinnest interface possible, take a look at
L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.

=head2 Using Moose roles to apply method modifiers

Rather than having a complex set of base classes which you have to mixin
via multiple inheritence, if your functionality is well structured, then
it's possible to use the composability of L<Moose> roles, and method modifiers
to hook onto to provide functionality.

These can be applied to your models/views/controllers, and your application
class, and shipped to CPAN.
Please see L<Catalyst::Manual::CatalystAndMoose> for specific information
about using Roles in combination with Catalyst, and L<Moose::Manual::Roles>
for more information about roles in general.

=head2 Inheritance and overriding methods

When overriding a method, keep in mind that some day additional
arguments may be provided to the method, if the last parameter is not
a flat list. It is thus better to override a method by shifting the
invocant off of C<@_> and assign the rest of the used arguments, so
you can pass your complete arguments to the original method via C<@_>:

  use MRO::Compat; ...

  sub foo {
    my $self = shift;
    my ($bar, $baz) = @_; # ...  return
    $self->next::method(@_);
  }

If you would do the common

  my ($self, $foo, $bar) = @_;

you'd have to use a much uglier construct to ensure that all arguments
will be passed along and the method is future proof:

  $self->next::method(@_[ 1 .. $#_ ]);

=head2 Tests and documentation

When you release your module to the CPAN, proper documentation and at
least a basic test suite (which means more than pod or even just
C<use_ok>, sorry) gives people a good base to contribute to the
module.  It also shows that you care for your users. If you would like
your module to become a recommended addition, these things will prove
invaluable.

If you're just getting started, try using
L<CatalystX::Starter|CatalystX::Starter> to generate some example
tests for your module.

=head2 Maintenance

In planning to release a module to the community (Catalyst or CPAN and
Perl), you should consider if you have the resources to keep it up to
date, including fixing bugs and accepting contributions.

If you're not sure about this, you can always ask in the proper
Catalyst or Perl channels if someone else might be interested in the
project, and would jump in as co-maintainer.

A public repository can further ease interaction with the
community. Even read only access enables people to provide you with
patches to your current development version. subversion, SVN and SVK,
are broadly preferred in the Catalyst community.

If you're developing a Catalyst extension, please consider asking the
core team for space in Catalyst's own subversion repository. You can
get in touch about this via IRC or the Catalyst developers mailing
list.

=head2 The context object

Sometimes you want to get a hold of the context object in a component
that was created on startup time, where no context existed yet. Often
this is about the model reading something out of the stash or other
context information (current language, for example).

If you use the context object in your component you have tied it to an
existing request.  This means that you might get into problems when
you try to use the component (e.g. the model - the most common case)
outside of Catalyst, for example in cronjobs.

A stable solution to this problem is to design the Catalyst model
separately from the underlying model logic. Let's take
L<Catalyst::Model::DBIC::Schema> as an example. You can create a
schema outside of Catalyst that knows nothing about the web. This kind
of design ensures encapsulation and makes development and maintenance
a whole lot easier. The you use the aforementioned model to tie your
schema to your application. This gives you a C<MyApp::DBIC> (the name
is of course just an example) model as well as
C<MyApp::DBIC::TableName> models to access your result sources
directly.

By creating such a thin layer between the actual model and the
Catalyst application, the schema itself is not at all tied to any
application and the layer in-between can access the model's API using
information from the context object.

A Catalyst component accesses the context object at request time with
L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.

=head1 CONFIGURATION

The application has to interact with the extension with some
configuration. There is of course again more than one way to do it.

=head2 Attributes

You can specify any valid Perl attribute on Catalyst actions you like.
(See L<attributes/"Syntax of Attribute Lists"> for a description of
what is valid.) These will be available on the C<Catalyst::Action>
instance via its C<attributes> accessor. To give an example, this
action:

  sub foo : Local Bar('Baz') {
      my ($self, $c) = @_;
      my $attributes = $self->action_for('foo')->attributes;
      $c->res->body($attributes->{Bar}[0] );
  }

will set the response body to C<Baz>. The values always come in an
array reference. As you can see, you can use attributes to configure
your actions. You can specify or alter these attributes via
L</"Component Configuration">, or even react on them as soon as
Catalyst encounters them by providing your own L<component base
class|/"Component Base Classes">.

=head2 Component Configuration

At creation time, the class configuration of your component (the one
available via C<$self-E<gt>config>) will be merged with possible
configuration settings from the applications configuration (either
directly or via config file). This is done by Catalyst, and the
correctly merged configuration is passed to your component's
constructor (i.e. the new method).

Ergo, if you define an accessor for each configuration value
that your component takes, then the value will be automatically stored
in the controller object's hash reference, and available from the
accessor.

The C<config> accessor always only contains the original class configuration
and you B<MUST NEVER> call $self->config to get your component configuration,
as the data there is likely to be a subset of the correct config.

For example:

  package MyApp
  use Moose;

  extends 'Catalyst';

  ...

  __PACKAGE__->config(
    'Controller::Foo' => { some_value => 'bar' },
  );

  ...

  package MyApp::Controller::Foo;
  use Moose;
  use namespace::autoclean;
  BEGIN { extends 'Catalyst::Controller' };

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

  sub some_method {
      my $self = shift;
      return "the value of 'some_value' is " . $self->some_value;
  }

  ...

  my $controller = $c->controller('Foo');
  warn $controller->some_value;
  warn $controller->some_method;

=head1 IMPLEMENTATION

This part contains the technical details of various implementation
methods. Please read the L</"BEST PRACTICES"> before you start your
implementation, if you haven't already.

=head2 Action classes

Usually, your action objects are of the class L<Catalyst::Action>.
You can override this with the C<ActionClass> attribute to influence
execution and/or dispatching of the action. A widely used example of
this is L<Catalyst::Action::RenderView>, which is used in every newly
created Catalyst application in your root controller:

  sub end : ActionClass('RenderView') { }

Usually, you want to override the C<execute> and/or the C<match>
method. The execute method of the action will naturally call the
methods code. You can surround this by overriding the method in a
subclass:

  package Catalyst::Action::MyFoo; 
  use Moose;
  use namespace::autoclean;
  use MRO::Compat; 
  extends 'Catalyst::Action';

  sub execute {
      my $self = shift;
      my ($controller, $c, @args) = @_;
      # put your 'before' code here
      my $r = $self->next::method(@_);
      # put your 'after' code here
      return $r;
  }
  1;

We are using L<MRO::Compat> to ensure that you have the next::method
call, from L<Class::C3> (in older perls), or natively (if you are using 
perl 5.10) to re-dispatch to the original C<execute> method in the 
L<Catalyst::Action> class.

The Catalyst dispatcher handles an incoming request and, depending
upon the dispatch type, will call the appropriate target or chain. 
From time to time it asks the actions themselves, or through the
controller, if they would match the current request. That's what the
C<match> method does.  So by overriding this, you can change on what
the action will match and add new matching criteria.

For example, the action class below will make the action only match on
Mondays:

  package Catalyst::Action::OnlyMondays; 
  use Moose;
  use namespace::autoclean;
  use MRO::Compat;
  extends 'Catalyst::Action';

  sub match {
      my $self = shift;
      return 0 if ( localtime(time) )[6] == 1;
      return $self->next::method(@_);
   }
  1;

And this is how we'd use it:

  sub foo: Local ActionClass('OnlyMondays') {
      my ($self, $c) = @_;
      $c->res->body('I feel motivated!');
  }

If you are using action classes often or have some specific base
classes that you want to specify more conveniently, you can implement
a component base class providing an attribute handler.

It is not possible to use multiple action classes at once, however
L<Catalyst::Controller::ActionRole> allows you to apply L<Moose Roles|Moose::Role>
to actions.

For further information on action classes and roles, please refer to
L<Catalyst::Action> and L<Catalyst::Manual::Actions>.

=head2 Component base classes

Many L<Catalyst::Plugin> that were written in Catalyst's early days
should really have been just controller base classes. With such a
class, you could provide functionality scoped to a single controller,
not polluting the global namespace in the context object.

You can provide regular Perl methods in a base class as well as
actions which will be inherited to the subclass. Please refer to
L</Controllers> for an example of this.

You can introduce your own attributes by specifying a handler method
in the controller base. For example, to use a C<FullClass> attribute
to specify a fully qualified action class name, you could use the
following implementation. Note, however, that this functionality is
already provided via the C<+> prefix for action classes. A simple

  sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }

will use C<MyApp::Action::Bar> as action class.

  package MyApp::Base::Controller::FullClass;
  use Moose;
  use namespace::autoclean;
  BEGIN { extends 'Catalyst::Controller'; }

  sub _parse_FullClass_attr {
      my ($self, $app_class, $action_name, $value, $attrs) = @_;
      return( ActionClass => $value );
  }
  1;

Note that the full line of arguments is only provided for completeness
sake. We could use this attribute in a subclass like any other
Catalyst attribute:

  package MyApp::Controller::Foo;
  use Moose;
  use namespace::autoclean;
  BEGIN { extends 'MyApp::Base::Controller::FullClass'; }

  sub foo : Local FullClass('MyApp::Action::Bar') { ... }

  1;

=head2 Controllers

Many things can happen in controllers, and it often improves
maintainability to abstract some of the code out into reusable base
classes.

You can provide usual Perl methods that will be available via your
controller object, or you can even define Catalyst actions which will
be inherited by the subclasses. Consider this controller base class:

  package MyApp::Base::Controller::ModelBase;
  use Moose;
  use namespace::autoclean;

  BEGIN { extends 'Catalyst::Controller'; }

  sub list : Chained('base') PathPart('') Args(0) {
      my ($self, $c) = @_;
      my $model = $c->model( $self->{model_name} );
      my $condition = $self->{model_search_condition} || {};
      my $attrs = $self->{model_search_attrs} || {};
      $c->stash(rs => $model->search($condition, $attrs);
  }

  sub load : Chained('base') PathPart('') CaptureArgs(1) {
      my ($self, $c, $id) = @_;
      my $model = $c->model( $self->{model_name} );
      $c->stash(row => $model->find($id));
  }
  1;

This example implements two simple actions. The C<list> action chains
to a (currently non-existent) C<base> action and puts a result-set
into the stash taking a configured C<model_name> as well as a search
condition and attributes. This action is a
L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
called C< load > is a chain midpoint that takes one argument. It takes
the value as an ID and loads the row from the configured model. Please
not that the above code is simplified for clarity. It misses error
handling, input validation, and probably other things.

The class above is not very useful on its own, but we can combine it
with some custom actions by sub-classing it:

  package MyApp::Controller::Foo;
  use Moose;
  use namespace::autoclean;
  
  BEGIN { extends 'MyApp::Base::Controller::ModelBase'; }

  __PACKAGE__->config( model_name => 'DB::Foo',
                       model_search_condition=> { is_active => 1 },
                       model_search_attrs => { order_by => 'name' },
                   );

  sub base : Chained PathPart('foo') CaptureArgs(0) { }

  sub view : Chained('load') Args(0) {
      my ($self, $c) = @_;
      my $row = $c->stash->{row};
      $c->res->body(join ': ', $row->name,
      $row->description); }
  1;

This class uses the formerly created controller as a base
class. First, we see the configurations that were used in the parent
class. Next comes the C<base> action, where everything chains off of.

Note that inherited actions act like they were declared in your
controller itself. You can therefor call them just by their name in
C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
important part of what makes this technique so useful.

The new C<view> action ties itself to the C<load> action specified in
the base class and outputs the loaded row's C<name> and C<description>
columns. The controller C<MyApp::Controller::Foo> now has these
publicly available paths:

=over

=item /foo

Will call the controller's C<base>, then the base classes C<list>
action.

=item /foo/$id/view

First, the controller's C<base> will be called, then it will C<load>
the row with the corresponding C<$id>. After that, C<view> will
display some fields out of the object.

=back

=head2 Models and Views

If the functionality you'd like to add is really a data-set that you
want to manipulate, for example internal document types, images,
files, it might be better suited as a model.

The same applies for views. If your code handles representation or
deals with the applications interface and should be universally
available, it could be a perfect candidate for a view.

Please implement a C<process> method in your views. This method will
be called by Catalyst if it is asked to forward to a component without
a specified action. Note that C<process> is B<not a Catalyst action>
but a simple Perl method.

You are also encouraged to implement a C<render> method corresponding
with the one in L<Catalyst::View::TT>. This has proven invaluable,
because people can use your view for much more fine-grained content
generation.

Here is some example code for a fictional view:

  package Catalyst::View::MyView;
  use Moose;
  use namespace::autoclean;
  
  extends 'Catalyst::View';

  sub process {
      my ($self, $c) = @_;
      my $template = $c->stash->{template};
      my $content = $self->render($c, $template, $c->stash);
      $c->res->body( $content );
  }

  sub render {
      my ($self, $c, $template, $args) = @_;
      # prepare content here
      return $content;
  }
  1;

=head2 Plugins

The first thing to say about plugins is that if you're not sure if
your module should be a plugin, it probably shouldn't. It once was
common to add features to Catalyst by writing plugins that provide
accessors to said functionality. As Catalyst grew more popular, it
became obvious that this qualifies as bad practice.

By designing your module as a Catalyst plugin, every method you
implement, import or inherit will be available via your applications
context object.  A plugin pollutes the global namespace, and you
should be only doing that when you really need to.

Often, developers design extensions as plugins because they need to
get hold of the context object. Either to get at the stash or
request/response objects are the widely spread reasons. It is,
however, perfectly possible to implement a regular Catalyst component
(read: model, view or controller) that receives the current context
object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.

When is a plugin suited to your task? Your code needs to be a
plugin to act upon or alter specific parts of Catalyst's request
lifecycle. If your functionality needs to change some C<prepare_*> or
C<finalize_*> stages, you won't get around a plugin.

Note, if you just want to hook into such a stage, and run code before,
or after it, then it is recommended that you use L<Moose>s method modifiers
to do this.

Another valid target for a plugin architecture are things that
B<really> have to be globally available, like sessions or
authentication.

B<Please do not> release Catalyst extensions as plugins only to
provide some functionality application wide. Design it as a controller
base class or another better suited technique with a smaller scope, so that
your code only influences those parts of the application where it is
needed, and namespace clashes and conflicts are ruled out.

The implementation is pretty easy. Your plugin will be inserted in the
application's inheritance list, above Catalyst itself. You can by this
alter Catalyst's request lifecycle behaviour. Every method you
declare, every import in your package will be available as method on
the application and the context object. As an example, let's say you
want Catalyst to warn you every time uri_for was called without an action
object as the first parameter, for example to test that all your chained
uris are generated from actions (a recommended best practice).
You could do this with this simple
implementation (excuse the lame class name, it's just an example):

  package Catalyst::Plugin::UriforUndefWarning;
  use strict;
  use Scalar::Util qw/blessed/;
  use MRO::Compat;

  sub uri_for {
      my $c = shift;
      my $uri = $c->next::method(@_);
      $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
        if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
      return $uri;
  }

  1;

This would override Catalyst's C<uri_for> method and emit a C<warn>
log entry containing the arguments to uri_for.

Please note this is not a practical example, as string URLs are fine for
static content etc.

A simple example like this is actually better as a L<Moose> role, for example:

  package CatalystX::UriforUndefWarning;
  use Moose::Role;
  use namespace::autoclean;

  after 'uri_for' => sub {
    my ($c, $arg) = @_;
    $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
      if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
    return $uri;
  };
  
Note that Catalyst will load any Moose Roles in the plugin list,
and apply them to your application class.

=head2 Factory components with COMPONENT()

Every component inheriting from L<Catalyst::Component> contains a
C<COMPONENT> method. It is used on application startup by
C<setup_components> to instantiate the component object for the
Catalyst application. By default, this will merge the components own
C<config>uration with the application wide overrides and call the
class' C<new> method to return the component object.

You can override this method and do and return whatever you want.
However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
to the original C<COMPONENT> method to merge the configuration of
your component.

Here is a stub C<COMPONENT> method:

  package CatalystX::Component::Foo;
  use Moose;
  use namespace::autoclean;
  
  extends 'Catalyst::Component';

  sub COMPONENT {
      my $class = shift;
      # Note: $app is like $c, but since the application isn't fully
      # initialized, we don't want to call it $c yet.  $config 
      # is a hashref of config options possibly set on this component.
      my ($app, $config) = @_;

      # Do things here before instantiation
      $new = $class->next::method(@_);
      # Do things to object after instantiation
      return $new;
  }

The arguments are the class name of the component, the class name of
the application instantiating the component, and a hash reference with
the controller's configuration.

You are free to re-bless the object, instantiate a whole other
component or really do anything compatible with Catalyst's
expectations on a component.

For more information, please see
L<Catalyst::Component/"COMPONENT($c,$arguments)">.

=head2 Applying roles to parts of the framework

L<CatalystX::RoleApplicator> will allow you to apply Roles to
the following classes:

=over

=item Request

=item Response

=item Engine

=item Dispatcher

=item Stats

=back

These roles can add new methods to these classes, or wrap preexisting methods.

The namespace for roles like this is C<Catalyst::TraitFor::XXX::YYYY>.

For an example of a CPAN component implemented in this manor, see
L<Catalyst::TraitFor::Request::BrowserDetect>.

=head1 SEE ALSO

L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>

=head1 AUTHORS

Catalyst Contributors, see Catalyst.pm

=head1 COPYRIGHT

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

=cut