Initial set of tutorial edits to go along with depluralization update.
[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
118via multiple inheritence, if your functionality is well structured, then
119it's possible to use the composability of L<Moose> roles, and method modifiers
fa025310 120to hook onto to provide functionality.
78170776 121
122For a simple example of this, see L<CatalystX::REPL>.
38017482 124=head2 Inheritance and overriding methods
38017482 126When overriding a method, keep in mind that some day additionally
127arguments may be provided to the method, if the last parameter is not
128a flat list. It is thus better to override a method by shifting the
129invocant off of C<@_> and assign the rest of the used arguments, so
130you can pass your complete arguments to the original method via C<@_>:
20a4dd98 132 use MRO::Compat; ...
38017482 133
fa025310 134 sub foo {
135 my $self = shift;
136 my ($bar, $baz) = @_; # ... return
137 $self->next::method(@_);
138 }
38017482 139
140If you would do the common
142 my ($self, $foo, $bar) = @_;
144you'd have to use a much uglier construct to ensure that all arguments
145will be passed along and the method is future proof:
147 $self->next::method(@_[ 1 .. $#_ ]);
149=head2 Tests and documentation
b7c570ac 151When you release your module to the CPAN, proper documentation and at
152least a basic test suite (which means more than pod or even just
153C<use_ok>, sorry) gives people a good base to contribute to the
154module. It also shows that you care for your users. If you would like
155your module to become a recommended addition, these things will prove
38017482 156invaluable.
1972ebdd 158If you're just getting started, try using
159L<CatalystX::Starter|CatalystX::Starter> to generate some example
160tests for your module.
38017482 162=head2 Maintenance
b7c570ac 164In planning to release a module to the community (Catalyst or CPAN and
165Perl), you should consider if you have the resources to keep it up to
166date, including fixing bugs and accepting contributions.
38017482 167
b7c570ac 168If you're not sure about this, you can always ask in the proper
169Catalyst or Perl channels if someone else might be interested in the
170project, and would jump in as co-maintainer.
38017482 171
b7c570ac 172A public repository can further ease interaction with the
173community. Even read only access enables people to provide you with
174patches to your current development version. subversion, SVN and SVK,
175are broadly preferred in the Catalyst community.
38017482 176
b7c570ac 177If you're developing a Catalyst extension, please consider asking the
178core team for space in Catalyst's own subversion repository. You can
179get in touch about this via IRC or the Catalyst developers mailing
38017482 181
182=head2 The context object
184Sometimes you want to get a hold of the context object in a component
b7c570ac 185that was created on startup time, where no context existed yet. Often
38017482 186this is about the model reading something out of the stash or other
b7c570ac 187context information (current language, for example).
38017482 188
b7c570ac 189If you use the context object in your component you have tied it to an
190existing request. This means that you might get into problems when
191you try to use the component (e.g. the model - the most common case)
192outside of Catalyst, for example in cronjobs.
38017482 193
b7c570ac 194A stable solution to this problem is to design the Catalyst model
195separately from the underlying model logic. Let's take
196L<Catalyst::Model::DBIC::Schema> as an example. You can create a
38017482 197schema outside of Catalyst that knows nothing about the web. This kind
198of design ensures encapsulation and makes development and maintenance
199a whole lot easier. The you use the aforementioned model to tie your
b7c570ac 200schema to your application. This gives you a C<MyApp::DBIC> (the name
201is of course just an example) model as well as
202C<MyApp::DBIC::TableName> models to access your result sources
205By creating such a thin layer between the actual model and the
206Catalyst application, the schema itself is not at all tied to any
207application and the layer in-between can access the model's API using
208information from the context object.
210A Catalyst component accesses the context object at request time with
38017482 211L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
b7c570ac 215The application has to interact with the extension with some
216configuration. There is of course again more than one way to do it.
38017482 217
218=head2 Attributes
b7c570ac 220You can specify any valid Perl attribute on Catalyst actions you like.
221(See L<attributes/"Syntax of Attribute Lists"> for a description of
222what is valid.) These will be available on the C<Catalyst::Action>
223instance via its C<attributes> accessor. To give an example, this
38017482 225
226 sub foo : Local Bar('Baz') {
227 my ($self, $c) = @_;
b7c570ac 228 my $attributes =
229 $self->action_for('foo')->attributes;
230 $c->res->body($attributes->{Bar}[0] );
38017482 231 }
b7c570ac 233will set the response body to C<Baz>. The values always come in an
234array reference. As you can see, you can use attributes to configure
235your actions. You can specify or alter these attributes via
236L</"Component Configuration">, or even react on them as soon as
237Catalyst encounters them by providing your own L<component base
238class|/"Component Base Classes">.
38017482 239
240=head2 Creating custom accessors
b7c570ac 242L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
243creation. Please refer to the modules documentation for usage
38017482 244information.
246=head2 Component configuration
b7c570ac 248At creation time, the class configuration of your component (the one
249available via C<$self-E<gt>config>) will be merged with possible
38017482 250configuration settings from the applications configuration (either
b7c570ac 251directly or via config file). This is then stored in the controller
252object's hash reference. So, if you read possible configurations like:
38017482 253
254 my $model_name = $controller->{model_name};
b7c570ac 256you will get the right value. The C<config> accessor always only
38017482 257contains the original class configuration and must not be used for
258component configuration.
260You are advised to create accessors on your component class for your
261configuration values. This is good practice and makes it easier to
b7c570ac 262capture configuration key typos. You can do this with the
38017482 263C<mk_ro_accessors> method provided to L<Catalyst::Component> via
266 use base 'Catalyst::Controller';
267 __PACKAGE__->mk_ro_accessors('model_name');
268 ...
269 my $model_name = $controller->model_name;
b7c570ac 273This part contains the technical details of various implementation
38017482 274methods. Please read the L</"BEST PRACTICES"> before you start your
275implementation, if you haven't already.
277=head2 Action classes
279Usually, your action objects are of the class L<Catalyst::Action>.
280You can override this with the C<ActionClass> attribute to influence
b7c570ac 281execution and/or dispatching of the action. A widely used example of
282this is L<Catalyst::Action::RenderView>, which is used in every newly
283created Catalyst application in your root controller:
38017482 284
285 sub end : ActionClass('RenderView') { }
b7c570ac 287Usually, you want to override the C<execute> and/or the C<match>
288method. The execute method of the action will naturally call the
289methods code. You can surround this by overriding the method in a
38017482 291
20a4dd98 292 package Catalyst::Action::MyFoo;
293 use strict;
38017482 294
20a4dd98 295 use MRO::Compat;
296 use base 'Catalyst::Action';
38017482 297
298 sub execute {
299 my $self = shift;
300 my ($controller, $c, @args) = @_;
38017482 301 # put your 'before' code here
302 my $r = $self->next::method(@_);
303 # put your 'after' code here
38017482 304 return $r;
305 }
38017482 306 1;
20a4dd98 308We are using L<MRO::Compat> to ensure that you have the next::method
309call, from L<Class::C3> (in older perls), or natively (if you are using
310perl 5.10) to re-dispatch to the original C<execute> method in the
311L<Catalyst::Action> class.
38017482 312
b7c570ac 313The Catalyst dispatcher handles an incoming request and, depending
314upon the dispatch type, will call the appropriate target or chain.
315From time to time it asks the actions themselves, or through the
316controller, if they would match the current request. That's what the
317C<match> method does. So by overriding this, you can change on what
318the action will match and add new matching criteria.
38017482 319
b7c570ac 320For example, the action class below will make the action only match on
38017482 322
78170776 323 package Catalyst::Action::OnlyMondays;
324 use strict;
38017482 325
20a4dd98 326 use MRO::Compat;
38017482 327 use base 'Catalyst::Action';
329 sub match {
330 my $self = shift;
331 return 0 if ( localtime(time) )[6] == 1;
332 return $self->next::method(@_);
b7c570ac 333 }
38017482 334 1;
336And this is how we'd use it:
338 sub foo: Local ActionClass('OnlyMondays') {
339 my ($self, $c) = @_;
340 $c->res->body('I feel motivated!');
341 }
b7c570ac 343If you are using action classes often or have some specific base
344classes that you want to specify more conveniently, you can implement
345a component base class providing an attribute handler.
38017482 346
b7c570ac 347For further information on action classes, please refer to
38017482 348L<Catalyst::Action> and L<Catalyst::Manual::Actions>.
350=head2 Component base classes
b7c570ac 352Many L<Catalyst::Plugin> that were written in Catalyst's early days
353should really have been just controller base classes. With such a
354class, you could provide functionality scoped to a single controller,
355not polluting the global namespace in the context object.
38017482 356
b7c570ac 357You can provide regular Perl methods in a base class as well as
358actions which will be inherited to the subclass. Please refer to
359L</Controllers> for an example of this.
38017482 360
b7c570ac 361You can introduce your own attributes by specifying a handler method
362in the controller base. For example, to use a C<FullClass> attribute
363to specify a fully qualified action class name, you could use the
364following implementation. Note, however, that this functionality is
365already provided via the C<+> prefix for action classes. A simple
38017482 366
367 sub foo : Local ActionClass('+MyApp::Action::Bar') { ... }
369will use C<MyApp::Action::Bar> as action class.
b7c570ac 371 package MyApp::Base::Controller::FullClass; use strict; use base
372 'Catalyst::Controller';
38017482 373
374 sub _parse_FullClass_attr {
375 my ($self, $app_class, $action_name, $value, $attrs) = @_;
376 return( ActionClass => $value );
377 }
38017482 378 1;
b7c570ac 380Note that the full line of arguments is only provided for completeness
381sake. We could use this attribute in a subclass like any other
382Catalyst attribute:
38017482 383
384 package MyApp::Controller::Foo;
385 use strict;
386 use base 'MyApp::Base::Controller::FullClass';
388 sub foo : Local FullClass('MyApp::Action::Bar') { ... }
390 1;
392=head2 Controllers
b7c570ac 394Many things can happen in controllers, and it often improves
395maintainability to abstract some of the code out into reusable base
38017482 396classes.
398You can provide usual Perl methods that will be available via your
b7c570ac 399controller object, or you can even define Catalyst actions which will
400be inherited by the subclasses. Consider this controller base class:
38017482 401
402 package MyApp::Base::Controller::ModelBase;
403 use strict;
404 use base 'Catalyst::Controller';
406 sub list : Chained('base') PathPart('') Args(0) {
407 my ($self, $c) = @_;
b7c570ac 408 my $model = $c->model( $self->{model_name} );
38017482 409 my $condition = $self->{model_search_condition} || {};
b7c570ac 410 my $attrs = $self->{model_search_attrs} || {};
38017482 411 $c->stash(rs => $model->search($condition, $attrs);
b7c570ac 412 }
38017482 413
414 sub load : Chained('base') PathPart('') CaptureArgs(1) {
415 my ($self, $c, $id) = @_;
416 my $model = $c->model( $self->{model_name} );
417 $c->stash(row => $model->find($id));
b7c570ac 418 }
38017482 419 1;
b7c570ac 421This example implements two simple actions. The C<list> action chains
422to a (currently non-existent) C<base> action and puts a result-set
423into the stash taking a configured C<model_name> as well as a search
424condition and attributes. This action is a
425L<chained|Catalyst::DispatchType::Chained> endpoint. The other action,
426called C< load > is a chain midpoint that takes one argument. It takes
427the value as an ID and loads the row from the configured model. Please
428not that the above code is simplified for clarity. It misses error
429handling, input validation, and probably other things.
38017482 430
b7c570ac 431The class above is not very useful on its own, but we can combine it
432with some custom actions by sub-classing it:
38017482 433
434 package MyApp::Controller::Foo;
435 use strict;
436 use base 'MyApp::Base::Controller::ModelBase';
b7c570ac 438 __PACKAGE__->config( model_name => 'DB::Foo',
439 model_search_condition=> { is_active => 1 },
440 model_search_attrs => { order_by => 'name' },
441 );
38017482 442
443 sub base : Chained PathPart('foo') CaptureArgs(0) { }
445 sub view : Chained('load') Args(0) {
446 my ($self, $c) = @_;
447 my $row = $c->stash->{row};
b7c570ac 448 $c->res->body(join ': ', $row->name,
449 $row->description); }
38017482 450 1;
b7c570ac 452This class uses the formerly created controller as a base
453class. First, we see the configurations that were used in the parent
454class. Next comes the C<base> action, where everything chains off of.
38017482 455
b7c570ac 456Note that inherited actions act like they were declared in your
457controller itself. You can therefor call them just by their name in
38017482 458C<forward>s, C<detaches> and C<Chained(..)> specifications. This is an
459important part of what makes this technique so useful.
b7c570ac 461The new C<view> action ties itself to the C<load> action specified in
462the base class and outputs the loaded row's C<name> and C<description>
463columns. The controller C<MyApp::Controller::Foo> now has these
464publicly available paths:
38017482 465
468=item /foo
b7c570ac 470Will call the controller's C<base>, then the base classes C<list>
38017482 472
473=item /foo/$id/view
b7c570ac 475First, the controller's C<base> will be called, then it will C<load>
476the row with the corresponding C<$id>. After that, C<view> will
477display some fields out of the object.
38017482 478
481=head2 Models and Views
b7c570ac 483If the functionality you'd like to add is really a data-set that you
484want to manipulate, for example internal document types, images,
485files, it might be better suited as a model.
38017482 486
b7c570ac 487The same applies for views. If your code handles representation or
488deals with the applications interface and should be universally
489available, it could be a perfect candidate for a view.
38017482 490
b7c570ac 491Please implement a C<process> method in your views. This method will
492be called by Catalyst if it is asked to forward to a component without
493a specified action. Note that C<process> is B<not a Catalyst action>
494but a simple Perl method.
38017482 495
496You are also encouraged to implement a C<render> method corresponding
497with the one in L<Catalyst::View::TT>. This has proven invaluable,
498because people can use your view for much more fine-grained content
501Here is some example code for a fictional view:
503 package CatalystX::View::MyView;
504 use strict;
505 use base 'Catalyst::View';
507 sub process {
508 my ($self, $c) = @_;
38017482 509 my $template = $c->stash->{template};
b7c570ac 510 my $content = $self->render($c, $template, $c->stash);
38017482 511 $c->res->body( $content );
512 }
514 sub render {
515 my ($self, $c, $template, $args) = @_;
b7c570ac 516 # prepare content here
38017482 517 return $content;
518 }
38017482 519 1;
521=head2 Plugins
b7c570ac 523The first thing to say about plugins is that if you're not sure if
524your module should be a plugin, it probably shouldn't. It once was
525common to add features to Catalyst by writing plugins that provide
526accessors to said functionality. As Catalyst grew more popular, it
527became obvious that this qualifies as bad practice.
529By designing your module as a Catalyst plugin, every method you
530implement, import or inherit will be available via your applications
531context object. A plugin pollutes the global namespace, and you
532should be only doing that when you really need to.
534Often, developers design extensions as plugins because they need to
535get hold of the context object. Either to get at the stash or
536request/response objects are the widely spread reasons. It is,
537however, perfectly possible to implement a regular Catalyst component
538(read: model, view or controller) that receives the current context
539object via L<Catalyst::Component/"ACCEPT_CONTEXT($c, @args)">.
541When is a plugin suited to your task? Your code needs to be a
542plugin to act upon or alter specific parts of Catalyst's request
78170776 543lifecycle. If your functionality needs to change some C<prepare_*> or
b7c570ac 544C<finalize_*> stages, you won't get around a plugin.
78170776 546Note, if you just want to hook into such a stage, and run code before,
547or after it, then it is recommended that you use L<Moose>s method modifiers
548to do this.
b7c570ac 550Another valid target for a plugin architecture are things that
551B<really> have to be globally available, like sessions or
554B<Please do not> release Catalyst extensions as plugins only to
555provide some functionality application wide. Design it as a controller
556base class or another suiting technique with a smaller scope, so that
557your code only influences those parts of the application where it is
558needed, and namespace clashes and conflicts are ruled out.
38017482 559
560The implementation is pretty easy. Your plugin will be inserted in the
561application's inheritance list, above Catalyst itself. You can by this
b7c570ac 562alter Catalyst's request lifecycle behaviour. Every method you
563declare, every import in your package will be available as method on
564the application and the context object. As an example, let's say you
78170776 565want Catalyst to warn you every time uri_for was called without an action
566object as the first parameter, for example to test that all your chained
567uris are generated from actions (a recommended best practice).
568You could do this with this simple
38017482 569implementation (excuse the lame class name, it's just an example):
571 package Catalyst::Plugin::UriforUndefWarning;
572 use strict;
78170776 573 use Scalar::Util qw/blessed/;
20a4dd98 574 use MRO::Compat;
38017482 575
576 sub uri_for {
b7c570ac 577 my $c = shift;
38017482 578 my $uri = $c->next::method(@_);
78170776 579 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
580 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
38017482 581 return $uri;
582 }
584 1;
b7c570ac 586This would override Catalyst's C<uri_for> method and emit a C<warn>
78170776 587log entry containing the arguments to uri_for.
589Please note this is not a practical example, as string URLs are fine for
590static content etc.
592A simple example like this is actually better as a L<Moose> role, for example:
594 package CatalystX::UriforUndefWarning;
595 use Moose::Role;
596 use namespace::clean -except => 'meta';
598 after 'uri_for' => sub {
599 my ($c, $arg) = @_;
600 $c->log->warn( 'uri_for with non action: ', join(', ', @_), )
601 if (!blessed($_[0]) || !$_[0]->isa('Catalyst::Action'));
602 return $uri;
fa025310 603 };
38017482 604
605=head2 Factory components with COMPONENT()
b7c570ac 607Every component inheriting from L<Catalyst::Component> contains a
608C<COMPONENT> method. It is used on application startup by
609C<setup_components> to instantiate the component object for the
610Catalyst application. By default, this will merge the components own
611C<config>uration with the application wide overrides and call the
612class' C<new> method to return the component object.
38017482 613
b7c570ac 614You can override this method and do and return whatever you want.
fa025310 615However, you should use L<Class::C3> (via L<MRO::Compat>) to forward
616to the original C<COMPONENT> method to merge the configuration of
20a4dd98 617your component.
38017482 618
619Here is a stub C<COMPONENT> method:
621 package CatalystX::Component::Foo;
622 use strict;
623 use base 'Catalyst::Component';
20a4dd98 625 use MRO::Compat;
38017482 626
627 sub COMPONENT {
628 my $class = shift;
a70cede4 629 # Note: $app is like $c, but since the application isn't fully
630 # initialized, we don't want to call it $c yet. $config
631 # is a hashref of config options possibly set on this component.
632 my ($app, $config) = @_;
634 # Do things here before instantiation
635 $new = $class->next::method(@_);
636 # Do things to object after instantiation
637 return $new;
38017482 638 }
640The arguments are the class name of the component, the class name of
b7c570ac 641the application instantiating the component, and a hash reference with
642the controller's configuration.
38017482 643
b7c570ac 644You are free to re-bless the object, instantiate a whole other
645component or really do anything compatible with Catalyst's
646expectations on a component.
38017482 647
fa025310 648For more information, please see
38017482 650
651=head1 SEE ALSO
b7c570ac 653L<Catalyst>, L<Catalyst::Manual::Actions>, L<Catalyst::Component>
38017482 654
655=head1 AUTHOR
1972ebdd 657Robert Sedlacek C<< <> >>
659Jonathan Rockway C<< <> >>
38017482 660
b7c570ac 663This document is free, you can redistribute it and/or modify it under
38017482 664the same terms as Perl itself.