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=da1d8db79bb489c9c2b79c1bd95e2e34048afb04;hp=a5acd72750e48d7f32b745a679e8e2857e2c6ad3;hb=3656a65d331cc79e95dc984a6a4fce89cfc7045f;hpb=be3349e1a2966ee8abc15c1b9a168a3c70125ccb diff --git a/lib/Catalyst/Manual/Intro.pod b/lib/Catalyst/Manual/Intro.pod index a5acd72..da1d8db 100644 --- a/lib/Catalyst/Manual/Intro.pod +++ b/lib/Catalyst/Manual/Intro.pod @@ -16,7 +16,7 @@ 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 @@ -181,6 +181,7 @@ Installation of Catalyst should be straightforward: # perl -MCPAN -e 'install Catalyst::Runtime' # perl -MCPAN -e 'install Catalyst::Devel' + # perl -MCPAN -e 'install Catalyst::View::TT' =head3 Setup @@ -266,23 +267,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 @@ -469,7 +459,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. @@ -540,7 +530,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: @@ -765,10 +755,10 @@ will look at the URL it is processing, and the actions that it has found, and automatically call the actions it finds that match the circumstances of the request. -The URL (for example http://localhost:3000/foo/bar) consists of two +The URL (for example C) consists of two parts, the base, describing how to connect to the server -(http://localhost:3000/ in this example) and the path, which the -server uses to decide what to return (foo/bar). Please note that the +(C in this example) and the path, which the +server uses to decide what to return (C). Please note that the trailing slash after the hostname[:port] always belongs to base and not to the path. Catalyst uses only the path part when trying to find actions to process. @@ -790,7 +780,7 @@ of Catalyst component class names. =item * B -Note that I<< __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; @@ -802,11 +792,11 @@ this is specially overridden with it matches using the namespace 'thing' instead. -=item * B +=item * B MyApp::Controller::Root, as created by the catalyst.pl script, will typically contain actions which are called for the top level of the -application (e.g. http://localhost:3000/ ): +application (e.g. C): package MyApp::Controller::Root; use base 'Catalyst::Controller'; @@ -854,7 +844,7 @@ of the path is passed as arguments. package MyApp::Controller::My::Controller; sub foo : Local { } -Matches any URL beginning with> http://localhost:3000/my/controller/foo. The namespace and +Matches any URL beginning with> C. The namespace and subroutine name together determine the path. =item * Root-level (C<:Global>) @@ -870,11 +860,11 @@ subroutine name together determine the path. 1; -Matches http://localhost:3000/bar - that is, the action is mapped +Matches C - 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 -shorthandfor C<:Path('/methodname')>. C<:Local> is shorthand for +shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for C<:Path('methodname')>, which takes the controller namespace as described above. @@ -887,7 +877,7 @@ legitimate use-cases for it may still exist. =item * Changing handler behaviour: eating arguments (C<:Args>) -Args is not an action type per se, but an action modifier - it adds a +C<:Args> is not an action type per se, but an action modifier - it adds a match restriction to any action it's provided to, additionally requiring as many path parts as are specified for the action to be matched. For example, in MyApp::Controller::Foo, @@ -901,13 +891,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 omitting C<:Args> are B the same thing. 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 C<:Args> at all means that B of arguments are taken. Thus, any URL that B the controller's path will match. Obviously, this means you cannot chain from an action that does not specify args, as the next action in the chain will be swallowed as an arg to the first! @@ -920,7 +910,7 @@ and nothing else. C actions without a leading forward slash match a specified path relative to their current namespace. This example matches URLs -starting http://localhost:3000/my/controller/foo/bar : +starting with C: package MyApp::Controller::My::Controller; sub bar : Path('foo/bar') { } @@ -931,7 +921,7 @@ match from the start of the URL path. Example: package MyApp::Controller::My::Controller; sub bar : Path('/foo/bar') { } -This matches URLs beginning http://localhost:3000/foo/bar. +This matches URLs beginning with C. Empty C definitions match on the namespace only, exactly like C<:Global>. @@ -939,7 +929,7 @@ C<:Global>. package MyApp::Controller::My::Controller; sub bar : Path { } -The above code matches http://localhost:3000/my/controller. +The above code matches C. Actions with the C<:Local> attribute are similarly equivalent to C<:Path('action_name')>: @@ -950,18 +940,22 @@ is equivalent to sub foo : Path('foo') { } -=item * Pattern-match (C<:Regex> and C<:LocalRegex>) +=item * Pattern match (C<:Regex> and C<:LocalRegex>) + +B Use Chained methods or other techniques. +If you really depend on this, install the standalone +L distribution. package MyApp::Controller::My::Controller; sub bar : Regex('^item(\d+)/order(\d+)$') { } This matches any URL that matches the pattern in the action key, e.g. -http://localhost:3000/item23/order42. The '' around the regexp is +C. The '' around the regexp is optional, but perltidy likes it. :) C<:Regex> matches act globally, i.e. without reference to the namespace from which they are called. So the above will B match -http://localhost:3000/my/controller/item23/order42 - use a +C - use a C<:LocalRegex> action instead. package MyApp::Controller::My::Controller; @@ -969,7 +963,7 @@ C<:LocalRegex> action instead. C<:LocalRegex> actions act locally, i.e. the namespace is matched first. The above example would match urls like -http://localhost:3000/my/controller/widget23. +C. If you omit the "C<^>" from either sort of regex, then it will match any depth from the base path: @@ -978,7 +972,7 @@ from the base path: sub bar : LocalRegex('widget(\d+)$') { } This differs from the previous example in that it will match -http://localhost:3000/my/controller/foo/widget23 - and a number of +C - and a number of other paths. For both C<:LocalRegex> and C<:Regex> actions, if you use capturing @@ -1374,7 +1368,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!