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>.
12 =head2 What is Catalyst?
14 Catalyst is an elegant web application framework, extremely flexible yet
15 extremely simple. It's similar to Ruby on Rails, Spring (Java), and
16 L<Maypole>, upon which it was originally based.
20 Catalyst follows the Model-View-Controller (MVC) design pattern,
21 allowing you to easily separate concerns, like content, presentation,
22 and flow control, into separate modules. This separation allows you to
23 modify code that handles one concern without affecting code that handles
24 the others. Catalyst promotes the re-use of existing Perl modules that
25 already handle common web application concerns well.
27 Here's how the M, V, and C map to those concerns, with examples of
28 well-known Perl modules you may want to use for each.
34 Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
35 L<Plucene>, L<Net::LDAP>...
39 Present content to the user. L<Template Toolkit|Template>,
40 L<Mason|HTML::Mason>, L<HTML::Template>...
44 Control the whole request phase, check parameters, dispatch actions, flow
45 control. Catalyst itself!
49 If you're unfamiliar with MVC and design patterns, you may want to
50 check out the original book on the subject, I<Design Patterns>, by
51 Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
52 (GoF). Many, many web application frameworks are based on MVC, which
53 is becoming a popular design method for web applications.
57 Catalyst is much more flexible than many other frameworks. We'll talk
58 more about this later, but rest assured you can use your favorite Perl
59 modules with Catalyst.
63 =item * B<Multiple Models, Views, and Controllers>
65 To build a Catalyst application, you handle each type of concern inside
66 special modules called L</Components>. Often this code will be very
67 simple, just calling out to Perl modules like those listed above under
68 L</MVC>. Catalyst handles these components in a very flexible way. Use
69 as many Models, Views, and Controllers as you like, using as many
70 different Perl modules as you like, all in the same application. Want to
71 manipulate multiple databases, and retrieve some data via LDAP? No
72 problem. Want to present data from the same Model using L<Template
73 Toolkit|Template> and L<PDF::Template>? Easy.
75 =item * B<Reuseable Components>
77 Not only does Catalyst promote the re-use of already existing Perl
78 modules, it also allows you to re-use your Catalyst components in
79 multiple Catalyst applications.
81 =item * B<Unrestrained URL-to-Action Dispatching>
83 Catalyst allows you to dispatch any URLs to any application L</Actions>,
84 even through regular expressions! Unlike most other frameworks, it
85 doesn't require mod_rewrite or class and method names in URLs.
87 With Catalyst you register your actions and address them directly. For
91 my ( $self, $context ) = @_;
92 $context->response->body('Hello World!');
95 Now http://localhost:3000/hello prints "Hello World!".
97 =item * B<Support for CGI, mod_perl, Apache::Request>
99 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>.
105 The best part is that Catalyst implements all this flexibility in a very
110 =item * B<Building Block Interface>
112 Components interoperate very smoothly. For example, Catalyst
113 automatically makes a L</Context> object available to every
114 component. Via the context, you can access the request object, share
115 data between components, and control the flow of your
116 application. Building a Catalyst application feels a lot like snapping
117 together toy building blocks, and everything just works.
119 =item * B<Component Auto-Discovery>
121 No need to C<use> all of your components. Catalyst automatically finds
124 =item * B<Pre-Built Components for Popular Modules>
126 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
127 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
129 =item * B<Built-in Test Framework>
131 Catalyst comes with a built-in, lightweight http server and test
132 framework, making it easy to test applications from the command line.
134 =item * B<Helper Scripts>
136 Catalyst provides helper scripts to quickly generate running starter
137 code for components and unit tests. See L<Catalyst::Helper>.
143 Here's how to install Catalyst and get a simple application up and
144 running, using the helper scripts described above.
148 $ perl -MCPAN -e 'install Task::Catalyst'
155 $ script/myapp_create.pl controller Library::Login
159 $ script/myapp_server.pl
161 Now visit these locations with your favorite browser or user agent to see
164 (NOTE: Although we create a controller here, we don't actually use it.
165 Both of these URLs should take you to the welcome page.)
170 =item http://localhost:3000/
172 =item http://localhost:3000/library/login/
180 Let's see how Catalyst works, by taking a closer look at the components
181 and other parts of a Catalyst application.
183 =head3 Application Class
185 In addition to the Model, View, and Controller components, there's a
186 single class that represents your application itself. This is where you
187 configure your application, load plugins, and extend Catalyst.
192 use Catalyst qw/-Debug/;
195 name => 'My Application',
197 # You can put anything else you want in here:
198 my_configuration_variable => 'something',
206 The name of your application.
210 Optionally, you can specify a B<root> parameter for templates and static
211 data. If omitted, Catalyst will try to auto-detect the directory's
212 location. You can define as many parameters as you want for plugins or
213 whatever you need. You can access them anywhere in your application via
214 C<$context-E<gt>config-E<gt>{$param_name}>.
218 Catalyst automatically blesses a Context object into your application
219 class and makes it available everywhere in your application. Use the
220 Context to directly interact with Catalyst and glue your L</Components>
221 together. For example, if you need to use the Context from within a
222 Template Toolkit template, it's already there:
224 <h1>Welcome to [% c.config.name %]!</h1>
226 As illustrated in our URL-to-Action dispatching example, the Context is
227 always the second method parameter, behind the Component object
228 reference or class name itself. Previously we called it C<$context> for
229 clarity, but most Catalyst developers just call it C<$c>:
232 my ( $self, $c ) = @_;
233 $c->res->body('Hello World!');
236 The Context contains several important objects:
240 =item * L<Catalyst::Request>
245 The request object contains all kinds of request-specific information, like
246 query parameters, cookies, uploads, headers, and more.
248 $c->req->params->{foo};
249 $c->req->cookies->{sessionid};
250 $c->req->headers->content_type;
253 =item * L<Catalyst::Response>
258 The response is like the request, but contains just response-specific
261 $c->res->body('Hello World');
262 $c->res->status(404);
263 $c->res->redirect('http://oook.de');
265 =item * L<Catalyst::Config>
271 =item * L<Catalyst::Log>
274 $c->log->debug('Something happened');
275 $c->log->info('Something you should know');
280 $c->stash->{foo} = 'bar';
281 $c->stash->{baz} = {baz => 'qox'};
282 $c->stash->{fred} = [qw/ wilma pebbles/];
288 The last of these, the stash, is a universal hash for sharing data among
289 application components. For an example, we return to our 'hello' action:
292 my ( $self, $c ) = @_;
293 $c->stash->{message} = 'Hello World!';
294 $c->forward('show_message');
297 sub show_message : Private {
298 my ( $self, $c ) = @_;
299 $c->res->body( $c->stash->{message} );
302 Note that the stash should be used only for passing data in an
303 individual request cycle; it gets cleared at a new request. If you need
304 to maintain more persistent data, use a session.
310 A Catalyst controller is defined by its actions. An action is a
311 subroutine with a special attribute. You've already seen some examples
312 of actions in this document. The URL (for example
313 http://localhost.3000/foo/bar) consists of two parts, the base
314 (http://localhost:3000/ in this example) and the path (foo/bar). Please
315 note that the trailing slash after the hostname[:port] always belongs to
316 base and not to the action.
320 =item * B<Application Wide Actions>
322 Actions which are called at the root level of the application
323 (e.g. http:///localhost:3000/ ) go in MyApp::Controller::Root, like
326 package MyApp::Controller::Root;
327 use base 'Catalyst::Controller';
328 # Sets the actions in this controller to be registered with no prefix
329 # so they function identically to actions created in MyApp.pm
330 __PACKAGE__->config->{namespace} = '';
331 sub default : Private {
332 my ( $self, $context ) = @_;
333 $context->response->body('Catalyst rocks!');
340 For most applications, Catalyst requires you to define only one config
345 Catalyst supports several types of actions:
349 =item * B<Literal> (B<Path> actions)
351 package MyApp::Controller::My::Controller;
352 sub bar : Path('foo/bar') { }
354 Literal C<Path> actions will act relative to their current
355 namespace. The above example matches only
356 http://localhost:3000/my/controller/foo/bar. If you start your path with
357 a forward slash, it will match from the root. Example:
359 package MyApp::Controller::My::Controller;
360 sub bar : Path('/foo/bar') { }
362 Matches only http://localhost:3000/foo/bar.
364 package MyApp::Controller::My::Controller;
367 By leaving the C<Path> definition empty, it will match on the namespace
368 root. The above code matches http://localhost:3000/my/controller.
372 sub bar : Regex('^item(\d+)/order(\d+)$') { }
374 Matches any URL that matches the pattern in the action key, e.g.
375 http://localhost:3000/item23/order42. The '' around the regexp is
376 optional, but perltidy likes it. :)
378 Regex matches act globally, i.e. without reference to the namespace from
379 which it is called, so that a C<bar> method in the
380 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
381 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
382 explicitly put this in the regex. To achieve the above, you should
383 consider using a C<LocalRegex> action.
385 =item * B<LocalRegex>
387 sub bar : LocalRegex('^widget(\d+)$') { }
389 LocalRegex actions act locally. If you were to use C<bar> in
390 C<MyApp::Controller::Catalog>, the above example would match urls like
391 http://localhost:3000/catalog/widget23.
393 If you omit the "C<^>" from your regex, then it will match any depth
394 from the controller and not immediately off of the controller name. The
395 following example differs from the above code in that it will match
396 http://localhost:3000/catalog/foo/widget23 as well.
398 package MyApp::Controller::Catalog;
399 sub bar : LocalRegex('widget(\d+)$') { }
401 For both LocalRegex and Regex actions, if you use capturing parentheses
402 to extract values within the matching URL, those values are available in
403 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
404 would capture "23" in the above example, and
405 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
406 arguments at the end of your URL, you must use regex action keys. See
407 L</URL Path Handling> below.
409 =item * B<Top-level> (B<Global>)
411 package MyApp::Controller::Foo;
414 Matches http://localhost:3000/foo. The function name is mapped
415 directly to the application base. You can provide an equivalent
416 function in this case by doing the following:
418 package MyApp::Controller::Root
421 =item * B<Namespace-Prefixed> (B<Local>)
423 package MyApp::Controller::My::Controller;
426 Matches http://localhost:3000/my/controller/foo.
428 This action type indicates that the matching URL must be prefixed with a
429 modified form of the component's class (package) name. This modified
430 class name excludes the parts that have a pre-defined meaning in
431 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
432 "/", and converts the name to lower case. See L</Components> for a full
433 explanation of the pre-defined meaning of Catalyst component class
438 sub foo : Private { }
440 Matches no URL, and cannot be executed by requesting a URL that
441 corresponds to the action key. Private actions can be executed only
442 inside a Catalyst application, by calling the C<forward> method:
446 See L</Flow Control> for a full explanation of C<forward>. Note that, as
447 discussed there, when forwarding from another component, you must use
448 the absolute path to the method, so that a private C<bar> method in your
449 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
450 from elsewhere, be reached with
451 C<$c-E<gt>forward('/catalog/order/process/bar')>.
455 Args is not an action type per se, but an action modifier - it adds a match
456 restriction to any action it's provided to, requiring only as many path parts
457 as are specified for the action to be valid - for example in
458 MyApp::Controller::Foo,
462 would match any URL starting /foo/bar/. To restrict this you can do
464 sub bar :Local :Args(1)
466 to only match /foo/bar/*/
470 B<Note:> After seeing these examples, you probably wonder what the point
471 is of defining names for regex and path actions. Every public action is
472 also a private one, so you have one unified way of addressing components
475 =head4 Built-in Private Actions
477 In response to specific application states, Catalyst will automatically
478 call these built-in private actions in your application class:
482 =item * B<default : Private>
484 Called when no other action matches. Could be used, for example, for
485 displaying a generic frontpage for the main app, or an error page for
486 individual controllers.
488 If C<default> isn't acting how you would expect, look at using a
489 L</Literal> C<Path> action (with an empty path string). The difference is
490 that C<Path> takes arguments relative from the namespace and C<default>
491 I<always> takes arguments relative from the root, regardless of what
494 =item * B<index : Private>
496 C<index> is much like C<default> except that it takes no arguments
497 and it is weighted slightly higher in the matching process. It is
498 useful as a static entry point to a controller, e.g. to have a static
499 welcome page. Note that it's also weighted higher than Path.
501 =item * B<begin : Private>
503 Called at the beginning of a request, before any matching actions are
506 =item * B<end : Private>
508 Called at the end of a request, after all matching actions are called.
512 =head4 Built-in actions in controllers/autochaining
514 Package MyApp::Controller::Foo;
515 sub begin : Private { }
516 sub default : Private { }
517 sub auto : Private { }
519 You can define built-in private actions within your controllers as
520 well. The actions will override the ones in less-specific controllers,
521 or your application class. In other words, for each of the three
522 built-in private actions, only one will be run in any request
523 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
524 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
525 and C<MyApp::Controller::Catalog::Order::begin> would override this in
528 In addition to the normal built-in actions, you have a special action
529 for making chains, C<auto>. Such C<auto> actions will be run after any
530 C<begin>, but before your action is processed. Unlike the other
531 built-ins, C<auto> actions I<do not> override each other; they will be
532 called in turn, starting with the application class and going through to
533 the I<most> specific class. I<This is the reverse of the order in which
534 the normal built-ins override each other>.
536 Here are some examples of the order in which the various built-ins
541 =item for a request for C</foo/foo>
545 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
548 =item for a request for C</foo/bar/foo>
550 MyApp::Controller::Foo::Bar::begin
552 MyApp::Controller::Foo::auto
553 MyApp::Controller::Foo::Bar::auto
554 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
555 MyApp::Controller::Foo::Bar::end
559 The C<auto> action is also distinguished by the fact that you can break
560 out of the processing chain by returning 0. If an C<auto> action returns
561 0, any remaining actions will be skipped, except for C<end>. So, for the
562 request above, if the first auto returns false, the chain would look
567 =item for a request for C</foo/bar/foo> where first C<auto> returns
570 MyApp::Controller::Foo::Bar::begin
572 MyApp::Controller::Foo::Bar::end
576 An example of why one might use this is an authentication action: you
577 could set up a C<auto> action to handle authentication in your
578 application class (which will always be called first), and if
579 authentication fails, returning 0 would skip any remaining methods
582 B<Note:> Looking at it another way, C<auto> actions have to return a
583 true value to continue processing! You can also C<die> in the autochain
584 action; in that case, the request will go straight to the finalize
585 stage, without processing further actions.
587 =head4 URL Path Handling
589 You can pass variable arguments as part of the URL path, separated with
590 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
591 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
592 where C<$bar> and C<$baz> may vary:
594 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
596 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
598 sub boo : Path('foo/boo') { .. }
599 sub hoo : Path('foo/boo/hoo') { .. }
601 Catalyst matches actions in most specific to least specific order:
605 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
607 So Catalyst would never mistakenly dispatch the first two URLs to the
610 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
611 still match a URL containing arguments, however the arguments won't be
614 =head4 Parameter Processing
616 Parameters passed in the URL query string are handled with methods in
617 the L<Catalyst::Request> class. The C<param> method is functionally
618 equivalent to the C<param> method of C<CGI.pm> and can be used in
619 modules that require this.
621 # http://localhost:3000/catalog/view/?category=hardware&page=3
622 my $category = $c->req->param('category');
623 my $current_page = $c->req->param('page') || 1;
625 # multiple values for single parameter name
626 my @values = $c->req->param('scrolling_list');
628 # DFV requires a CGI.pm-like input hash
629 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
633 You control the application flow with the C<forward> method, which
634 accepts the key of an action to execute. This can be an action in the
635 same or another Catalyst controller, or a Class name, optionally
636 followed by a method name. After a C<forward>, the control flow will
637 return to the method from which the C<forward> was issued.
639 A C<forward> is similar to a method call. The main differences are that
640 it wraps the call in an C<eval> to allow exception handling; it
641 automatically passes along the context object (C<$c> or C<$context>);
642 and it allows profiling of each call (displayed in the log with
646 my ( $self, $c ) = @_;
647 $c->stash->{message} = 'Hello World!';
648 $c->forward('check_message'); # $c is automatically included
651 sub check_message : Private {
652 my ( $self, $c ) = @_;
653 return unless $c->stash->{message};
654 $c->forward('show_message');
657 sub show_message : Private {
658 my ( $self, $c ) = @_;
659 $c->res->body( $c->stash->{message} );
662 A C<forward> does not create a new request, so your request
663 object (C<$c-E<gt>req>) will remain unchanged. This is a
664 key difference between using C<forward> and issuing a
667 You can pass new arguments to a C<forward> by adding them
668 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
669 will be changed for the duration of the C<forward> only; upon
670 return, the original value of C<$c-E<gt>req-E<gt>args> will
674 my ( $self, $c ) = @_;
675 $c->stash->{message} = 'Hello World!';
676 $c->forward('check_message',[qw/test1/]);
677 # now $c->req->args is back to what it was before
680 sub check_message : Private {
681 my ( $self, $c ) = @_;
682 my $first_argument = $c->req->args->[0]; # now = 'test1'
686 As you can see from these examples, you can just use the method name as
687 long as you are referring to methods in the same controller. If you want
688 to forward to a method in another controller, or the main application,
689 you will have to refer to the method by absolute path.
691 $c->forward('/my/controller/action');
692 $c->forward('/default'); # calls default in main application
694 Here are some examples of how to forward to classes and methods.
697 my ( $self, $c ) = @_;
698 $c->forward(qw/MyApp::Model::Hello say_hello/);
702 my ( $self, $c ) = @_;
703 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
706 package MyApp::Model::Hello;
709 my ( $self, $c ) = @_;
710 $c->res->body('Hello World!');
714 my ( $self, $c ) = @_;
715 $c->res->body('Goodbye World!');
718 Note that C<forward> returns to the calling action and continues
719 processing after the action finishes. If you want all further processing
720 in the calling action to stop, use C<detach> instead, which will execute
721 the C<detach>ed action and not return to the calling sub. In both cases,
722 Catalyst will automatically try to call process() if you omit the
727 Catalyst has an uncommonly flexible component system. You can define as
728 many L</Models>, L</Views>, and L</Controllers> as you like.
730 All components must inherit from L<Catalyst::Base>, which provides a
731 simple class structure and some common class methods like C<config> and
732 C<new> (constructor).
734 package MyApp::Controller::Catalog;
737 use base 'Catalyst::Base';
739 __PACKAGE__->config( foo => 'bar' );
743 You don't have to C<use> or otherwise register Models, Views, and
744 Controllers. Catalyst automatically discovers and instantiates them
745 when you call C<setup> in the main application. All you need to do is
746 put them in directories named for each Component type. Notice that you
747 can use some very terse aliases for each one.
751 =item * B<MyApp/Model/>
755 =item * B<MyApp/View/>
759 =item * B<MyApp/Controller/>
767 To show how to define views, we'll use an already-existing base class for the
768 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
769 inherit from this class:
771 package MyApp::View::TT;
774 use base 'Catalyst::View::TT';
778 (You can also generate this automatically by using the helper script:
780 script/myapp_create.pl view TT TT
782 where the first C<TT> tells the script that the name of the view should
783 be C<TT>, and the second that it should be a Template Toolkit view.)
785 This gives us a process() method and we can now just do
786 $c->forward('MyApp::View::TT') to render our templates. The base class
787 makes process() implicit, so we don't have to say
788 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
791 my ( $self, $c ) = @_;
792 $c->stash->{template} = 'hello.tt';
796 my ( $self, $c ) = @_;
797 $c->forward('MyApp::View::TT');
800 You normally render templates at the end of a request, so it's a perfect
801 use for the global C<end> action.
803 Also, be sure to put the template under the directory specified in
804 C<$c-E<gt>config-E<gt>{root}>, or you'll be forced to look at our
805 eyecandy debug screen. ;)
809 To show how to define models, again we'll use an already-existing base
810 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
811 We'll also need L<DBIx::Class::Schema::Loader>.
813 But first, we need a database.
817 id INTEGER PRIMARY KEY,
822 id INTEGER PRIMARY KEY,
823 foo INTEGER REFERENCES foo,
827 INSERT INTO foo (data) VALUES ('TEST!');
830 % sqlite /tmp/myapp.db < myapp.sql
832 Now we can create a DBIC::SchemaLoader component for this database.
834 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
836 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
837 relationships. Use the stash to pass data to your templates.
839 We add the following to MyApp/Controller/Root.pm
842 my ( $self, $c, $id ) = @_;
844 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
850 my ( $self, $c ) = @_;
852 $c->stash->{template} ||= 'index.tt';
853 $c->forward( $c->view('TT') );
856 We then create a new template file "root/index.tt" containing:
858 The Id's data is [% item.data %]
860 Models do not have to be part of your Catalyst application; you
861 can always call an outside module that serves as your Model:
865 my ( $self, $c ) = @_;
867 $c->stash->{template} = 'list.tt';
869 use Some::Outside::DBIC::Module;
870 my @records = Some::Outside::DBIC::Module->search({
874 $c->stash->{records} = \@records;
877 But by using a Model that is part of your Catalyst application, you gain
878 several things: you don't have to C<use> each component, Catalyst will
879 find and load it automatically at compile-time; you can C<forward> to
880 the module, which can only be done to Catalyst components; and only
881 Catalyst components can be fetched with
882 C<$c-E<gt>model('SomeModel')>.
884 Happily, since many people have existing Model classes that they
885 would like to use with Catalyst (or, conversely, they want to
886 write Catalyst models that can be used outside of Catalyst, e.g.
887 in a cron job), it's trivial to write a simple component in
888 Catalyst that slurps in an outside Model:
890 package MyApp::Model::DB;
891 use base qw/Catalyst::Model::DBIC::Schema/;
893 schema_class => 'Some::DBIC::Schema',
894 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
898 and that's it! Now C<Some::DBIC::Schema> is part of your
899 Cat app as C<MyApp::Model::DB>.
903 Multiple controllers are a good way to separate logical domains of your
906 package MyApp::Controller::Login;
908 use base qw/Catalyst::Controller/;
910 sub sign_in : Path("sign-in") { }
911 sub new_password : Path("new-password") { }
912 sub sign_out : Path("sign-out") { }
914 package MyApp::Controller::Catalog;
916 use base qw/Catalyst::Controller/;
921 package MyApp::Controller::Cart;
923 use base qw/Catalyst::Controller/;
926 sub update : Local { }
927 sub order : Local { }
929 Note that you can also supply attributes via the Controller's config so long
930 as you have at least one attribute on a subref to be exported (:Action is
931 commonly used for this) - for example the following is equivalent to the same
934 package MyApp::Controller::Login;
936 use base qw/Catalyst::Controller/;
940 'sign_in' => { Path => 'sign-in' },
941 'new_password' => { Path => 'new-password' },
942 'sign_out' => { Path => 'sign-out' },
946 sub sign_in : Action { }
947 sub new_password : Action { }
948 sub sign_out : Action { }
952 Models are providers of data. This data could come from anywhere - a search
953 engine index, a database table, etc. Typically the data source does not have
954 much to do with web applications or Catalyst - it could be used to write an
955 offline report generator or a command line tool just the same.
957 The common approach to writing a Catalyst-style model for your application is
958 wrapping a generic model (e.g. L<DBIx::Class::Schema>, a bunch of XMLs, or
959 anything really) with an object that contains configuration data, convenience
960 methods, and so forth.
962 #### editor: move this part to =head3 Components somehow, right after this
963 #### section - this will require deeply rephrasing this paragraph.
965 Technically, within Catalyst a model is a B<component> - an instance of the
966 model's class belonging to the application. It is important to stress that the
967 lifetime of these objects is per application, not per request.
969 While the model base class (L<Catalyst::Model>) provides things like C<config>
970 and stuff to better integrate the model into the application, sometimes this is
971 not enough, and the model requires access to C<$c> itself.
973 Situations where this need might arise include:
979 Interacting with another model
983 Using per-request data to control behavior
987 Using plugins in (for example L<Catalyst::Plugin::Cache>).
991 From a style perspective usually it's bad to make your model "too smart" about
992 things - it should worry about business logic and leave the integration details
993 to the controllers. If, however, you find that it does not make sense at all to
994 use an auxillary controller around the model, and the model's need to access
995 C<$c> cannot be sidestepped, there exists a power tool called C<ACCEPT_CONTEXT>.
997 #### editor note: this part is "generic" - it also applies to views and
1000 =head3 ACCEPT_CONTEXT
1002 Whenever you call $c->component("Foo") you get back an object - the instance of
1003 the model. If the component supports the C<ACCEPT_CONTEXT> method instead of
1004 returning the model itself, the return value of
1005 C<< $model->ACCEPT_CONTEXT( $c ) >> will be used.
1007 This means that whenever your model/view/controller needs to talk to C<$c> it
1008 gets a chance to do this when it's needed.
1010 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
1011 with the context object set, or it will return a thin wrapper that contains
1012 C<$c> and delegates to the per-application model object.
1014 A typicall C<ACCEPT_CONTEXT> method could look like this:
1016 sub ACCEPT_CONTEXT {
1017 my ( $self, $c, @extra_arguments ) = @_;
1018 bless { %$self, c => $c }, ref($self);
1021 effectively treating $self as a B<prototype object> that gets a new parameter.
1022 C<@extra_arguments> comes from any trailing arguments to
1023 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
1024 C<< $c->view(...) >> etc).
1026 The life time of this value is B<per usage>, and not per request. To make this
1027 per request you can use the following technique:
1029 Add a field to C<$c>, like C<my_model_instance>. Then write your
1030 C<ACCEPT_CONTEXT> method to look like this:
1032 sub ACCEPT_CONTEXT {
1033 my ( $self, $c ) = @_;
1035 if ( my $per_request = $c->my_model_instance ) {
1036 return $per_request;
1038 my $new_instance = bless { %$self, c => $c }, ref($self);
1039 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
1040 $c->my_model_instance( $new_instance );
1041 return $new_instance;
1049 Catalyst has a built-in http server for testing! (Later, you can easily
1050 use a more powerful server, e.g. Apache/mod_perl, in a production
1053 Start your application on the command line...
1055 script/myapp_server.pl
1057 ...then visit http://localhost:3000/ in a browser to view the output.
1059 You can also do it all from the command line:
1061 script/myapp_test.pl http://localhost/
1069 Join #catalyst on irc.perl.org.
1073 http://lists.rawmode.org/mailman/listinfo/catalyst
1074 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1078 Sebastian Riedel, C<sri@oook.de>
1079 David Naughton, C<naughton@umn.edu>
1080 Marcus Ramberg, C<mramberg@cpan.org>
1081 Jesse Sheidlower, C<jester@panix.com>
1082 Danijel Milicevic, C<me@danijel.de>
1083 Kieren Diment, C<kd@totaldatasolution.com>
1084 Yuval Kogman, C<nothingmuch@woobling.org>
1088 This program is free software, you can redistribute it and/or modify it
1089 under the same terms as Perl itself.