X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=a75c5ca879cbfbbd0fe5e589fcbadd46747a7343;hb=c37916b01100919966ccae588dcb00ec415d28f9;hp=a6da2a1646525446eb1654876d72d73b46ef182f;hpb=56d8daebfb3b83c215625ae0fd3fddce455851c6;p=catagits%2FCatalyst-Runtime.git

diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod
index a6da2a1..a75c5ca 100644
--- a/lib/Catalyst/Manual/Intro.pod
+++ b/lib/Catalyst/Manual/Intro.pod
@@ -80,7 +80,7 @@ multiple Catalyst applications.
 
 =item * B<Unrestrained URL-to-Action Dispatching>
 
-Catalyst allows you to dispatch any URLs to any application L<Actions>,
+Catalyst allows you to dispatch any URLs to any application L</Actions>,
 even through regular expressions! Unlike most other frameworks, it
 doesn't require mod_rewrite or class and method names in URLs.
 
@@ -110,7 +110,7 @@ simple way.
 =item * B<Building Block Interface>
 
 Components interoperate very smoothly. For example, Catalyst
-automatically makes a L<context> object available to every
+automatically makes a L</Context> object available to every
 component. Via the context, you can access the request object, share
 data between components, and control the flow of your
 application. Building a Catalyst application feels a lot like snapping
@@ -161,6 +161,10 @@ running, using the helper scripts described above.
 Now visit these locations with your favorite browser or user agent to see
 Catalyst in action:
 
+(NOTE: Although we create a controller here, we don't actually use it.
+Both of these URLs should take you to the welcome page.)
+
+
 =over 4
 
 =item http://localhost:3000/
@@ -180,8 +184,7 @@ and other parts of a Catalyst application.
 
 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, define application-wide
-actions, and extend Catalyst.
+configure your application, load plugins, and extend Catalyst.
 
     package MyApp;
 
@@ -194,17 +197,8 @@ actions, and extend Catalyst.
         # You can put anything else you want in here:
         my_configuration_variable => 'something',
     );
-
-    sub default : Private {
-        my ( $self, $context ) = @_;
-        $context->response->body('Catalyst rocks!');
-    }
-
     1;
 
-For most applications, Catalyst requires you to define only one config
-parameter:
-
 =over 4
 
 =item * B<name>
@@ -223,7 +217,7 @@ C<$context-E<gt>config-E<gt>{$param_name}>.
 
 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>
+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:
 
@@ -307,6 +301,8 @@ to maintain more persistent data, use a session.
 
 =head3 Actions
 
+
+
 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
@@ -315,6 +311,33 @@ http://localhost.3000/foo/bar) consists of two parts, the base
 note that the trailing slash after the hostname[:port] always belongs to
 base and not to the action.
 
+=over 4
+
+=item * B<Application Wide Actions>
+
+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
+
+For most applications, Catalyst requires you to define only one config
+parameter:
+
+=head4 Action types
+
 Catalyst supports several types of actions:
 
 =over 4
@@ -373,19 +396,23 @@ http://localhost:3000/catalog/foo/widget23 as well.
 
 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>snippets> array. In the above example, "widget23"
+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>snippets-E<gt>[0]> would be "23". If you want to pass
+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; 
+    package MyApp::Controller::Foo;
     sub foo : Global { }
 
-Matches http://localhost:3000/foo. The function name is mapped directly
-to the application base.
+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>)
 
@@ -419,6 +446,21 @@ 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
@@ -440,7 +482,7 @@ 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
+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.
@@ -633,7 +675,7 @@ be reset.
 
     sub check_message : Private {
         my ( $self, $c ) = @_;
-        my $first_argument = $c->req->args[0]; # now = 'test1'
+        my $first_argument = $c->req->args->[0]; # now = 'test1'
         # do something...
     }
 
@@ -679,7 +721,7 @@ 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.
+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
@@ -845,7 +887,7 @@ Catalyst that slurps in an outside Model:
     use base qw/Catalyst::Model::DBIC::Schema/;
     __PACKAGE__->config(
         schema_class => 'Some::DBIC::Schema',
-        connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}];
+        connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
     );
     1;
 
@@ -859,21 +901,48 @@ application.
 
     package MyApp::Controller::Login;
 
-    sub sign-in : Local { }
-    sub new-password : Local { }
-    sub sign-out : Local { }
+    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 Testing
 
 Catalyst has a built-in http server for testing! (Later, you can easily
@@ -910,6 +979,7 @@ David Naughton, C<naughton@umn.edu>
 Marcus Ramberg, C<mramberg@cpan.org>
 Jesse Sheidlower, C<jester@panix.com>
 Danijel Milicevic, C<me@danijel.de>
+Kieren Diment, C<kd@totaldatasolution.com>
 
 =head1 COPYRIGHT