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
17 yet extremely simple. It's similar to Ruby on Rails, Spring (Java),
18 and 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
20 to develop web applications, with few restrictions on how you need to
21 use these tools. However, this does mean that it is always possible to
22 do things in a different way. Other web frameworks are B<initially>
23 simpler to use, but achieve this by locking the programmer into a
24 single set of tools. Catalyst's emphasis on flexibility means that you
25 have to think more to use it. We view this as a feature. For example,
26 this leads to Catalyst being more suited to system integration tasks
27 than other web frameworks.
31 Catalyst follows the Model-View-Controller (MVC) design pattern,
32 allowing you to easily separate concerns, like content, presentation,
33 and flow control, into separate modules. This separation allows you to
34 modify code that handles one concern without affecting code that handles
35 the others. Catalyst promotes the re-use of existing Perl modules that
36 already handle common web application concerns well.
38 Here's how the Model, View, and Controller map to those concerns, with
39 examples of well-known Perl modules you may want to use for each.
45 Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
46 L<Xapian>, L<Net::LDAP>...
50 Present content to the user. L<Template Toolkit|Template>,
51 L<Mason|HTML::Mason>, L<HTML::Template>...
55 Control the whole request phase, check parameters, dispatch actions, flow
56 control. Catalyst itself!
60 If you're unfamiliar with MVC and design patterns, you may want to
61 check out the original book on the subject, I<Design Patterns>, by
62 Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
63 (GoF). Many, many web application frameworks are based on MVC, which
64 is becoming a popular design paradigm for the world wide web.
68 Catalyst is much more flexible than many other frameworks. Rest assured
69 you can use your favorite Perl 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, FastCGI>
109 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
110 engines are also available.
116 The best part is that Catalyst implements all this flexibility in a very
121 =item * B<Building Block Interface>
123 Components interoperate very smoothly. For example, Catalyst
124 automatically makes a L</Context> object available to every
125 component. Via the context, you can access the request object, share
126 data between components, and control the flow of your
127 application. Building a Catalyst application feels a lot like snapping
128 together toy building blocks, and everything just works.
130 =item * B<Component Auto-Discovery>
132 No need to C<use> all of your components. Catalyst automatically finds
135 =item * B<Pre-Built Components for Popular Modules>
137 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
138 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
140 =item * B<Built-in Test Framework>
142 Catalyst comes with a built-in, lightweight http server and test
143 framework, making it easy to test applications from the web browser,
144 and the command line.
146 =item * B<Helper Scripts>
148 Catalyst provides helper scripts to quickly generate running starter
149 code for components and unit tests. Install L<Catalyst::Devel> and see
156 Here's how to install Catalyst and get a simple application up and
157 running, using the helper scripts described above.
161 Installation of Catalyst can be a time-consuming and frustrating
162 effort, due to its large number of dependencies. The easiest way
163 to get up and running is to use Matt Trout's C<cat-install>
164 script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
165 and then install L<Catalyst::Devel>.
168 # perl -MCPAN -e 'install Catalyst::Devel'
175 $ script/myapp_create.pl controller Library::Login
179 $ script/myapp_server.pl
181 Now visit these locations with your favorite browser or user agent to see
184 (NOTE: Although we create a controller here, we don't actually use it.
185 Both of these URLs should take you to the welcome page.)
190 =item http://localhost:3000/
192 =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.
203 Catalyst has an uncommonly flexible component system. You can define as
204 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
205 previously, the general idea is that the View is responsible for the
206 output of data to the user (typically via a web browser, but a View can
207 also generate PDFs or e-mails, for example); the Model is responsible
208 for providing data (typically from a relational database); and the
209 Controller is responsible for interacting with the user and deciding
210 how user input determines what actions the application takes.
212 In the world of MVC, there are frequent discussions and disagreements
213 about the nature of each element - whether certain types of logic
214 belong in the Model or the Controller, etc. Catalyst's flexibility
215 means that this decision is entirely up to you, the programmer;
216 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
217 a general discussion of these issues.
219 All components must inherit from L<Catalyst::Base>, which provides a
220 simple class structure and some common class methods like C<config> and
221 C<new> (constructor).
223 package MyApp::Controller::Catalog;
226 use base 'Catalyst::Base';
228 __PACKAGE__->config( foo => 'bar' );
232 You don't have to C<use> or otherwise register Models, Views, and
233 Controllers. Catalyst automatically discovers and instantiates them
234 when you call C<setup> in the main application. All you need to do is
235 put them in directories named for each Component type. You can use a
236 short alias for each one.
240 =item * B<MyApp/Model/>
244 =item * B<MyApp/View/>
248 =item * B<MyApp/Controller/>
254 In older versions of Catalyst, the recommended practice (and the one
255 automatically created by helper scripts) was to name the directories
256 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
257 the use of the full names.
261 To show how to define views, we'll use an already-existing base class for the
262 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
263 inherit from this class:
265 package MyApp::View::TT;
268 use base 'Catalyst::View::TT';
272 (You can also generate this automatically by using the helper script:
274 script/myapp_create.pl view TT TT
276 where the first C<TT> tells the script that the name of the view should
277 be C<TT>, and the second that it should be a Template Toolkit view.)
279 This gives us a process() method and we can now just do
280 $c->forward('MyApp::View::TT') to render our templates. The base class
281 makes process() implicit, so we don't have to say
282 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
285 my ( $self, $c ) = @_;
286 $c->stash->{template} = 'hello.tt';
290 my ( $self, $c ) = @_;
291 $c->forward( $c->view('TT') );
294 You normally render templates at the end of a request, so it's a perfect
295 use for the global C<end> action.
297 In practice, however, you would use a default C<end> action as supplied
298 by L<Catalyst::Action::RenderView>.
300 Also, be sure to put the template under the directory specified in
301 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
306 Models are providers of data. This data could come from anywhere - a
307 search engine index, a spreadsheet, the file system - but typically a
308 Model represents a database table. The data source does not
309 intrinsically have much to do with web applications or Catalyst - it
310 could just as easily be used to write an offline report generator or a
313 To show how to define models, again we'll use an already-existing base
314 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
315 We'll also need L<DBIx::Class::Schema::Loader>.
317 But first, we need a database.
321 id INTEGER PRIMARY KEY,
326 id INTEGER PRIMARY KEY,
327 foo INTEGER REFERENCES foo,
331 INSERT INTO foo (data) VALUES ('TEST!');
333 % sqlite /tmp/myapp.db < myapp.sql
335 Now we can create a DBIC::Schema model for this database.
337 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
339 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
340 relationships, and converts them into a static schema definition C<MySchema>,
341 which you can edit later.
343 Use the stash to pass data to your templates.
345 We add the following to MyApp/Controller/Root.pm
348 my ( $self, $c, $id ) = @_;
350 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
356 my ( $self, $c ) = @_;
358 $c->stash->{template} ||= 'index.tt';
359 $c->forward( $c->view('TT') );
362 We then create a new template file "root/index.tt" containing:
364 The Id's data is [% item.data %]
366 Models do not have to be part of your Catalyst application; you
367 can always call an outside module that serves as your Model:
371 my ( $self, $c ) = @_;
373 $c->stash->{template} = 'list.tt';
375 use Some::Outside::Database::Module;
376 my @records = Some::Outside::Database::Module->search({
377 artist => 'Led Zeppelin',
380 $c->stash->{records} = \@records;
383 But by using a Model that is part of your Catalyst application, you
384 gain several things: you don't have to C<use> each component, Catalyst
385 will find and load it automatically at compile-time; you can
386 C<forward> to the module, which can only be done to Catalyst
387 components. Only Catalyst components can be fetched with
388 C<$c-E<gt>model('SomeModel')>.
390 Happily, since many people have existing Model classes that they
391 would like to use with Catalyst (or, conversely, they want to
392 write Catalyst models that can be used outside of Catalyst, e.g.
393 in a cron job), it's trivial to write a simple component in
394 Catalyst that slurps in an outside Model:
396 package MyApp::Model::DB;
397 use base qw/Catalyst::Model::DBIC::Schema/;
399 schema_class => 'Some::DBIC::Schema',
400 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
404 and that's it! Now C<Some::DBIC::Schema> is part of your
405 Cat app as C<MyApp::Model::DB>.
407 Within Catalyst, the common approach to writing a model for your
408 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
409 bunch of XMLs, or anything really) with an object that contains
410 configuration data, convenience methods, and so forth. Thus you
411 will in effect have two models - a wrapper model that knows something
412 about Catalyst and your web application, and a generic model that is
413 totally independent of these needs.
415 Technically, within Catalyst a model is a B<component> - an instance of
416 the model's class belonging to the application. It is important to
417 stress that the lifetime of these objects is per application, not per
420 While the model base class (L<Catalyst::Model>) provides things like
421 C<config> to better integrate the model into the application, sometimes
422 this is not enough, and the model requires access to C<$c> itself.
424 Situations where this need might arise include:
430 Interacting with another model
434 Using per-request data to control behavior
438 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
442 From a style perspective it's usually considered bad form to make your
443 model "too smart" about things - it should worry about business logic
444 and leave the integration details to the controllers. If, however, you
445 find that it does not make sense at all to use an auxillary controller
446 around the model, and the model's need to access C<$c> cannot be
447 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
451 Multiple controllers are a good way to separate logical domains of your
454 package MyApp::Controller::Login;
456 use base qw/Catalyst::Controller/;
458 sub login : Path("login") { }
459 sub new_password : Path("new-password") { }
460 sub logout : Path("logout") { }
462 package MyApp::Controller::Catalog;
464 use base qw/Catalyst::Controller/;
469 package MyApp::Controller::Cart;
471 use base qw/Catalyst::Controller/;
474 sub update : Local { }
475 sub order : Local { }
477 Note that you can also supply attributes via the Controller's config so
478 long as you have at least one attribute on a subref to be exported
479 (:Action is commonly used for this) - for example the following is
480 equivalent to the same controller above:
482 package MyApp::Controller::Login;
484 use base qw/Catalyst::Controller/;
488 'sign_in' => { Path => 'sign-in' },
489 'new_password' => { Path => 'new-password' },
490 'sign_out' => { Path => 'sign-out' },
494 sub sign_in : Action { }
495 sub new_password : Action { }
496 sub sign_out : Action { }
498 =head3 ACCEPT_CONTEXT
500 Whenever you call $c->component("Foo") you get back an object - the
501 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
502 method instead of returning the model itself, the return value of C<<
503 $model->ACCEPT_CONTEXT( $c ) >> will be used.
505 This means that whenever your model/view/controller needs to talk to C<$c> it
506 gets a chance to do this when it's needed.
508 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
509 with the context object set, or it will return a thin wrapper that contains
510 C<$c> and delegates to the per-application model object.
512 A typical C<ACCEPT_CONTEXT> method could look like this:
515 my ( $self, $c, @extra_arguments ) = @_;
516 bless { %$self, c => $c }, ref($self);
519 effectively treating $self as a B<prototype object> that gets a new parameter.
520 C<@extra_arguments> comes from any trailing arguments to
521 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
522 C<< $c->view(...) >> etc).
524 The life time of this value is B<per usage>, and not per request. To make this
525 per request you can use the following technique:
527 Add a field to C<$c>, like C<my_model_instance>. Then write your
528 C<ACCEPT_CONTEXT> method to look like this:
531 my ( $self, $c ) = @_;
533 if ( my $per_request = $c->my_model_instance ) {
536 my $new_instance = bless { %$self, c => $c }, ref($self);
537 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
538 $c->my_model_instance( $new_instance );
539 return $new_instance;
543 =head3 Application Class
545 In addition to the Model, View, and Controller components, there's a
546 single class that represents your application itself. This is where you
547 configure your application, load plugins, and extend Catalyst.
552 use Catalyst qw/-Debug/; # Add other plugins here, e.g.
553 # for session support
556 name => 'My Application',
558 # You can put anything else you want in here:
559 my_configuration_variable => 'something',
563 In older versions of Catalyst, the application class was where you put
564 global actions. However, as of version 5.66, the recommended practice is
565 to place such actions in a special Root controller (see L</Actions>,
566 below), to avoid namespace collisions.
572 The name of your application.
576 Optionally, you can specify a B<root> parameter for templates and static
577 data. If omitted, Catalyst will try to auto-detect the directory's
578 location. You can define as many parameters as you want for plugins or
579 whatever you need. You can access them anywhere in your application via
580 C<$context-E<gt>config-E<gt>{$param_name}>.
584 Catalyst automatically blesses a Context object into your application
585 class and makes it available everywhere in your application. Use the
586 Context to directly interact with Catalyst and glue your L</Components>
587 together. For example, if you need to use the Context from within a
588 Template Toolkit template, it's already there:
590 <h1>Welcome to [% c.config.name %]!</h1>
592 As illustrated in our URL-to-Action dispatching example, the Context is
593 always the second method parameter, behind the Component object
594 reference or class name itself. Previously we called it C<$context> for
595 clarity, but most Catalyst developers just call it C<$c>:
598 my ( $self, $c ) = @_;
599 $c->res->body('Hello World!');
602 The Context contains several important objects:
606 =item * L<Catalyst::Request>
611 The request object contains all kinds of request-specific information, like
612 query parameters, cookies, uploads, headers, and more.
614 $c->req->params->{foo};
615 $c->req->cookies->{sessionid};
616 $c->req->headers->content_type;
618 $c->req->uri_with( { page = $pager->next_page } );
620 =item * L<Catalyst::Response>
625 The response is like the request, but contains just response-specific
628 $c->res->body('Hello World');
629 $c->res->status(404);
630 $c->res->redirect('http://oook.de');
632 =item * L<Catalyst::Config>
638 =item * L<Catalyst::Log>
641 $c->log->debug('Something happened');
642 $c->log->info('Something you should know');
647 $c->stash->{foo} = 'bar';
648 $c->stash->{baz} = {baz => 'qox'};
649 $c->stash->{fred} = [qw/wilma pebbles/];
655 The last of these, the stash, is a universal hash for sharing data among
656 application components. For an example, we return to our 'hello' action:
659 my ( $self, $c ) = @_;
660 $c->stash->{message} = 'Hello World!';
661 $c->forward('show_message');
664 sub show_message : Private {
665 my ( $self, $c ) = @_;
666 $c->res->body( $c->stash->{message} );
669 Note that the stash should be used only for passing data in an
670 individual request cycle; it gets cleared at a new request. If you need
671 to maintain persistent data, use a session. See
672 L<Catalyst::Plugin::Session> for a comprehensive set of
673 Catalyst-friendly session-handling tools.
677 A Catalyst controller is defined by its actions. An action is a
678 subroutine with a special attribute. You've already seen some examples
679 of actions in this document. The URL (for example
680 http://localhost.3000/foo/bar) consists of two parts, the base
681 (http://localhost:3000/ in this example) and the path (foo/bar). Please
682 note that the trailing slash after the hostname[:port] always belongs to
683 base and not to the action.
687 =item * B<Application Wide Actions>
689 Actions which are called at the root level of the application
690 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
693 package MyApp::Controller::Root;
694 use base 'Catalyst::Controller';
695 # Sets the actions in this controller to be registered with no prefix
696 # so they function identically to actions created in MyApp.pm
697 __PACKAGE__->config->{namespace} = '';
698 sub default : Private {
699 my ( $self, $context ) = @_;
700 $context->response->body('Catalyst rocks!');
708 Catalyst supports several types of actions:
712 =item * B<Literal> (B<Path> actions)
714 package MyApp::Controller::My::Controller;
715 sub bar : Path('foo/bar') { }
717 Literal C<Path> actions will act relative to their current
718 namespace. The above example matches only
719 http://localhost:3000/my/controller/foo/bar. If you start your path with
720 a forward slash, it will match from the root. Example:
722 package MyApp::Controller::My::Controller;
723 sub bar : Path('/foo/bar') { }
725 Matches only http://localhost:3000/foo/bar.
727 package MyApp::Controller::My::Controller;
730 By leaving the C<Path> definition empty, it will match on the namespace
731 root. The above code matches http://localhost:3000/my/controller.
735 sub bar : Regex('^item(\d+)/order(\d+)$') { }
737 Matches any URL that matches the pattern in the action key, e.g.
738 http://localhost:3000/item23/order42. The '' around the regexp is
739 optional, but perltidy likes it. :)
741 Regex matches act globally, i.e. without reference to the namespace from
742 which it is called, so that a C<bar> method in the
743 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
744 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
745 explicitly put this in the regex. To achieve the above, you should
746 consider using a C<LocalRegex> action.
748 =item * B<LocalRegex>
750 sub bar : LocalRegex('^widget(\d+)$') { }
752 LocalRegex actions act locally. If you were to use C<bar> in
753 C<MyApp::Controller::Catalog>, the above example would match urls like
754 http://localhost:3000/catalog/widget23.
756 If you omit the "C<^>" from your regex, then it will match any depth
757 from the controller and not immediately off of the controller name. The
758 following example differs from the above code in that it will match
759 http://localhost:3000/catalog/foo/widget23 as well.
761 package MyApp::Controller::Catalog;
762 sub bar : LocalRegex('widget(\d+)$') { }
764 For both LocalRegex and Regex actions, if you use capturing parentheses
765 to extract values within the matching URL, those values are available in
766 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
767 would capture "23" in the above example, and
768 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
769 arguments at the end of your URL, you must use regex action keys. See
770 L</URL Path Handling> below.
772 =item * B<Top-level> (B<Global>)
774 package MyApp::Controller::Foo;
777 Matches http://localhost:3000/foo. The function name is mapped
778 directly to the application base. You can provide an equivalent
779 function in this case by doing the following:
781 package MyApp::Controller::Root
784 =item * B<Namespace-Prefixed> (B<Local>)
786 package MyApp::Controller::My::Controller;
789 Matches http://localhost:3000/my/controller/foo.
791 This action type indicates that the matching URL must be prefixed with a
792 modified form of the component's class (package) name. This modified
793 class name excludes the parts that have a pre-defined meaning in
794 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
795 "/", and converts the name to lower case. See L</Components> for a full
796 explanation of the pre-defined meaning of Catalyst component class
801 Catalyst also provides a method to build and dispatch chains of actions,
804 sub catalog : Chained : CaptureArgs(1) {
805 my ( $self, $c, $arg ) = @_;
809 sub item : Chained('catalog') : Args(1) {
810 my ( $self, $c, $arg ) = @_;
814 to handle a C</catalog/*/item/*> path. For further information about this
815 dispatch type, please see L<Catalyst::DispatchType::Chained>.
819 sub foo : Private { }
821 Matches no URL, and cannot be executed by requesting a URL that
822 corresponds to the action key. Private actions can be executed only
823 inside a Catalyst application, by calling the C<forward> method:
827 See L</Flow Control> for a full explanation of C<forward>. Note that, as
828 discussed there, when forwarding from another component, you must use
829 the absolute path to the method, so that a private C<bar> method in your
830 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
831 from elsewhere, be reached with
832 C<$c-E<gt>forward('/catalog/order/process/bar')>.
836 Args is not an action type per se, but an action modifier - it adds a
837 match restriction to any action it's provided to, requiring only as many
838 path parts as are specified for the action to be valid - for example in
839 MyApp::Controller::Foo,
843 would match any URL starting /foo/bar/. To restrict this you can do
845 sub bar :Local :Args(1)
847 to only match /foo/bar/*/
851 B<Note:> After seeing these examples, you probably wonder what the point
852 is of defining names for regex and path actions. Every public action is
853 also a private one, so you have one unified way of addressing components
856 =head4 Built-in Private Actions
858 In response to specific application states, Catalyst will automatically
859 call these built-in private actions in your application class:
863 =item * B<default : Private>
865 Called when no other action matches. Could be used, for example, for
866 displaying a generic frontpage for the main app, or an error page for
867 individual controllers.
869 If C<default> isn't acting how you would expect, look at using a
870 L</Literal> C<Path> action (with an empty path string). The difference
871 is that C<Path> takes arguments relative from the namespace and
872 C<default> I<always> takes arguments relative from the root, regardless
873 of what controller it's in. Indeed, this is now the recommended way of
874 handling default situations; the C<default> private controller should
875 be considered deprecated.
877 =item * B<index : Private>
879 C<index> is much like C<default> except that it takes no arguments
880 and it is weighted slightly higher in the matching process. It is
881 useful as a static entry point to a controller, e.g. to have a static
882 welcome page. Note that it's also weighted higher than Path.
884 =item * B<begin : Private>
886 Called at the beginning of a request, before any matching actions are
889 =item * B<end : Private>
891 Called at the end of a request, after all matching actions are called.
895 =head4 Built-in actions in controllers/autochaining
897 Package MyApp::Controller::Foo;
898 sub begin : Private { }
899 sub default : Private { }
900 sub auto : Private { }
902 You can define built-in private actions within your controllers as
903 well. The actions will override the ones in less-specific controllers,
904 or your application class. In other words, for each of the three
905 built-in private actions, only one will be run in any request
906 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
907 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
908 and C<MyApp::Controller::Catalog::Order::begin> would override this in
913 =item * B<auto : Private>
915 In addition to the normal built-in actions, you have a special action
916 for making chains, C<auto>. Such C<auto> actions will be run after any
917 C<begin>, but before your action is processed. Unlike the other
918 built-ins, C<auto> actions I<do not> override each other; they will be
919 called in turn, starting with the application class and going through to
920 the I<most> specific class. I<This is the reverse of the order in which
921 the normal built-ins override each other>.
925 Here are some examples of the order in which the various built-ins
930 =item for a request for C</foo/foo>
934 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
937 =item for a request for C</foo/bar/foo>
939 MyApp::Controller::Foo::Bar::begin
941 MyApp::Controller::Foo::auto
942 MyApp::Controller::Foo::Bar::auto
943 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
944 MyApp::Controller::Foo::Bar::end
948 The C<auto> action is also distinguished by the fact that you can break
949 out of the processing chain by returning 0. If an C<auto> action returns
950 0, any remaining actions will be skipped, except for C<end>. So, for the
951 request above, if the first auto returns false, the chain would look
956 =item for a request for C</foo/bar/foo> where first C<auto> returns
959 MyApp::Controller::Foo::Bar::begin
961 MyApp::Controller::Foo::Bar::end
965 An example of why one might use this is an authentication action: you
966 could set up a C<auto> action to handle authentication in your
967 application class (which will always be called first), and if
968 authentication fails, returning 0 would skip any remaining methods
971 B<Note:> Looking at it another way, C<auto> actions have to return a
972 true value to continue processing! You can also C<die> in the auto
973 action; in that case, the request will go straight to the finalize
974 stage, without processing further actions.
976 =head4 URL Path Handling
978 You can pass variable arguments as part of the URL path, separated with
979 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
980 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
981 where C<$bar> and C<$baz> may vary:
983 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
985 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
987 sub boo : Path('foo/boo') { .. }
988 sub hoo : Path('foo/boo/hoo') { .. }
990 Catalyst matches actions in most specific to least specific order:
994 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
996 So Catalyst would never mistakenly dispatch the first two URLs to the
999 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1000 still match a URL containing arguments, however the arguments won't be
1001 available via C<@_>.
1003 =head4 Parameter Processing
1005 Parameters passed in the URL query string are handled with methods in
1006 the L<Catalyst::Request> class. The C<param> method is functionally
1007 equivalent to the C<param> method of C<CGI.pm> and can be used in
1008 modules that require this.
1010 # http://localhost:3000/catalog/view/?category=hardware&page=3
1011 my $category = $c->req->param('category');
1012 my $current_page = $c->req->param('page') || 1;
1014 # multiple values for single parameter name
1015 my @values = $c->req->param('scrolling_list');
1017 # DFV requires a CGI.pm-like input hash
1018 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1022 You control the application flow with the C<forward> method, which
1023 accepts the key of an action to execute. This can be an action in the
1024 same or another Catalyst controller, or a Class name, optionally
1025 followed by a method name. After a C<forward>, the control flow will
1026 return to the method from which the C<forward> was issued.
1028 A C<forward> is similar to a method call. The main differences are that
1029 it wraps the call in an C<eval> to allow exception handling; it
1030 automatically passes along the context object (C<$c> or C<$context>);
1031 and it allows profiling of each call (displayed in the log with
1034 sub hello : Global {
1035 my ( $self, $c ) = @_;
1036 $c->stash->{message} = 'Hello World!';
1037 $c->forward('check_message'); # $c is automatically included
1040 sub check_message : Private {
1041 my ( $self, $c ) = @_;
1042 return unless $c->stash->{message};
1043 $c->forward('show_message');
1046 sub show_message : Private {
1047 my ( $self, $c ) = @_;
1048 $c->res->body( $c->stash->{message} );
1051 A C<forward> does not create a new request, so your request object
1052 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1053 using C<forward> and issuing a redirect.
1055 You can pass new arguments to a C<forward> by adding them
1056 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1057 will be changed for the duration of the C<forward> only; upon
1058 return, the original value of C<$c-E<gt>req-E<gt>args> will
1061 sub hello : Global {
1062 my ( $self, $c ) = @_;
1063 $c->stash->{message} = 'Hello World!';
1064 $c->forward('check_message',[qw/test1/]);
1065 # now $c->req->args is back to what it was before
1068 sub check_message : Private {
1069 my ( $self, $c ) = @_;
1070 my $first_argument = $c->req->args->[0]; # now = 'test1'
1074 As you can see from these examples, you can just use the method name as
1075 long as you are referring to methods in the same controller. If you want
1076 to forward to a method in another controller, or the main application,
1077 you will have to refer to the method by absolute path.
1079 $c->forward('/my/controller/action');
1080 $c->forward('/default'); # calls default in main application
1082 Here are some examples of how to forward to classes and methods.
1084 sub hello : Global {
1085 my ( $self, $c ) = @_;
1086 $c->forward(qw/MyApp::Model::Hello say_hello/);
1090 my ( $self, $c ) = @_;
1091 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1094 package MyApp::Model::Hello;
1097 my ( $self, $c ) = @_;
1098 $c->res->body('Hello World!');
1102 my ( $self, $c ) = @_;
1103 $c->res->body('Goodbye World!');
1106 Note that C<forward> returns to the calling action and continues
1107 processing after the action finishes. If you want all further processing
1108 in the calling action to stop, use C<detach> instead, which will execute
1109 the C<detach>ed action and not return to the calling sub. In both cases,
1110 Catalyst will automatically try to call process() if you omit the
1116 Catalyst has a built-in http server for testing or local
1117 deployment. (Later, you can easily use a more powerful server, for
1118 example Apache/mod_perl or FastCGI, in a production environment.)
1120 Start your application on the command line...
1122 script/myapp_server.pl
1124 ...then visit http://localhost:3000/ in a browser to view the output.
1126 You can also do it all from the command line:
1128 script/myapp_test.pl http://localhost/
1130 Catalyst has a number of tools for actual regression testing of
1131 applications. The helper scripts will automatically generate basic tests
1132 that can be extended as you develop your project. To write your own
1133 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1136 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1144 =item * L<Catalyst::Manual::About>
1146 =item * L<Catalyst::Manual::Tutorial>
1156 Join #catalyst on irc.perl.org.
1157 Join #catalyst-dev on irc.perl.org to help with development.
1161 http://lists.rawmode.org/mailman/listinfo/catalyst
1162 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1166 Sebastian Riedel, C<sri@oook.de>
1167 David Naughton, C<naughton@umn.edu>
1168 Marcus Ramberg, C<mramberg@cpan.org>
1169 Jesse Sheidlower, C<jester@panix.com>
1170 Danijel Milicevic, C<me@danijel.de>
1171 Kieren Diment, C<kd@totaldatasolution.com>
1172 Yuval Kogman, C<nothingmuch@woobling.org>
1176 This program is free software. You can redistribute it and/or modify it
1177 under the same terms as Perl itself.