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=002640263af9383b1748dd911826be1b8616fd99;hpb=baf5120b807f1be08f251e0916046ccec0cdc2d4;p=catagits%2FCatalyst-Runtime.git diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index 0026402..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 @@ -46,11 +56,11 @@ control. Catalyst itself! =back -If you're unfamiliar with MVC and design patterns, you may want to check -out the original book on the subject, I, by Gamma, -Helm, Johnson, and Vlissides, also known as the Gang of Four (GoF). -Many, many web application frameworks are based on MVC, including all -those listed above. +If you're unfamiliar with MVC and design patterns, you may want to +check out the original book on the subject, I, by +Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four +(GoF). Many, many web application frameworks are based on MVC, which +is becoming a popular design method for web applications. =head3 Flexibility @@ -184,8 +194,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; @@ -198,16 +207,12 @@ 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: +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 @@ -259,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 @@ -288,6 +294,10 @@ information. $c->stash $c->stash->{foo} = 'bar'; + $c->stash->{baz} = {baz => 'qox'}; + $c->stash->{fred} = [qw/ wilma pebbles/]; + +and so on. =back @@ -307,7 +317,9 @@ 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 @@ -319,6 +331,29 @@ 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 + +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 @@ -385,11 +420,15 @@ L below. =item * B (B) - 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 (B) @@ -406,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 { } @@ -459,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 @@ -632,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> @@ -717,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 @@ -735,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 @@ -771,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 @@ -839,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; @@ -878,26 +942,150 @@ 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 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, 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 - 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) provides things like C +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). + +=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. + +#### 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. + +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 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 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 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, and not per request. To make this +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; + } + } + + =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... @@ -929,6 +1117,8 @@ David Naughton, C Marcus Ramberg, C Jesse Sheidlower, C Danijel Milicevic, C +Kieren Diment, C +Yuval Kogman, C =head1 COPYRIGHT