X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=9f39c49baa5decfd4ff6c915472a64e3526df450;hb=75c0ec035b7fdca765a41974a7970bf170b273d0;hp=21a701d22b509352faa6b6a0b1986cab53cb43d5;hpb=5882c86e1f256e122583dcc311b17bdbf9a4d766;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index 21a701d..9f39c49 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -34,8 +34,8 @@ modify code that handles one concern without affecting code that handles
 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
 
@@ -64,9 +64,8 @@ is becoming a popular design method for web applications.
 
 =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
 
@@ -104,9 +103,10 @@ example:
 
 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
 
@@ -144,7 +144,8 @@ framework, making it easy to test applications from the command line.
 =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
 
@@ -155,7 +156,14 @@ running, using the helper scripts described above.
 
 =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
 
@@ -183,465 +191,740 @@ Both of these URLs should take you to the welcome page.)
 
 =back
 
-Easy!
-
 =head2 How It Works
 
 Let's see how Catalyst works, by taking a closer look at the components
 and other parts of a Catalyst application.
 
-=head3 Application Class
+=head3 Components
 
-In addition to the Model, View, and Controller components, there's a
-single class that represents your application itself. This is where you
-configure your application, load plugins, and extend Catalyst.
+Catalyst has an uncommonly flexible component system. You can define as
+many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
+previously, the general idea is that the View is responsible for the
+output of data to the user (typically via a web browser, but a View can
+also generate PDFs or e-mails, for example); the Model is responsible 
+for providing data (typically from a relational database); and the
+Controller is responsible for interacting with the user and deciding
+how user input determines what actions the application takes.
+
+In the world of MVC, there are frequent discussions and disagreements
+about the nature of each element - whether certain types of logic
+belong in the Model or the Controller, etc. Catalyst's flexibility
+means that this decision is entirely up to you, the programmer; 
+Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
+a general discussion of these concerns.
 
-    package MyApp;
+All components must inherit from L<Catalyst::Base>, which provides a
+simple class structure and some common class methods like C<config> and
+C<new> (constructor).
+
+    package MyApp::Controller::Catalog;
 
     use strict;
-    use Catalyst qw/-Debug/;
+    use base 'Catalyst::Base';
 
-    MyApp->config(
-        name => 'My Application',
+    __PACKAGE__->config( foo => 'bar' );
 
-        # You can put anything else you want in here:
-        my_configuration_variable => 'something',
-    );
     1;
 
-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.
+You don't have to C<use> or otherwise register Models, Views, and
+Controllers.  Catalyst automatically discovers and instantiates them
+when you call C<setup> in the main application. All you need to do is
+put them in directories named for each Component type. You can use a
+short alias for each one.
 
 =over 4
 
-=item * B<name>
+=item * B<MyApp/Model/> 
 
-The name of your application.
+=item * B<MyApp/M/>
+
+=item * B<MyApp/View/>
+
+=item * B<MyApp/V/>
+
+=item * B<MyApp/Controller/>
+
+=item * B<MyApp/C/>
 
 =back
 
-Optionally, you can specify a B<root> parameter for templates and static
-data.  If omitted, Catalyst will try to auto-detect the directory's
-location. You can define as many parameters as you want for plugins or
-whatever you need. You can access them anywhere in your application via
-C<$context-E<gt>config-E<gt>{$param_name}>.
+In older versions of Catalyst, the recommended practice (and the one
+automatically created by helper scripts) was to name the directories
+C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
+the use of the full names.
 
-###### We need a short section on configuration here.
+=head4 Views
 
-=head3 Context
+To show how to define views, we'll use an already-existing base class for the
+L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
+inherit from this class:
 
-Catalyst automatically blesses a Context object into your application
-class and makes it available everywhere in your application. Use the
-Context to directly interact with Catalyst and glue your L</Components>
-together. For example, if you need to use the Context from within a
-Template Toolkit template, it's already there:
+    package MyApp::View::TT;
 
-    <h1>Welcome to [% c.config.name %]!</h1>
+    use strict;
+    use base 'Catalyst::View::TT';
 
-As illustrated in our URL-to-Action dispatching example, the Context is
-always the second method parameter, behind the Component object
-reference or class name itself. Previously we called it C<$context> for
-clarity, but most Catalyst developers just call it C<$c>:
+    1;
 
-    sub hello : Global {
-        my ( $self, $c ) = @_;
-        $c->res->body('Hello World!');
-    }
+(You can also generate this automatically by using the helper script:
 
-The Context contains several important objects:
+    script/myapp_create.pl view TT TT
 
-=over 4
+where the first C<TT> tells the script that the name of the view should
+be C<TT>, and the second that it should be a Template Toolkit view.)
 
-=item * L<Catalyst::Request>
+This gives us a process() method and we can now just do
+$c->forward('MyApp::View::TT') to render our templates. The base class
+makes process() implicit, so we don't have to say
+C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
 
-    $c->request
-    $c->req # alias
+    sub hello : Global {
+        my ( $self, $c ) = @_;
+        $c->stash->{template} = 'hello.tt';
+    }
 
