Fix reference to non-existant class
[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!
1972ebdd 49If your extension isn't a Model, View, Controller, Plugin, or Engine,
50it's best to leave it out of the C<Catalyst::> namespace. Use
51<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
59=item There's a community. Use it!
b7c570ac 61There are many experienced developers in the Catalyst community,
62there's always the IRC channel and the mailing list to discuss things.
38017482 63
64=item Add tests and documentation!
b7c570ac 66This gives a stable basis for contribution, and even more importantly,
67builds trust. The easiest way is a test application. See
38017482 68L<Catalyst::Manual::Tutorial::Testing> for more information.
72=head2 Namespaces
b7c570ac 74While some core extensions (engines, plugins, etc.) have to be placed
75in the C<Catalyst::*> namespace, the Catalyst core would like to ask
38017482 76developers to use the C<CatalystX::*> namespace if possible.
b7c570ac 78When you try to put a base class for a C<Model>, C<View> or
79C<Controller> directly under your C<MyApp> directory as, for example,
80C<MyApp::Controller::Foo>, you will have the problem that Catalyst
81will try to load that base class as a component of your
82application. The solution is simple: Use another namespace. Common
83ones are C<MyApp::Base::Controller::*> or C<MyApp::ControllerBase::*>
84as examples.
38017482 85
86=head2 Can it be a simple module?
b7c570ac 88Sometimes you want to use functionality in your application that
89doesn't require the framework at all. Remember that Catalyst is just
90Perl and you always can just C<use> a module. If you have application
91specific code that doesn't need the framework, there is no problem in
92putting it in your C<MyApp::*> namespace. Just don't put it in
93C<Model>, C<Controller> or C<View>, because that would make Catalyst
94try to load them as components.
38017482 95
1972ebdd 96Writing a generic component that only works with Catalyst is wasteful
97of your time. Try writing a plain perl module, and then a small bit
98of glue that integrates it with Catalyst. See
99L<Catalyst::Model::DBIC::Schema|Catalyst::Model::DBIC::Schema> for a
100module that takes the approach. The advantage here is that your
101"Catalyst" DBIC schema works perfectly outside of Catalyst, making
102testing (and command-line scripts) a breeze. The actual Catalyst
103Model is just a few lines of glue that makes working with the schema
7d36d4ac 106If you want the thinnest interface possible, take a look at
38017482 109=head2 Inheritance and overriding methods
b7c570ac 111While Catalyst itself is still based on L<NEXT> (for multiple
112inheritance), extension developers are encouraged to use L<Class::C3>,
20a4dd98 113via MRO::Compat, which is what Catalyst will be switching to in the
1145.80 release.
38017482 115
116When overriding a method, keep in mind that some day additionally
117arguments may be provided to the method, if the last parameter is not
118a flat list. It is thus better to override a method by shifting the
119invocant off of C<@_> and assign the rest of the used arguments, so
120you can pass your complete arguments to the original method via C<@_>:
20a4dd98 122 use MRO::Compat; ...
38017482 123
b7c570ac 124 sub foo { my $self = shift;
125 my ($bar, $baz) = @_; # ... return
126 $self->next::method(@_); }
38017482 127
128If you would do the common
130 my ($self, $foo, $bar) = @_;
132you'd have to use a much uglier construct to ensure that all arguments
133will be passed along and the method is future proof:
135 $self->next::method(@_[ 1 .. $#_ ]);
137=head2 Tests and documentation
b7c570ac 139When you release your module to the CPAN, proper documentation and at
140least a basic test suite (which means more than pod or even just
141C<use_ok>, sorry) gives people a good base to contribute to the
142module. It also shows that you care for your users. If you would like
143your module to become a recommended addition, these things will prove
38017482 144invaluable.
1972ebdd 146If you're just getting started, try using
147L<CatalystX::Starter|CatalystX::Starter> to generate some example
148tests for your module.
38017482 150=head2 Maintenance
b7c570ac 152In planning to release a module to the community (Catalyst or CPAN and
153Perl), you should consider if you have the resources to keep it up to
154date, including fixing bugs and accepting contributions.
38017482 155
b7c570ac 156If you're not sure about this, you can always ask in the proper
157Catalyst or Perl channels if someone else might be interested in the
158project, and would jump in as co-maintainer.
38017482 159
b7c570ac 160A public repository can further ease interaction with the
161community. Even read only access enables people to provide you with
162patches to your current development version. subversion, SVN and SVK,
163are broadly preferred in the Catalyst community.
38017482 164
b7c570ac 165If you're developing a Catalyst extension, please consider asking the
166core team for space in Catalyst's own subversion repository. You can
167get in touch about this via IRC or the Catalyst developers mailing
38017482 169
170=head2 The context object
172Sometimes you want to get a hold of the context object in a component
b7c570ac 173that was created on startup time, where no context existed yet. Often
38017482 174this is about the model reading something out of the stash or other
b7c570ac 175context information (current language, for example).
38017482 176
b7c570ac 177If you use the context object in your component you have tied it to an
178existing request. This means that you might get into problems when
179you try to use the component (e.g. the model - the most common case)
180outside of Catalyst, for example in cronjobs.
38017482 181
b7c570ac 182A stable solution to this problem is to design the Catalyst model
183separately from the underlying model logic. Let's take
184L<Catalyst::Model::DBIC::Schema> as an example. You can create a
38017482 185schema outside of Catalyst that knows nothing about the web. This kind
186of design ensures encapsulation and makes development and maintenance
187a whole lot easier. The you use the aforementioned model to tie your
b7c570ac 188schema to your application. This gives you a C<MyApp::DBIC> (the name
189is of course just an example) model as well as
190C<MyApp::DBIC::TableName> models to access your result sources
193By creating such a thin layer between the actual model and the
194Catalyst application, the schema itself is not at all tied to any
195application and the layer in-between can access the model's API using
196information from the context object.
198A Catalyst component accesses the context object at request time with
38017482 199L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
b7c570ac 203The application has to interact with the extension with some
204configuration. There is of course again more than one way to do it.
38017482 205
206=head2 Attributes
b7c570ac 208You can specify any valid Perl attribute on Catalyst actions you like.
209(See L<attributes/"Syntax of Attribute Lists"> for a description of
210what is valid.) These will be available on the C<Catalyst::Action>
211instance via its C<attributes> accessor. To give an example, this
38017482 213
214 sub foo : Local Bar('Baz') {
215 my ($self, $c) = @_;
b7c570ac 216 my $attributes =
217 $self->action_for('foo')->attributes;
218 $c->res->body($attributes->{Bar}[0] );
38017482 219 }
b7c570ac 221will set the response body to C<Baz>. The values always come in an
222array reference. As you can see, you can use attributes to configure
223your actions. You can specify or alter these attributes via
224L</"Component Configuration">, or even react on them as soon as
225Catalyst encounters them by providing your own L<component base
226class|/"Component Base Classes">.
38017482 227
228=head2 Creating custom accessors
b7c570ac 230L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
231creation. Please refer to the modules documentation for usage
38017482 232information.
234=head2 Component configuration
b7c570ac 236At creation time, the class configuration of your component (the one
237available via C<$self-E<gt>config>) will be merged with possible
38017482 238configuration settings from the applications configuration (either
b7c570ac 239directly or via config file). This is then stored in the controller
240object's hash reference. So, if you read possible configurations like:
38017482 241
242 my $model_name = $controller->{model_name};
b7c570ac 244you will get the right value. The C<config> accessor always only
38017482 245contains the original class configuration and must not be used for
246component configuration.
248You are advised to create accessors on your component class for your
249configuration values. This is good practice and makes it easier to
b7c570ac 250capture configuration key typos. You can do this with the
38017482 251C<mk_ro_accessors> method provided to L<Catalyst::Component> via
254 use base 'Catalyst::Controller';
255 __PACKAGE__->mk_ro_accessors('model_name');
256 ...
257 my $model_name = $controller->model_name;
b7c570ac 261This part contains the technical details of various implementation
38017482 262methods. Please read the L</"BEST PRACTICES"> before you start your
263implementation, if you haven't already.
265=head2 Action classes
267Usually, your action objects are of the class L<Catalyst::Action>.
268You can override this with the C<ActionClass> attribute to influence
b7c570ac 269execution and/or dispatching of the action. A widely used example of
270this is L<Catalyst::Action::RenderView>, which is used in every newly
271created Catalyst application in your root controller:
38017482 272
273 sub end : ActionClass('RenderView') { }
b7c570ac 275Usually, you want to override the C<execute> and/or the C<match>
276method. The execute method of the action will naturally call the
277methods code. You can surround this by overriding the method in a
38017482 279
20a4dd98 280 package Catalyst::Action::MyFoo;
281 use strict;
38017482 282
20a4dd98 283 use MRO::Compat;
284 use base 'Catalyst::Action';
38017482 285
286 sub execute {
287 my $self = shift;
288 my ($controller, $c, @args) = @_;
38017482 289 # put your 'before' code here
290 my $r = $self->next::method(@_);
291 # put your 'after' code here
38017482 292 return $r;
293 }
38017482 294 1;
20a4dd98 296We are using L<MRO::Compat> to ensure that you have the next::method
297call, from L<Class::C3> (in older perls), or natively (if you are using
298perl 5.10) to re-dispatch to the original C<execute> method in the
299L<Catalyst::Action> class.
38017482 300
b7c570ac 301The Catalyst dispatcher handles an incoming request and, depending
302upon the dispatch type, will call the appropriate target or chain.
303From time to time it asks the actions themselves, or through the
304controller, if they would match the current request. That's what the
305C<match> method does. So by overriding this, you can change on what
306the action will match and add new matching criteria.
38017482 307
b7c570ac 308For example, the action class below will make the action only match on
38017482 310
b7c570ac 311 package Catalyst::Action::OnlyMondays; use strict;
38017482 312
20a4dd98 313 use MRO::Compat;
38017482 314 use base 'Catalyst::Action';
316 sub match {
317 my $self = shift;
318 return 0 if ( localtime(time) )[6] == 1;
319 return $self->next::method(@_);
b7c570ac 320 }
38017482 321 1;
323And this is how we'd use it:
325 sub foo: Local ActionClass('OnlyMondays') {
326 my ($self, $c) = @_;
327 $c->res->body('I feel motivated!');
328 }
b7c570ac 330If you are using action classes often or have some specific base
331classes that you want to specify more conveniently, you can implement
332a component base class providing an attribute handler.
38017482 333
b7c570ac 334For further information on action classes, please refer to
38017482 335L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
337=head2 Component base classes
b7c570ac 339Many L<Catalyst::Plugin> that were written in Catalyst's early days
340should really have been just controller base classes. With such a
341class, you could provide functionality scoped to a single controller,
342not polluting the global namespace in the context object.
38017482 343
b7c570ac 344You can provide regular Perl methods in a base class as well as
345actions which will be inherited to the subclass. Please refer to
346L</Controllers> for an example of this.
38017482 347
b7c570ac 348You can introduce your own attributes by specifying a handler method
349in the controller base. For example, to use a C<FullClass> attribute
350to specify a fully qualified action class name, you could use the
351following implementation. Note, however, that this functionality is
352already provided via the C<+> prefix for action classes. A simple
38017482 353
354 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
356will use C<MyApp::Action::Bar> as action class.
b7c570ac 358 package MyApp::Base::Controller::FullClass; use strict; use base
359 'Catalyst::Controller';
38017482 360
361 sub _parse_FullClass_attr {
362 my ($self, $app_class, $action_name, $value, $attrs) = @_;
363 return( ActionClass => $value );
364 }
38017482 365 1;
b7c570ac 367Note that the full line of arguments is only provided for completeness
368sake. We could use this attribute in a subclass like any other
369Catalyst attribute:
38017482 370
371 package MyApp::Controller::Foo;
372 use strict;
373 use base 'MyApp::Base::Controller::FullClass';
375 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
377 1;
379=head2 Controllers
b7c570ac 381Many things can happen in controllers, and it often improves
382maintainability to abstract some of the code out into reusable base
38017482 383classes.
385You can provide usual Perl methods that will be available via your
b7c570ac 386controller object, or you can even define Catalyst actions which will
387be inherited by the subclasses. Consider this controller base class:
38017482 388
389 package MyApp::Base::Controller::ModelBase;
390 use strict;
391 use base 'Catalyst::Controller';
393 sub list : Chained('base') PathPart('') Args(0) {
394 my ($self, $c) = @_;
b7c570ac 395 my $model = $c->model( $self->{model_name} );
38017482 396 my $condition = $self->{model_search_condition} || {};
b7c570ac 397 my $attrs = $self->{model_search_attrs} || {};
38017482 398 $c->stash(rs => $model->search($condition, $attrs);
b7c570ac 399 }
38017482 400
401 sub load : Chained('base') PathPart('') CaptureArgs(1) {
402 my ($self, $c, $id) = @_;
403 my $model = $c->model( $self->{model_name} );
404 $c->stash(row => $model->find($id));
b7c570ac 405 }
38017482 406 1;
b7c570ac 408This example implements two simple actions. The C<list> action chains
409to a (currently non-existent) C<base> action and puts a result-set
410into the stash taking a configured C<model_name> as well as a search
411condition and attributes. This action is a
412L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
413called C< load > is a chain midpoint that takes one argument. It takes
414the value as an ID and loads the row from the configured model. Please
415not that the above code is simplified for clarity. It misses error
416handling, input validation, and probably other things.
38017482 417
b7c570ac 418The class above is not very useful on its own, but we can combine it
419with some custom actions by sub-classing it:
38017482 420
421 package MyApp::Controller::Foo;
422 use strict;
423 use base 'MyApp::Base::Controller::ModelBase';
b7c570ac 425 __PACKAGE__->config( model_name => 'DB::Foo',
426 model_search_condition=> { is_active => 1 },
427 model_search_attrs => { order_by => 'name' },
428 );
38017482 429
430 sub base : Chained PathPart('foo') CaptureArgs(0) { }
432 sub view : Chained('load') Args(0) {
433 my ($self, $c) = @_;
434 my $row = $c->stash->{row};
b7c570ac 435 $c->res->body(join ': ', $row->name,
436 $row->description); }
38017482 437 1;
b7c570ac 439This class uses the formerly created controller as a base
440class. First, we see the configurations that were used in the parent
441class. Next comes the C<base> action, where everything chains off of.
38017482 442
b7c570ac 443Note that inherited actions act like they were declared in your
444controller itself. You can therefor call them just by their name in
38017482 445C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
446important part of what makes this technique so useful.
b7c570ac 448The new C<view> action ties itself to the C<load> action specified in
449the base class and outputs the loaded row's C<name> and C<description>
450columns. The controller C<MyApp::Controller::Foo> now has these
451publicly available paths:
38017482 452
455=item /foo
b7c570ac 457Will call the controller's C<base>, then the base classes C<list>
38017482 459
460=item /foo/$id/view
b7c570ac 462First, the controller's C<base> will be called, then it will C<load>
463the row with the corresponding C<$id>. After that, C<view> will
464display some fields out of the object.
38017482 465
468=head2 Models and Views
b7c570ac 470If the functionality you'd like to add is really a data-set that you
471want to manipulate, for example internal document types, images,
472files, it might be better suited as a model.
38017482 473
b7c570ac 474The same applies for views. If your code handles representation or
475deals with the applications interface and should be universally
476available, it could be a perfect candidate for a view.
38017482 477
b7c570ac 478Please implement a C<process> method in your views. This method will
479be called by Catalyst if it is asked to forward to a component without
480a specified action. Note that C<process> is B<not a Catalyst action>
481but a simple Perl method.
38017482 482
483You are also encouraged to implement a C<render> method corresponding
484with the one in L<Catalyst::View::TT>. This has proven invaluable,
485because people can use your view for much more fine-grained content
488Here is some example code for a fictional view:
490 package CatalystX::View::MyView;
491 use strict;
492 use base 'Catalyst::View';
494 sub process {
495 my ($self, $c) = @_;
38017482 496 my $template = $c->stash->{template};
b7c570ac 497 my $content = $self->render($c, $template, $c->stash);
38017482 498 $c->res->body( $content );
499 }
501 sub render {
502 my ($self, $c, $template, $args) = @_;
b7c570ac 503 # prepare content here
38017482 504 return $content;
505 }
38017482 506 1;
508=head2 Plugins
b7c570ac 510The first thing to say about plugins is that if you're not sure if
511your module should be a plugin, it probably shouldn't. It once was
512common to add features to Catalyst by writing plugins that provide
513accessors to said functionality. As Catalyst grew more popular, it
514became obvious that this qualifies as bad practice.
516By designing your module as a Catalyst plugin, every method you
517implement, import or inherit will be available via your applications
518context object. A plugin pollutes the global namespace, and you
519should be only doing that when you really need to.
521Often, developers design extensions as plugins because they need to
522get hold of the context object. Either to get at the stash or
523request/response objects are the widely spread reasons. It is,
524however, perfectly possible to implement a regular Catalyst component
525(read: model, view or controller) that receives the current context
526object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
528When is a plugin suited to your task? Your code needs to be a
529plugin to act upon or alter specific parts of Catalyst's request
530lifecycle. If your functionality needs to wrap some C<prepare_*> or
531C<finalize_*> stages, you won't get around a plugin.
533Another valid target for a plugin architecture are things that
534B<really> have to be globally available, like sessions or
537B<Please do not> release Catalyst extensions as plugins only to
538provide some functionality application wide. Design it as a controller
539base class or another suiting technique with a smaller scope, so that
540your code only influences those parts of the application where it is
541needed, and namespace clashes and conflicts are ruled out.
38017482 542
543The implementation is pretty easy. Your plugin will be inserted in the
544application's inheritance list, above Catalyst itself. You can by this
b7c570ac 545alter Catalyst's request lifecycle behaviour. Every method you
546declare, every import in your package will be available as method on
547the application and the context object. As an example, let's say you
548want Catalyst to warn you every time uri_for returned an undefined
549value, for example because you specified the wrong number of captures
550for the targeted action chain. You could do this with this simple
38017482 551implementation (excuse the lame class name, it's just an example):
553 package Catalyst::Plugin::UriforUndefWarning;
554 use strict;
20a4dd98 555 use MRO::Compat;
38017482 556
557 sub uri_for {
b7c570ac 558 my $c = shift;
38017482 559 my $uri = $c->next::method(@_);
b7c570ac 560 $c->log->warn( 'uri_for returned undef for:', join(', ', @_), );
38017482 561 return $uri;
562 }
564 1;
b7c570ac 566This would override Catalyst's C<uri_for> method and emit a C<warn>
567log entry containing the arguments that led to the undefined return
38017482 569
570=head2 Factory components with COMPONENT()
b7c570ac 572Every component inheriting from L<Catalyst::Component> contains a
573C<COMPONENT> method. It is used on application startup by
574C<setup_components> to instantiate the component object for the
575Catalyst application. By default, this will merge the components own
576C<config>uration with the application wide overrides and call the
577class' C<new> method to return the component object.
38017482 578
b7c570ac 579You can override this method and do and return whatever you want.
20a4dd98 580However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
581to the original C<COMPONENT> method to merge the configuration of
582your component.
38017482 583
584Here is a stub C<COMPONENT> method:
586 package CatalystX::Component::Foo;
587 use strict;
588 use base 'Catalyst::Component';
20a4dd98 590 use MRO::Compat;
38017482 591
592 sub COMPONENT {
593 my $class = shift;
594 my ($app_class, $config) = @_;
b7c570ac 596 # do things here before instantiation my
597 $obj = $self->next::method(@_);
38017482 598 # do things to object after instantiation
38017482 599 return $object;
600 }
602The arguments are the class name of the component, the class name of
b7c570ac 603the application instantiating the component, and a hash reference with
604the controller's configuration.
38017482 605
b7c570ac 606You are free to re-bless the object, instantiate a whole other
607component or really do anything compatible with Catalyst's
608expectations on a component.
38017482 609
b7c570ac 610For more information, please see L<Catalyst::Component/"COMPONENT($c,$arguments)">.
38017482 611
612=head1 SEE ALSO
b7c570ac 614L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
38017482 615
616=head1 AUTHOR
1972ebdd 618Robert Sedlacek C<< <> >>
620Jonathan Rockway C<< <> >>
38017482 621
b7c570ac 624This document is free, you can redistribute it and/or modify it under
38017482 625the same terms as Perl itself.