Catalyst is an elegant web application framework, extremely flexible
yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
L<Maypole|Maypole>, 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
# perl -MCPAN -e 'install Catalyst::Runtime'
# perl -MCPAN -e 'install Catalyst::Devel'
+ # perl -MCPAN -e 'install Catalyst::View::TT'
=head3 Setup
be C<TT>, and the second that it should be a Template Toolkit view.)
This gives us a process() method and we can now just do
-$c->forward('MyApp::View::TT') to render our templates. The base class
+C<< $c->forward('MyApp::View::TT') >> to render our templates. The base class
makes process() implicit, so we don't have to say
-C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
+C<< $c->forward(qw/MyApp::View::TT process/) >>.
sub hello : Global {
my ( $self, $c ) = @_;
by L<Catalyst::Action::RenderView>.
Also, be sure to put the template under the directory specified in
-C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
+C<< $c->config->{root} >>, or you'll end up looking at the debug
screen.
=head4 Models
will find and load it automatically at compile-time; you can
C<forward> to the module, which can only be done to Catalyst
components. Only Catalyst components can be fetched with
-C<$c-E<gt>model('SomeModel')>.
+C<< $c->model('SomeModel') >>.
Happily, since many people have existing Model classes that they
would like to use with Catalyst (or, conversely, they want to
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</ACCEPT_CONTEXT>.
=head3 ACCEPT_CONTEXT
-Whenever you call $c->component("Foo") you get back an object - the
+Whenever you call C<< $c->component("Foo") >> you get back an object - the
instance of the model. If the component supports the C<ACCEPT_CONTEXT>
method instead of returning the model itself, the return value of C<<
$model->ACCEPT_CONTEXT( $c ) >> will be used.
Note that we still want the Catalyst models to be a thin wrapper
around classes that will work independently of the Catalyst
application to promote reusability of code. Here we might just want
-to grab the $c->model('DB')->schema so as to get the connection
+to grab the C<< $c->model('DB')->schema >> so as to get the connection
information from the Catalyst application's configuration for example.
The life time of this value is B<per usage>, and not per request. To
data. If omitted, Catalyst will try to auto-detect the directory's
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-E<gt>config-E<gt>{$param_name}>.
+C<< $context->config->{$param_name} >>.
=head3 Context
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<http://localhost:3000/foo/bar>) 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<http://localhost:3000/> in this example) and the path, which the
+server uses to decide what to return (C<foo/bar>). 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.
it matches using the namespace 'thing' instead.
-=item * B<Application Wide Actions>
+=item * B<Application-Wide Actions>
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<http://localhost:3000/>):
package MyApp::Controller::Root;
use base 'Catalyst::Controller';
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<http://localhost:3000/my/controller/foo>. The namespace and
subroutine name together determine the path.
=item * Root-level (C<:Global>)
1;
-Matches http://localhost:3000/bar - that is, the action is mapped
+Matches C<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
-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.
=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,
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<not>
+NOTE that adding C<:Args(0)> and omitting C<:Args> are B<not>
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<any number> of arguments are taken. Thus, any
+No C<:Args> at all means that B<any number> of arguments are taken. Thus, any
URL that B<starts with> 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!
C<Path> 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<http://localhost:3000/my/controller/foo/bar>:
package MyApp::Controller::My::Controller;
sub bar : Path('foo/bar') { }
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<http://localhost:3000/foo/bar>.
Empty C<Path> definitions match on the namespace only, exactly like
C<:Global>.
package MyApp::Controller::My::Controller;
sub bar : Path { }
-The above code matches http://localhost:3000/my/controller.
+The above code matches C<http://localhost:3000/my/controller>.
Actions with the C<:Local> attribute are similarly equivalent to
C<:Path('action_name')>:
sub foo : Path('foo') { }
-=item * Pattern-match (C<:Regex> and C<:LocalRegex>)
+=item * Pattern match (C<:Regex> and C<:LocalRegex>)
+
+B<Status: deprecated.> Use Chained methods or other techniques.
+If you really depend on this, install the standalone
+L<Catalyst::DispatchType::Regex> 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<http://localhost:3000/item23/order42>. 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<not> match
-http://localhost:3000/my/controller/item23/order42 - use a
+C<http://localhost:3000/my/controller/item23/order42> - use a
C<:LocalRegex> action instead.
package MyApp::Controller::My::Controller;
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<http://localhost:3000/my/controller/widget23>.
If you omit the "C<^>" from either sort of regex, then it will match any depth
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<http://localhost:3000/my/controller/foo/widget23> - and a number of
other paths.
For both C<:LocalRegex> and C<:Regex> actions, if you use capturing
parentheses to extract values within the matching URL, those values
-are available in the C<$c-E<gt>req-E<gt>captures> array. In the above
+are available in the C<< $c->req->captures >> array. In the above
example, "widget23" would capture "23" in the above example, and
-C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to
+C<< $c->req->captures->[0] >> would be "23". If you want to
pass arguments at the end of your URL, you must use regex action
keys. See L</URL Path Handling> below.
the method, so that a private C<bar> method in your
C<MyApp::Controller::Catalog::Order::Process> controller must, if
called from elsewhere, be reached with
-C<$c-E<gt>forward('/catalog/order/process/bar')>.
+C<< $c->forward('/catalog/order/process/bar') >>.
=back
Parameters passed in the URL query string are handled with methods in
the L<Catalyst::Request> class. The C<param> method is functionally
-equivalent to the C<param> method of C<CGI.pm> and can be used in
+equivalent to the C<param> method of L<CGI.pm|CGI> and can be used in
modules that require this.
# http://localhost:3000/catalog/view/?category=hardware&page=3
}
A C<forward> does not create a new request, so your request object
-(C<$c-E<gt>req>) will remain unchanged. This is a key difference between
+(C<< $c->req >>) will remain unchanged. This is a key difference between
using C<forward> and issuing a redirect.
You can pass new arguments to a C<forward> by adding them
-in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
+in an anonymous array. In this case C<< $c->req->args >>
will be changed for the duration of the C<forward> only; upon
-return, the original value of C<$c-E<gt>req-E<gt>args> will
+return, the original value of C<< $c->req->args >> will
be reset.
sub hello : Global {
$c->stash->{message} = 'Hello World!';
$self->check_message( $c, 'test1' );
}
-
+
sub check_message {
my ( $self, $c, $first_argument ) = @_;
# do something...
comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
invaluable tool.
-For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
+For more testing ideas, see L<Catalyst::Manual::Tutorial::08_Testing>.
Have fun!
projects / catagits/Catalyst-Manual.git / blobdiff