-The request object contains all kinds of request-specific information, like
-query parameters, cookies, uploads, headers, and more.
+    sub end : Private {
+        my ( $self, $c ) = @_;
+        $c->forward( $c->view('TT') );
+    }
 
-    $c->req->params->{foo};
-    $c->req->cookies->{sessionid};
-    $c->req->headers->content_type;
-    $c->req->base;
+You normally render templates at the end of a request, so it's a perfect
+use for the global C<end> action.
 
-=item * L<Catalyst::Response>
+In practice, however, you would use a default C<end> action as supplied
+by L<Catalyst::Action::RenderView>.
 
-    $c->response
-    $c->res # alias
+Also, be sure to put the template under the directory specified in
+C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
+screen.
 
-The response is like the request, but contains just response-specific
-information.
+=head4 Models
 
-    $c->res->body('Hello World');
-    $c->res->status(404);
-    $c->res->redirect('http://oook.de');
+Models are providers of data. This data could come from anywhere - a
+search engine index, a spreadsheet - but typically a Model represents a
+database table. The data source does not intrinsically have much to do
+with web applications or Catalyst - it could just as easily be used to
+write an offline report generator or a command-line tool.
 
-=item * L<Catalyst::Config>
+To show how to define models, again we'll use an already-existing base
+class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
+We'll also need L<DBIx::Class::Schema::Loader>.
 
-    $c->config
-    $c->config->root;
-    $c->config->name;
+But first, we need a database.
 
-=item * L<Catalyst::Log>
+    -- myapp.sql
+    CREATE TABLE foo (
+        id INTEGER PRIMARY KEY,
+        data TEXT
+    );
 
-    $c->log
-    $c->log->debug('Something happened');
-    $c->log->info('Something you should know');
+    CREATE TABLE bar (
+        id INTEGER PRIMARY KEY,
+        foo INTEGER REFERENCES foo,
+        data TEXT
+    );
 
-=item * B<Stash>
+    INSERT INTO foo (data) VALUES ('TEST!');
 
-    $c->stash
-    $c->stash->{foo} = 'bar';
-    $c->stash->{baz} = {baz => 'qox'};
-    $c->stash->{fred} = [qw/ wilma pebbles/];
+    % sqlite /tmp/myapp.db < myapp.sql
 
-and so on.
+Now we can create a DBIC::SchemaLoader component for this database.
 
-=back
+    script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
 
-The last of these, the stash, is a universal hash for sharing data among
-application components. For an example, we return to our 'hello' action:
+L<DBIx::Class::Schema::Loader> automatically loads table layouts and
+relationships. Use the stash to pass data to your templates.
 
