=head2 What is Catalyst?
Catalyst is an elegant web application framework, extremely flexible
-yet extremely simple. It's similar to Ruby on Rails, Spring (Java),
-and L<Maypole>, upon which it was originally based. Its most important
-design philosphy is to provide easy access to all the tools you need
-to develop web applications, with few restrictions on how you need to
-use these tools. However, this does mean that it is always possible to
-do things in a different way. Other web frameworks are B<initially>
-simpler to use, but achieve this by locking the programmer into a
-single set of tools. Catalyst's emphasis on flexibility means that you
-have to think more to use it. We view this as a feature. For example,
-this leads to Catalyst being more suited to system integration tasks
-than other web frameworks.
+yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
+L<Maypole|Maypole>, upon which it was originally based. Its most
+important design philosphy is to provide easy access to all the tools
+you need to develop web applications, with few restrictions on how you
+need to use these tools. However, this does mean that it is always
+possible to do things in a different way. Other web frameworks are
+I<initially> simpler to use, but achieve this by locking the programmer
+into a single set of tools. Catalyst's emphasis on flexibility means
+that you have to think more to use it. We view this as a feature. For
+example, this leads to Catalyst being more suited to system integration
+tasks than other web frameworks.
=head3 MVC
With Catalyst you register your actions and address them directly. For
example:
- sub hello : Global {
+ sub hello : Local {
my ( $self, $context ) = @_;
$context->response->body('Hello World!');
}
Now http://localhost:3000/hello prints "Hello World!".
+Note that actions with the C< :Global > attribute are equivalent to
+using a C<:Path('action_name') > attribute, so our action could be
+equivalently:
+
+ sub hi : Path('hello') {
+ my ( $self, $context ) = @_;
+ $context->response->body('Hello World!');
+ }
+
+
=item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
-Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
-engines are also available.
+Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Another
+interesting engine is L<Catalyst::Engine::HTTP::Prefork> - available from CPAN
+separately - which will turn the built server into a fully fledged production
+ready server (although you'll probably want to run it behind a front end proxy
+if you end up using it).
=back
=head3 Install
-Installation of Catalyst can be a time-consuming and frustrating
-effort, due to its large number of dependencies. The easiest way
-to get up and running is to use Matt Trout's C<cat-install>
-script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
-and then install L<Catalyst::Devel>.
+Installation of Catalyst can be a time-consuming effort, due to its
+large number of dependencies. Although most of the frustrations
+associated with this are now ironed out and a simple C<cpan
+Catalyst::Devel> or C<cpan Catalyst::Runtime> are now usually
+straightforward, if you still have problems, you can use use Matt
+Trout's C<cat-install> script, from
+L<http://www.shadowcatsystems.co.uk/static/cat-install>, and then
+install L<Catalyst::Devel>.
# perl cat-install
# perl -MCPAN -e 'install Catalyst::Devel'
$ cd MyApp
$ script/myapp_create.pl controller Library::Login
+=head4 Frank Speiser's Amazon EC2 Catalyst SDK
+
+There are currently two flavors of publicly available Amazon Machine
+Images (AMI) that include all the elements you'd need to begin
+developing in a fully functional Catalyst environment within
+minutes. See
+L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
+more details.
+
+
=head3 Run
$ script/myapp_server.pl
a general discussion of these issues.
Model, View and Controller components must inherit from L<Catalyst::Model>,
-L<Catalyst::View> and L<Catalyst::Model>, respectively. These, in turn, inherit
+L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
from L<Catalyst::Component> which provides a simple class structure and some
common class methods like C<config> and C<new> (constructor).
script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
-L<DBIx::Class::Schema::Loader> automatically loads table layouts and
-relationships, and converts them into a static schema definition C<MySchema>,
-which you can edit later.
+L<DBIx::Class::Schema::Loader> can automaticall load table layouts and
+relationships, and convert them into a static schema definition
+C<MySchema>, which you can edit later.
Use the stash to pass data to your templates.
method instead of returning the model itself, the return value of C<<
$model->ACCEPT_CONTEXT( $c ) >> will be used.
-This means that whenever your model/view/controller needs to talk to C<$c> it
-gets a chance to do this when it's needed.
+This means that whenever your model/view/controller needs to talk to
+C<$c> it gets a chance to do this when it's needed.
A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
with the context object set, or it will return a thin wrapper that contains
C<$c> and delegates to the per-application model object.
-A typical C<ACCEPT_CONTEXT> method could look like this:
-
- sub ACCEPT_CONTEXT {
- my ( $self, $c, @extra_arguments ) = @_;
- bless { %$self, c => $c }, ref($self);
- }
-
-effectively treating $self as a B<prototype object> that gets a new parameter.
-C<@extra_arguments> comes from any trailing arguments to
-C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
-C<< $c->view(...) >> etc).
-
-The life time of this value is B<per usage>, and not per request. To make this
-per request you can use the following technique:
+Generally it's a bad idea to expose the context object (C<$c>) in your
+model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
+to grab the bits of the context object that you need, and provide
+accessors to them in the model. This ensures that C<$c> is only in
+scope where it is neaded which reduces maintenance and debugging
+headaches. So, if for example you needed two
+L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
+code, you might do something like this:
+
+ __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
+ sub ACCEPT_CONTEXT {
+ my ( $self, $c, @extra_arguments ) = @_;
+ $self = bless({ %$self,
+ model1_schema => $c->model('Model1')->schema,
+ model2_schema => $c->model('Model2')->schema
+ }, ref($self));
+ return $self;
+ }
+
+This effectively treats $self as a B<prototype object> that gets a new
+parameter. C<@extra_arguments> comes from any trailing arguments to
+C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
+>>, C<< $c->view(...) >> etc).
+
+In a subroutine in the model code, we can then do this:
+
+ sub whatever {
+ my ($self) = @_;
+ my $schema1 = $self->model1_schema;
+ my $schema2 = $self->model2_schema;
+ ...
+ }
+
+Note that we still want the Catalyst models to be a thin wrapper
+around classes that will work independently of the Catalyst
+application to promote reusability of code. Here we might just want
+to grab the $c->model('DB')->schema so as to get the connection
+information from the Catalyst application's configuration for example.
+
+The life time of this value is B<per usage>, and not per request. To
+make this per request you can use the following technique:
Add a field to C<$c>, like C<my_model_instance>. Then write your
C<ACCEPT_CONTEXT> method to look like this:
}
}
+For a similar technique to grab a new component instance on each
+request, see L<Catalyst::Component::InstancePerContext>.
+
=head3 Application Class
In addition to the Model, View, and Controller components, there's a
package MyApp;
use strict;
- use Catalyst qw/-Debug/; # Add other plugins here, e.g.
- # for session support
-
+ use parent qw/Catalyst/;
+ use Catalyst qw/-Debug ConfigLoader Static::Simple/;
MyApp->config(
name => 'My Application',
$c->res->status(404);
$c->res->redirect('http://oook.de');
-=item * L<Catalyst::Config>
+=item * config
$c->config
$c->config->{root};
# Sets the actions in this controller to be registered with no prefix
# so they function identically to actions created in MyApp.pm
__PACKAGE__->config->{namespace} = '';
- sub default : Private {
+ sub default : Path {
my ( $self, $context ) = @_;
- $context->response->body('Catalyst rocks!');
+ $context->response->status(404);
+ $context->response->body('404 not found');
}
1;
explanation of the pre-defined meaning of Catalyst component class
names.
+Note that actions with the C< :Local > attribute are equivalent to the
+<:Path('action_name') > so sub foo : Local { } is equivalent to -
+
+ sub foo : Path('foo') { }
+
=item * B<Chained>
Catalyst also provides a method to build and dispatch chains of actions,
=over 4
-=item * B<default : Private>
+=item * B<default : Path>
Called when no other action matches. Could be used, for example, for
displaying a generic frontpage for the main app, or an error page for
-individual controllers.
+individual controllers. B<Note>: in older Catalyst applications you
+will see C<default : Private> which is roughly speaking equivalent.
-If C<default> isn't acting how you would expect, look at using a
-L</Literal> C<Path> action (with an empty path string). The difference
-is that C<Path> takes arguments relative from the namespace and
-C<default> I<always> takes arguments relative from the root, regardless
-of what controller it's in. Indeed, this is now the recommended way of
-handling default situations; the C<default> private controller should
-be considered deprecated.
-=item * B<index : Private>
+=item * B<index : Path : Args (0) >
-C<index> is much like C<default> except that it takes no arguments
-and it is weighted slightly higher in the matching process. It is
-useful as a static entry point to a controller, e.g. to have a static
-welcome page. Note that it's also weighted higher than Path.
+C<index> is much like C<default> except that it takes no arguments and
+it is weighted slightly higher in the matching process. It is useful
+as a static entry point to a controller, e.g. to have a static welcome
+page. Note that it's also weighted higher than Path. Actually the sub
+name C<index> can be called anything you want. The sub attributes are
+what determines the behaviour of the action. B<Note>: in older
+Catalyst applications, you will see C<index : Private> used, which is
+roughly speaking equivalent.
=item * B<begin : Private>
=head4 Built-in actions in controllers/autochaining
- Package MyApp::Controller::Foo;
+ package MyApp::Controller::Foo;
sub begin : Private { }
- sub default : Private { }
+ sub default : Path { }
sub auto : Private { }
You can define built-in private actions within your controllers as
=item for a request for C</foo/foo>
- MyApp::begin
- MyApp::auto
+ MyApp::Controller::Foo::auto
MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
- MyApp::end
+ MyApp::Controller::Foo::end
=item for a request for C</foo/bar/foo>
MyApp::Controller::Foo::Bar::begin
- MyApp::auto
MyApp::Controller::Foo::auto
MyApp::Controller::Foo::Bar::auto
MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
false
MyApp::Controller::Foo::Bar::begin
- MyApp::auto
MyApp::Controller::Foo::Bar::end
=back
http://lists.scsys.co.uk/mailman/listinfo/catalyst
http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
+Wiki:
+
+ http://dev.catalystframework.org/wiki
+
+FAQ:
+
+ http://dev.catalystframework.org/wiki/faq
+
=head1 AUTHOR
Sebastian Riedel, C<sri@oook.de>
projects / catagits/Catalyst-Manual.git / blobdiff