written to help you understand the possibilities, current practices
and their consequences.
-Please read the L<BEST PRACTICES> section before deciding on a design,
+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 your plugin doesn't really need to muck with the internals, make it a
base Controller or Model.
-If you need to hook (but not alter) the internals, then make it a L<Moose::Role>
+Also, if you think you really need a plugin, please instead consider
+using a L<Moose::Role>.
=item There's a community. Use it!
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.
+L<Catalyst::Manual::Tutorial::Testing|Catalyst::Manual::Tutorial::08_Testing>
+for more information.
=back
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
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
+L<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
convenient.
If you want the thinnest interface possible, take a look at
-L<Catalyst::Model::Adaptor|Catalyst::Model::Adaptor>.
+L<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
+via multiple inheritance, 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.
-
-For a simple example of this, see L<CatalystX::REPL>.
+to hook onto to provide functionality.
-B<Note:> Currently, controllers with attributes will not function correctly
-in conjunction with Moose roles.
+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
-While Catalyst itself is still based on L<NEXT> (for multiple
-inheritance), extension developers are encouraged to use L<Class::C3>,
-via L<MRO::Compat>, which is what Catalyst will be switching to in the
-5.80 release.
-
-When overriding a method, keep in mind that some day additionally
+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
use MRO::Compat; ...
- sub foo { my $self = shift;
- my ($bar, $baz) = @_; # ... return
- $self->next::method(@_); }
+ sub foo {
+ my $self = shift;
+ my ($bar, $baz) = @_; # ... return
+ $self->next::method(@_);
+ }
If you would do the common
invaluable.
If you're just getting started, try using
-L<CatalystX::Starter|CatalystX::Starter> to generate some example
+L<CatalystX::Starter> to generate some example
tests for your module.
=head2 Maintenance
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>
+what is valid.) These will be available on the L<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;
+ my $attributes = $self->action_for('foo')->attributes;
$c->res->body($attributes->{Bar}[0] );
}
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">.
+class|/"Component base classes">.
-=head2 Creating custom accessors
-
-L<Catalyst::Component> uses L<Class::Accessor::Fast> for accessor
-creation. Please refer to the modules documentation for usage
-information.
-
-=head2 Component configuration
+=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
+available via C<< $self->config >>) will be merged with possible
configuration settings from the applications configuration (either
-directly or via config file). This is then stored in the controller
-object's hash reference. So, if you read possible configurations like:
+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 C<< $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' },
+ );
- my $model_name = $controller->{model_name};
+ ...
-you will get the right value. The C<config> accessor always only
-contains the original class configuration and must not be used for
-component configuration.
+ package MyApp::Controller::Foo;
+ use Moose;
+ use namespace::autoclean;
+ BEGIN { extends 'Catalyst::Controller' };
-You are advised to create accessors on your component class for your
-configuration values. This is good practice and makes it easier to
-capture configuration key typos. You can do this with the
-C<mk_ro_accessors> method provided to L<Catalyst::Component> via
-L<Class::Accessor::Fast>:
+ has some_value ( is => 'ro', required => 1 );
+
+ sub some_method {
+ my $self = shift;
+ return "the value of 'some_value' is " . $self->some_value;
+ }
- use base 'Catalyst::Controller';
- __PACKAGE__->mk_ro_accessors('model_name');
...
- my $model_name = $controller->model_name;
+
+ my $controller = $c->controller('Foo');
+ warn $controller->some_value;
+ warn $controller->some_method;
=head1 IMPLEMENTATION
methods code. You can surround this by overriding the method in a
subclass:
- package Catalyst::Action::MyFoo;
- use strict;
-
- use MRO::Compat;
- use base 'Catalyst::Action';
+ package Catalyst::Action::MyFoo;
+ use Moose;
+ use namespace::autoclean;
+ use MRO::Compat;
+ extends 'Catalyst::Action';
sub execute {
my $self = shift;
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
+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.
+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
For example, the action class below will make the action only match on
Mondays:
- package Catalyst::Action::OnlyMondays;
- use strict;
-
+ package Catalyst::Action::OnlyMondays;
+ use Moose;
+ use namespace::autoclean;
use MRO::Compat;
- use base 'Catalyst::Action';
+ extends 'Catalyst::Action';
sub match {
my $self = shift;
classes that you want to specify more conveniently, you can implement
a component base class providing an attribute handler.
-For further information on action classes, please refer to
+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
will use C<MyApp::Action::Bar> as action class.
- package MyApp::Base::Controller::FullClass; use strict; use base
- 'Catalyst::Controller';
+ 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) = @_;
Catalyst attribute:
package MyApp::Controller::Foo;
- use strict;
- use base 'MyApp::Base::Controller::FullClass';
+ use Moose;
+ use namespace::autoclean;
+ BEGIN { extends 'MyApp::Base::Controller::FullClass'; }
sub foo : Local FullClass('MyApp::Action::Bar') { ... }
be inherited by the subclasses. Consider this controller base class:
package MyApp::Base::Controller::ModelBase;
- use strict;
- use base 'Catalyst::Controller';
+ use Moose;
+ use namespace::autoclean;
+
+ BEGIN { extends 'Catalyst::Controller'; }
sub list : Chained('base') PathPart('') Args(0) {
my ($self, $c) = @_;
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
with some custom actions by sub-classing it:
package MyApp::Controller::Foo;
- use strict;
- use base 'MyApp::Base::Controller::ModelBase';
+ use Moose;
+ use namespace::autoclean;
+
+ BEGIN { extends 'MyApp::Base::Controller::ModelBase'; }
__PACKAGE__->config( model_name => 'DB::Foo',
model_search_condition=> { is_active => 1 },
Here is some example code for a fictional view:
- package CatalystX::View::MyView;
- use strict;
- use base 'Catalyst::View';
+ package Catalyst::View::MyView;
+ use Moose;
+ use namespace::autoclean;
+
+ extends 'Catalyst::View';
sub process {
my ($self, $c) = @_;
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
+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<Please do not> release Catalyst extensions as plugins only to
provide some functionality application wide. Design it as a controller
-base class or another suiting technique with a smaller scope, so that
+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.
package CatalystX::UriforUndefWarning;
use Moose::Role;
- use namespace::clean -except => 'meta';
+ 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()
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
+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 strict;
- use base 'Catalyst::Component';
+ use Moose;
+ use namespace::autoclean;
- use MRO::Compat;
+ extends 'Catalyst::Component';
sub COMPONENT {
my $class = shift;
- my ($app_class, $config) = @_;
-
- # do things here before instantiation my
- $obj = $self->next::method(@_);
- # do things to object after instantiation
- return $object;
+ # 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
component or really do anything compatible with Catalyst's
expectations on a component.
-For more information, please see L<Catalyst::Component/"COMPONENT($c,$arguments)">.
+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 AUTHOR
-
-Robert Sedlacek C<< <rs@474.at> >>
+=head1 AUTHORS
-Jonathan Rockway C<< <jrockway@cpan.org> >>
+Catalyst Contributors, see Catalyst.pm
-=head1 LICENSE AND COPYRIGHT
+=head1 COPYRIGHT
-This document is free, you can redistribute it and/or modify it under
+This library is free software. You can redistribute it and/or modify it under
the same terms as Perl itself.
=cut
-
projects / catagits/Catalyst-Manual.git / blobdiff