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!');
355 For most applications, Catalyst requires you to define only one config
360 Catalyst supports several types of actions:
364 =item * B<Literal> (B<Path> actions)
366 package MyApp::Controller::My::Controller;
367 sub bar : Path('foo/bar') { }
369 Literal C<Path> actions will act relative to their current
370 namespace. The above example matches only
371 http://localhost:3000/my/controller/foo/bar. If you start your path with
372 a forward slash, it will match from the root. Example:
374 package MyApp::Controller::My::Controller;
375 sub bar : Path('/foo/bar') { }
377 Matches only http://localhost:3000/foo/bar.
379 package MyApp::Controller::My::Controller;
382 By leaving the C<Path> definition empty, it will match on the namespace
383 root. The above code matches http://localhost:3000/my/controller.
387 sub bar : Regex('^item(\d+)/order(\d+)$') { }
389 Matches any URL that matches the pattern in the action key, e.g.
390 http://localhost:3000/item23/order42. The '' around the regexp is
391 optional, but perltidy likes it. :)
393 Regex matches act globally, i.e. without reference to the namespace from
394 which it is called, so that a C<bar> method in the
395 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
396 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
397 explicitly put this in the regex. To achieve the above, you should
398 consider using a C<LocalRegex> action.
400 =item * B<LocalRegex>
402 sub bar : LocalRegex('^widget(\d+)$') { }
404 LocalRegex actions act locally. If you were to use C<bar> in
405 C<MyApp::Controller::Catalog>, the above example would match urls like
406 http://localhost:3000/catalog/widget23.
408 If you omit the "C<^>" from your regex, then it will match any depth
409 from the controller and not immediately off of the controller name. The
410 following example differs from the above code in that it will match
411 http://localhost:3000/catalog/foo/widget23 as well.
413 package MyApp::Controller::Catalog;
414 sub bar : LocalRegex('widget(\d+)$') { }
416 For both LocalRegex and Regex actions, if you use capturing parentheses
417 to extract values within the matching URL, those values are available in
418 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
419 would capture "23" in the above example, and
420 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
421 arguments at the end of your URL, you must use regex action keys. See
422 L</URL Path Handling> below.
426 sub section :PathPart('section') :ChildOf('/') :Captures(1) { }
428 ChildOf is a powerful way to handle canonical URIs of the form
431 Taking the above URI as an example in Controller::Root you can do the following :-
433 sub section_handler :PathPart('section') :ChildOf('/') :Captures(1) {
434 my ( $self, $c ) = @_;
435 $c->stash->{'section'} =
436 $c->Model('Sections')->find($c->req->captures->[0]);
439 sub item_handler :PathPart('item') :ChildOf('/section_handler') :Args(1) {
440 my ( $self, $c ) = @_;
441 $c->stash->{'item'} =
442 $c->stash->{'section'}->find_related('item',$c->args->[0]);
445 The subroutine section_handler matched the path segment 'section' as a child of '/'. It
446 then took the next path segment, as referenced by :Captures(1) and stashed it in the
447 arrayref $c->req->captures. Since there was also a child of this handler - it also gets run.
448 The same rules apply here - This time however it has the 'Args' attribute which means
449 this particular routine will run if there is exactly 1 argument. See Args below for more
452 It is not important in which controller or on which namespace level a parent action is.
453 Also, there can be more than one action using another one as parent by specifying C<ChildOf>.
457 The action of the parent - for instance, if you have method item_handler in controller
458 SuperMarket::Aisle, the action would be /supermarket/aisle/item_handler. For a root handler
459 this would be '/'. For an action in the same controller namespace you can use a relative
460 name like C<:ChildOf('foo')>.
462 =item PathPart('xyz')
464 The name of this path section in the ChildOf tree mapping to the URI. If you specify
465 C<:PathPart> without arguments, it takes the name of the action specifying the argument.
466 For example, these two declarations have the same effect:
468 sub foo :PathPart('foo') :ChildOf('bar') :Args(1) {
474 sub foo :PathPart :ChildOf('bar') :Args(1) {
478 The value can also contain a slash, for example:
480 sub baz :PathPart('bar/baz') :ChildOf('/') :Captures(1) {
484 would be involved in matches on C</bar/baz/*/...> paths.
488 Will 'collapse' the next x path segments in the request URI and push them into
489 the arrayref $c->req->captures. An action specifying C<Captures> is thought to
490 be used as target for C<ChildOf> specifications. Also see the C<Args> attribute
491 below, which is used for endpoints.
495 The number of path segments to capture at the end of a request URI. This *must* be
496 included in your leaf nodes. You can use Args(0) for an equivalent of the index
498 Args with no parameters will capture every postfixed segment into $c->req->args.
500 A specification of C<Args> is seen as endpoint in regard to an additional
501 C<ChildOf> specification.
503 =item * B<Top-level> (B<Global>)
505 package MyApp::Controller::Foo;
508 Matches http://localhost:3000/foo. The function name is mapped
509 directly to the application base. You can provide an equivalent
510 function in this case by doing the following:
512 package MyApp::Controller::Root
515 =item * B<Namespace-Prefixed> (B<Local>)
517 package MyApp::Controller::My::Controller;
520 Matches http://localhost:3000/my/controller/foo.
522 This action type indicates that the matching URL must be prefixed with a
523 modified form of the component's class (package) name. This modified
524 class name excludes the parts that have a pre-defined meaning in
525 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
526 "/", and converts the name to lower case. See L</Components> for a full
527 explanation of the pre-defined meaning of Catalyst component class
532 sub foo : Private { }
534 Matches no URL, and cannot be executed by requesting a URL that
535 corresponds to the action key. Private actions can be executed only
536 inside a Catalyst application, by calling the C<forward> method:
540 See L</Flow Control> for a full explanation of C<forward>. Note that, as
541 discussed there, when forwarding from another component, you must use
542 the absolute path to the method, so that a private C<bar> method in your
543 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
544 from elsewhere, be reached with
545 C<$c-E<gt>forward('/catalog/order/process/bar')>.
549 Args is not an action type per se, but an action modifier - it adds a match
550 restriction to any action it's provided to, requiring only as many path parts
551 as are specified for the action to be valid - for example in
552 MyApp::Controller::Foo,
556 would match any URL starting /foo/bar/. To restrict this you can do
558 sub bar :Local :Args(1)
560 to only match /foo/bar/*/
564 B<Note:> After seeing these examples, you probably wonder what the point
565 is of defining names for regex and path actions. Every public action is
566 also a private one, so you have one unified way of addressing components
569 =head4 Built-in Private Actions
571 In response to specific application states, Catalyst will automatically
572 call these built-in private actions in your application class:
576 =item * B<default : Private>
578 Called when no other action matches. Could be used, for example, for
579 displaying a generic frontpage for the main app, or an error page for
580 individual controllers.
582 If C<default> isn't acting how you would expect, look at using a
583 L</Literal> C<Path> action (with an empty path string). The difference is
584 that C<Path> takes arguments relative from the namespace and C<default>
585 I<always> takes arguments relative from the root, regardless of what
588 =item * B<index : Private>
590 C<index> is much like C<default> except that it takes no arguments
591 and it is weighted slightly higher in the matching process. It is
592 useful as a static entry point to a controller, e.g. to have a static
593 welcome page. Note that it's also weighted higher than Path.
595 =item * B<begin : Private>
597 Called at the beginning of a request, before any matching actions are
600 =item * B<end : Private>
602 Called at the end of a request, after all matching actions are called.
606 =head4 Built-in actions in controllers/autochaining
608 Package MyApp::Controller::Foo;
609 sub begin : Private { }
610 sub default : Private { }
611 sub auto : Private { }
613 You can define built-in private actions within your controllers as
614 well. The actions will override the ones in less-specific controllers,
615 or your application class. In other words, for each of the three
616 built-in private actions, only one will be run in any request
617 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
618 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
619 and C<MyApp::Controller::Catalog::Order::begin> would override this in
622 In addition to the normal built-in actions, you have a special action
623 for making chains, C<auto>. Such C<auto> actions will be run after any
624 C<begin>, but before your action is processed. Unlike the other
625 built-ins, C<auto> actions I<do not> override each other; they will be
626 called in turn, starting with the application class and going through to
627 the I<most> specific class. I<This is the reverse of the order in which
628 the normal built-ins override each other>.
630 Here are some examples of the order in which the various built-ins
635 =item for a request for C</foo/foo>
639 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
642 =item for a request for C</foo/bar/foo>
644 MyApp::Controller::Foo::Bar::begin
646 MyApp::Controller::Foo::auto
647 MyApp::Controller::Foo::Bar::auto
648 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
649 MyApp::Controller::Foo::Bar::end
653 The C<auto> action is also distinguished by the fact that you can break
654 out of the processing chain by returning 0. If an C<auto> action returns
655 0, any remaining actions will be skipped, except for C<end>. So, for the
656 request above, if the first auto returns false, the chain would look
661 =item for a request for C</foo/bar/foo> where first C<auto> returns
664 MyApp::Controller::Foo::Bar::begin
666 MyApp::Controller::Foo::Bar::end
670 An example of why one might use this is an authentication action: you
671 could set up a C<auto> action to handle authentication in your
672 application class (which will always be called first), and if
673 authentication fails, returning 0 would skip any remaining methods
676 B<Note:> Looking at it another way, C<auto> actions have to return a
677 true value to continue processing! You can also C<die> in the autochain
678 action; in that case, the request will go straight to the finalize
679 stage, without processing further actions.
681 =head4 URL Path Handling
683 You can pass variable arguments as part of the URL path, separated with
684 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
685 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
686 where C<$bar> and C<$baz> may vary:
688 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
690 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
692 sub boo : Path('foo/boo') { .. }
693 sub hoo : Path('foo/boo/hoo') { .. }
695 Catalyst matches actions in most specific to least specific order:
699 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
701 So Catalyst would never mistakenly dispatch the first two URLs to the
704 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
705 still match a URL containing arguments, however the arguments won't be
708 =head4 Parameter Processing
710 Parameters passed in the URL query string are handled with methods in
711 the L<Catalyst::Request> class. The C<param> method is functionally
712 equivalent to the C<param> method of C<CGI.pm> and can be used in
713 modules that require this.
715 # http://localhost:3000/catalog/view/?category=hardware&page=3
716 my $category = $c->req->param('category');
717 my $current_page = $c->req->param('page') || 1;
719 # multiple values for single parameter name
720 my @values = $c->req->param('scrolling_list');
722 # DFV requires a CGI.pm-like input hash
723 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
727 You control the application flow with the C<forward> method, which
728 accepts the key of an action to execute. This can be an action in the
729 same or another Catalyst controller, or a Class name, optionally
730 followed by a method name. After a C<forward>, the control flow will
731 return to the method from which the C<forward> was issued.
733 A C<forward> is similar to a method call. The main differences are that
734 it wraps the call in an C<eval> to allow exception handling; it
735 automatically passes along the context object (C<$c> or C<$context>);
736 and it allows profiling of each call (displayed in the log with
740 my ( $self, $c ) = @_;
741 $c->stash->{message} = 'Hello World!';
742 $c->forward('check_message'); # $c is automatically included
745 sub check_message : Private {
746 my ( $self, $c ) = @_;
747 return unless $c->stash->{message};
748 $c->forward('show_message');
751 sub show_message : Private {
752 my ( $self, $c ) = @_;
753 $c->res->body( $c->stash->{message} );
756 A C<forward> does not create a new request, so your request object
757 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
758 using C<forward> and issuing a redirect.
760 You can pass new arguments to a C<forward> by adding them
761 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
762 will be changed for the duration of the C<forward> only; upon
763 return, the original value of C<$c-E<gt>req-E<gt>args> will
767 my ( $self, $c ) = @_;
768 $c->stash->{message} = 'Hello World!';
769 $c->forward('check_message',[qw/test1/]);
770 # now $c->req->args is back to what it was before
773 sub check_message : Private {
774 my ( $self, $c ) = @_;
775 my $first_argument = $c->req->args->[0]; # now = 'test1'
779 As you can see from these examples, you can just use the method name as
780 long as you are referring to methods in the same controller. If you want
781 to forward to a method in another controller, or the main application,
782 you will have to refer to the method by absolute path.
784 $c->forward('/my/controller/action');
785 $c->forward('/default'); # calls default in main application
787 Here are some examples of how to forward to classes and methods.
790 my ( $self, $c ) = @_;
791 $c->forward(qw/MyApp::Model::Hello say_hello/);
795 my ( $self, $c ) = @_;
796 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
799 package MyApp::Model::Hello;
802 my ( $self, $c ) = @_;
803 $c->res->body('Hello World!');
807 my ( $self, $c ) = @_;
808 $c->res->body('Goodbye World!');
811 Note that C<forward> returns to the calling action and continues
812 processing after the action finishes. If you want all further processing
813 in the calling action to stop, use C<detach> instead, which will execute
814 the C<detach>ed action and not return to the calling sub. In both cases,
815 Catalyst will automatically try to call process() if you omit the
820 Catalyst has an uncommonly flexible component system. You can define as
821 many L</Models>, L</Views>, and L</Controllers> as you like.
823 All components must inherit from L<Catalyst::Base>, which provides a
824 simple class structure and some common class methods like C<config> and
825 C<new> (constructor).
827 package MyApp::Controller::Catalog;
830 use base 'Catalyst::Base';
832 __PACKAGE__->config( foo => 'bar' );
836 You don't have to C<use> or otherwise register Models, Views, and
837 Controllers. Catalyst automatically discovers and instantiates them
838 when you call C<setup> in the main application. All you need to do is
839 put them in directories named for each Component type. Notice that you
840 can use a terse alias for each one.
844 =item * B<MyApp/Model/>
848 =item * B<MyApp/View/>
852 =item * B<MyApp/Controller/>
858 In older versions of Catalyst, the recommended practice (and the one
859 automatically created by helper scripts) was to name the directories
860 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
861 the use of the full names.
865 To show how to define views, we'll use an already-existing base class for the
866 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
867 inherit from this class:
869 package MyApp::View::TT;
872 use base 'Catalyst::View::TT';
876 (You can also generate this automatically by using the helper script:
878 script/myapp_create.pl view TT TT
880 where the first C<TT> tells the script that the name of the view should
881 be C<TT>, and the second that it should be a Template Toolkit view.)
883 This gives us a process() method and we can now just do
884 $c->forward('MyApp::View::TT') to render our templates. The base class
885 makes process() implicit, so we don't have to say
886 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
889 my ( $self, $c ) = @_;
890 $c->stash->{template} = 'hello.tt';
894 my ( $self, $c ) = @_;
895 $c->forward('MyApp::View::TT');
898 You normally render templates at the end of a request, so it's a perfect
899 use for the global C<end> action.
901 Also, be sure to put the template under the directory specified in
902 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
903 eyecandy debug screen. ;)
907 To show how to define models, again we'll use an already-existing base
908 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
909 We'll also need L<DBIx::Class::Schema::Loader>.
911 But first, we need a database.
915 id INTEGER PRIMARY KEY,
920 id INTEGER PRIMARY KEY,
921 foo INTEGER REFERENCES foo,
925 INSERT INTO foo (data) VALUES ('TEST!');
928 % sqlite /tmp/myapp.db < myapp.sql
930 Now we can create a DBIC::SchemaLoader component for this database.
932 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
934 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
935 relationships. Use the stash to pass data to your templates.
937 We add the following to MyApp/Controller/Root.pm
940 my ( $self, $c, $id ) = @_;
942 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
948 my ( $self, $c ) = @_;
950 $c->stash->{template} ||= 'index.tt';
951 $c->forward( $c->view('TT') );
954 We then create a new template file "root/index.tt" containing:
956 The Id's data is [% item.data %]
958 Models do not have to be part of your Catalyst application; you
959 can always call an outside module that serves as your Model:
963 my ( $self, $c ) = @_;
965 $c->stash->{template} = 'list.tt';
967 use Some::Outside::DBIC::Module;
968 my @records = Some::Outside::DBIC::Module->search({
972 $c->stash->{records} = \@records;
975 But by using a Model that is part of your Catalyst application, you gain
976 several things: you don't have to C<use> each component, Catalyst will
977 find and load it automatically at compile-time; you can C<forward> to
978 the module, which can only be done to Catalyst components; and only
979 Catalyst components can be fetched with
980 C<$c-E<gt>model('SomeModel')>.
982 Happily, since many people have existing Model classes that they
983 would like to use with Catalyst (or, conversely, they want to
984 write Catalyst models that can be used outside of Catalyst, e.g.
985 in a cron job), it's trivial to write a simple component in
986 Catalyst that slurps in an outside Model:
988 package MyApp::Model::DB;
989 use base qw/Catalyst::Model::DBIC::Schema/;
991 schema_class => 'Some::DBIC::Schema',
992 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
996 and that's it! Now C<Some::DBIC::Schema> is part of your
997 Cat app as C<MyApp::Model::DB>.
1001 Multiple controllers are a good way to separate logical domains of your
1004 package MyApp::Controller::Login;
1006 use base qw/Catalyst::Controller/;
1008 sub sign_in : Path("sign-in") { }
1009 sub new_password : Path("new-password") { }
1010 sub sign_out : Path("sign-out") { }
1012 package MyApp::Controller::Catalog;
1014 use base qw/Catalyst::Controller/;
1016 sub view : Local { }
1017 sub list : Local { }
1019 package MyApp::Controller::Cart;
1021 use base qw/Catalyst::Controller/;
1024 sub update : Local { }
1025 sub order : Local { }
1027 Note that you can also supply attributes via the Controller's config so long
1028 as you have at least one attribute on a subref to be exported (:Action is
1029 commonly used for this) - for example the following is equivalent to the same
1032 package MyApp::Controller::Login;
1034 use base qw/Catalyst::Controller/;
1036 __PACKAGE__->config(
1038 'sign_in' => { Path => 'sign-in' },
1039 'new_password' => { Path => 'new-password' },
1040 'sign_out' => { Path => 'sign-out' },
1044 sub sign_in : Action { }
1045 sub new_password : Action { }
1046 sub sign_out : Action { }
1050 Models are providers of data. This data could come from anywhere - a search
1051 engine index, a database table, etc. Typically the data source does not have
1052 much to do with web applications or Catalyst - it could be used to write an
1053 offline report generator or a command line tool just the same.
1055 The common approach to writing a Catalyst-style model for your application is
1056 wrapping a generic model (e.g. L<DBIx::Class::Schema>, a bunch of XMLs, or
1057 anything really) with an object that contains configuration data, convenience
1058 methods, and so forth.
1060 #### editor: move this part to =head3 Components somehow, right after this
1061 #### section - this will require deeply rephrasing this paragraph.
1063 Technically, within Catalyst a model is a B<component> - an instance of the
1064 model's class belonging to the application. It is important to stress that the
1065 lifetime of these objects is per application, not per request.
1067 While the model base class (L<Catalyst::Model>) provides things like C<config>
1068 and stuff to better integrate the model into the application, sometimes this is
1069 not enough, and the model requires access to C<$c> itself.
1071 Situations where this need might arise include:
1077 Interacting with another model
1081 Using per-request data to control behavior
1085 Using plugins in (for example L<Catalyst::Plugin::Cache>).
1089 From a style perspective usually it's bad to make your model "too smart"
1090 about things - it should worry about business logic and leave the
1091 integration details to the controllers. If, however, you find that it
1092 does not make sense at all to use an auxillary controller around the
1093 model, and the model's need to access C<$c> cannot be sidestepped, there
1094 exists a power tool called C<ACCEPT_CONTEXT>.
1096 #### editor note: this part is "generic" - it also applies to views and
1099 =head3 ACCEPT_CONTEXT
1101 Whenever you call $c->component("Foo") you get back an object - the
1102 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
1103 method instead of returning the model itself, the return value of C<<
1104 $model->ACCEPT_CONTEXT( $c ) >> will be used.
1106 This means that whenever your model/view/controller needs to talk to C<$c> it
1107 gets a chance to do this when it's needed.
1109 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
1110 with the context object set, or it will return a thin wrapper that contains
1111 C<$c> and delegates to the per-application model object.
1113 A typical C<ACCEPT_CONTEXT> method could look like this:
1115 sub ACCEPT_CONTEXT {
1116 my ( $self, $c, @extra_arguments ) = @_;
1117 bless { %$self, c => $c }, ref($self);
1120 effectively treating $self as a B<prototype object> that gets a new parameter.
1121 C<@extra_arguments> comes from any trailing arguments to
1122 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
1123 C<< $c->view(...) >> etc).
1125 The life time of this value is B<per usage>, and not per request. To make this
1126 per request you can use the following technique:
1128 Add a field to C<$c>, like C<my_model_instance>. Then write your
1129 C<ACCEPT_CONTEXT> method to look like this:
1131 sub ACCEPT_CONTEXT {
1132 my ( $self, $c ) = @_;
1134 if ( my $per_request = $c->my_model_instance ) {
1135 return $per_request;
1137 my $new_instance = bless { %$self, c => $c }, ref($self);
1138 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
1139 $c->my_model_instance( $new_instance );
1140 return $new_instance;
1147 Catalyst has a built-in http server for testing. (Later, you can easily
1148 use a more powerful server, e.g. Apache/mod_perl or FastCGI, in a
1149 production environment.)
1151 Start your application on the command line...
1153 script/myapp_server.pl
1155 ...then visit http://localhost:3000/ in a browser to view the output.
1157 You can also do it all from the command line:
1159 script/myapp_test.pl http://localhost/
1167 Join #catalyst on irc.perl.org.
1171 http://lists.rawmode.org/mailman/listinfo/catalyst
1172 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1176 Sebastian Riedel, C<sri@oook.de>
1177 David Naughton, C<naughton@umn.edu>
1178 Marcus Ramberg, C<mramberg@cpan.org>
1179 Jesse Sheidlower, C<jester@panix.com>
1180 Danijel Milicevic, C<me@danijel.de>
1181 Kieren Diment, C<kd@totaldatasolution.com>
1182 Yuval Kogman, C<nothingmuch@woobling.org>
1186 This program is free software, you can redistribute it and/or modify it
1187 under the same terms as Perl itself.