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=0139fefec61f86045291ba6181abe9d1db59a38f;hp=0f7c410acb6ec026e202785b3461892991f26034;hb=b86fa467f50cf672137eca75a4d2a9d52169e948;hpb=1b2f9849ec61b6974892a679ba3d4030054a2cfa diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index 0f7c410..0139fef 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -16,14 +16,14 @@ with Catalyst, see L. 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. Its most -important design philosphy is to provide easy access to all the tools +important design philosophy 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. However, this does mean that it is always possible to do things in a different way. Other web frameworks are I simpler to use, 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. For -example, this leads to Catalyst being more suited to system integration +example, this leads to Catalyst being better suited to system integration tasks than other web frameworks. =head3 MVC @@ -53,7 +53,7 @@ L, L... =item * B Control the whole request phase, check parameters, dispatch actions, flow -control. Catalyst itself! +control. This is the meat of where Catalyst works. =back @@ -122,6 +122,12 @@ separately - which will turn the built server into a fully fledged production ready server (although you'll probably want to run it behind a front end proxy if you end up using it). +=item * PSGI Support + +Starting with Catalyst version 5.9 Catalyst ships with L integration +for even more powerful and flexible testing and deployment options. See +L for details. + =back =head3 Simplicity @@ -260,23 +266,12 @@ short alias for each one. =item * B -=item * B - =item * B -=item * B - =item * B -=item * B - =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, they are deprecated -and 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 @@ -463,7 +458,7 @@ Using plugins from a Model (for example L). From a style perspective it's usually considered bad form 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 +find that it does not make sense at all to use an auxiliary controller around the model, and the model's need to access C<$c> cannot be sidestepped, there exists a power tool called L. @@ -476,9 +471,9 @@ application. use base qw/Catalyst::Controller/; - sub login : Path("login") { } + sub sign_in : Path("sign-in") { } sub new_password : Path("new-password") { } - sub logout : Path("logout") { } + sub sign_out : Path("sign-out") { } package MyApp::Controller::Catalog; @@ -534,7 +529,7 @@ Generally it's a bad idea to expose the context object (C<$c>) in your model or view code. Instead you use the C subroutine to grab the bits of the context object that you need, and provide accessors to them in the model. This ensures that C<$c> is only in -scope where it is neaded which reduces maintenance and debugging +scope where it is needed which reduces maintenance and debugging headaches. So, if for example you needed two L models in the same Catalyst model code, you might do something like this: @@ -784,7 +779,7 @@ of Catalyst component class names. =item * B -Note that __PACKAGE__->config->{namespace} can be used to override the +Note that C<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the current namespace when matching. So: package MyApp::Controller::Example; @@ -792,7 +787,7 @@ current namespace when matching. So: would normally use 'example' as its namespace for matching, but if this is specially overridden with - __PACKAGE__->config->{namespace}='thing'; + __PACKAGE__->config( namespace => 'thing' ); it matches using the namespace 'thing' instead. @@ -804,25 +799,29 @@ application (e.g. http://localhost:3000/ ): 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} = ''; + + __PACKAGE__->config( namespace => ''); + sub default : Path { my ( $self, $context ) = @_; $context->response->status(404); $context->response->body('404 not found'); } + 1; The code - __PACKAGE__->config->{namespace} = ''; + __PACKAGE__->config( namespace => '' ); makes the controller act as if its namespace is empty. As you'll see -below, an empty namespace makes many of the URL-matching attributes, -such as :Path, :Local and :Global matches, match at the start of the -URL path. +below, an empty namespace makes many of the URL-matching attributes, such +as :Path and :Local match at the start of the URL path (i.e. the +application root). =back @@ -850,20 +849,30 @@ subroutine name together determine the path. =item * Root-level (C<:Global>) package MyApp::Controller::Foo; - sub foo : Global { } -Matches http://localhost:3000/foo - that is, the action is mapped -directly to the controller namespace, ignoring the function name. + sub bar : Global { + my ($self, $c) = @_; + $c->res->body( + $c->res->body('sub bar in Controller::Foo triggered on a request for ' + . $c->req->uri)); + } -C<:Global> always matches from root: it is sugar for C<:Path('/methodname')>. -C<:Local> is simply sugar for C<:Path('methodname')>, which takes the package -namespace as described above. +1; - package MyApp::Controller::Root; - __PACKAGE__->config->{namespace}=''; - sub foo : Local { } +Matches http://localhost:3000/bar - that is, the action is mapped +directly to the method name, ignoring the controller namespace. + +C<:Global> always matches from the application root: it is simply +shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for +C<:Path('methodname')>, which takes the controller namespace as described +above. -Use whichever makes the most sense for your application. +Usage of the C handler is rare in all but very old Catalyst +applications (e.g. before Catalyst 5.7). The use cases where C +used to make sense are now largely replaced by the C dispatch +type, or by empty C declarations on an controller action. C +is still included in Catalyst for backwards compatibility, although +legitimate use-cases for it may still exist. =item * Changing handler behaviour: eating arguments (C<:Args>) @@ -1099,7 +1108,7 @@ turn. sub auto : Private { } C, however, doesn't override like this: providing they exist, -C, C and +C, C and C would be called in turn. Here are some examples of the order in which the various built-ins @@ -1354,7 +1363,7 @@ that can be extended as you develop your project. To write your own comprehensive test scripts, L is an invaluable tool. -For more testing ideas, see L. +For more testing ideas, see L. Have fun!