3 Catalyst::Manual::Intro - Introduction to Catalyst
7 This is a brief overview of why and how to use Catalyst. It explains how
8 Catalyst works and shows how to get a simple application up and running quickly.
10 =head2 What is Catalyst?
12 Catalyst is an elegant web application framework, extremely flexible yet
13 extremely simple. It's similar to Ruby on Rails, Spring (Java) and L<Maypole>,
14 upon which it was originally based.
18 Catalyst follows the Model-View-Controller (MVC) design pattern, allowing you to
19 easily separate concerns, like content, presentation, and flow control, into
20 separate modules. This separation allows you to modify code that handles one
21 concern without affecting code that handles the others. Catalyst promotes the
22 re-use of existing Perl modules that already handle common web application
25 Here's how the M, V, and C map to those concerns, with examples of well-known
26 Perl modules you may want to use for each.
32 Access and modify content (data). L<Class::DBI>, L<Plucene>, L<Net::LDAP>...
36 Present content to the user. L<Template Toolkit|Template>, L<Mason|HTML::Mason>,
41 Control the whole request phase, check parameters, dispatch actions, flow
46 If you're unfamiliar with MVC and design patterns, you may want to check out the
47 original book on the subject, I<Design Patterns>, by Gamma, Helm, Johson and
48 Vlissides, also known as the Gang of Four (GoF). You can also just google it.
49 Many, many web application frameworks are based on MVC, including all those
54 Catalyst is much more flexible than many other frameworks. We'll talk more about
55 this later, but rest assured you can use your favorite Perl modules with
60 =item * B<Multiple Models, Views, and Controllers>
62 To build a Catalyst application, you handle each type of concern inside special
63 modules called L</Components>. Often this code will be very simple, just calling
64 out to Perl modules like those listed above under L</MVC>. Catalyst handles
65 these components in a very flexible way. Use as many Models, Views, and
66 Controllers as you like, using as many different Perl modules as you like, all
67 in the same application. Want to manipulate multiple databases, and retrieve
68 some data via LDAP? No problem. Want to present data from the same Model using
69 L<Template Toolkit|Template> and L<PDF::Template>? Easy.
71 =item * B<Reuseable Components>
73 Not only does Catalyst promote the re-use of already existing Perl modules, it
74 also allows you to re-use your Catalyst components in multiple Catalyst
77 =item * B<Unrestrained URL-to-Action Dispatching>
79 Catalyst allows you to dispatch any URLs to any application L<Actions>, even
80 through regular expressions! Unlike most other frameworks, it doesn't require
81 mod_rewrite or class and method names in URLs.
83 With Catalyst you register your actions and address them directly. For example:
86 my ( $self, $context ) = @_;
87 $context->response->output('Hello World!');
90 Now http://localhost:3000/hello prints "Hello World!".
92 =item * B<Support for CGI, mod_perl, Apache::Request>
94 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
100 The best part is that Catalyst implements all this flexibility in a very simple
105 =item * B<Building Block Interface>
107 Components interoperate very smoothly. For example, Catalyst automatically makes
108 a L<Context> object available to every component. Via the context, you can
109 access the request object, share data between components, and control the flow
110 of your application. Building a Catalyst application feels a lot like snapping
111 together toy building blocks, and everything just works.
113 =item * B<Component Auto-Discovery>
115 No need to C<use> all of your components. Catalyst automatically finds and loads
118 =item * B<Pre-Built Components for Popular Modules>
120 See L<Catalyst::Model::CDBI> for L<Class::DBI>, or L<Catalyst::View::TT> for
121 L<Template Toolkit|Template>. You can even get an instant web database front end
122 with L<Catalyst::Model::CDBI::CRUD>.
124 =item * B<Built-in Test Framework>
126 Catalyst comes with a built-in, lightweight http server and test framework,
127 making it easy to test applications from the command line.
129 =item * B<Helper Scripts>
131 Catalyst provides helper scripts to quickly generate running starter code for
132 components and unit tests.
138 Here's how to install Catalyst and get a simple application up and running,
139 using the helper scripts described above.
143 $ perl -MCPAN -e 'install Bundle::Catalyst'
150 $ script/myapp_create.pl controller Library::Login
154 $ script/myapp_server.pl
156 Now visit these locations with your favorite browser or user agent to see
161 =item http://localhost:3000/
163 =item http://localhost:3000/library/login/
171 Let's see how Catalyst works, by taking a closer look at the components and
172 other parts of a Catalyst application.
174 =head3 Application Class
176 In addition to the Model, View, and Controller components, there's a single
177 class that represents your application itself. This is where you configure your
178 application, load plugins, define application-wide actions, and extend Catalyst.
183 use Catalyst qw/-Debug/;
186 name => 'My Application',
187 root => '/home/joeuser/myapp/root',
189 # You can put anything else you want in here:
190 my_configuration_variable => 'something',
193 sub default : Private {
194 my ( $self, $context ) = @_;
195 $context->response->output('Catalyst rockz!');
200 For most applications, Catalyst requires you to define only two config
207 Name of your application.
211 Path to additional files such as templates, images, or other static data.
215 However, you can define as many parameters as you want for plugins or whatever
216 you need. You can access them anywhere in your application via
217 C<$context-E<gt>config-E<gt>{$param_name}>.
221 Catalyst automatically blesses a Context object into your application class and
222 makes it available everywhere in your application. Use the Context to directly
223 interact with Catalyst and glue your L<Components> together. For example, if you
224 need to use the Context from within a Template Toolkit template, it's already
227 <h1>Welcome to [% c.config.name %]!</h1>
229 As illustrated earlier in our URL-to-Action dispatching example, the Context is
230 always the second method parameter, behind the Component object reference or
231 class name itself. Previously we called it C<$context> for clarity, but most
232 Catalyst developers just call it C<$c>:
235 my ( $self, $c ) = @_;
236 $c->res->output('Hello World!');
239 The Context contains several important objects:
243 =item * L<Catalyst::Request>
248 The request object contains all kinds of request-specific information, like
249 query parameters, cookies, uploads, headers, and more.
251 $c->req->params->{foo};
252 $c->req->cookies->{sessionid};
253 $c->req->headers->content_type;
256 =item * L<Catalyst::Response>
261 The response is like the request, but contains just response-specific
264 $c->res->output('Hello World');
265 $c->res->status(404);
266 $c->res->redirect('http://oook.de');
268 =item * L<Catalyst::Config>
275 =item * L<Catalyst::Log>
279 $c->log->debug('Something happened');
280 $c->log->info('Something you should know');
286 $c->stash->{foo} = 'bar';
290 The last of these, the stash, is a universal hash for sharing data among
291 application components. For an example, we return to our 'hello' action:
294 my ( $self, $c ) = @_;
295 $c->stash->{message} = 'Hello World!';
296 $c->forward('show_message');
299 sub show_message : Private {
300 my ( $self, $c ) = @_;
301 $c->res->output( $c->stash->{message} );
304 Note that the stash should be used only for passing data in an individual
305 request cycle; it gets cleared at a new request. If you need to maintain more
306 persistent data, use a session.
310 A Catalyst controller is defined by its actions. An action is a sub with a
311 special attribute. You've already seen some examples of actions in this
312 document. The URL (for example http://localhost.3000/foo/bar) consists of two
313 parts, the base (http://localhost:3000/ in this example) and the path (foo/bar).
314 Please note that the trailing slash after the hostname[:port] always belongs to
315 base and not to the action.
317 Catalyst supports several types of actions:
323 sub bar : Path('foo/bar') { }
325 Matches only http://localhost:3000/foo/bar.
329 sub bar : Regex('^item(\d+)/order(\d+)$') { }
331 Matches any URL that matches the pattern in the action key, e.g.
332 http://localhost:3000/item23/order42. The '' around the regexp is optional, but
333 perltidy likes it. :)
335 Regex matches act globally, i.e. without reference to the namespace from which
336 it is called, so that a C<bar> method in the
337 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any form of
338 C<bar>, C<Catalog>, C<Order>, or C<Process> unless you explicitly put this in
341 If you use capturing parentheses to extract values within the matching URL (23,
342 42 in the above example), those values are available in the $c->req->snippets
343 array. If you want to pass arguments at the end of your URL, you must use regex
344 action keys. See L</URL Argument Handling> below.
351 Matches http://localhost:3000/foo. The function name is mapped directly
352 to the application base.
354 =item * B<Namespace-Prefixed>
356 package MyApp::C::My::Controller;
359 Matches http://localhost:3000/my/controller/foo.
361 This action type indicates that the matching URL must be prefixed with a
362 modified form of the component's class (package) name. This modified class name
363 excludes the parts that have a pre-defined meaning in Catalyst ("MyApp::C" in
364 the above example), replaces "::" with "/", and converts the name to lower case.
365 See L</Components> for a full explanation of the pre-defined meaning of Catalyst
366 component class names.
370 sub foo : Private { }
372 Matches no URL, and cannot be executed by requesting a URL that corresponds to
373 the action key. Private actions can be executed only inside a Catalyst
374 application, by calling the C<forward> method:
378 See L</Flow Control> for a full explanation of C<forward>. Note that, as
379 discussed there, when forwarding from another component, you must use
380 the absolute path to the method, so that a private C<bar> method in your
381 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
382 from elsewhere, be reached with
383 C<$c-E<gt>forward('/catalog/order/process/bar')>.
387 B<Note:> After seeing these examples, you probably wonder what the point
388 is of defining names for regex and path actions. Actually, every public
389 action is also a private one, so you have one unified way of addressing
390 components in your C<forward>s.
392 =head4 Built-in Private Actions
394 In response to specific application states, Catalyst will automatically
395 call these built-in private actions in your application class:
399 =item * B<default : Private>
401 Called when no other action matches. Could be used, for example, for
402 displaying a generic frontpage for the main app, or an error page for
403 individual controllers.
405 =item * B<begin : Private>
407 Called at the beginning of a request, before any matching actions are
410 =item * B<end : Private>
412 Called at the end of a request, after all matching actions are called.
416 =head4 B<Built-in actions in controllers/autochaining>
418 Package MyApp::C::Foo;
419 sub begin : Private { }
420 sub default : Private { }
422 You can define built-in private actions within your controllers as
423 well. The actions will override the ones in less-specific controllers,
424 or your application class. In other words, for each of the three
425 built-in private actions, only one will be run in any request
426 cycle. Thus, if C<MyApp::C::Catalog::begin> exists, it will be run in
427 place of C<MyApp::begin> if you're in the C<catalog> namespace, and
428 C<MyApp::C::Catalog::Order::begin> would override this in turn.
430 In addition to the normal built-ins, you have a special action for
431 making chains, C<auto>. Such C<auto> actions will be run after any
432 C<begin>, but before your action is processed. Unlike the other
433 built-ins, C<auto> actions I<do not> override each other; they will
434 be called in turn, starting with the application class and going
435 through to the I<most> specific class. I<This is the reverse of the
436 order in which the normal built-ins override each other>.
438 Here are some examples of the order in which the various built-ins
443 =item for a request for C</foo/foo>
447 MyApp::C::Foo::default # in the absence of MyApp::C::Foo::Foo
450 =item for a request for C</foo/bar/foo>
452 MyApp::C::Foo::Bar::begin
455 MyApp::C::Foo::Bar::auto
456 MyApp::C::Foo::Bar::default # for MyApp::C::Foo::Bar::foo
457 MyApp::C::Foo::Bar::end
461 The C<auto> action is also distinguished by the fact that you can break
462 out of the processing chain by returning 0. If an C<auto> action returns
463 0, any remaining actions will be skipped, except for C<end>. So, for the
464 request above, if the first auto returns false, the chain would look
469 =item for a request for C</foo/bar/foo> where first C<auto> returns
472 MyApp::C::Foo::Bar::begin
474 MyApp::C::Foo::Bar::end
478 An example of why one might use this is an authentication action: you
479 could set up a C<auto> action to handle authentication in your
480 application class (which will always be called first), and if
481 authentication fails, returning 0 would skip any remaining methods
484 B<Note:> Looking at it another way, C<auto> actions have to return a
485 true value to continue processing! You can also C<die> in the autochain
486 action; in that case, the request will go straight to the finalize
487 stage, without processing further actions.
489 =head4 B<URL Path Handling>
491 You can pass variable arguments as part of the URL path. In this case,
492 you must use regex action keys with '^' and '$' anchors, and the
493 arguments must be separated with forward slashes (/) in the URL. For
494 example, suppose you want to handle C</foo/$bar/$baz>, where C<$bar> and
497 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
499 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
501 sub boo : Path('foo/boo') { .. }
502 sub hoo : Path('foo/boo/hoo') { .. }
504 Catalyst matches actions in most specific to least specific order:
508 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
510 So Catalyst would never mistakenly dispatch the first two URLs to the
513 =head4 B<Parameter Processing>
515 Parameters passed in the URL query string are handled with methods in
516 the L<Catalyst::Request> class. The C<param> method is functionally
517 equivalent to the C<param> method of C<CGI.pm> and can be used in
518 modules that require this.
520 # http://localhost:3000/catalog/view/?category=hardware&page=3
521 my $category = $c->req->param('category');
522 my $current_page = $c->req->param('page') || 1;
524 # multiple values for single parameter name
525 my @values = $c->req->param('scrolling_list');
527 # DFV requires a CGI.pm-like input hash
528 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
532 You control the application flow with the C<forward> method, which
533 accepts the key of an action to execute. This can be an action in the
534 same or another Catalyst controller, or a Class name, optionally
535 followed by a method name. After a C<forward>, the control flow will
536 return to the method from which the C<forward> was issued.
538 A C<forward> is similar to a method call. The main differences are that
539 it wraps the call in an C<eval> to allow exception handling; it
540 automatically passes along the context object (C<$c> or C<$context>);
541 and it allows profiling of each call (displayed in the log with
545 my ( $self, $c ) = @_;
546 $c->stash->{message} = 'Hello World!';
547 $c->forward('check_message'); # $c is automatically included
550 sub check_message : Private {
551 my ( $self, $c ) = @_;
552 return unless $c->stash->{message};
553 $c->forward('show_message');
556 sub show_message : Private {
557 my ( $self, $c ) = @_;
558 $c->res->output( $c->stash->{message} );
561 A C<forward> does not create a new request, so your request
562 object (C<$c-E<gt>req>) will remain unchanged. This is a
563 key difference between using C<forward> and issuing a
566 You can pass new arguments to a C<forward> by adding them
567 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
568 will be changed for the duration of the C<forward> only; upon
569 return, the original value of C<$c-E<gt>req-E<gt>args> will
573 my ( $self, $c ) = @_;
574 $c->stash->{message} = 'Hello World!';
575 $c->forward('check_message',[qw/test1/]);
576 # now $c->req->args is back to what it was before
579 sub check_message : Private {
580 my ( $self, $c ) = @_;
581 my $first_argument = $c->req->args[0]; # now = 'test1'
585 As you can see from these examples, you can just use the method name as
586 long as you are referring to methods in the same controller. If you want
587 to forward to a method in another controller, or the main application,
588 you will have to refer to the method by absolute path.
590 $c->forward('/my/controller/action');
591 $c->forward('/default'); # calls default in main application
593 Here are some examples of how to forward to classes and methods.
596 my ( $self, $c ) = @_;
597 $c->forward(qw/MyApp::M::Hello say_hello/);
601 my ( $self, $c ) = @_;
602 $c->forward('MyApp::M::Hello'); # no method: will try 'process'
605 package MyApp::M::Hello;
608 my ( $self, $c ) = @_;
609 $c->res->output('Hello World!');
613 my ( $self, $c ) = @_;
614 $c->res->output('Goodbye World!');
617 Note that C<forward> returns to the calling action and continues
618 processing after the action finishes. Catalyst will automatically try
619 to call process() if you omit the method.
623 Catalyst has an uncommonly flexible component system. You can define as many
624 L<Models>, L<Views>, and L<Controllers> as you like.
626 All components must inherit from L<Catalyst::Base>, which provides a simple
627 class structure and some common class methods like C<config> and C<new>
630 package MyApp::C::Catalog;
633 use base 'Catalyst::Base';
635 __PACKAGE__->config( foo => 'bar' );
639 You don't have to C<use> or otherwise register Models, Views, and Controllers.
640 Catalyst automatically discovers and instantiates them when you call C<setup> in
641 the main application. All you need to do is put them in directories named for
642 each Component type. Notice that you can use some very terse aliases for each
647 =item * B<MyApp/Model/>
651 =item * B<MyApp/View/>
655 =item * B<MyApp/Controller/>
663 To show how to define views, we'll use an already-existing base class for the
664 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
665 inherit from this class:
667 package MyApp::V::TT;
670 use base 'Catalyst::View::TT';
674 (You can also generate this automatically by using the helper script:
676 script/myapp_create.pl view TT TT
678 where the first C<TT> tells the script to create a Template Toolkit
679 view, and the second tells the script that its name should be C<TT>.)
681 This gives us a process() method and we can now just do
682 $c->forward('MyApp::V::TT') to render our templates. The base class makes
683 process() implicit, so we don't have to say C<$c-E<gt>forward(qw/MyApp::V::TT
687 my ( $self, $c ) = @_;
688 $c->stash->{template} = 'hello.tt';
692 my ( $self, $c ) = @_;
693 $c->forward('MyApp::V::TT');
696 You normally render templates at the end of a request, so it's a perfect use for
697 the global C<end> action.
699 Also, be sure to put the template under the directory specified in
700 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our eyecandy debug
705 To show how to define models, again we'll use an already-existing base class,
706 this time for L<Class::DBI>: L<Catalyst::Model::CDBI>.
708 But first, we need a database.
712 id INTEGER PRIMARY KEY,
717 id INTEGER PRIMARY KEY,
718 foo INTEGER REFERENCES foo,
722 INSERT INTO foo (data) VALUES ('TEST!');
725 % sqlite /tmp/myapp.db < myapp.sql
727 Now we can create a CDBI component for this database.
729 package MyApp::M::CDBI;
732 use base 'Catalyst::Model::CDBI';
735 dsn => 'dbi:SQLite:/tmp/myapp.db',
741 Catalyst automatically loads table layouts and relationships. Use the stash to
742 pass data to your templates.
747 use Catalyst '-Debug';
750 name => 'My Application',
751 root => '/home/joeuser/myapp/root'
757 my ( $self, $c ) = @_;
758 $c->stash->{template} ||= 'index.tt';
759 $c->forward('MyApp::V::TT');
763 my ( $self, $c, $id ) = @_;
764 $c->stash->{item} = MyApp::M::CDBI::Foo->retrieve($id);
769 The id is [% item.data %]
773 Multiple controllers are a good way to separate logical domains of your
776 package MyApp::C::Login;
779 new-password : Local { }
782 package MyApp::C::Catalog;
787 package MyApp::C::Cart;
790 sub update : Local { }
791 sub order : Local { }
795 Catalyst has a built-in http server for testing! (Later, you can easily use a
796 more powerful server, e.g. Apache/mod_perl, in a production environment.)
798 Start your application on the command line...
800 script/myapp_server.pl
802 ...then visit http://localhost:3000/ in a browser to view the output.
804 You can also do it all from the command line:
806 script/myapp_test.pl http://localhost/
814 Join #catalyst on irc.perl.org.
818 http://lists.rawmode.org/mailman/listinfo/catalyst
819 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
823 Sebastian Riedel, C<sri@oook.de>
824 David Naughton, C<naughton@umn.edu>
825 Marcus Ramberg, C<mramberg@cpan.org>
826 Jesse Sheidlower, C<jester@panix.com>
827 Danijel Milicevic, C<me@danijel.de>
831 This program is free software, you can redistribute it and/or modify it under
832 the same terms as Perl itself.