3 Catalyst::Manual::Intro - Introduction to Catalyst
7 This is a brief introduction to Catalyst. It explains the most important
8 features of how Catalyst works and shows how to get a simple application
9 up and running quickly. For an introduction (without code) to Catalyst
10 itself, and why you should be using it, see L<Catalyst::Manual::About>.
11 For a systematic step-by-step introduction to writing an application
12 with Catalyst, see L<Catalyst::Manual::Tutorial>.
14 =head2 What is Catalyst?
16 Catalyst is an elegant web application framework, extremely flexible yet
17 extremely simple. It's similar to Ruby on Rails, Spring (Java), and
18 L<Maypole>, upon which it was originally based. Its most important
19 design philosphy is to provide easy access to all the tools you need to
20 develop web applications, with few restrictions on how you need to use
21 these tools. Under Catalyst, it is always possible to do things in a
22 different way. However, this does mean that it is always possible to do
23 things in a different way. Other web frameworks are simpler to use and
24 easy to get up and running, but achieve this by locking the programmer
25 into a single set of tools. Catalyst's emphasis on flexibility means
26 that you have to think more to use it. We view this as a feature.
30 Catalyst follows the Model-View-Controller (MVC) design pattern,
31 allowing you to easily separate concerns, like content, presentation,
32 and flow control, into separate modules. This separation allows you to
33 modify code that handles one concern without affecting code that handles
34 the others. Catalyst promotes the re-use of existing Perl modules that
35 already handle common web application concerns well.
37 Here's how the M, V, and C map to those concerns, with examples of
38 well-known Perl modules you may want to use for each.
44 Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
45 L<Xapian>, L<Net::LDAP>...
49 Present content to the user. L<Template Toolkit|Template>,
50 L<Mason|HTML::Mason>, L<HTML::Template>...
54 Control the whole request phase, check parameters, dispatch actions, flow
55 control. Catalyst itself!
59 If you're unfamiliar with MVC and design patterns, you may want to
60 check out the original book on the subject, I<Design Patterns>, by
61 Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
62 (GoF). Many, many web application frameworks are based on MVC, which
63 is becoming a popular design method for web applications.
67 Catalyst is much more flexible than many other frameworks. We'll talk
68 more about this later, but rest assured you can use your favorite Perl
69 modules with Catalyst.
73 =item * B<Multiple Models, Views, and Controllers>
75 To build a Catalyst application, you handle each type of concern inside
76 special modules called L</Components>. Often this code will be very
77 simple, just calling out to Perl modules like those listed above under
78 L</MVC>. Catalyst handles these components in a very flexible way. Use
79 as many Models, Views, and Controllers as you like, using as many
80 different Perl modules as you like, all in the same application. Want to
81 manipulate multiple databases, and retrieve some data via LDAP? No
82 problem. Want to present data from the same Model using L<Template
83 Toolkit|Template> and L<PDF::Template>? Easy.
85 =item * B<Reuseable Components>
87 Not only does Catalyst promote the re-use of already existing Perl
88 modules, it also allows you to re-use your Catalyst components in
89 multiple Catalyst applications.
91 =item * B<Unrestrained URL-to-Action Dispatching>
93 Catalyst allows you to dispatch any URLs to any application L</Actions>,
94 even through regular expressions! Unlike most other frameworks, it
95 doesn't require mod_rewrite or class and method names in URLs.
97 With Catalyst you register your actions and address them directly. For
101 my ( $self, $context ) = @_;
102 $context->response->body('Hello World!');
105 Now http://localhost:3000/hello prints "Hello World!".
107 =item * B<Support for CGI, mod_perl, Apache::Request>
109 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
115 The best part is that Catalyst implements all this flexibility in a very
120 =item * B<Building Block Interface>
122 Components interoperate very smoothly. For example, Catalyst
123 automatically makes a L</Context> object available to every
124 component. Via the context, you can access the request object, share
125 data between components, and control the flow of your
126 application. Building a Catalyst application feels a lot like snapping
127 together toy building blocks, and everything just works.
129 =item * B<Component Auto-Discovery>
131 No need to C<use> all of your components. Catalyst automatically finds
134 =item * B<Pre-Built Components for Popular Modules>
136 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
137 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
139 =item * B<Built-in Test Framework>
141 Catalyst comes with a built-in, lightweight http server and test
142 framework, making it easy to test applications from the command line.
144 =item * B<Helper Scripts>
146 Catalyst provides helper scripts to quickly generate running starter
147 code for components and unit tests. See L<Catalyst::Helper>.
153 Here's how to install Catalyst and get a simple application up and
154 running, using the helper scripts described above.
158 $ perl -MCPAN -e 'install Task::Catalyst'
165 $ script/myapp_create.pl controller Library::Login
169 $ script/myapp_server.pl
171 Now visit these locations with your favorite browser or user agent to see
174 (NOTE: Although we create a controller here, we don't actually use it.
175 Both of these URLs should take you to the welcome page.)
180 =item http://localhost:3000/
182 =item http://localhost:3000/library/login/
190 Let's see how Catalyst works, by taking a closer look at the components
191 and other parts of a Catalyst application.
193 =head3 Application Class
195 In addition to the Model, View, and Controller components, there's a
196 single class that represents your application itself. This is where you
197 configure your application, load plugins, and extend Catalyst.
202 use Catalyst qw/-Debug/;
205 name => 'My Application',
207 # You can put anything else you want in here:
208 my_configuration_variable => 'something',
212 In older versions of Catalyst, the application class was where you put
213 global actions. However, as of version 5.66, the recommended practice is
214 to place such actions in a special Root controller (see #####, below),
215 to avoid namespace collisions.
221 The name of your application.
225 Optionally, you can specify a B<root> parameter for templates and static
226 data. If omitted, Catalyst will try to auto-detect the directory's
227 location. You can define as many parameters as you want for plugins or
228 whatever you need. You can access them anywhere in your application via
229 C<$context-E<gt>config-E<gt>{$param_name}>.
231 ###### We need a short section on configuration here.
235 Catalyst automatically blesses a Context object into your application
236 class and makes it available everywhere in your application. Use the
237 Context to directly interact with Catalyst and glue your L</Components>
238 together. For example, if you need to use the Context from within a
239 Template Toolkit template, it's already there:
241 <h1>Welcome to [% c.config.name %]!</h1>
243 As illustrated in our URL-to-Action dispatching example, the Context is
244 always the second method parameter, behind the Component object
245 reference or class name itself. Previously we called it C<$context> for
246 clarity, but most Catalyst developers just call it C<$c>:
249 my ( $self, $c ) = @_;
250 $c->res->body('Hello World!');
253 The Context contains several important objects:
257 =item * L<Catalyst::Request>
262 The request object contains all kinds of request-specific information, like
263 query parameters, cookies, uploads, headers, and more.
265 $c->req->params->{foo};
266 $c->req->cookies->{sessionid};
267 $c->req->headers->content_type;
270 =item * L<Catalyst::Response>
275 The response is like the request, but contains just response-specific
278 $c->res->body('Hello World');
279 $c->res->status(404);
280 $c->res->redirect('http://oook.de');
282 =item * L<Catalyst::Config>
288 =item * L<Catalyst::Log>
291 $c->log->debug('Something happened');
292 $c->log->info('Something you should know');
297 $c->stash->{foo} = 'bar';
298 $c->stash->{baz} = {baz => 'qox'};
299 $c->stash->{fred} = [qw/ wilma pebbles/];
305 The last of these, the stash, is a universal hash for sharing data among
306 application components. For an example, we return to our 'hello' action:
309 my ( $self, $c ) = @_;
310 $c->stash->{message} = 'Hello World!';
311 $c->forward('show_message');
314 sub show_message : Private {
315 my ( $self, $c ) = @_;
316 $c->res->body( $c->stash->{message} );
319 Note that the stash should be used only for passing data in an
320 individual request cycle; it gets cleared at a new request. If you need
321 to maintain more persistent data, use a session.
325 A Catalyst controller is defined by its actions. An action is a
326 subroutine with a special attribute. You've already seen some examples
327 of actions in this document. The URL (for example
328 http://localhost.3000/foo/bar) consists of two parts, the base
329 (http://localhost:3000/ in this example) and the path (foo/bar). Please
330 note that the trailing slash after the hostname[:port] always belongs to
331 base and not to the action.
335 =item * B<Application Wide Actions>
337 Actions which are called at the root level of the application
338 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
341 package MyApp::Controller::Root;
342 use base 'Catalyst::Controller';
343 # Sets the actions in this controller to be registered with no prefix
344 # so they function identically to actions created in MyApp.pm
345 __PACKAGE__->config->{namespace} = '';
346 sub default : Private {
347 my ( $self, $context ) = @_;
348 $context->response->body('Catalyst rocks!');
356 Catalyst supports several types of actions:
360 =item * B<Literal> (B<Path> actions)
362 package MyApp::Controller::My::Controller;
363 sub bar : Path('foo/bar') { }
365 Literal C<Path> actions will act relative to their current
366 namespace. The above example matches only
367 http://localhost:3000/my/controller/foo/bar. If you start your path with
368 a forward slash, it will match from the root. Example:
370 package MyApp::Controller::My::Controller;
371 sub bar : Path('/foo/bar') { }
373 Matches only http://localhost:3000/foo/bar.
375 package MyApp::Controller::My::Controller;
378 By leaving the C<Path> definition empty, it will match on the namespace
379 root. The above code matches http://localhost:3000/my/controller.
383 sub bar : Regex('^item(\d+)/order(\d+)$') { }
385 Matches any URL that matches the pattern in the action key, e.g.
386 http://localhost:3000/item23/order42. The '' around the regexp is
387 optional, but perltidy likes it. :)
389 Regex matches act globally, i.e. without reference to the namespace from
390 which it is called, so that a C<bar> method in the
391 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
392 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
393 explicitly put this in the regex. To achieve the above, you should
394 consider using a C<LocalRegex> action.
396 =item * B<LocalRegex>
398 sub bar : LocalRegex('^widget(\d+)$') { }
400 LocalRegex actions act locally. If you were to use C<bar> in
401 C<MyApp::Controller::Catalog>, the above example would match urls like
402 http://localhost:3000/catalog/widget23.
404 If you omit the "C<^>" from your regex, then it will match any depth
405 from the controller and not immediately off of the controller name. The
406 following example differs from the above code in that it will match
407 http://localhost:3000/catalog/foo/widget23 as well.
409 package MyApp::Controller::Catalog;
410 sub bar : LocalRegex('widget(\d+)$') { }
412 For both LocalRegex and Regex actions, if you use capturing parentheses
413 to extract values within the matching URL, those values are available in
414 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
415 would capture "23" in the above example, and
416 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
417 arguments at the end of your URL, you must use regex action keys. See
418 L</URL Path Handling> below.
422 The C<Chained> attribute allows you to chain public path parts together
423 by their private names. A chain part's path can be specified with C<PathPart>
424 and can be declared to expect an arbitrary number of arguments. The endpoint
425 of the chain specifies how many arguments it gets through the C<Args>
426 attribute. C<:Args(0)> would be none at all, C<:Args> without an integer
427 would be unlimited. The path parts that aren't endpoints are using
428 C<Captures> to specify how many parameters they expect to receive. As an
431 package MyApp::Controller::Greeting;
432 use base qw/ Catalyst::Controller /;
434 # this is the beginning of our chain
435 sub hello : PathPart('hello') Chained('/') Captures(1) {
436 my ( $self, $c, $integer ) = @_;
437 $c->stash->{ message } = "Hello ";
438 $c->stash->{ arg_sum } = $integer;
441 # this is our endpoint, because it has no :Captures
442 sub world : PathPart('world') Chained('hello') Args(1) {
443 my ( $self, $c, $integer ) = @_;
444 $c->stash->{ message } .= "World!";
445 $c->stash->{ arg_sum } += $integer;
447 $c->response->body( join "<br/>\n" =>
448 $c->stash->{ message }, $c->stash->{ arg_sum } );
451 The debug output provides a separate table for chained actions, showing
452 the whole chain as it would match and the actions it contains. Here's
453 an example of the startup output with our actions above:
456 [debug] Loaded Path Part actions:
457 .-----------------------+------------------------------.
458 | Path Spec | Private |
459 +-----------------------+------------------------------+
460 | /hello/*/world/* | /greeting/hello (1) |
461 | | => /greeting/world |
462 '-----------------------+------------------------------'
465 As you can see, Catalyst only deals with chains as whole path and
466 builds one for each endpoint, which are the actions with C<:Chained>
467 but without C<:Captures>.
469 Let's assume this application gets a request at the path
470 C</hello/23/world/12>, what happens then? First, Catalyst will dispatch
471 to the C<hello> action and pass the value C<23> as argument to it after
472 the context. It does so because we have previously used C<:Captures(1)>
473 to declare that it has one path part after itself as it's argument. We
474 told Catalyst that this is the beginning of the chain by specifying
475 C<:Chained('/')>. Also note that instead of saying C<:PathPart('hello')>
476 we could also just have said C<:PathPart>, as it defaults to the name of
479 After C<hello> has run, Catalyst goes on to dispatch to the C<world>
480 action. This is the last action to be called, as Catalyst knows this
481 is an endpoint because we specified no C<:Captures> attribute. Nevertheless
482 we specify that this action expects an argument, but at this point we're
483 using C<:Args(1)> to do that. We could also have said C<:Args> or leave
484 it out alltogether, which would mean this action gets all arguments that
485 are there. This action's C<:Chained> attribute says C<hello> and tells
486 Catalyst that the C<hello> action in the current controller is it's
489 With this we have built a chain consisting of two public path parts.
490 C<hello> captures one part of the path as it's argument, and also specifies
491 the path root as it's parent. So this part is C</hello/$arg>. The next part
492 is the endpoint C<world>, expecting one argument. It sums up to the path
493 part C<world/$arg>. This leads to a complete chain of
494 C</hello/$arg/world/$arg> which is matched against the requested paths.
496 This example application would, if run and called by e.g.
497 C</hello/23/world/12>, set the stash value C<message> to C<Hello > and
498 the value C<arg_sum> to C<23>. The C<world> action would then append
499 C<World!> to C<message> and add C<12> to the stash's C<arg_sum> value.
500 For the sake of simplicity no view is shown. Instead we just put the
501 values of the stash into our body. So the output would look like:
506 And our test server would've given us this debugging output for the
510 [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
511 [debug] Path is "/greeting/world"
512 [debug] Arguments are "12"
513 [info] Request took 0.164113s (6.093/s)
514 .------------------------------------------+-----------.
516 +------------------------------------------+-----------+
517 | /greeting/hello | 0.000029s |
518 | /greeting/world | 0.000024s |
519 '------------------------------------------+-----------'
522 What would be common usecases of this dispatching technique? It gives the
523 possibility to split up logic that contains steps that each depend on each
524 other. An example would be, for example, a wiki path like
525 C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
528 sub wiki : PathPart('wiki') Chained('/') Captures(1) {
529 my ( $self, $c, $page_name ) = @_;
530 # load the page named $page_name and put the object
534 sub rev : PathPart('rev') Chained('wiki') Captures(1) {
535 my ( $self, $c, $revision_id ) = @_;
536 # use the page object in the stash to get at it's
537 # revision with number $revision_id
540 sub view : PathPart Chained('rev') Args(0) {
541 my ( $self, $c ) = @_;
542 # display the revision in our stash. An other option
543 # would be to forward a compatible object to the action
544 # that displays the default wiki pages, unless we want
545 # a different interface here, for example restore
549 It would now be possible to add other endpoints. For example C<restore> to
550 restore this specific revision as current state.
552 Also, you of course don't have to put all the chained actions in one
553 controller. The specification of the parent through C<:Chained> also takes
554 an absolute action path as it's argument. Just specify it with a leading
557 If you want, for example, to have actions for the public paths
558 C</foo/12/edit> and C</foo/12>, just specify two actions with
559 C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
560 path needs a C<:Captures(1)> attribute and a endpoint with
561 C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
562 the action just a C<:Args(1)> to mark it as endpoint. This sums up to
563 this debugging output:
566 [debug] Loaded Path Part actions:
567 .-----------------------+------------------------------.
568 | Path Spec | Private |
569 +-----------------------+------------------------------+
570 | /foo/* | /controller/foo_view |
571 | /foo/*/edit | /controller/foo_load (1) |
572 | | => /controller/edit |
573 '-----------------------+------------------------------'
576 Here's a more detailed specification of the attributes belonging to
583 Sets the name of this part of the chain. If it is specified without
584 arguments, it takes the name of the action as default. So basically
585 C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
586 This can also contain slashes to bind to a deeper level. An action
587 with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
588 C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
589 effect as using C<:PathPart>, it would default to the action name.
593 Has to be specified for every child in the chain. Possible values are
594 absolute and relative private action paths, with the relatives pointing
595 to the current controller, or a single slash C</> to tell Catalyst that
596 this is the root of a chain. The attribute C<:Chained> without aguments
597 also defaults to the C</> behaviour.
599 Due to the fact that you can specify an absolute path to the parent
600 action, it doesn't matter to Catalyst where that parent is located. So,
601 if your design requests it, you can redispatch a chain through every
602 controller or namespace you want.
604 Another interesting possibility gives C<:Chained('.')>, which chains
605 itself to an action with the path of the current controllers namespace.
608 # in MyApp::Controller::Foo
609 sub bar : Chained Captures(1) { ... }
611 # in MyApp::Controller::Foo::Bar
612 sub baz : Chained('.') Args(1) { ... }
614 This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
615 as argument to Chained here chains the C<baz> action to an action with
616 the path of the current controller namespace, namely C</foo/bar>. That
617 action chains directly to C</>, so the above chain comes out as end
622 Also has to be specified for every part of the chain that is not an
623 endpoint. With this attribute Catalyst knows how many of the following
624 parts of the path (separated by C</>) this action wants to captures as
625 it's arguments. If it doesn't expect any, just specify C<:Captures(0)>.
626 The captures get passed to the action's C<@_> right after the context,
627 but you can also find them as array reference in
628 C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
629 level of the action in the chain that captured the parts of the path.
631 An action that is part of a chain (read: that has a C<:Chained> attribute)
632 but has no C<:Captures> attribute is treated by Catalyst as a chain end.
636 By default, endpoints receive the rest of the arguments in the path. You
637 can tell Catalyst through C<:Args> explicitly how many arguments your
638 endpoint expects, just like you can with C<:Captures>. Note that this
639 also influences if this chain is invoked on a request. A chain with an
640 endpoint specifying one argument will only match if exactly one argument
643 You can specify an exact number of arguments like C<:Args(3)>, including
644 C<0>. If you just say C<:Args> without any arguments, it is the same as
645 leaving it out alltogether: The chain is matched independent of the number
646 of path parts after the endpoint.
648 Just like with C<:Captures>, the arguments get passed to the action in
649 C<@_> after the context object. They can also be reached through
650 C<$c-E<gt>request-E<gt>arguments>.
654 Note that the list of C<auto> actions called depends on the private path
655 of the endpoint of the chain, not on the chained actions way. The C<auto>
656 actions will be run before the chain dispatching begins. In every other
657 aspect, C<auto> actions behave as documented.
659 The C<forward>ing to other actions does just what you would expect. But if
660 you C<detach> out of a chain, the rest of the chain will not get called
661 after the C<detach> returned.
663 =item * B<Top-level> (B<Global>)
665 package MyApp::Controller::Foo;
668 Matches http://localhost:3000/foo. The function name is mapped
669 directly to the application base. You can provide an equivalent
670 function in this case by doing the following:
672 package MyApp::Controller::Root
675 =item * B<Namespace-Prefixed> (B<Local>)
677 package MyApp::Controller::My::Controller;
680 Matches http://localhost:3000/my/controller/foo.
682 This action type indicates that the matching URL must be prefixed with a
683 modified form of the component's class (package) name. This modified
684 class name excludes the parts that have a pre-defined meaning in
685 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
686 "/", and converts the name to lower case. See L</Components> for a full
687 explanation of the pre-defined meaning of Catalyst component class
692 sub foo : Private { }
694 Matches no URL, and cannot be executed by requesting a URL that
695 corresponds to the action key. Private actions can be executed only
696 inside a Catalyst application, by calling the C<forward> method:
700 See L</Flow Control> for a full explanation of C<forward>. Note that, as
701 discussed there, when forwarding from another component, you must use
702 the absolute path to the method, so that a private C<bar> method in your
703 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
704 from elsewhere, be reached with
705 C<$c-E<gt>forward('/catalog/order/process/bar')>.
709 Args is not an action type per se, but an action modifier - it adds a match
710 restriction to any action it's provided to, requiring only as many path parts
711 as are specified for the action to be valid - for example in
712 MyApp::Controller::Foo,
716 would match any URL starting /foo/bar/. To restrict this you can do
718 sub bar :Local :Args(1)
720 to only match /foo/bar/*/
724 B<Note:> After seeing these examples, you probably wonder what the point
725 is of defining names for regex and path actions. Every public action is
726 also a private one, so you have one unified way of addressing components
729 =head4 Built-in Private Actions
731 In response to specific application states, Catalyst will automatically
732 call these built-in private actions in your application class:
736 =item * B<default : Private>
738 Called when no other action matches. Could be used, for example, for
739 displaying a generic frontpage for the main app, or an error page for
740 individual controllers.
742 If C<default> isn't acting how you would expect, look at using a
743 L</Literal> C<Path> action (with an empty path string). The difference is
744 that C<Path> takes arguments relative from the namespace and C<default>
745 I<always> takes arguments relative from the root, regardless of what
748 =item * B<index : Private>
750 C<index> is much like C<default> except that it takes no arguments
751 and it is weighted slightly higher in the matching process. It is
752 useful as a static entry point to a controller, e.g. to have a static
753 welcome page. Note that it's also weighted higher than Path.
755 =item * B<begin : Private>
757 Called at the beginning of a request, before any matching actions are
760 =item * B<end : Private>
762 Called at the end of a request, after all matching actions are called.
766 =head4 Built-in actions in controllers/autochaining
768 Package MyApp::Controller::Foo;
769 sub begin : Private { }
770 sub default : Private { }
771 sub auto : Private { }
773 You can define built-in private actions within your controllers as
774 well. The actions will override the ones in less-specific controllers,
775 or your application class. In other words, for each of the three
776 built-in private actions, only one will be run in any request
777 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
778 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
779 and C<MyApp::Controller::Catalog::Order::begin> would override this in
782 In addition to the normal built-in actions, you have a special action
783 for making chains, C<auto>. Such C<auto> actions will be run after any
784 C<begin>, but before your action is processed. Unlike the other
785 built-ins, C<auto> actions I<do not> override each other; they will be
786 called in turn, starting with the application class and going through to
787 the I<most> specific class. I<This is the reverse of the order in which
788 the normal built-ins override each other>.
790 Here are some examples of the order in which the various built-ins
795 =item for a request for C</foo/foo>
799 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
802 =item for a request for C</foo/bar/foo>
804 MyApp::Controller::Foo::Bar::begin
806 MyApp::Controller::Foo::auto
807 MyApp::Controller::Foo::Bar::auto
808 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
809 MyApp::Controller::Foo::Bar::end
813 The C<auto> action is also distinguished by the fact that you can break
814 out of the processing chain by returning 0. If an C<auto> action returns
815 0, any remaining actions will be skipped, except for C<end>. So, for the
816 request above, if the first auto returns false, the chain would look
821 =item for a request for C</foo/bar/foo> where first C<auto> returns
824 MyApp::Controller::Foo::Bar::begin
826 MyApp::Controller::Foo::Bar::end
830 An example of why one might use this is an authentication action: you
831 could set up a C<auto> action to handle authentication in your
832 application class (which will always be called first), and if
833 authentication fails, returning 0 would skip any remaining methods
836 B<Note:> Looking at it another way, C<auto> actions have to return a
837 true value to continue processing! You can also C<die> in the autochain
838 action; in that case, the request will go straight to the finalize
839 stage, without processing further actions.
841 =head4 URL Path Handling
843 You can pass variable arguments as part of the URL path, separated with
844 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
845 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
846 where C<$bar> and C<$baz> may vary:
848 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
850 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
852 sub boo : Path('foo/boo') { .. }
853 sub hoo : Path('foo/boo/hoo') { .. }
855 Catalyst matches actions in most specific to least specific order:
859 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
861 So Catalyst would never mistakenly dispatch the first two URLs to the
864 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
865 still match a URL containing arguments, however the arguments won't be
868 =head4 Parameter Processing
870 Parameters passed in the URL query string are handled with methods in
871 the L<Catalyst::Request> class. The C<param> method is functionally
872 equivalent to the C<param> method of C<CGI.pm> and can be used in
873 modules that require this.
875 # http://localhost:3000/catalog/view/?category=hardware&page=3
876 my $category = $c->req->param('category');
877 my $current_page = $c->req->param('page') || 1;
879 # multiple values for single parameter name
880 my @values = $c->req->param('scrolling_list');
882 # DFV requires a CGI.pm-like input hash
883 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
887 You control the application flow with the C<forward> method, which
888 accepts the key of an action to execute. This can be an action in the
889 same or another Catalyst controller, or a Class name, optionally
890 followed by a method name. After a C<forward>, the control flow will
891 return to the method from which the C<forward> was issued.
893 A C<forward> is similar to a method call. The main differences are that
894 it wraps the call in an C<eval> to allow exception handling; it
895 automatically passes along the context object (C<$c> or C<$context>);
896 and it allows profiling of each call (displayed in the log with
900 my ( $self, $c ) = @_;
901 $c->stash->{message} = 'Hello World!';
902 $c->forward('check_message'); # $c is automatically included
905 sub check_message : Private {
906 my ( $self, $c ) = @_;
907 return unless $c->stash->{message};
908 $c->forward('show_message');
911 sub show_message : Private {
912 my ( $self, $c ) = @_;
913 $c->res->body( $c->stash->{message} );
916 A C<forward> does not create a new request, so your request object
917 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
918 using C<forward> and issuing a redirect.
920 You can pass new arguments to a C<forward> by adding them
921 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
922 will be changed for the duration of the C<forward> only; upon
923 return, the original value of C<$c-E<gt>req-E<gt>args> will
927 my ( $self, $c ) = @_;
928 $c->stash->{message} = 'Hello World!';
929 $c->forward('check_message',[qw/test1/]);
930 # now $c->req->args is back to what it was before
933 sub check_message : Private {
934 my ( $self, $c ) = @_;
935 my $first_argument = $c->req->args->[0]; # now = 'test1'
939 As you can see from these examples, you can just use the method name as
940 long as you are referring to methods in the same controller. If you want
941 to forward to a method in another controller, or the main application,
942 you will have to refer to the method by absolute path.
944 $c->forward('/my/controller/action');
945 $c->forward('/default'); # calls default in main application
947 Here are some examples of how to forward to classes and methods.
950 my ( $self, $c ) = @_;
951 $c->forward(qw/MyApp::Model::Hello say_hello/);
955 my ( $self, $c ) = @_;
956 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
959 package MyApp::Model::Hello;
962 my ( $self, $c ) = @_;
963 $c->res->body('Hello World!');
967 my ( $self, $c ) = @_;
968 $c->res->body('Goodbye World!');
971 Note that C<forward> returns to the calling action and continues
972 processing after the action finishes. If you want all further processing
973 in the calling action to stop, use C<detach> instead, which will execute
974 the C<detach>ed action and not return to the calling sub. In both cases,
975 Catalyst will automatically try to call process() if you omit the
980 Catalyst has an uncommonly flexible component system. You can define as
981 many L</Models>, L</Views>, and L</Controllers> as you like.
983 All components must inherit from L<Catalyst::Base>, which provides a
984 simple class structure and some common class methods like C<config> and
985 C<new> (constructor).
987 package MyApp::Controller::Catalog;
990 use base 'Catalyst::Base';
992 __PACKAGE__->config( foo => 'bar' );
996 You don't have to C<use> or otherwise register Models, Views, and
997 Controllers. Catalyst automatically discovers and instantiates them
998 when you call C<setup> in the main application. All you need to do is
999 put them in directories named for each Component type. Notice that you
1000 can use a terse alias for each one.
1004 =item * B<MyApp/Model/>
1008 =item * B<MyApp/View/>
1012 =item * B<MyApp/Controller/>
1018 In older versions of Catalyst, the recommended practice (and the one
1019 automatically created by helper scripts) was to name the directories
1020 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
1021 the use of the full names.
1025 To show how to define views, we'll use an already-existing base class for the
1026 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
1027 inherit from this class:
1029 package MyApp::View::TT;
1032 use base 'Catalyst::View::TT';
1036 (You can also generate this automatically by using the helper script:
1038 script/myapp_create.pl view TT TT
1040 where the first C<TT> tells the script that the name of the view should
1041 be C<TT>, and the second that it should be a Template Toolkit view.)
1043 This gives us a process() method and we can now just do
1044 $c->forward('MyApp::View::TT') to render our templates. The base class
1045 makes process() implicit, so we don't have to say
1046 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
1048 sub hello : Global {
1049 my ( $self, $c ) = @_;
1050 $c->stash->{template} = 'hello.tt';
1054 my ( $self, $c ) = @_;
1055 $c->forward('MyApp::View::TT');
1058 You normally render templates at the end of a request, so it's a perfect
1059 use for the global C<end> action.
1061 Also, be sure to put the template under the directory specified in
1062 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
1063 eyecandy debug screen. ;)
1067 To show how to define models, again we'll use an already-existing base
1068 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
1069 We'll also need L<DBIx::Class::Schema::Loader>.
1071 But first, we need a database.
1075 id INTEGER PRIMARY KEY,
1080 id INTEGER PRIMARY KEY,
1081 foo INTEGER REFERENCES foo,
1085 INSERT INTO foo (data) VALUES ('TEST!');
1088 % sqlite /tmp/myapp.db < myapp.sql
1090 Now we can create a DBIC::SchemaLoader component for this database.
1092 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
1094 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
1095 relationships. Use the stash to pass data to your templates.
1097 We add the following to MyApp/Controller/Root.pm
1100 my ( $self, $c, $id ) = @_;
1102 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
1108 my ( $self, $c ) = @_;
1110 $c->stash->{template} ||= 'index.tt';
1111 $c->forward( $c->view('TT') );
1114 We then create a new template file "root/index.tt" containing:
1116 The Id's data is [% item.data %]
1118 Models do not have to be part of your Catalyst application; you
1119 can always call an outside module that serves as your Model:
1123 my ( $self, $c ) = @_;
1125 $c->stash->{template} = 'list.tt';
1127 use Some::Outside::DBIC::Module;
1128 my @records = Some::Outside::DBIC::Module->search({
1132 $c->stash->{records} = \@records;
1135 But by using a Model that is part of your Catalyst application, you gain
1136 several things: you don't have to C<use> each component, Catalyst will
1137 find and load it automatically at compile-time; you can C<forward> to
1138 the module, which can only be done to Catalyst components; and only
1139 Catalyst components can be fetched with
1140 C<$c-E<gt>model('SomeModel')>.
1142 Happily, since many people have existing Model classes that they
1143 would like to use with Catalyst (or, conversely, they want to
1144 write Catalyst models that can be used outside of Catalyst, e.g.
1145 in a cron job), it's trivial to write a simple component in
1146 Catalyst that slurps in an outside Model:
1148 package MyApp::Model::DB;
1149 use base qw/Catalyst::Model::DBIC::Schema/;
1150 __PACKAGE__->config(
1151 schema_class => 'Some::DBIC::Schema',
1152 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
1156 and that's it! Now C<Some::DBIC::Schema> is part of your
1157 Cat app as C<MyApp::Model::DB>.
1161 Multiple controllers are a good way to separate logical domains of your
1164 package MyApp::Controller::Login;
1166 use base qw/Catalyst::Controller/;
1168 sub sign_in : Path("sign-in") { }
1169 sub new_password : Path("new-password") { }
1170 sub sign_out : Path("sign-out") { }
1172 package MyApp::Controller::Catalog;
1174 use base qw/Catalyst::Controller/;
1176 sub view : Local { }
1177 sub list : Local { }
1179 package MyApp::Controller::Cart;
1181 use base qw/Catalyst::Controller/;
1184 sub update : Local { }
1185 sub order : Local { }
1187 Note that you can also supply attributes via the Controller's config so long
1188 as you have at least one attribute on a subref to be exported (:Action is
1189 commonly used for this) - for example the following is equivalent to the same
1192 package MyApp::Controller::Login;
1194 use base qw/Catalyst::Controller/;
1196 __PACKAGE__->config(
1198 'sign_in' => { Path => 'sign-in' },
1199 'new_password' => { Path => 'new-password' },
1200 'sign_out' => { Path => 'sign-out' },
1204 sub sign_in : Action { }
1205 sub new_password : Action { }
1206 sub sign_out : Action { }
1210 Models are providers of data. This data could come from anywhere - a search
1211 engine index, a database table, etc. Typically the data source does not have
1212 much to do with web applications or Catalyst - it could be used to write an
1213 offline report generator or a command line tool just the same.
1215 The common approach to writing a Catalyst-style model for your application is
1216 wrapping a generic model (e.g. L<DBIx::Class::Schema>, a bunch of XMLs, or
1217 anything really) with an object that contains configuration data, convenience
1218 methods, and so forth.
1220 #### editor: move this part to =head3 Components somehow, right after this
1221 #### section - this will require deeply rephrasing this paragraph.
1223 Technically, within Catalyst a model is a B<component> - an instance of the
1224 model's class belonging to the application. It is important to stress that the
1225 lifetime of these objects is per application, not per request.
1227 While the model base class (L<Catalyst::Model>) provides things like C<config>
1228 and stuff to better integrate the model into the application, sometimes this is
1229 not enough, and the model requires access to C<$c> itself.
1231 Situations where this need might arise include:
1237 Interacting with another model
1241 Using per-request data to control behavior
1245 Using plugins in (for example L<Catalyst::Plugin::Cache>).
1249 From a style perspective usually it's bad to make your model "too smart"
1250 about things - it should worry about business logic and leave the
1251 integration details to the controllers. If, however, you find that it
1252 does not make sense at all to use an auxillary controller around the
1253 model, and the model's need to access C<$c> cannot be sidestepped, there
1254 exists a power tool called C<ACCEPT_CONTEXT>.
1256 #### editor note: this part is "generic" - it also applies to views and
1259 =head3 ACCEPT_CONTEXT
1261 Whenever you call $c->component("Foo") you get back an object - the
1262 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
1263 method instead of returning the model itself, the return value of C<<
1264 $model->ACCEPT_CONTEXT( $c ) >> will be used.
1266 This means that whenever your model/view/controller needs to talk to C<$c> it
1267 gets a chance to do this when it's needed.
1269 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
1270 with the context object set, or it will return a thin wrapper that contains
1271 C<$c> and delegates to the per-application model object.
1273 A typical C<ACCEPT_CONTEXT> method could look like this:
1275 sub ACCEPT_CONTEXT {
1276 my ( $self, $c, @extra_arguments ) = @_;
1277 bless { %$self, c => $c }, ref($self);
1280 effectively treating $self as a B<prototype object> that gets a new parameter.
1281 C<@extra_arguments> comes from any trailing arguments to
1282 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
1283 C<< $c->view(...) >> etc).
1285 The life time of this value is B<per usage>, and not per request. To make this
1286 per request you can use the following technique:
1288 Add a field to C<$c>, like C<my_model_instance>. Then write your
1289 C<ACCEPT_CONTEXT> method to look like this:
1291 sub ACCEPT_CONTEXT {
1292 my ( $self, $c ) = @_;
1294 if ( my $per_request = $c->my_model_instance ) {
1295 return $per_request;
1297 my $new_instance = bless { %$self, c => $c }, ref($self);
1298 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
1299 $c->my_model_instance( $new_instance );
1300 return $new_instance;
1307 Catalyst has a built-in http server for testing. (Later, you can easily
1308 use a more powerful server, e.g. Apache/mod_perl or FastCGI, in a
1309 production environment.)
1311 Start your application on the command line...
1313 script/myapp_server.pl
1315 ...then visit http://localhost:3000/ in a browser to view the output.
1317 You can also do it all from the command line:
1319 script/myapp_test.pl http://localhost/
1327 Join #catalyst on irc.perl.org.
1331 http://lists.rawmode.org/mailman/listinfo/catalyst
1332 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1336 Sebastian Riedel, C<sri@oook.de>
1337 David Naughton, C<naughton@umn.edu>
1338 Marcus Ramberg, C<mramberg@cpan.org>
1339 Jesse Sheidlower, C<jester@panix.com>
1340 Danijel Milicevic, C<me@danijel.de>
1341 Kieren Diment, C<kd@totaldatasolution.com>
1342 Yuval Kogman, C<nothingmuch@woobling.org>
1346 This program is free software, you can redistribute it and/or modify it
1347 under the same terms as Perl itself.