X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=6bbebde0959bfbdbef443812f08b6b05b32cd393;hb=5403ad4276fae2b6cca25c6d0d7c388f71fdd4bb;hp=b6823ef869f9019802cd32ce74ddc72df9e0d267;hpb=24cda51b9aafb235b2b839200810b7624606f47a;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index b6823ef..6bbebde 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -8,12 +8,22 @@ This is a brief introduction to Catalyst. It explains the most important features of how Catalyst works and shows how to get a simple application up and running quickly. For an introduction (without code) to Catalyst itself, and why you should be using it, see L. +For a systematic step-by-step introduction to writing an application +with Catalyst, see L. =head2 What is Catalyst? Catalyst is an elegant web application framework, extremely flexible yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and -L, upon which it was originally based. +L, upon which it was originally based. Its most important +design philosphy is to provide easy access to all the tools you need to +develop web applications, with few restrictions on how you need to use +these tools. Under Catalyst, it is always possible to do things in a +different way. However, this does mean that it is always possible to do +things in a different way. Other web frameworks are simpler to use and +easy to get up and running, but achieve this by locking the programmer +into a single set of tools. Catalyst's emphasis on flexibility means +that you have to think more to use it. We view this as a feature. =head3 MVC @@ -32,7 +42,7 @@ well-known Perl modules you may want to use for each. =item * B Access and modify content (data). L, L, -L, L... +L, L... =item * B @@ -199,6 +209,11 @@ configure your application, load plugins, and extend Catalyst. ); 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 L, +below), to avoid namespace collisions. + =over 4 =item * B @@ -249,6 +264,7 @@ query parameters, cookies, uploads, headers, and more. $c->req->cookies->{sessionid}; $c->req->headers->content_type; $c->req->base; + $c->req->uri_with( { page = $pager->next_page } ); =item * L @@ -301,12 +317,12 @@ application components. For an example, we return to our 'hello' action: 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 for a comprehensive set of +Catalyst-friendly session-handling tools. =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 @@ -320,7 +336,7 @@ base and not to the action. =item * B Actions which are called at the root level of the application -(e.g. http:///localhost:3000/ ) go in MyApp::Controller::Root, like +(e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like this: package MyApp::Controller::Root; @@ -334,12 +350,8 @@ this: } 1; - =back -For most applications, Catalyst requires you to define only one config -parameter: - =head4 Action types Catalyst supports several types of actions: @@ -433,6 +445,24 @@ Catalyst ("MyApp::Controller" in the above example), replaces "::" with explanation of the pre-defined meaning of Catalyst component class names. +=item * B + +Catalyst also provides a method to build and dispatch chains of actions, +like + + sub foo : Chained : CaptureArgs(1) { + my ( $self, $c, $arg ) = @_; + ... + } + + sub bar : Chained('foo') : Args(1) { + my ( $self, $c, $arg ) = @_; + ... + } + +to handle a C path. For extensive information about this +dispatch type, please see L. + =item * B sub foo : Private { } @@ -486,10 +516,12 @@ displaying a generic frontpage for the main app, or an error page for individual controllers. If C isn't acting how you would expect, look at using a -L C action (with an empty path string). The difference is -that C takes arguments relative from the namespace and C -I takes arguments relative from the root, regardless of what -controller it's in. +L C action (with an empty path string). The difference +is that C takes arguments relative from the namespace and +C I 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 private controller should +be considered deprecated. =item * B @@ -659,10 +691,9 @@ debugging enabled). $c->res->body( $c->stash->{message} ); } -A C does not create a new request, so your request -object (C<$c-Ereq>) will remain unchanged. This is a -key difference between using C and issuing a -redirect. +A C does not create a new request, so your request object +(C<$c-Ereq>) will remain unchanged. This is a key difference between +using C and issuing a redirect. You can pass new arguments to a C by adding them in an anonymous array. In this case C<$c-Ereq-Eargs> @@ -744,7 +775,7 @@ You don't have to C or otherwise register Models, Views, and Controllers. Catalyst automatically discovers and instantiates them when you call C in the main application. All you need to do is put them in directories named for each Component type. Notice that you -can use some very terse aliases for each one. +can use a terse alias for each one. =over 4 @@ -762,6 +793,11 @@ can use some very terse aliases for each one. =back +In older versions of Catalyst, the recommended practice (and the one +automatically created by helper scripts) was to name the directories +C, C, and 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 @@ -798,11 +834,12 @@ C<$c-Eforward(qw/MyApp::View::TT process/)>. } You normally render templates at the end of a request, so it's a perfect -use for the global C action. +use for the global C action. (In practice, however, you would use a +default C action as supplied by L.) Also, be sure to put the template under the directory specified in -C<$c-Econfig-E{root}>, or you'll be forced to look at our -eyecandy debug screen. ;) +C<$c-Econfig-E{root}>, or you'll end up looking at the debug +screen. =head4 Models @@ -866,9 +903,9 @@ can always call an outside module that serves as your Model: $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; @@ -988,21 +1025,22 @@ Using plugins in (for example L). =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. +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. #### 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 method instead of -returning the model itself, the return value of -C<< $model->ACCEPT_CONTEXT( $c ) >> will be used. +Whenever you call $c->component("Foo") you get back an object - the +instance of the model. If the component supports the C +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. @@ -1011,7 +1049,7 @@ A typical C 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 typicall C method could look like this: +A typical C method could look like this: sub ACCEPT_CONTEXT { my ( $self, $c, @extra_arguments ) = @_; @@ -1029,26 +1067,25 @@ per request you can use the following technique: Add a field to C<$c>, like C. Then write your C 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 -Catalyst has a built-in http server for testing! (Later, you can easily -use a more powerful server, e.g. Apache/mod_perl, in a production -environment.) +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.) Start your application on the command line...