From: Jesse Sheidlower Date: Sun, 26 Jun 2005 23:57:24 +0000 (+0000) Subject: more on built-in actions in Intro.pod X-Git-Tag: 5.7099_04~1282 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=fc9c8698111d321eb33af14931779886eed5497f more on built-in actions in Intro.pod --- diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index 06ea0c1..50ffca5 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -376,10 +376,11 @@ application, by calling the C method: $c->forward('foo'); See L for a full explanation of C. Note that, as -discussed there, when forwarding from another component, you must use the -absolute path to the method, so that a private C method in your -C controller must, if called from -elsewhere, be reach with C<$c-Eforward('/catalog/order/process/bar')>. +discussed there, when forwarding from another component, you must use +the absolute path to the method, so that a private C method in your +C controller must, if called +from elsewhere, be reached with +C<$c-Eforward('/catalog/order/process/bar')>. =back @@ -390,66 +391,83 @@ components in your Cs. =head4 Built-in Private Actions -In response to specific application states, Catalyst will automatically call -these 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 -Called when no other action matches. +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. =item * B -Called at the beginning of a request, before any matching actions are called. +Called at the beginning of a request, before any matching actions are +called. =item * B -=back - Called at the end of a request, after all matching actions are called. +=back + =head4 B Package MyApp::C::Foo; sub begin : Private { } sub default : Private { } -You can define the Built-in Private Actions within your controllers as -well. The actions will override the ones in lower level controllers or -your global application. - -In addition to the normal built-ins, you have a special action for -making inheritance chains, 'auto'. These will be run after C, -but before your action is processed. +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 exists, it will be run in +place of C if you're in the C namespace, and +C would override this in turn. + +In addition to the normal built-ins, you have a special action for +making chains, C. Such C actions will be run after any +C, but before your action is processed. Unlike the other +built-ins, C actions I override each other; they will +be called in turn, starting with the application class and going +through to the I specific class. I. + +Here are some examples of the order in which the various built-ins +would be called: =over 4 -=item for a request for /foo/foo +=item for a request for C MyApp::begin MyApp::auto - MyApp::C::Foo::default + MyApp::C::Foo::default # in the absence of MyApp::C::Foo::Foo MyApp::end -=item for a request for /foo/bar/foo +=item for a request for C MyApp::C::Foo::Bar::begin MyApp::auto MyApp::C::Foo::auto - MyApp::C::Foo::Bar::default + MyApp::C::Foo::Bar::auto + MyApp::C::Foo::Bar::default # for MyApp::C::Foo::Bar::foo MyApp::C::Foo::Bar::end =back -Also, if you need to break out of the chain in one of your auto -actions, you can return 0, if so, your action will not be processed, -but the end will, so for the request above, if the first auto returns -false, it would look like this: +The C action is also distinguished by the fact that you can break +out of the processing chain by returning 0. If an C action returns +0, any remaining actions will be skipped, except for C. So, for the +request above, if the first auto returns false, the chain would look +like this: =over 4 -=item for a request for /foo/bar/foo where auto returns false +=item for a request for C where first C returns +false MyApp::C::Foo::Bar::begin MyApp::auto @@ -457,22 +475,28 @@ false, it would look like this: =back -B auto actions have to return a true value to continue -processing! You can also die in the autochain action, in that case, the -request will go straight to the finalize stage, without processing -further actions. +An example of why one might use this is an authentication action: you +could set up a C action to handle authentication in your +application class (which will always be called first), and if +authentication fails, returning 0 would skip any remaining methods +for that URL. +B Looking at it another way, C actions have to return a +true value to continue processing! You can also C in the autochain +action; in that case, the request will go straight to the finalize +stage, without processing further actions. -=head4 B +=head4 B -If you want to pass variable arguments at the end of a URL, you must use regex -actions keys with '^' and '$' anchors, and the arguments must be separated with -forward slashes (/) in the URL. For example, suppose you want to handle -/foo/$bar/$baz, where $bar and $baz may vary: +You can pass variable arguments as part of the URL path. In this case, +you must use regex action keys with '^' and '$' anchors, and the +arguments must be separated with forward slashes (/) in the URL. For +example, suppose you want to handle C, where C<$bar> and +C<$baz> may vary: sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; } -But what if you also defined actions for /foo/boo and /foo/boo/hoo ? +But what if you also defined actions for C and C? sub boo : Path('foo/boo') { .. } sub hoo : Path('foo/boo/hoo') { .. } @@ -481,15 +505,17 @@ Catalyst matches actions in most specific to least specific order: /foo/boo/hoo /foo/boo - /foo # might be /foo/bar/baz + /foo # might be /foo/bar/baz but won't be /foo/boo/hoo -So Catalyst would never mistakenly dispatch the first two URLs to the '^foo$' action. +So Catalyst would never mistakenly dispatch the first two URLs to the +'^foo$' action. =head4 B -Parameters are handled with methods in the L -class. The C method is functionally equivalent to the C -method of C and can be used in modules that require this. +Parameters passed in the URL query string are handled with methods in +the L class. The C method is functionally +equivalent to the C method of C and can be used in +modules that require this. # http://localhost:3000/catalog/view/?category=hardware&page=3 my $category = $c->req->param('category');