=head1 DESCRIPTION
-This document provides an overview of the internals of Catalyst. As Catalyst
-is still developing rapidly details may become out of date.
+This document provides an overview of the internals of
+Catalyst. As Catalyst is still developing rapidly, details
+may become out of date: please treat this as a guide, and
+look at the source for the last word.
The coverage is split into initialization and request lifecycle.
-
=head2 Initialization
Catalyst initializes itself in two stages (I may be wrong in some of
=item 1
-When the Catalyst module is imported in the main application module it
-evaluates any options (C<-Debug>, C<-Engine=XXX>) and loads any specified
-plugins, making application module inherit from the plugin classes. It also
-sets up a default log object and ensures that the application module inherits
-from C<Catalyst> and from the selected specialized Engine module.
+When the Catalyst module is imported in the main application
+module it evaluates any options (C<-Debug>, C<-Engine=XXX>)
+and loads any specified plugins, making the application module
+inherit from the plugin classes. It also sets up a default log
+object and ensures that the application module inherits from
+C<Catalyst> and from the selected specialized Engine module.
=item 2
When the application module makes the first call to C<< __PACKAGE__->action() >>
-(implemented in C<Catalyst::Engine>) Catalyst automatically loads all
-components it finds in the C<$class\::Controller>, C<$class\::C>,
-C<$class\::Model>, C<$class\::M>, C<$class\::View> and C<$class\::V>
+(implemented in C<Catalyst::Engine>), Catalyst automatically loads all
+components it finds in the C<$class::Controller>, C<$class::C>,
+C<$class::Model>, C<$class::M>, C<$class::View> and C<$class::V>
namespaces (using C<Module::Pluggable::Fast>). A table of actions is built up
and added to on subsequent calls to C<action()>.
=head2 Request Lifecycle
For each request Catalyst builds a I<context> object, which includes
-information about the request, and searches the action table for matching
+information about the request, and then searches the action table for matching
actions.
The handling of a request can be divided into three stages: preparation of the
new system, e-mailed Slashdot, and waited for the onslaught.
When it hit Slashdot, things held up very nicely. (Some early
-error pages, embarrassedly pointed out by a Slashdot poster,
+error pages, embarrassingly pointed out by a Slashdot poster,
were in fact caused by a lack of available MySQL connections,
for which misconfiguration the DB admin was harshly
criticized, rather than from any app-specific failings.) In
=head2 Testing out the sample application
You can test out your new application by running the server script that
-catalyst provides:
+Catalyst provides:
$ cd My-App
$ script/server.pl
.=----------------------+----------------------+---------------=.
| Private | Class | Code |
|=----------------------+----------------------+---------------=|
- | /default | MyApp | CODE(0x86f08ac |
+ | /default | MyApp | CODE(0x86f08ac)|
'=----------------------+----------------------+---------------='
"My::App" defined "!default" as "CODE(0x83fd570)"
[...] [catalyst] [info] My::App powered by Catalyst 5.00
The call to C<config> sets up configuration data for the application.
The C<name> and C<root> items are the minimum required, and specify
the name of the application and the path to the root directory where
-documents, images and templates can be found.
+documents, images, and templates can be found.
Catalyst associates I<actions> with URLs and on receiving a request
dispatches to the action that matches to request URL. The call to
As you see, the default action is defined as a Private action.
Most private actions are not directly available from a web url. This
-also includes the built-in actions, 'default','begin','end' and
+also includes the built-in actions, 'default','begin','end', and
'auto', although they will be called as part of some chains.
The rest can only be reached by using C<forward>.
-
The call to the C<setup> method also triggers the second stage of
Catalyst's initialization process. In this phase Catalyst searches
for any component modules, locating and registering any actions it
}
-TODO: explain briefly about plugins, actions and components
+TODO: explain briefly about plugins, actions, and components
regex actions passed subexpression matches in $c->req->snippets
(array ref).
Template Toolkit then I suggest you look at L<http://tt2.org>, install
C<Template>, read the documentation and play around with it, and have
a look at the I<Badger Book> (I<Template Toolkit> by Darren
-Chamberlain, Dave Cross and Andy Wardly, O'Reilly & Associates, 2004).
+Chamberlain, Dave Cross, and Andy Wardley, O'Reilly & Associates, 2004).
You can create a stub Template Toolkit view component using the create
script that Catalyst set up as part of the skeleton application:
=item 1
-expand this document fairly rapidly to cover topics relevant to
-a newcomer to Catalyst in an order that can be read sequentially
+Expand this document fairly rapidly to cover topics relevant to
+a newcomer to Catalyst, in an order that can be read sequentially
=item 2
-incorporate feedback
+Incorporate feedback
=item 3
-revise the text
+Revise the text
=back