-    sub hello : Global {
-        my ( $self, $c ) = @_;
-        $c->stash->{message} = 'Hello World!';
-        $c->forward('show_message');
+We add the following to MyApp/Controller/Root.pm
+
+    sub view : Global {
+        my ( $self, $c, $id ) = @_;
+        
+        $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
     }
 
-    sub show_message : Private {
+    1;
+    
+    sub end : Private {
         my ( $self, $c ) = @_;
-        $c->res->body( $c->stash->{message} );
+        
+        $c->stash->{template} ||= 'index.tt';
+        $c->forward( $c->view('TT') );
     }
 
-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.
+We then create a new template file "root/index.tt" containing:
 
-=head3 Actions
+    The Id's data is [% item.data %]
 
-A Catalyst controller is defined by its actions. An action is a
-subroutine with a special attribute. You've already seen some examples
-of actions in this document. The URL (for example
-http://localhost.3000/foo/bar) consists of two parts, the base
-(http://localhost:3000/ in this example) and the path (foo/bar).  Please
-note that the trailing slash after the hostname[:port] always belongs to
-base and not to the action.
+Models do not have to be part of your Catalyst application; you
+can always call an outside module that serves as your Model:
 
-=over 4
+    # in a Controller
+    sub list : Local {
+      my ( $self, $c ) = @_;
+      
+      $c->stash->{template} = 'list.tt';
+      
+      use Some::Outside::Database::Module;
+      my @records = Some::Outside::Database::Module->search({
+        artist => 'Led Zeppelin',
+        });
+      
+      $c->stash->{records} = \@records;
+    }
 
-=item * B<Application Wide Actions>
+But by using a Model that is part of your Catalyst application, you gain
+several things: you don't have to C<use> each component, Catalyst will
+find and load it automatically at compile-time; you can C<forward> to
+the module, which can only be done to Catalyst components; and only
+Catalyst components can be fetched with
+C<$c-E<gt>model('SomeModel')>.
 
-Actions which are called at the root level of the application
-(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
-this:
+Happily, since many people have existing Model classes that they
+would like to use with Catalyst (or, conversely, they want to
+write Catalyst models that can be used outside of Catalyst, e.g.
+in a cron job), it's trivial to write a simple component in
+Catalyst that slurps in an outside Model:
 
-    package MyApp::Controller::Root;
-    use base 'Catalyst::Controller';
-    # 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 {
-        my ( $self, $context ) = @_;
-        $context->response->body('Catalyst rocks!');
-    }
+    package MyApp::Model::DB;
+    use base qw/Catalyst::Model::DBIC::Schema/;
+    __PACKAGE__->config(
+        schema_class => 'Some::DBIC::Schema',
+        connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
+    );
     1;
 
-=back
+and that's it! Now C<Some::DBIC::Schema> is part of your
+Cat app as C<MyApp::Model::DB>.
 
-=head4 Action types
+Within Catalyst, the common approach to writing a 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. Thus you
+will in effect have two models - a wrapper model that knows something
+about Catalyst and your web application, and a generic model that is
+totally independent of these needs.
 
-Catalyst supports several types of actions:
+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> 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:
 
 =over 4
 
-=item * B<Literal> (B<Path> actions)
+=item *
 
-    package MyApp::Controller::My::Controller;
-    sub bar : Path('foo/bar') { }
+Interacting with another model
 
-Literal C<Path> actions will act relative to their current
-namespace. The above example matches only
-http://localhost:3000/my/controller/foo/bar. If you start your path with
-a forward slash, it will match from the root. Example:
+=item *
 
-    package MyApp::Controller::My::Controller;
-    sub bar : Path('/foo/bar') { }
+Using per-request data to control behavior
 
-Matches only http://localhost:3000/foo/bar.
+=item *
 
-    package MyApp::Controller::My::Controller;
-    sub bar : Path { }
+Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
 
-By leaving the C<Path> definition empty, it will match on the namespace
-root. The above code matches http://localhost:3000/my/controller.
+=back
 
-=item * B<Regex>
+From a style perspective it's usually considered bad form to make your
+model "too smart" about things - it should worry about business logic
+and leave the integration details to the controllers. If, however, you
+find that it does not make sense at all to use an auxillary controller
+around the model, and the model's need to access C<$c> cannot be
+sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
 
-    sub bar : Regex('^item(\d+)/order(\d+)$') { }
+=head4 Controllers
 
-Matches any URL that matches the pattern in the action key, e.g.
-http://localhost:3000/item23/order42. The '' around the regexp is
-optional, but perltidy likes it. :)
+Multiple controllers are a good way to separate logical domains of your
+application.
 
-Regex matches act globally, i.e. without reference to the namespace from
-which it is called, so that a C<bar> method in the
-C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
-form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
-explicitly put this in the regex. To achieve the above, you should
-consider using a C<LocalRegex> action.
-
-=item * B<LocalRegex>
-
-    sub bar : LocalRegex('^widget(\d+)$') { }
+    package MyApp::Controller::Login;
 
-LocalRegex actions act locally. If you were to use C<bar> in
-C<MyApp::Controller::Catalog>, the above example would match urls like
-http://localhost:3000/catalog/widget23.
+    use base qw/Catalyst::Controller/;
 
-If you omit the "C<^>" from your regex, then it will match any depth
-from the controller and not immediately off of the controller name. The
-following example differs from the above code in that it will match
-http://localhost:3000/catalog/foo/widget23 as well.
+    sub login : Path("login") { }
+    sub new_password : Path("new-password") { }
+    sub logout : Path("logout") { }
 
     package MyApp::Controller::Catalog;
-    sub bar : LocalRegex('widget(\d+)$') { }
-
-For both LocalRegex and Regex actions, if you use capturing parentheses
-to extract values within the matching URL, those values are available in
-the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
-would capture "23" in the above example, and
-C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
-arguments at the end of your URL, you must use regex action keys. See
-L</URL Path Handling> below.
-
-=item * B<Chained>
 
-    sub section :PathPart('section') :Chained('/') :Captures(1) { }
+    use base qw/Catalyst::Controller/;
 
-Chained is a powerful way to handle canonical URIs of the form
-C<http://localhost:3000/section/1/item/2>. Using this URI as an example,
-in Controller::Root you can do the following:
+    sub view : Local { }
+    sub list : Local { }
 
-  sub section_handler :PathPart('section') :Chained('/') :Captures(1) {
-      my ( $self, $c ) = @_;
-      $c->stash->{'section'} =
-        $c->Model('Sections')->find($c->req->captures->[0]);
-  }
+    package MyApp::Controller::Cart;
 
-  sub item_handler :PathPart('item') :Chained('/section_handler') :Args(1) {
-      my ( $self, $c ) = @_;
-      $c->stash->{'item'} =
-        $c->stash->{'section'}->find_related('item',$c->args->[0]);
-  }
+    use base qw/Catalyst::Controller/;
 
-The subroutine C<section_handler> matches the path segment "section" as
-a child of "/". It then takes the next path segment, as referenced by
-C<:Captures(1)>, and stashes it in the arrayref
-C<$c-E<gt>req-E<gt>captures>. Since there is also a child of this
-handler, it also gets run, functioning in the same way. However, the
-C<item_handler> subroutine has the C<Args> attribute which means this
-particular routine will only run if there is exactly one argument. See
-L</Args> below for more options.
+    sub add : Local { }
+    sub update : Local { }
+    sub order : Local { }
 
-A parent action can be in any controller or namespace.  
+Note that you can also supply attributes via the Controller's config so
+long as you have at least one attribute on a subref to be exported
+(:Action is commonly used for this) - for example the following is
+equivalent to the same controller above:
 
-Multiple actions can specify the same parent action in their C<Chained>;
-that is, one action can have multiple children.
+    package MyApp::Controller::Login;
 
-=item Chained('xyz')
+    use base qw/Catalyst::Controller/;
 
-The action of the parent. For instance, if you have a method
-C<item_handler> in the controller C<SuperMarket::Aisle>, the action
-would be C</supermarket/aisle/item_handler>. For a Root handler this
-would be '/'. For an action in the same controller namespace you can use
-a relative name like C<:Chained('foo')>.
+    __PACKAGE__->config(
+      actions => {
+        'sign_in' => { Path => 'sign-in' },
+        'new_password' => { Path => 'new-password' },
+        'sign_out' => { Path => 'sign-out' },
+      },
+    );
 
-=item PathPart('xyz')
+    sub sign_in : Action { }
+    sub new_password : Action { }
+    sub sign_out : Action { }
 
-The name of this path section in the Chained tree mapping to the URI. If
-you specify C<:PathPart> without arguments, it takes the name of the
-action specifying the argument.  For example, these two declarations
-have the same effect:
+=head3 ACCEPT_CONTEXT
 
-  sub foo :PathPart('foo') :Chained('bar') :Args(1) {
-      ...
-  }
+Whenever you call $c->component("Foo") you get back an object - the
+instance of the model. If the component supports the C<ACCEPT_CONTEXT>
+method instead of returning the model itself, the return value of C<<
+$model->ACCEPT_CONTEXT( $c ) >> will be used.
 
-and
+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.
 
-  sub foo :PathPart :Chained('bar') :Args(1) {
-      ...
-  }
+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.
 
-The value can also contain a slash, for example:
+A typical C<ACCEPT_CONTEXT> method could look like this:
 
-  sub baz :PathPart('bar/baz') :Chained('/') :Captures(1) {
-      ...
-  }
+    sub ACCEPT_CONTEXT {
+      my ( $self, $c, @extra_arguments ) = @_;
+      bless { %$self, c => $c }, ref($self);
+    }
 
-would be involved in matches on C</bar/baz/*/...> paths.
+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).
 
-=item Captures(integer)
+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:
 
-Will 'collapse' the next C<integer> path segments in the request URI and
-push them into the arrayref C<$c-E<gt>req-E<gt>captures>. An action
-specifying C<Captures> is thought to be used as target for C<Chained>
-specifications. Also see the C<Args> attribute below, which is used for
-endpoints.
+Add a field to C<$c>, like C<my_model_instance>. Then write your
+C<ACCEPT_CONTEXT> method to look like this:
 
-=item Args(int)
+    sub ACCEPT_CONTEXT {
+      my ( $self, $c ) = @_;
 
-The number of path segments to capture at the end of a request URI. This
-B<must> be included in your leaf nodes. You can use C<Args(0)> for an
-equivalent of the index action.  Args with no parameters will capture
-every postfixed segment into C<$c-E<gt>req-E<gt>args>.
+      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;
+      }
+    }
 
-A specification of C<Args> is seen as endpoint in regard to an additional
-C<Chained> specification.
+=head3 Application Class
 
-=item * B<Top-level> (B<Global>)
+In addition to the Model, View, and Controller components, there's a
+single class that represents your application itself. This is where you
+configure your application, load plugins, and extend Catalyst.
 
-    package MyApp::Controller::Foo;
-    sub foo : Global { }
+    package MyApp;
 
-Matches http://localhost:3000/foo. The function name is mapped
-directly to the application base.  You can provide an equivalent
-function in this case  by doing the following:
+    use strict;
+    use Catalyst qw/-Debug/; # Add other plugins here, e.g.
+                             # for session support
 
-    package MyApp::Controller::Root
-    sub foo : Local { }
+    MyApp->config(
+        name => 'My Application',
 
-=item * B<Namespace-Prefixed> (B<Local>)
+        # You can put anything else you want in here:
+        my_configuration_variable => 'something',
+    );
+    1;
 
-    package MyApp::Controller::My::Controller; 
-    sub foo : Local { }
+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 L</Actions>,
+below), to avoid namespace collisions.
 
-Matches http://localhost:3000/my/controller/foo. 
+=over 4
 
-This action type indicates that the matching URL must be prefixed with a
-modified form of the component's class (package) name. This modified
-class name excludes the parts that have a pre-defined meaning in
-Catalyst ("MyApp::Controller" in the above example), replaces "::" with
-"/", and converts the name to lower case.  See L</Components> for a full
-explanation of the pre-defined meaning of Catalyst component class
-names.
+=item * B<name>
 
-=item * B<Private>
+The name of your application.
 
-    sub foo : Private { }
+=back
 
-Matches no URL, and cannot be executed by requesting a URL that
-corresponds to the action key. Private actions can be executed only
-inside a Catalyst application, by calling the C<forward> method:
+Optionally, you can specify a B<root> parameter for templates and static
+data.  If omitted, Catalyst will try to auto-detect the directory's
+location. You can define as many parameters as you want for plugins or
+whatever you need. You can access them anywhere in your application via
+C<$context-E<gt>config-E<gt>{$param_name}>.
 
-    $c->forward('foo');
+=head3 Context
 
-See L</Flow Control> for a full explanation of C<forward>. Note that, as
-discussed there, when forwarding from another component, you must use
-the absolute path to the method, so that a private C<bar> method in your
-C<MyApp::Controller::Catalog::Order::Process> controller must, if called
-from elsewhere, be reached with
-C<$c-E<gt>forward('/catalog/order/process/bar')>.
+Catalyst automatically blesses a Context object into your application
+class and makes it available everywhere in your application. Use the
+Context to directly interact with Catalyst and glue your L</Components>
+together. For example, if you need to use the Context from within a
+Template Toolkit template, it's already there:
 
-=item * B<Args>
+    <h1>Welcome to [% c.config.name %]!</h1>
 
-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,
+As illustrated in our URL-to-Action dispatching example, the Context is
+always the second method parameter, behind the Component object
+reference or class name itself. Previously we called it C<$context> for
+clarity, but most Catalyst developers just call it C<$c>:
 
-  sub bar :Local
+    sub hello : Global {
+        my ( $self, $c ) = @_;
+        $c->res->body('Hello World!');
+    }
 
-would match any URL starting /foo/bar/. To restrict this you can do
+The Context contains several important objects:
 
-  sub bar :Local :Args(1)
+=over 4
 
-to only match /foo/bar/*/
+=item * L<Catalyst::Request>
 
-=back
+    $c->request
+    $c->req # alias
 
-B<Note:> After seeing these examples, you probably wonder what the point
-is of defining names for regex and path actions. Every public action is
-also a private one, so you have one unified way of addressing components
-in your C<forward>s.
+The request object contains all kinds of request-specific information, like
+query parameters, cookies, uploads, headers, and more.
 
-=head4 Built-in Private Actions
+    $c->req->params->{foo};
+    $c->req->cookies->{sessionid};
+    $c->req->headers->content_type;
+    $c->req->base;
+    $c->req->uri_with( { page = $pager->next_page } );
 
-In response to specific application states, Catalyst will automatically
-call these built-in private actions in your application class:
+=item * L<Catalyst::Response>
 
-=over 4
+    $c->response
+    $c->res # alias
 
-=item * B<default : Private>
+The response is like the request, but contains just response-specific
+information.
 
-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.
+    $c->res->body('Hello World');
+    $c->res->status(404);
+    $c->res->redirect('http://oook.de');
 
-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.
+=item * L<Catalyst::Config>
 
-=item * B<index : Private>
+    $c->config
+    $c->config->root;
+    $c->config->name;
 
-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.
+=item * L<Catalyst::Log>
 
-=item * B<begin : Private>
+    $c->log
+    $c->log->debug('Something happened');
+    $c->log->info('Something you should know');
 
-Called at the beginning of a request, before any matching actions are
-called.
+=item * B<Stash>
 
-=item * B<end : Private>
+    $c->stash
+    $c->stash->{foo} = 'bar';
+    $c->stash->{baz} = {baz => 'qox'};
+    $c->stash->{fred} = [qw/wilma pebbles/];
 
-Called at the end of a request, after all matching actions are called.
+and so on.
 
 =back
 
-=head4 Built-in actions in controllers/autochaining
+The last of these, the stash, is a universal hash for sharing data among
+application components. For an example, we return to our 'hello' action:
 
-    Package MyApp::Controller::Foo;
-    sub begin : Private { }
-    sub default : Private { }
-    sub auto : Private { }
+    sub hello : Global {
+        my ( $self, $c ) = @_;
+        $c->stash->{message} = 'Hello World!';
+        $c->forward('show_message');
+    }
 
-You can define built-in private actions within your controllers as
-well. The actions will override the ones in less-specific controllers,
-or your application class. In other words, for each of the three
-built-in private actions, only one will be run in any request
-cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
-run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
-and C<MyApp::Controller::Catalog::Order::begin> would override this in
-turn.
+    sub show_message : Private {
+        my ( $self, $c ) = @_;
+        $c->res->body( $c->stash->{message} );
+    }
 
-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
-built-ins, C<auto> actions I<do not> override each other; they will be
-called in turn, starting with the application class and going through to
-the I<most> specific class. I<This is the reverse of the order in which
-the normal built-ins override each other>.
+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 persistent data, use a session. See
+L<Catalyst::Plugin::Session> for a comprehensive set of
+Catalyst-friendly session-handling tools.
 
-Here are some examples of the order in which the various built-ins
-would be called:
+=head3 Actions
 
-=over 4
+A Catalyst controller is defined by its actions. An action is a
+subroutine with a special attribute. You've already seen some examples
+of actions in this document. The URL (for example
+http://localhost.3000/foo/bar) consists of two parts, the base
+(http://localhost:3000/ in this example) and the path (foo/bar).  Please
+note that the trailing slash after the hostname[:port] always belongs to
+base and not to the action.
 
-=item for a request for C</foo/foo>
+=over 4
 
-  MyApp::begin
-  MyApp::auto
-  MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
-  MyApp::end
+=item * B<Application Wide Actions>
 
-=item for a request for C</foo/bar/foo>
+Actions which are called at the root level of the application
+(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
+this:
+
+    package MyApp::Controller::Root;
+    use base 'Catalyst::Controller';
+    # 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 {
+        my ( $self, $context ) = @_;
+        $context->response->body('Catalyst rocks!');
+    }
+    1;
+
+=back
+
+=head4 Action types
+
+Catalyst supports several types of actions:
+
+=over 4
+
+=item * B<Literal> (B<Path> actions)
+
+    package MyApp::Controller::My::Controller;
+    sub bar : Path('foo/bar') { }
+
+Literal C<Path> actions will act relative to their current
+namespace. The above example matches only
+http://localhost:3000/my/controller/foo/bar. If you start your path with
+a forward slash, it will match from the root. Example:
+
+    package MyApp::Controller::My::Controller;
+    sub bar : Path('/foo/bar') { }
+
+Matches only http://localhost:3000/foo/bar.
+
+    package MyApp::Controller::My::Controller;
+    sub bar : Path { }
+
+By leaving the C<Path> definition empty, it will match on the namespace
+root. The above code matches http://localhost:3000/my/controller.
+
+=item * B<Regex>
+
+    sub bar : Regex('^item(\d+)/order(\d+)$') { }
+
+Matches any URL that matches the pattern in the action key, e.g.
+http://localhost:3000/item23/order42. The '' around the regexp is
+optional, but perltidy likes it. :)
+
+Regex matches act globally, i.e. without reference to the namespace from
+which it is called, so that a C<bar> method in the
+C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
+form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
+explicitly put this in the regex. To achieve the above, you should
+consider using a C<LocalRegex> action.
+
+=item * B<LocalRegex>
+
+    sub bar : LocalRegex('^widget(\d+)$') { }
+
+LocalRegex actions act locally. If you were to use C<bar> in
+C<MyApp::Controller::Catalog>, the above example would match urls like
+http://localhost:3000/catalog/widget23.
+
+If you omit the "C<^>" from your regex, then it will match any depth
+from the controller and not immediately off of the controller name. The
+following example differs from the above code in that it will match
+http://localhost:3000/catalog/foo/widget23 as well.
+
+    package MyApp::Controller::Catalog;
+    sub bar : LocalRegex('widget(\d+)$') { }
+
+For both LocalRegex and Regex actions, if you use capturing parentheses
+to extract values within the matching URL, those values are available in
+the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
+would capture "23" in the above example, and
+C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
+arguments at the end of your URL, you must use regex action keys. See
+L</URL Path Handling> below.
+
+=item * B<Top-level> (B<Global>)
+
+    package MyApp::Controller::Foo;
+    sub foo : Global { }
+
+Matches http://localhost:3000/foo. The function name is mapped
+directly to the application base.  You can provide an equivalent
+function in this case  by doing the following:
+
+    package MyApp::Controller::Root
+    sub foo : Local { }
+
+=item * B<Namespace-Prefixed> (B<Local>)
+
+    package MyApp::Controller::My::Controller; 
+    sub foo : Local { }
+
+Matches http://localhost:3000/my/controller/foo. 
+
+This action type indicates that the matching URL must be prefixed with a
+modified form of the component's class (package) name. This modified
+class name excludes the parts that have a pre-defined meaning in
+Catalyst ("MyApp::Controller" in the above example), replaces "::" with
+"/", and converts the name to lower case.  See L</Components> for a full
+explanation of the pre-defined meaning of Catalyst component class
+names.
+
+=item * B<Chained>
+
+Catalyst also provides a method to build and dispatch chains of actions,
+like
+
+    sub catalog : Chained : CaptureArgs(1) {
+        my ( $self, $c, $arg ) = @_;
+        ...
+    }
+
+    sub item : Chained('catalog') : Args(1) {
+        my ( $self, $c, $arg ) = @_;
+        ...
+    }
+
+to handle a C</catalog/*/item/*> path. For extensive information about this
+dispatch type, please see L<Catalyst::DispatchType::Chained>.
+
+=item * B<Private>
+
+    sub foo : Private { }
+
+Matches no URL, and cannot be executed by requesting a URL that
+corresponds to the action key. Private actions can be executed only
+inside a Catalyst application, by calling the C<forward> method:
+
+    $c->forward('foo');
+
+See L</Flow Control> for a full explanation of C<forward>. Note that, as
+discussed there, when forwarding from another component, you must use
+the absolute path to the method, so that a private C<bar> method in your
+C<MyApp::Controller::Catalog::Order::Process> controller must, if called
+from elsewhere, be reached with
+C<$c-E<gt>forward('/catalog/order/process/bar')>.
+
+=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
+MyApp::Controller::Foo,
+
+  sub bar :Local
+
+would match any URL starting /foo/bar/. To restrict this you can do
+
+  sub bar :Local :Args(1)
+
+to only match /foo/bar/*/
+
+=back
+
+B<Note:> After seeing these examples, you probably wonder what the point
+is of defining names for regex and path actions. Every public action is
+also a private one, so you have one unified way of addressing components
+in your C<forward>s.
+
+=head4 Built-in Private Actions
+
+In response to specific application states, Catalyst will automatically
+call these built-in private actions in your application class:
+
+=over 4
+
+=item * B<default : Private>
+
+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.
+
+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>
+
+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.
+
+=item * B<begin : Private>
+
+Called at the beginning of a request, before any matching actions are
+called.
+
+=item * B<end : Private>
+
+Called at the end of a request, after all matching actions are called.
+
+=back
+
+=head4 Built-in actions in controllers/autochaining
+
+    Package MyApp::Controller::Foo;
+    sub begin : Private { }
+    sub default : Private { }
+    sub auto : Private { }
+
+You can define built-in private actions within your controllers as
+well. The actions will override the ones in less-specific controllers,
+or your application class. In other words, for each of the three
+built-in private actions, only one will be run in any request
+cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
+run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
+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
+built-ins, C<auto> actions I<do not> override each other; they will be
+called in turn, starting with the application class and going through to
+the I<most> specific class. I<This is the reverse of the order in which
+the normal built-ins override each other>.
+
+Here are some examples of the order in which the various built-ins
+would be called:
+
+=over 4
+
+=item for a request for C</foo/foo>
+
+  MyApp::begin
+  MyApp::auto
+  MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
+  MyApp::end
+
+=item for a request for C</foo/bar/foo>
 
   MyApp::Controller::Foo::Bar::begin
   MyApp::auto
@@ -676,7 +959,7 @@ authentication fails, returning 0 would skip any remaining methods
 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.
 
@@ -817,338 +1100,12 @@ the C<detach>ed action and not return to the calling sub. In both cases,
 Catalyst will automatically try to call process() if you omit the
 method.
 
-=head3 Components
-
-Catalyst has an uncommonly flexible component system. You can define as
-many L</Models>, L</Views>, and L</Controllers> as you like.
-
-All components must inherit from L<Catalyst::Base>, which provides a
-simple class structure and some common class methods like C<config> and
-C<new> (constructor).
-
-    package MyApp::Controller::Catalog;
-
-    use strict;
-    use base 'Catalyst::Base';
-
-    __PACKAGE__->config( foo => 'bar' );
-
-    1;
-
-You don't have to C<use> or otherwise register Models, Views, and
-Controllers.  Catalyst automatically discovers and instantiates them
-when you call C<setup> in the main application. All you need to do is
-put them in directories named for each Component type. Notice that you
-can use a terse alias for each one.
-
-=over 4
-
-=item * B<MyApp/Model/> 
-
-=item * B<MyApp/M/>
-
-=item * B<MyApp/View/>
-
-=item * B<MyApp/V/>
-
-=item * B<MyApp/Controller/>
-
-=item * B<MyApp/C/>
-
-=back
-
-In older versions of Catalyst, the recommended practice (and the one
-automatically created by helper scripts) was to name the directories
-C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
-the use of the full names.
-
-=head4 Views
-
-To show how to define views, we'll use an already-existing base class for the
-L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
-inherit from this class:
-
-    package MyApp::View::TT;
-
-    use strict;
-    use base 'Catalyst::View::TT';
-
-    1;
-
-(You can also generate this automatically by using the helper script:
-
-    script/myapp_create.pl view TT TT
-
-where the first C<TT> tells the script that the name of the view should
-be C<TT>, and the second that it should be a Template Toolkit view.)
-
-This gives us a process() method and we can now just do
-$c->forward('MyApp::View::TT') to render our templates. The base class
-makes process() implicit, so we don't have to say
-C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
-
-    sub hello : Global {
-        my ( $self, $c ) = @_;
-        $c->stash->{template} = 'hello.tt';
-    }
-
-    sub end : Private {
-        my ( $self, $c ) = @_;
-        $c->forward('MyApp::View::TT');
-    }
-
-You normally render templates at the end of a request, so it's a perfect
-use for the global C<end> action.
-
-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. ;)
-
-=head4 Models
-
-To show how to define models, again we'll use an already-existing base
-class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
-We'll also need L<DBIx::Class::Schema::Loader>.
-
-But first, we need a database.
-
-    -- myapp.sql
-    CREATE TABLE foo (
-        id INTEGER PRIMARY KEY,
-        data TEXT
-    );
-
-    CREATE TABLE bar (
-        id INTEGER PRIMARY KEY,
-        foo INTEGER REFERENCES foo,
-        data TEXT
-    );
-
-    INSERT INTO foo (data) VALUES ('TEST!');
-
-
-    % sqlite /tmp/myapp.db < myapp.sql
-
-Now we can create a DBIC::SchemaLoader component for this database.
-
-    script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
-
-L<DBIx::Class::Schema::Loader> automatically loads table layouts and
-relationships. Use the stash to pass data to your templates.
-
-We add the following to MyApp/Controller/Root.pm
-
-    sub view : Global {
-        my ( $self, $c, $id ) = @_;
-        
-        $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
-    }
-
-    1;
-    
-    sub end : Private {
-        my ( $self, $c ) = @_;
-        
-        $c->stash->{template} ||= 'index.tt';
-        $c->forward( $c->view('TT') );
-    }
-
-We then create a new template file "root/index.tt" containing:
-
-    The Id's data is [% item.data %]
-
-Models do not have to be part of your Catalyst application; you
-can always call an outside module that serves as your Model:
-
-    # in a Controller
-    sub list : Local {
-      my ( $self, $c ) = @_;
-      
-      $c->stash->{template} = 'list.tt';
-      
-      use Some::Outside::DBIC::Module;
-      my @records = Some::Outside::DBIC::Module->search({
-        artist => 'sri',
-        });
-      
-      $c->stash->{records} = \@records;
-    }
-
-But by using a Model that is part of your Catalyst application, you gain
-several things: you don't have to C<use> each component, Catalyst will
-find and load it automatically at compile-time; you can C<forward> to
-the module, which can only be done to Catalyst components; and only
-Catalyst components can be fetched with
-C<$c-E<gt>model('SomeModel')>.
-
-Happily, since many people have existing Model classes that they
-would like to use with Catalyst (or, conversely, they want to
-write Catalyst models that can be used outside of Catalyst, e.g.
-in a cron job), it's trivial to write a simple component in
-Catalyst that slurps in an outside Model:
-
-    package MyApp::Model::DB;
-    use base qw/Catalyst::Model::DBIC::Schema/;
-    __PACKAGE__->config(
-        schema_class => 'Some::DBIC::Schema',
-        connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
-    );
-    1;
-
-and that's it! Now C<Some::DBIC::Schema> is part of your
-Cat app as C<MyApp::Model::DB>.
-
-=head4 Controllers
-
-Multiple controllers are a good way to separate logical domains of your
-application.
-
-    package MyApp::Controller::Login;
-
-    use base qw/Catalyst::Controller/;
-
-    sub sign_in : Path("sign-in") { }
-    sub new_password : Path("new-password") { }
-    sub sign_out : Path("sign-out") { }
-
-    package MyApp::Controller::Catalog;
-
-    use base qw/Catalyst::Controller/;
-
-    sub view : Local { }
-    sub list : Local { }
-
-    package MyApp::Controller::Cart;
-
-    use base qw/Catalyst::Controller/;
-
-    sub add : Local { }
-    sub update : Local { }
-    sub order : Local { }
-
-Note that you can also supply attributes via the Controller's config so long
-as you have at least one attribute on a subref to be exported (:Action is
-commonly used for this) - for example the following is equivalent to the same
-controller above
-
-    package MyApp::Controller::Login;
-
-    use base qw/Catalyst::Controller/;
-
-    __PACKAGE__->config(
-      actions => {
-        'sign_in' => { Path => 'sign-in' },
-        'new_password' => { Path => 'new-password' },
-        'sign_out' => { Path => 'sign-out' },
-      },
-    );
-
-    sub sign_in : Action { }
-    sub new_password : Action { }
-    sub sign_out : Action { }
-
-=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.
-
-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.
-
-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:
-
-=over 4
-
-=item *
-
-Interacting with another model
-
-=item *
-
-Using per-request data to control behavior
-
-=item *
-
-Using plugins in (for example L<Catalyst::Plugin::Cache>).
-
-=back
-
-From a style perspective usually it's bad to make your model "too smart"
-about things - it should worry about business logic and leave the
-integration details to the controllers. If, however, you find that it
-does not make sense at all to use an auxillary controller around the
-model, and the model's need to access C<$c> cannot be sidestepped, there
-exists a power tool called C<ACCEPT_CONTEXT>.
-
-#### editor note: this part is "generic" - it also applies to views and
-#### controllers.
-
-=head3 ACCEPT_CONTEXT
-
-Whenever you call $c->component("Foo") you get back an object - the
-instance of the model. If the component supports the C<ACCEPT_CONTEXT>
-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.
-
-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:
-
-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;
-		}
-	}
-
 
 =head3 Testing
 
-Catalyst has a built-in http server for testing. (Later, you can easily
-use a more powerful server, e.g. Apache/mod_perl or FastCGI, in a
-production environment.)
+Catalyst has a built-in http server for testing or local
+deployment. (Later, you can easily use a more powerful server, for
+example Apache/mod_perl or FastCGI, in a production environment.)
 
 Start your application on the command line...
 
@@ -1160,15 +1117,32 @@ You can also do it all from the command line:
 
     script/myapp_test.pl http://localhost/
 
+Catalyst has a number of tools for actual regression testing of
+applications. The helper scripts will automatically generate basic tests
+that can be extended as you develop your project. To write your own
+comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
+invaluable tool.
+
+For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
+
 Have fun!
 
+=head1 SEE ALSO
+
+=item * L<Catalyst::Manual::About>
+
+=item * L<Catalyst::Manual::Tutorial>
+
+=item * L<Catalyst>
+
 =head1 SUPPORT
 
 IRC:
 
     Join #catalyst on irc.perl.org.
+    Join #catalyst-dev on irc.perl.org to help with development.
 
-Mailing-lists:
+Mailing lists:
 
     http://lists.rawmode.org/mailman/listinfo/catalyst
     http://lists.rawmode.org/mailman/listinfo/catalyst-dev
@@ -1185,5 +1159,5 @@ Yuval Kogman, C<nothingmuch@woobling.org>
 
 =head1 COPYRIGHT
 
-This program is free software, you can redistribute it and/or modify it
+This program is free software. You can redistribute it and/or modify it
 under the same terms as Perl itself.