X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FIntro.pod;h=28646636380e4204824b495344dc26a217c7cc6f;hp=a15f7d12c23e5d3d2e4ea623011f98818fcb5a40;hb=e8556dab015903c85f3a413224a12493d95a7934;hpb=845ef40515e6cfbdfb8c6b53a5872fb216225feb diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index a15f7d1..2864663 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -171,16 +171,9 @@ running, using the helper scripts described above. =head3 Install -Installation of Catalyst can be a time-consuming effort, due to its -large number of dependencies. Although most of the frustrations -associated with this are now ironed out and a simple C or C are now usually -straightforward, if you still have problems, you can use use Matt -Trout's C script, from -L, and then -install L. - - # perl cat-install +Installation of Catalyst should be straightforward: + + # perl -MCPAN -e 'install Catalyst::Runtime' # perl -MCPAN -e 'install Catalyst::Devel' =head3 Setup @@ -230,7 +223,7 @@ Catalyst has an uncommonly flexible component system. You can define as many L, L, and L as you like. As discussed previously, the general idea is that the View is responsible for the output of data to the user (typically via a web browser, but a View can -also generate PDFs or e-mails, for example); the Model is responsible +also generate PDFs or e-mails, for example); the Model is responsible for providing data (typically from a relational database); and the Controller is responsible for interacting with the user and deciding how user input determines what actions the application takes. @@ -238,7 +231,7 @@ how user input determines what actions the application takes. In the world of MVC, there are frequent discussions and disagreements about the nature of each element - whether certain types of logic belong in the Model or the Controller, etc. Catalyst's flexibility -means that this decision is entirely up to you, the programmer; +means that this decision is entirely up to you, the programmer; Catalyst doesn't enforce anything. See L for a general discussion of these issues. @@ -248,9 +241,10 @@ from L which provides a simple class structure and some common class methods like C and C (constructor). package MyApp::Controller::Catalog; + use Moose; + use namespace::autoclean; - use strict; - use base 'Catalyst::Controller'; + BEGIN { extends 'Catalyst::Controller' } __PACKAGE__->config( foo => 'bar' ); @@ -264,7 +258,7 @@ short alias for each one. =over 4 -=item * B +=item * B =item * B @@ -280,8 +274,8 @@ short alias for each one. 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. +C, C, and C. Though these still work, they are deprecated +and we now recommend the use of the full names. =head4 Views @@ -373,15 +367,15 @@ We add the following to MyApp/Controller/Root.pm sub view : Global { my ( $self, $c, $id ) = @_; - + $c->stash->{item} = $c->model('MyModel::Foo')->find($id); } 1; - + sub end : Private { my ( $self, $c ) = @_; - + $c->stash->{template} ||= 'index.tt'; $c->forward( $c->view('TT') ); } @@ -396,14 +390,14 @@ can always call an outside module that serves as your Model: # in a Controller sub list : Local { my ( $self, $c ) = @_; - + $c->stash->{template} = 'list.tt'; - + use Some::Outside::Database::Module; my @records = Some::Outside::Database::Module->search({ artist => 'Led Zeppelin', }); - + $c->stash->{records} = \@records; } @@ -847,7 +841,7 @@ of the path is passed as arguments. =item * Namespace-prefixed (C<:Local>) - package MyApp::Controller::My::Controller; + package MyApp::Controller::My::Controller; sub foo : Local { } Matches any URL beginning with> http://localhost:3000/my/controller/foo. The namespace and @@ -859,10 +853,10 @@ subroutine name together determine the path. sub foo : Global { } Matches http://localhost:3000/foo - that is, the action is mapped -directly to the controller namespace, ignoring the function name. +directly to the controller namespace, ignoring the function name. C<:Global> is equivalent C<:Local> one level higher in -the namespace. +the namespace. package MyApp::Controller::Root; __PACKAGE__->config->{namespace}=''; @@ -886,13 +880,13 @@ would match any URL starting /foo/bar. To restrict this you can do to only match URLs starting /foo/bar/* - with one additional path element required after 'bar'. -NOTE that adding C<:Args(0)> and missing out :Args completely are B +NOTE that adding C<:Args(0)> and missing out :Args completely are B the same thing. -C<:Args(0)> means that no arguments are taken. Thus, the URL and path must +C<:Args(0)> means that no arguments are taken. Thus, the URL and path must match precisely. -No :Args at all means that B of arguments are taken. Thus, any +No :Args at all means that B of arguments are taken. Thus, any URL that B the controller's path will match. @@ -927,14 +921,14 @@ The above code matches http://localhost:3000/my/controller. Actions with the C<:Local> attribute are similarly equivalent to C<:Path('action_name')>: - sub foo : Local { } + sub foo : Local { } -is equivalent to +is equivalent to sub foo : Path('foo') { } =item * Pattern-match (C<:Regex> and C<:LocalRegex>) - + package MyApp::Controller::My::Controller; sub bar : Regex('^item(\d+)/order(\d+)$') { } @@ -1157,7 +1151,7 @@ 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! +true value to continue processing! =head4 URL Path Handling @@ -1182,8 +1176,8 @@ Catalyst matches actions in most specific to least specific order - that is, wha So Catalyst would never mistakenly dispatch the first two URLs to the '^foo$' action. -If a Regex or LocalRegex action doesn't use the '$' anchor, the action will -still match a URL containing arguments; however the arguments won't be +If a Regex or LocalRegex action doesn't use the '$' anchor, the action will +still match a URL containing arguments; however the arguments won't be available via C<@_>, because the Regex will 'eat' them. Beware! If you write two matchers, that match the same path, with the @@ -1215,7 +1209,7 @@ modules that require this. my $current_page = $c->req->param('page') || 1; # multiple values for single parameter name - my @values = $c->req->param('scrolling_list'); + my @values = $c->req->param('scrolling_list'); # DFV requires a CGI.pm-like input hash my $results = Data::FormValidator->check($c->req->params, \%dfv_profile); @@ -1268,9 +1262,9 @@ be reset. # now $c->req->args is back to what it was before } - sub check_message : Private { - my ( $self, $c ) = @_; - my $first_argument = $c->req->args->[0]; # now = 'test1' + sub check_message : Action { + my ( $self, $c, $first_argument ) = @_; + my $also_first_argument = $c->req->args->[0]; # now = 'test1' # do something... } @@ -1282,11 +1276,11 @@ you will have to refer to the method by absolute path. $c->forward('/my/controller/action'); $c->forward('/default'); # calls default in main application -Here are some examples of how to forward to classes and methods. +You can also forward to classes and methods. sub hello : Global { my ( $self, $c ) = @_; - $c->forward(qw/MyApp::Model::Hello say_hello/); + $c->forward(qw/MyApp::View:Hello say_hello/); } sub bye : Global { @@ -1294,7 +1288,7 @@ Here are some examples of how to forward to classes and methods. $c->forward('MyApp::Model::Hello'); # no method: will try 'process' } - package MyApp::Model::Hello; + package MyApp::View::Hello; sub say_hello { my ( $self, $c ) = @_; @@ -1306,6 +1300,28 @@ Here are some examples of how to forward to classes and methods. $c->res->body('Goodbye World!'); } +This mechanism is used by L to forward +to the C method in a view class. + +It should be noted that whilst forward is useful, it is not the only way +of calling other code in Catalyst. Forward just gives you stats in the debug +screen, wraps the code you're calling in an exception handler and localises +C<< $c->request->args >>. + +If you don't want or need these features then it's perfectly acceptable +(and faster) to do something like this: + + sub hello : Global { + my ( $self, $c ) = @_; + $c->stash->{message} = 'Hello World!'; + $self->check_message( $c, 'test1' ); + } + + sub check_message { + my ( $self, $c, $first_argument ) = @_; + # do something... + } + Note that C returns to the calling action and continues processing after the action finishes. If you want all further processing in the calling action to stop, use C instead, which will execute @@ -1313,7 +1329,6 @@ the Ced action and not return to the calling sub. In both cases, Catalyst will automatically try to call process() if you omit the method. - =head3 Testing Catalyst has a built-in http server for testing or local @@ -1372,17 +1387,13 @@ FAQ: http://dev.catalystframework.org/wiki/faq -=head1 AUTHOR +=head1 AUTHORS -Sebastian Riedel, C -David Naughton, C -Marcus Ramberg, C -Jesse Sheidlower, C -Danijel Milicevic, C -Kieren Diment, C -Yuval Kogman, C +Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT -This program is free software. You can redistribute it and/or modify it -under the same terms as Perl itself. +This library is free software. You can redistribute it and/or modify it under +the same terms as Perl itself. + +=cut