the others. Catalyst promotes the re-use of existing Perl modules that
already handle common web application concerns well.
-Here's how the M, V, and C map to those concerns, with examples of
-well-known Perl modules you may want to use for each.
+Here's how the Model, View, and Controller map to those concerns, with
+examples of well-known Perl modules you may want to use for each.
=over 4
=head3 Flexibility
-Catalyst is much more flexible than many other frameworks. We'll talk
-more about this later, but rest assured you can use your favorite Perl
-modules with Catalyst.
+Catalyst is much more flexible than many other frameworks. Rest assured
+you can use your favorite Perl modules with Catalyst.
=over 4
Now http://localhost:3000/hello prints "Hello World!".
-=item * B<Support for CGI, mod_perl, Apache::Request>
+=item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
-Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
+Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
+engines are also available.
=back
=item * B<Helper Scripts>
Catalyst provides helper scripts to quickly generate running starter
-code for components and unit tests. See L<Catalyst::Helper>.
+code for components and unit tests. Install L<Catalyst::Devel> and see
+L<Catalyst::Helper>.
=back
=head3 Install
- $ perl -MCPAN -e 'install Task::Catalyst'
+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>.
+
+ # perl cat-install
+ # perl -MCPAN -e 'install Catalyst::Devel'
=head3 Setup
package MyApp;
use strict;
- use Catalyst qw/-Debug/;
+ use Catalyst qw/-Debug/; # Add other plugins here, e.g.
+ # for session support
MyApp->config(
name => 'My Application',
In older versions of Catalyst, the application class was where you put
global actions. However, as of version 5.66, the recommended practice is
-to place such actions in a special Root controller (see #####, below),
-to avoid namespace collisions.
+to place such actions in a special Root controller (see L</Actions>,
+below), to avoid namespace collisions.
=over 4
whatever you need. You can access them anywhere in your application via
C<$context-E<gt>config-E<gt>{$param_name}>.
-###### We need a short section on configuration here.
-
=head3 Context
Catalyst automatically blesses a Context object into your application
$c->req->cookies->{sessionid};
$c->req->headers->content_type;
$c->req->base;
+ $c->req->uri_with( { page = $pager->next_page } );
=item * L<Catalyst::Response>
$c->stash
$c->stash->{foo} = 'bar';
$c->stash->{baz} = {baz => 'qox'};
- $c->stash->{fred} = [qw/ wilma pebbles/];
+ $c->stash->{fred} = [qw/wilma pebbles/];
and so on.
Note that the stash should be used only for passing data in an
individual request cycle; it gets cleared at a new request. If you need
-to maintain more persistent data, use a session.
+to maintain persistent data, use a session. See
+L<Catalyst::Plugin::Session> for a comprehensive set of
+Catalyst-friendly session-handling tools.
=head3 Actions
Catalyst also provides a method to build and dispatch chains of actions,
like
- sub foo : Chained : CaptureArgs(1) {
+ sub catalog : Chained : CaptureArgs(1) {
my ( $self, $c, $arg ) = @_;
...
}
- sub bar : Chained('foo') : Args(1) {
+ sub item : Chained('catalog') : Args(1) {
my ( $self, $c, $arg ) = @_;
...
}
-to handle a C</foo/*/bar/*> path. For more information about this dispatch
-type, please read L<Catalyst::DispatchType::Chained>.
+to handle a C</catalog/*/item/*> path. For extensive information about this
+dispatch type, please see L<Catalyst::DispatchType::Chained>.
=item * B<Private>
=item * B<Args>
-Args is not an action type per se, but an action modifier - it adds a match
-restriction to any action it's provided to, requiring only as many path parts
-as are specified for the action to be valid - for example in
+Args is not an action type per se, but an action modifier - it adds a
+match restriction to any action it's provided to, requiring only as many
+path parts as are specified for the action to be valid - for example in
MyApp::Controller::Foo,
sub bar :Local
individual controllers.
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.
+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>
and C<MyApp::Controller::Catalog::Order::begin> would override this in
turn.
+=item * B<auto : Private>
+
In addition to the normal built-in actions, you have a special action
for making chains, C<auto>. Such C<auto> actions will be run after any
C<begin>, but before your action is processed. Unlike the other
for that URL.
B<Note:> Looking at it another way, C<auto> actions have to return a
-true value to continue processing! You can also C<die> in the autochain
+true value to continue processing! You can also C<die> in the auto
action; in that case, the request will go straight to the finalize
stage, without processing further actions.
}
You normally render templates at the end of a request, so it's a perfect
-use for the global C<end> action. (In practice, however, you would use a
-default C<end> action as supplied by L<Catalyst::Action::DefaultEnd>.)
+use for the global C<end> action.
+
+In practice, however, you would use a default C<end> action as supplied
+by L<Catalyst::Action::RenderView>.
Also, be sure to put the template under the directory specified in
-C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
-eyecandy debug screen. ;)
+C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
+screen.
=head4 Models
$c->stash->{template} = 'list.tt';
- use Some::Outside::DBIC::Module;
- my @records = Some::Outside::DBIC::Module->search({
- artist => 'sri',
+ use Some::Outside::Database::Module;
+ my @records = Some::Outside::Database::Module->search({
+ artist => 'Led Zeppelin',
});
$c->stash->{records} = \@records;
=head3 Models
-Models are providers of data. This data could come from anywhere - a search
-engine index, a database table, etc. Typically the data source does not have
-much to do with web applications or Catalyst - it could be used to write an
-offline report generator or a command line tool just the same.
+Models are providers of data. This data could come from anywhere - a
+search engine index, a database table, etc. Typically the data source
+does not have much to do with web applications or Catalyst - it could be
+used to write an offline report generator or a command line tool just
+the same.
-The common approach to writing a Catalyst-style model for your application is
-wrapping a generic model (e.g. L<DBIx::Class::Schema>, a bunch of XMLs, or
-anything really) with an object that contains configuration data, convenience
-methods, and so forth.
+The common approach to writing a Catalyst-style model for your
+application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
+bunch of XMLs, or anything really) with an object that contains
+configuration data, convenience methods, and so forth.
#### editor: move this part to =head3 Components somehow, right after this
#### section - this will require deeply rephrasing this paragraph.
-Technically, within Catalyst a model is a B<component> - an instance of the
-model's class belonging to the application. It is important to stress that the
-lifetime of these objects is per application, not per request.
+Technically, within Catalyst a model is a B<component> - an instance of
+the model's class belonging to the application. It is important to
+stress that the lifetime of these objects is per application, not per
+request.
-While the model base class (L<Catalyst::Model>) provides things like C<config>
-and stuff to better integrate the model into the application, sometimes this is
-not enough, and the model requires access to C<$c> itself.
+While the model base class (L<Catalyst::Model>) provides things like
+C<config> and stuff to better integrate the model into the application,
+sometimes this is not enough, and the model requires access to C<$c>
+itself.
Situations where this need might arise include:
A typical C<ACCEPT_CONTEXT> method could look like this:
- sub ACCEPT_CONTEXT {
- my ( $self, $c, @extra_arguments ) = @_;
- bless { %$self, c => $c }, ref($self);
- }
+ 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
Add a field to C<$c>, like C<my_model_instance>. Then write your
C<ACCEPT_CONTEXT> method to look like this:
- sub ACCEPT_CONTEXT {
- my ( $self, $c ) = @_;
-
- if ( my $per_request = $c->my_model_instance ) {
- return $per_request;
- } else {
- my $new_instance = bless { %$self, c => $c }, ref($self);
- Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
- $c->my_model_instance( $new_instance );
- return $new_instance;
- }
- }
+ sub ACCEPT_CONTEXT {
+ my ( $self, $c ) = @_;
+
+ if ( my $per_request = $c->my_model_instance ) {
+ return $per_request;
+ } else {
+ my $new_instance = bless { %$self, c => $c }, ref($self);
+ Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
+ $c->my_model_instance( $new_instance );
+ return $new_instance;
+ }
+ }
=head3 Testing
projects / catagits/Catalyst-Runtime.git / blobdiff