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