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 Model, View, and Controller map to those concerns, with
38 examples of 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. Rest assured
68 you can use your favorite Perl modules with Catalyst.
72 =item * B<Multiple Models, Views, and Controllers>
74 To build a Catalyst application, you handle each type of concern inside
75 special modules called L</Components>. Often this code will be very
76 simple, just calling out to Perl modules like those listed above under
77 L</MVC>. Catalyst handles these components in a very flexible way. Use
78 as many Models, Views, and Controllers as you like, using as many
79 different Perl modules as you like, all in the same application. Want to
80 manipulate multiple databases, and retrieve some data via LDAP? No
81 problem. Want to present data from the same Model using L<Template
82 Toolkit|Template> and L<PDF::Template>? Easy.
84 =item * B<Reuseable Components>
86 Not only does Catalyst promote the re-use of already existing Perl
87 modules, it also allows you to re-use your Catalyst components in
88 multiple Catalyst applications.
90 =item * B<Unrestrained URL-to-Action Dispatching>
92 Catalyst allows you to dispatch any URLs to any application L</Actions>,
93 even through regular expressions! Unlike most other frameworks, it
94 doesn't require mod_rewrite or class and method names in URLs.
96 With Catalyst you register your actions and address them directly. For
100 my ( $self, $context ) = @_;
101 $context->response->body('Hello World!');
104 Now http://localhost:3000/hello prints "Hello World!".
106 =item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
108 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
109 engines are also available.
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. Install L<Catalyst::Devel> and see
154 Here's how to install Catalyst and get a simple application up and
155 running, using the helper scripts described above.
159 Installation of Catalyst can be a time-consuming and frustrating
160 effort, due to its large number of dependencies. The easiest way
161 to get up and running is to use Matt Trout's C<cat-install>
162 script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
163 and then install L<Catalyst::Devel>.
166 # perl -MCPAN -e 'install Catalyst::Devel'
173 $ script/myapp_create.pl controller Library::Login
177 $ script/myapp_server.pl
179 Now visit these locations with your favorite browser or user agent to see
182 (NOTE: Although we create a controller here, we don't actually use it.
183 Both of these URLs should take you to the welcome page.)
188 =item http://localhost:3000/
190 =item http://localhost:3000/library/login/
198 Let's see how Catalyst works, by taking a closer look at the components
199 and other parts of a Catalyst application.
201 =head3 Application Class
203 In addition to the Model, View, and Controller components, there's a
204 single class that represents your application itself. This is where you
205 configure your application, load plugins, and extend Catalyst.
210 use Catalyst qw/-Debug/; # Add other plugins here, e.g.
211 # for session support
214 name => 'My Application',
216 # You can put anything else you want in here:
217 my_configuration_variable => 'something',
221 In older versions of Catalyst, the application class was where you put
222 global actions. However, as of version 5.66, the recommended practice is
223 to place such actions in a special Root controller (see L</Actions>,
224 below), to avoid namespace collisions.
230 The name of your application.
234 Optionally, you can specify a B<root> parameter for templates and static
235 data. If omitted, Catalyst will try to auto-detect the directory's
236 location. You can define as many parameters as you want for plugins or
237 whatever you need. You can access them anywhere in your application via
238 C<$context-E<gt>config-E<gt>{$param_name}>.
242 Catalyst automatically blesses a Context object into your application
243 class and makes it available everywhere in your application. Use the
244 Context to directly interact with Catalyst and glue your L</Components>
245 together. For example, if you need to use the Context from within a
246 Template Toolkit template, it's already there:
248 <h1>Welcome to [% c.config.name %]!</h1>
250 As illustrated in our URL-to-Action dispatching example, the Context is
251 always the second method parameter, behind the Component object
252 reference or class name itself. Previously we called it C<$context> for
253 clarity, but most Catalyst developers just call it C<$c>:
256 my ( $self, $c ) = @_;
257 $c->res->body('Hello World!');
260 The Context contains several important objects:
264 =item * L<Catalyst::Request>
269 The request object contains all kinds of request-specific information, like
270 query parameters, cookies, uploads, headers, and more.
272 $c->req->params->{foo};
273 $c->req->cookies->{sessionid};
274 $c->req->headers->content_type;
276 $c->req->uri_with( { page = $pager->next_page } );
278 =item * L<Catalyst::Response>
283 The response is like the request, but contains just response-specific
286 $c->res->body('Hello World');
287 $c->res->status(404);
288 $c->res->redirect('http://oook.de');
290 =item * L<Catalyst::Config>
296 =item * L<Catalyst::Log>
299 $c->log->debug('Something happened');
300 $c->log->info('Something you should know');
305 $c->stash->{foo} = 'bar';
306 $c->stash->{baz} = {baz => 'qox'};
307 $c->stash->{fred} = [qw/wilma pebbles/];
313 The last of these, the stash, is a universal hash for sharing data among
314 application components. For an example, we return to our 'hello' action:
317 my ( $self, $c ) = @_;
318 $c->stash->{message} = 'Hello World!';
319 $c->forward('show_message');
322 sub show_message : Private {
323 my ( $self, $c ) = @_;
324 $c->res->body( $c->stash->{message} );
327 Note that the stash should be used only for passing data in an
328 individual request cycle; it gets cleared at a new request. If you need
329 to maintain persistent data, use a session. See
330 L<Catalyst::Plugin::Session> for a comprehensive set of
331 Catalyst-friendly session-handling tools.
335 A Catalyst controller is defined by its actions. An action is a
336 subroutine with a special attribute. You've already seen some examples
337 of actions in this document. The URL (for example
338 http://localhost.3000/foo/bar) consists of two parts, the base
339 (http://localhost:3000/ in this example) and the path (foo/bar). Please
340 note that the trailing slash after the hostname[:port] always belongs to
341 base and not to the action.
345 =item * B<Application Wide Actions>
347 Actions which are called at the root level of the application
348 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
351 package MyApp::Controller::Root;
352 use base 'Catalyst::Controller';
353 # Sets the actions in this controller to be registered with no prefix
354 # so they function identically to actions created in MyApp.pm
355 __PACKAGE__->config->{namespace} = '';
356 sub default : Private {
357 my ( $self, $context ) = @_;
358 $context->response->body('Catalyst rocks!');
366 Catalyst supports several types of actions:
370 =item * B<Literal> (B<Path> actions)
372 package MyApp::Controller::My::Controller;
373 sub bar : Path('foo/bar') { }
375 Literal C<Path> actions will act relative to their current
376 namespace. The above example matches only
377 http://localhost:3000/my/controller/foo/bar. If you start your path with
378 a forward slash, it will match from the root. Example:
380 package MyApp::Controller::My::Controller;
381 sub bar : Path('/foo/bar') { }
383 Matches only http://localhost:3000/foo/bar.
385 package MyApp::Controller::My::Controller;
388 By leaving the C<Path> definition empty, it will match on the namespace
389 root. The above code matches http://localhost:3000/my/controller.
393 sub bar : Regex('^item(\d+)/order(\d+)$') { }
395 Matches any URL that matches the pattern in the action key, e.g.
396 http://localhost:3000/item23/order42. The '' around the regexp is
397 optional, but perltidy likes it. :)
399 Regex matches act globally, i.e. without reference to the namespace from
400 which it is called, so that a C<bar> method in the
401 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
402 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
403 explicitly put this in the regex. To achieve the above, you should
404 consider using a C<LocalRegex> action.
406 =item * B<LocalRegex>
408 sub bar : LocalRegex('^widget(\d+)$') { }
410 LocalRegex actions act locally. If you were to use C<bar> in
411 C<MyApp::Controller::Catalog>, the above example would match urls like
412 http://localhost:3000/catalog/widget23.
414 If you omit the "C<^>" from your regex, then it will match any depth
415 from the controller and not immediately off of the controller name. The
416 following example differs from the above code in that it will match
417 http://localhost:3000/catalog/foo/widget23 as well.
419 package MyApp::Controller::Catalog;
420 sub bar : LocalRegex('widget(\d+)$') { }
422 For both LocalRegex and Regex actions, if you use capturing parentheses
423 to extract values within the matching URL, those values are available in
424 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
425 would capture "23" in the above example, and
426 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
427 arguments at the end of your URL, you must use regex action keys. See
428 L</URL Path Handling> below.
430 =item * B<Top-level> (B<Global>)
432 package MyApp::Controller::Foo;
435 Matches http://localhost:3000/foo. The function name is mapped
436 directly to the application base. You can provide an equivalent
437 function in this case by doing the following:
439 package MyApp::Controller::Root
442 =item * B<Namespace-Prefixed> (B<Local>)
444 package MyApp::Controller::My::Controller;
447 Matches http://localhost:3000/my/controller/foo.
449 This action type indicates that the matching URL must be prefixed with a
450 modified form of the component's class (package) name. This modified
451 class name excludes the parts that have a pre-defined meaning in
452 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
453 "/", and converts the name to lower case. See L</Components> for a full
454 explanation of the pre-defined meaning of Catalyst component class
459 Catalyst also provides a method to build and dispatch chains of actions,
462 sub catalog : Chained : CaptureArgs(1) {
463 my ( $self, $c, $arg ) = @_;
467 sub item : Chained('catalog') : Args(1) {
468 my ( $self, $c, $arg ) = @_;
472 to handle a C</catalog/*/item/*> path. For extensive information about this
473 dispatch type, please see L<Catalyst::DispatchType::Chained>.
477 sub foo : Private { }
479 Matches no URL, and cannot be executed by requesting a URL that
480 corresponds to the action key. Private actions can be executed only
481 inside a Catalyst application, by calling the C<forward> method:
485 See L</Flow Control> for a full explanation of C<forward>. Note that, as
486 discussed there, when forwarding from another component, you must use
487 the absolute path to the method, so that a private C<bar> method in your
488 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
489 from elsewhere, be reached with
490 C<$c-E<gt>forward('/catalog/order/process/bar')>.
494 Args is not an action type per se, but an action modifier - it adds a
495 match restriction to any action it's provided to, requiring only as many
496 path parts as are specified for the action to be valid - for example in
497 MyApp::Controller::Foo,
501 would match any URL starting /foo/bar/. To restrict this you can do
503 sub bar :Local :Args(1)
505 to only match /foo/bar/*/
509 B<Note:> After seeing these examples, you probably wonder what the point
510 is of defining names for regex and path actions. Every public action is
511 also a private one, so you have one unified way of addressing components
514 =head4 Built-in Private Actions
516 In response to specific application states, Catalyst will automatically
517 call these built-in private actions in your application class:
521 =item * B<default : Private>
523 Called when no other action matches. Could be used, for example, for
524 displaying a generic frontpage for the main app, or an error page for
525 individual controllers.
527 If C<default> isn't acting how you would expect, look at using a
528 L</Literal> C<Path> action (with an empty path string). The difference
529 is that C<Path> takes arguments relative from the namespace and
530 C<default> I<always> takes arguments relative from the root, regardless
531 of what controller it's in. Indeed, this is now the recommended way of
532 handling default situations; the C<default> private controller should
533 be considered deprecated.
535 =item * B<index : Private>
537 C<index> is much like C<default> except that it takes no arguments
538 and it is weighted slightly higher in the matching process. It is
539 useful as a static entry point to a controller, e.g. to have a static
540 welcome page. Note that it's also weighted higher than Path.
542 =item * B<begin : Private>
544 Called at the beginning of a request, before any matching actions are
547 =item * B<end : Private>
549 Called at the end of a request, after all matching actions are called.
553 =head4 Built-in actions in controllers/autochaining
555 Package MyApp::Controller::Foo;
556 sub begin : Private { }
557 sub default : Private { }
558 sub auto : Private { }
560 You can define built-in private actions within your controllers as
561 well. The actions will override the ones in less-specific controllers,
562 or your application class. In other words, for each of the three
563 built-in private actions, only one will be run in any request
564 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
565 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
566 and C<MyApp::Controller::Catalog::Order::begin> would override this in
569 =item * B<auto : Private>
571 In addition to the normal built-in actions, you have a special action
572 for making chains, C<auto>. Such C<auto> actions will be run after any
573 C<begin>, but before your action is processed. Unlike the other
574 built-ins, C<auto> actions I<do not> override each other; they will be
575 called in turn, starting with the application class and going through to
576 the I<most> specific class. I<This is the reverse of the order in which
577 the normal built-ins override each other>.
579 Here are some examples of the order in which the various built-ins
584 =item for a request for C</foo/foo>
588 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
591 =item for a request for C</foo/bar/foo>
593 MyApp::Controller::Foo::Bar::begin
595 MyApp::Controller::Foo::auto
596 MyApp::Controller::Foo::Bar::auto
597 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
598 MyApp::Controller::Foo::Bar::end
602 The C<auto> action is also distinguished by the fact that you can break
603 out of the processing chain by returning 0. If an C<auto> action returns
604 0, any remaining actions will be skipped, except for C<end>. So, for the
605 request above, if the first auto returns false, the chain would look
610 =item for a request for C</foo/bar/foo> where first C<auto> returns
613 MyApp::Controller::Foo::Bar::begin
615 MyApp::Controller::Foo::Bar::end
619 An example of why one might use this is an authentication action: you
620 could set up a C<auto> action to handle authentication in your
621 application class (which will always be called first), and if
622 authentication fails, returning 0 would skip any remaining methods
625 B<Note:> Looking at it another way, C<auto> actions have to return a
626 true value to continue processing! You can also C<die> in the auto
627 action; in that case, the request will go straight to the finalize
628 stage, without processing further actions.
630 =head4 URL Path Handling
632 You can pass variable arguments as part of the URL path, separated with
633 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
634 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
635 where C<$bar> and C<$baz> may vary:
637 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
639 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
641 sub boo : Path('foo/boo') { .. }
642 sub hoo : Path('foo/boo/hoo') { .. }
644 Catalyst matches actions in most specific to least specific order:
648 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
650 So Catalyst would never mistakenly dispatch the first two URLs to the
653 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
654 still match a URL containing arguments, however the arguments won't be
657 =head4 Parameter Processing
659 Parameters passed in the URL query string are handled with methods in
660 the L<Catalyst::Request> class. The C<param> method is functionally
661 equivalent to the C<param> method of C<CGI.pm> and can be used in
662 modules that require this.
664 # http://localhost:3000/catalog/view/?category=hardware&page=3
665 my $category = $c->req->param('category');
666 my $current_page = $c->req->param('page') || 1;
668 # multiple values for single parameter name
669 my @values = $c->req->param('scrolling_list');
671 # DFV requires a CGI.pm-like input hash
672 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
676 You control the application flow with the C<forward> method, which
677 accepts the key of an action to execute. This can be an action in the
678 same or another Catalyst controller, or a Class name, optionally
679 followed by a method name. After a C<forward>, the control flow will
680 return to the method from which the C<forward> was issued.
682 A C<forward> is similar to a method call. The main differences are that
683 it wraps the call in an C<eval> to allow exception handling; it
684 automatically passes along the context object (C<$c> or C<$context>);
685 and it allows profiling of each call (displayed in the log with
689 my ( $self, $c ) = @_;
690 $c->stash->{message} = 'Hello World!';
691 $c->forward('check_message'); # $c is automatically included
694 sub check_message : Private {
695 my ( $self, $c ) = @_;
696 return unless $c->stash->{message};
697 $c->forward('show_message');
700 sub show_message : Private {
701 my ( $self, $c ) = @_;
702 $c->res->body( $c->stash->{message} );
705 A C<forward> does not create a new request, so your request object
706 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
707 using C<forward> and issuing a redirect.
709 You can pass new arguments to a C<forward> by adding them
710 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
711 will be changed for the duration of the C<forward> only; upon
712 return, the original value of C<$c-E<gt>req-E<gt>args> will
716 my ( $self, $c ) = @_;
717 $c->stash->{message} = 'Hello World!';
718 $c->forward('check_message',[qw/test1/]);
719 # now $c->req->args is back to what it was before
722 sub check_message : Private {
723 my ( $self, $c ) = @_;
724 my $first_argument = $c->req->args->[0]; # now = 'test1'
728 As you can see from these examples, you can just use the method name as
729 long as you are referring to methods in the same controller. If you want
730 to forward to a method in another controller, or the main application,
731 you will have to refer to the method by absolute path.
733 $c->forward('/my/controller/action');
734 $c->forward('/default'); # calls default in main application
736 Here are some examples of how to forward to classes and methods.
739 my ( $self, $c ) = @_;
740 $c->forward(qw/MyApp::Model::Hello say_hello/);
744 my ( $self, $c ) = @_;
745 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
748 package MyApp::Model::Hello;
751 my ( $self, $c ) = @_;
752 $c->res->body('Hello World!');
756 my ( $self, $c ) = @_;
757 $c->res->body('Goodbye World!');
760 Note that C<forward> returns to the calling action and continues
761 processing after the action finishes. If you want all further processing
762 in the calling action to stop, use C<detach> instead, which will execute
763 the C<detach>ed action and not return to the calling sub. In both cases,
764 Catalyst will automatically try to call process() if you omit the
769 Catalyst has an uncommonly flexible component system. You can define as
770 many L</Models>, L</Views>, and L</Controllers> as you like.
772 All components must inherit from L<Catalyst::Base>, which provides a
773 simple class structure and some common class methods like C<config> and
774 C<new> (constructor).
776 package MyApp::Controller::Catalog;
779 use base 'Catalyst::Base';
781 __PACKAGE__->config( foo => 'bar' );
785 You don't have to C<use> or otherwise register Models, Views, and
786 Controllers. Catalyst automatically discovers and instantiates them
787 when you call C<setup> in the main application. All you need to do is
788 put them in directories named for each Component type. Notice that you
789 can use a terse alias for each one.
793 =item * B<MyApp/Model/>
797 =item * B<MyApp/View/>
801 =item * B<MyApp/Controller/>
807 In older versions of Catalyst, the recommended practice (and the one
808 automatically created by helper scripts) was to name the directories
809 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
810 the use of the full names.
814 To show how to define views, we'll use an already-existing base class for the
815 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
816 inherit from this class:
818 package MyApp::View::TT;
821 use base 'Catalyst::View::TT';
825 (You can also generate this automatically by using the helper script:
827 script/myapp_create.pl view TT TT
829 where the first C<TT> tells the script that the name of the view should
830 be C<TT>, and the second that it should be a Template Toolkit view.)
832 This gives us a process() method and we can now just do
833 $c->forward('MyApp::View::TT') to render our templates. The base class
834 makes process() implicit, so we don't have to say
835 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
838 my ( $self, $c ) = @_;
839 $c->stash->{template} = 'hello.tt';
843 my ( $self, $c ) = @_;
844 $c->forward('MyApp::View::TT');
847 You normally render templates at the end of a request, so it's a perfect
848 use for the global C<end> action.
850 In practice, however, you would use a default C<end> action as supplied
851 by L<Catalyst::Action::RenderView>.
853 Also, be sure to put the template under the directory specified in
854 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
859 To show how to define models, again we'll use an already-existing base
860 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
861 We'll also need L<DBIx::Class::Schema::Loader>.
863 But first, we need a database.
867 id INTEGER PRIMARY KEY,
872 id INTEGER PRIMARY KEY,
873 foo INTEGER REFERENCES foo,
877 INSERT INTO foo (data) VALUES ('TEST!');
880 % sqlite /tmp/myapp.db < myapp.sql
882 Now we can create a DBIC::SchemaLoader component for this database.
884 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
886 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
887 relationships. Use the stash to pass data to your templates.
889 We add the following to MyApp/Controller/Root.pm
892 my ( $self, $c, $id ) = @_;
894 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
900 my ( $self, $c ) = @_;
902 $c->stash->{template} ||= 'index.tt';
903 $c->forward( $c->view('TT') );
906 We then create a new template file "root/index.tt" containing:
908 The Id's data is [% item.data %]
910 Models do not have to be part of your Catalyst application; you
911 can always call an outside module that serves as your Model:
915 my ( $self, $c ) = @_;
917 $c->stash->{template} = 'list.tt';
919 use Some::Outside::Database::Module;
920 my @records = Some::Outside::Database::Module->search({
921 artist => 'Led Zeppelin',
924 $c->stash->{records} = \@records;
927 But by using a Model that is part of your Catalyst application, you gain
928 several things: you don't have to C<use> each component, Catalyst will
929 find and load it automatically at compile-time; you can C<forward> to
930 the module, which can only be done to Catalyst components; and only
931 Catalyst components can be fetched with
932 C<$c-E<gt>model('SomeModel')>.
934 Happily, since many people have existing Model classes that they
935 would like to use with Catalyst (or, conversely, they want to
936 write Catalyst models that can be used outside of Catalyst, e.g.
937 in a cron job), it's trivial to write a simple component in
938 Catalyst that slurps in an outside Model:
940 package MyApp::Model::DB;
941 use base qw/Catalyst::Model::DBIC::Schema/;
943 schema_class => 'Some::DBIC::Schema',
944 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
948 and that's it! Now C<Some::DBIC::Schema> is part of your
949 Cat app as C<MyApp::Model::DB>.
953 Multiple controllers are a good way to separate logical domains of your
956 package MyApp::Controller::Login;
958 use base qw/Catalyst::Controller/;
960 sub sign_in : Path("sign-in") { }
961 sub new_password : Path("new-password") { }
962 sub sign_out : Path("sign-out") { }
964 package MyApp::Controller::Catalog;
966 use base qw/Catalyst::Controller/;
971 package MyApp::Controller::Cart;
973 use base qw/Catalyst::Controller/;
976 sub update : Local { }
977 sub order : Local { }
979 Note that you can also supply attributes via the Controller's config so long
980 as you have at least one attribute on a subref to be exported (:Action is
981 commonly used for this) - for example the following is equivalent to the same
984 package MyApp::Controller::Login;
986 use base qw/Catalyst::Controller/;
990 'sign_in' => { Path => 'sign-in' },
991 'new_password' => { Path => 'new-password' },
992 'sign_out' => { Path => 'sign-out' },
996 sub sign_in : Action { }
997 sub new_password : Action { }
998 sub sign_out : Action { }
1002 Models are providers of data. This data could come from anywhere - a
1003 search engine index, a database table, etc. Typically the data source
1004 does not have much to do with web applications or Catalyst - it could be
1005 used to write an offline report generator or a command line tool just
1008 The common approach to writing a Catalyst-style model for your
1009 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
1010 bunch of XMLs, or anything really) with an object that contains
1011 configuration data, convenience methods, and so forth.
1013 #### editor: move this part to =head3 Components somehow, right after this
1014 #### section - this will require deeply rephrasing this paragraph.
1016 Technically, within Catalyst a model is a B<component> - an instance of
1017 the model's class belonging to the application. It is important to
1018 stress that the lifetime of these objects is per application, not per
1021 While the model base class (L<Catalyst::Model>) provides things like
1022 C<config> and stuff to better integrate the model into the application,
1023 sometimes this is not enough, and the model requires access to C<$c>
1026 Situations where this need might arise include:
1032 Interacting with another model
1036 Using per-request data to control behavior
1040 Using plugins in (for example L<Catalyst::Plugin::Cache>).
1044 From a style perspective usually it's bad to make your model "too smart"
1045 about things - it should worry about business logic and leave the
1046 integration details to the controllers. If, however, you find that it
1047 does not make sense at all to use an auxillary controller around the
1048 model, and the model's need to access C<$c> cannot be sidestepped, there
1049 exists a power tool called C<ACCEPT_CONTEXT>.
1051 #### editor note: this part is "generic" - it also applies to views and
1054 =head3 ACCEPT_CONTEXT
1056 Whenever you call $c->component("Foo") you get back an object - the
1057 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
1058 method instead of returning the model itself, the return value of C<<
1059 $model->ACCEPT_CONTEXT( $c ) >> will be used.
1061 This means that whenever your model/view/controller needs to talk to C<$c> it
1062 gets a chance to do this when it's needed.
1064 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
1065 with the context object set, or it will return a thin wrapper that contains
1066 C<$c> and delegates to the per-application model object.
1068 A typical C<ACCEPT_CONTEXT> method could look like this:
1070 sub ACCEPT_CONTEXT {
1071 my ( $self, $c, @extra_arguments ) = @_;
1072 bless { %$self, c => $c }, ref($self);
1075 effectively treating $self as a B<prototype object> that gets a new parameter.
1076 C<@extra_arguments> comes from any trailing arguments to
1077 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
1078 C<< $c->view(...) >> etc).
1080 The life time of this value is B<per usage>, and not per request. To make this
1081 per request you can use the following technique:
1083 Add a field to C<$c>, like C<my_model_instance>. Then write your
1084 C<ACCEPT_CONTEXT> method to look like this:
1086 sub ACCEPT_CONTEXT {
1087 my ( $self, $c ) = @_;
1089 if ( my $per_request = $c->my_model_instance ) {
1090 return $per_request;
1092 my $new_instance = bless { %$self, c => $c }, ref($self);
1093 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
1094 $c->my_model_instance( $new_instance );
1095 return $new_instance;
1102 Catalyst has a built-in http server for testing. (Later, you can easily
1103 use a more powerful server, e.g. Apache/mod_perl or FastCGI, in a
1104 production environment.)
1106 Start your application on the command line...
1108 script/myapp_server.pl
1110 ...then visit http://localhost:3000/ in a browser to view the output.
1112 You can also do it all from the command line:
1114 script/myapp_test.pl http://localhost/
1122 Join #catalyst on irc.perl.org.
1126 http://lists.rawmode.org/mailman/listinfo/catalyst
1127 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1131 Sebastian Riedel, C<sri@oook.de>
1132 David Naughton, C<naughton@umn.edu>
1133 Marcus Ramberg, C<mramberg@cpan.org>
1134 Jesse Sheidlower, C<jester@panix.com>
1135 Danijel Milicevic, C<me@danijel.de>
1136 Kieren Diment, C<kd@totaldatasolution.com>
1137 Yuval Kogman, C<nothingmuch@woobling.org>
1141 This program is free software, you can redistribute it and/or modify it
1142 under the same terms as Perl itself.