X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=6ba61e38a9e872f1220be7bd64863607cf1a21fd;hb=a74c2d1a1e12c43e5dbb4caef23f7cc25e57bd1f;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..6ba61e3 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 #####, below), +to avoid namespace collisions. + =over 4 =item * B @@ -213,6 +228,8 @@ 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-Econfig-E{$param_name}>. +###### We need a short section on configuration here. + =head3 Context Catalyst automatically blesses a Context object into your application @@ -305,8 +322,6 @@ 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 @@ -320,7 +335,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 +349,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 +444,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 more information about this dispatch +type, please read L. + =item * B sub foo : Private { } @@ -659,10 +688,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 +772,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 +790,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,7 +831,8 @@ 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 @@ -988,21 +1022,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 +1046,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 ) = @_; @@ -1043,12 +1078,11 @@ C method to look like this: } - =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...