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/
196 Let's see how Catalyst works, by taking a closer look at the components
197 and other parts of a Catalyst application.
201 Catalyst has an uncommonly flexible component system. You can define as
202 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
203 previously, the general idea is that the View is responsible for the
204 output of data to the user (typically via a web browser, but a View can
205 also generate PDFs or e-mails, for example); the Model is responsible
206 for providing data (typically from a relational database); and the
207 Controller is responsible for interacting with the user and deciding
208 how user input determines what actions the application takes.
210 In the world of MVC, there are frequent discussions and disagreements
211 about the nature of each element - whether certain types of logic
212 belong in the Model or the Controller, etc. Catalyst's flexibility
213 means that this decision is entirely up to you, the programmer;
214 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
215 a general discussion of these concerns.
217 All components must inherit from L<Catalyst::Base>, which provides a
218 simple class structure and some common class methods like C<config> and
219 C<new> (constructor).
221 package MyApp::Controller::Catalog;
224 use base 'Catalyst::Base';
226 __PACKAGE__->config( foo => 'bar' );
230 You don't have to C<use> or otherwise register Models, Views, and
231 Controllers. Catalyst automatically discovers and instantiates them
232 when you call C<setup> in the main application. All you need to do is
233 put them in directories named for each Component type. You can use a
234 short alias for each one.
238 =item * B<MyApp/Model/>
242 =item * B<MyApp/View/>
246 =item * B<MyApp/Controller/>
252 In older versions of Catalyst, the recommended practice (and the one
253 automatically created by helper scripts) was to name the directories
254 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
255 the use of the full names.
259 To show how to define views, we'll use an already-existing base class for the
260 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
261 inherit from this class:
263 package MyApp::View::TT;
266 use base 'Catalyst::View::TT';
270 (You can also generate this automatically by using the helper script:
272 script/myapp_create.pl view TT TT
274 where the first C<TT> tells the script that the name of the view should
275 be C<TT>, and the second that it should be a Template Toolkit view.)
277 This gives us a process() method and we can now just do
278 $c->forward('MyApp::View::TT') to render our templates. The base class
279 makes process() implicit, so we don't have to say
280 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
283 my ( $self, $c ) = @_;
284 $c->stash->{template} = 'hello.tt';
288 my ( $self, $c ) = @_;
289 $c->forward( $c->view('TT') );
292 You normally render templates at the end of a request, so it's a perfect
293 use for the global C<end> action.
295 In practice, however, you would use a default C<end> action as supplied
296 by L<Catalyst::Action::RenderView>.
298 Also, be sure to put the template under the directory specified in
299 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
304 Models are providers of data. This data could come from anywhere - a
305 search engine index, a spreadsheet - but typically a Model represents a
306 database table. The data source does not intrinsically have much to do
307 with web applications or Catalyst - it could just as easily be used to
308 write an offline report generator or a command-line tool.
310 To show how to define models, again we'll use an already-existing base
311 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
312 We'll also need L<DBIx::Class::Schema::Loader>.
314 But first, we need a database.
318 id INTEGER PRIMARY KEY,
323 id INTEGER PRIMARY KEY,
324 foo INTEGER REFERENCES foo,
328 INSERT INTO foo (data) VALUES ('TEST!');
330 % sqlite /tmp/myapp.db < myapp.sql
332 Now we can create a DBIC::SchemaLoader component for this database.
334 script/myapp_create.pl model DBIC DBIC::SchemaLoader 'dbi:SQLite:/tmp/myapp.db'
336 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
337 relationships. Use the stash to pass data to your templates.
339 We add the following to MyApp/Controller/Root.pm
342 my ( $self, $c, $id ) = @_;
344 $c->stash->{item} = $c->model('DBIC::Foo')->find($id);
350 my ( $self, $c ) = @_;
352 $c->stash->{template} ||= 'index.tt';
353 $c->forward( $c->view('TT') );
356 We then create a new template file "root/index.tt" containing:
358 The Id's data is [% item.data %]
360 Models do not have to be part of your Catalyst application; you
361 can always call an outside module that serves as your Model:
365 my ( $self, $c ) = @_;
367 $c->stash->{template} = 'list.tt';
369 use Some::Outside::Database::Module;
370 my @records = Some::Outside::Database::Module->search({
371 artist => 'Led Zeppelin',
374 $c->stash->{records} = \@records;
377 But by using a Model that is part of your Catalyst application, you gain
378 several things: you don't have to C<use> each component, Catalyst will
379 find and load it automatically at compile-time; you can C<forward> to
380 the module, which can only be done to Catalyst components; and only
381 Catalyst components can be fetched with
382 C<$c-E<gt>model('SomeModel')>.
384 Happily, since many people have existing Model classes that they
385 would like to use with Catalyst (or, conversely, they want to
386 write Catalyst models that can be used outside of Catalyst, e.g.
387 in a cron job), it's trivial to write a simple component in
388 Catalyst that slurps in an outside Model:
390 package MyApp::Model::DB;
391 use base qw/Catalyst::Model::DBIC::Schema/;
393 schema_class => 'Some::DBIC::Schema',
394 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
398 and that's it! Now C<Some::DBIC::Schema> is part of your
399 Cat app as C<MyApp::Model::DB>.
401 Within Catalyst, the common approach to writing a model for your
402 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
403 bunch of XMLs, or anything really) with an object that contains
404 configuration data, convenience methods, and so forth. Thus you
405 will in effect have two models - a wrapper model that knows something
406 about Catalyst and your web application, and a generic model that is
407 totally independent of these needs.
409 Technically, within Catalyst a model is a B<component> - an instance of
410 the model's class belonging to the application. It is important to
411 stress that the lifetime of these objects is per application, not per
414 While the model base class (L<Catalyst::Model>) provides things like
415 C<config> to better integrate the model into the application, sometimes
416 this is not enough, and the model requires access to C<$c> itself.
418 Situations where this need might arise include:
424 Interacting with another model
428 Using per-request data to control behavior
432 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
436 From a style perspective it's usually considered bad form to make your
437 model "too smart" about things - it should worry about business logic
438 and leave the integration details to the controllers. If, however, you
439 find that it does not make sense at all to use an auxillary controller
440 around the model, and the model's need to access C<$c> cannot be
441 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
445 Multiple controllers are a good way to separate logical domains of your
448 package MyApp::Controller::Login;
450 use base qw/Catalyst::Controller/;
452 sub login : Path("login") { }
453 sub new_password : Path("new-password") { }
454 sub logout : Path("logout") { }
456 package MyApp::Controller::Catalog;
458 use base qw/Catalyst::Controller/;
463 package MyApp::Controller::Cart;
465 use base qw/Catalyst::Controller/;
468 sub update : Local { }
469 sub order : Local { }
471 Note that you can also supply attributes via the Controller's config so
472 long as you have at least one attribute on a subref to be exported
473 (:Action is commonly used for this) - for example the following is
474 equivalent to the same controller above:
476 package MyApp::Controller::Login;
478 use base qw/Catalyst::Controller/;
482 'sign_in' => { Path => 'sign-in' },
483 'new_password' => { Path => 'new-password' },
484 'sign_out' => { Path => 'sign-out' },
488 sub sign_in : Action { }
489 sub new_password : Action { }
490 sub sign_out : Action { }
492 =head3 ACCEPT_CONTEXT
494 Whenever you call $c->component("Foo") you get back an object - the
495 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
496 method instead of returning the model itself, the return value of C<<
497 $model->ACCEPT_CONTEXT( $c ) >> will be used.
499 This means that whenever your model/view/controller needs to talk to C<$c> it
500 gets a chance to do this when it's needed.
502 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
503 with the context object set, or it will return a thin wrapper that contains
504 C<$c> and delegates to the per-application model object.
506 A typical C<ACCEPT_CONTEXT> method could look like this:
509 my ( $self, $c, @extra_arguments ) = @_;
510 bless { %$self, c => $c }, ref($self);
513 effectively treating $self as a B<prototype object> that gets a new parameter.
514 C<@extra_arguments> comes from any trailing arguments to
515 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
516 C<< $c->view(...) >> etc).
518 The life time of this value is B<per usage>, and not per request. To make this
519 per request you can use the following technique:
521 Add a field to C<$c>, like C<my_model_instance>. Then write your
522 C<ACCEPT_CONTEXT> method to look like this:
525 my ( $self, $c ) = @_;
527 if ( my $per_request = $c->my_model_instance ) {
530 my $new_instance = bless { %$self, c => $c }, ref($self);
531 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
532 $c->my_model_instance( $new_instance );
533 return $new_instance;
537 =head3 Application Class
539 In addition to the Model, View, and Controller components, there's a
540 single class that represents your application itself. This is where you
541 configure your application, load plugins, and extend Catalyst.
546 use Catalyst qw/-Debug/; # Add other plugins here, e.g.
547 # for session support
550 name => 'My Application',
552 # You can put anything else you want in here:
553 my_configuration_variable => 'something',
557 In older versions of Catalyst, the application class was where you put
558 global actions. However, as of version 5.66, the recommended practice is
559 to place such actions in a special Root controller (see L</Actions>,
560 below), to avoid namespace collisions.
566 The name of your application.
570 Optionally, you can specify a B<root> parameter for templates and static
571 data. If omitted, Catalyst will try to auto-detect the directory's
572 location. You can define as many parameters as you want for plugins or
573 whatever you need. You can access them anywhere in your application via
574 C<$context-E<gt>config-E<gt>{$param_name}>.
578 Catalyst automatically blesses a Context object into your application
579 class and makes it available everywhere in your application. Use the
580 Context to directly interact with Catalyst and glue your L</Components>
581 together. For example, if you need to use the Context from within a
582 Template Toolkit template, it's already there:
584 <h1>Welcome to [% c.config.name %]!</h1>
586 As illustrated in our URL-to-Action dispatching example, the Context is
587 always the second method parameter, behind the Component object
588 reference or class name itself. Previously we called it C<$context> for
589 clarity, but most Catalyst developers just call it C<$c>:
592 my ( $self, $c ) = @_;
593 $c->res->body('Hello World!');
596 The Context contains several important objects:
600 =item * L<Catalyst::Request>
605 The request object contains all kinds of request-specific information, like
606 query parameters, cookies, uploads, headers, and more.
608 $c->req->params->{foo};
609 $c->req->cookies->{sessionid};
610 $c->req->headers->content_type;
612 $c->req->uri_with( { page = $pager->next_page } );
614 =item * L<Catalyst::Response>
619 The response is like the request, but contains just response-specific
622 $c->res->body('Hello World');
623 $c->res->status(404);
624 $c->res->redirect('http://oook.de');
626 =item * L<Catalyst::Config>
632 =item * L<Catalyst::Log>
635 $c->log->debug('Something happened');
636 $c->log->info('Something you should know');
641 $c->stash->{foo} = 'bar';
642 $c->stash->{baz} = {baz => 'qox'};
643 $c->stash->{fred} = [qw/wilma pebbles/];
649 The last of these, the stash, is a universal hash for sharing data among
650 application components. For an example, we return to our 'hello' action:
653 my ( $self, $c ) = @_;
654 $c->stash->{message} = 'Hello World!';
655 $c->forward('show_message');
658 sub show_message : Private {
659 my ( $self, $c ) = @_;
660 $c->res->body( $c->stash->{message} );
663 Note that the stash should be used only for passing data in an
664 individual request cycle; it gets cleared at a new request. If you need
665 to maintain persistent data, use a session. See
666 L<Catalyst::Plugin::Session> for a comprehensive set of
667 Catalyst-friendly session-handling tools.
671 A Catalyst controller is defined by its actions. An action is a
672 subroutine with a special attribute. You've already seen some examples
673 of actions in this document. The URL (for example
674 http://localhost.3000/foo/bar) consists of two parts, the base
675 (http://localhost:3000/ in this example) and the path (foo/bar). Please
676 note that the trailing slash after the hostname[:port] always belongs to
677 base and not to the action.
681 =item * B<Application Wide Actions>
683 Actions which are called at the root level of the application
684 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
687 package MyApp::Controller::Root;
688 use base 'Catalyst::Controller';
689 # Sets the actions in this controller to be registered with no prefix
690 # so they function identically to actions created in MyApp.pm
691 __PACKAGE__->config->{namespace} = '';
692 sub default : Private {
693 my ( $self, $context ) = @_;
694 $context->response->body('Catalyst rocks!');
702 Catalyst supports several types of actions:
706 =item * B<Literal> (B<Path> actions)
708 package MyApp::Controller::My::Controller;
709 sub bar : Path('foo/bar') { }
711 Literal C<Path> actions will act relative to their current
712 namespace. The above example matches only
713 http://localhost:3000/my/controller/foo/bar. If you start your path with
714 a forward slash, it will match from the root. Example:
716 package MyApp::Controller::My::Controller;
717 sub bar : Path('/foo/bar') { }
719 Matches only http://localhost:3000/foo/bar.
721 package MyApp::Controller::My::Controller;
724 By leaving the C<Path> definition empty, it will match on the namespace
725 root. The above code matches http://localhost:3000/my/controller.
729 sub bar : Regex('^item(\d+)/order(\d+)$') { }
731 Matches any URL that matches the pattern in the action key, e.g.
732 http://localhost:3000/item23/order42. The '' around the regexp is
733 optional, but perltidy likes it. :)
735 Regex matches act globally, i.e. without reference to the namespace from
736 which it is called, so that a C<bar> method in the
737 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
738 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
739 explicitly put this in the regex. To achieve the above, you should
740 consider using a C<LocalRegex> action.
742 =item * B<LocalRegex>
744 sub bar : LocalRegex('^widget(\d+)$') { }
746 LocalRegex actions act locally. If you were to use C<bar> in
747 C<MyApp::Controller::Catalog>, the above example would match urls like
748 http://localhost:3000/catalog/widget23.
750 If you omit the "C<^>" from your regex, then it will match any depth
751 from the controller and not immediately off of the controller name. The
752 following example differs from the above code in that it will match
753 http://localhost:3000/catalog/foo/widget23 as well.
755 package MyApp::Controller::Catalog;
756 sub bar : LocalRegex('widget(\d+)$') { }
758 For both LocalRegex and Regex actions, if you use capturing parentheses
759 to extract values within the matching URL, those values are available in
760 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
761 would capture "23" in the above example, and
762 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
763 arguments at the end of your URL, you must use regex action keys. See
764 L</URL Path Handling> below.
766 =item * B<Top-level> (B<Global>)
768 package MyApp::Controller::Foo;
771 Matches http://localhost:3000/foo. The function name is mapped
772 directly to the application base. You can provide an equivalent
773 function in this case by doing the following:
775 package MyApp::Controller::Root
778 =item * B<Namespace-Prefixed> (B<Local>)
780 package MyApp::Controller::My::Controller;
783 Matches http://localhost:3000/my/controller/foo.
785 This action type indicates that the matching URL must be prefixed with a
786 modified form of the component's class (package) name. This modified
787 class name excludes the parts that have a pre-defined meaning in
788 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
789 "/", and converts the name to lower case. See L</Components> for a full
790 explanation of the pre-defined meaning of Catalyst component class
795 Catalyst also provides a method to build and dispatch chains of actions,
798 sub catalog : Chained : CaptureArgs(1) {
799 my ( $self, $c, $arg ) = @_;
803 sub item : Chained('catalog') : Args(1) {
804 my ( $self, $c, $arg ) = @_;
808 to handle a C</catalog/*/item/*> path. For extensive information about this
809 dispatch type, please see L<Catalyst::DispatchType::Chained>.
813 sub foo : Private { }
815 Matches no URL, and cannot be executed by requesting a URL that
816 corresponds to the action key. Private actions can be executed only
817 inside a Catalyst application, by calling the C<forward> method:
821 See L</Flow Control> for a full explanation of C<forward>. Note that, as
822 discussed there, when forwarding from another component, you must use
823 the absolute path to the method, so that a private C<bar> method in your
824 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
825 from elsewhere, be reached with
826 C<$c-E<gt>forward('/catalog/order/process/bar')>.
830 Args is not an action type per se, but an action modifier - it adds a
831 match restriction to any action it's provided to, requiring only as many
832 path parts as are specified for the action to be valid - for example in
833 MyApp::Controller::Foo,
837 would match any URL starting /foo/bar/. To restrict this you can do
839 sub bar :Local :Args(1)
841 to only match /foo/bar/*/
845 B<Note:> After seeing these examples, you probably wonder what the point
846 is of defining names for regex and path actions. Every public action is
847 also a private one, so you have one unified way of addressing components
850 =head4 Built-in Private Actions
852 In response to specific application states, Catalyst will automatically
853 call these built-in private actions in your application class:
857 =item * B<default : Private>
859 Called when no other action matches. Could be used, for example, for
860 displaying a generic frontpage for the main app, or an error page for
861 individual controllers.
863 If C<default> isn't acting how you would expect, look at using a
864 L</Literal> C<Path> action (with an empty path string). The difference
865 is that C<Path> takes arguments relative from the namespace and
866 C<default> I<always> takes arguments relative from the root, regardless
867 of what controller it's in. Indeed, this is now the recommended way of
868 handling default situations; the C<default> private controller should
869 be considered deprecated.
871 =item * B<index : Private>
873 C<index> is much like C<default> except that it takes no arguments
874 and it is weighted slightly higher in the matching process. It is
875 useful as a static entry point to a controller, e.g. to have a static
876 welcome page. Note that it's also weighted higher than Path.
878 =item * B<begin : Private>
880 Called at the beginning of a request, before any matching actions are
883 =item * B<end : Private>
885 Called at the end of a request, after all matching actions are called.
889 =head4 Built-in actions in controllers/autochaining
891 Package MyApp::Controller::Foo;
892 sub begin : Private { }
893 sub default : Private { }
894 sub auto : Private { }
896 You can define built-in private actions within your controllers as
897 well. The actions will override the ones in less-specific controllers,
898 or your application class. In other words, for each of the three
899 built-in private actions, only one will be run in any request
900 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
901 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
902 and C<MyApp::Controller::Catalog::Order::begin> would override this in
905 =item * B<auto : Private>
907 In addition to the normal built-in actions, you have a special action
908 for making chains, C<auto>. Such C<auto> actions will be run after any
909 C<begin>, but before your action is processed. Unlike the other
910 built-ins, C<auto> actions I<do not> override each other; they will be
911 called in turn, starting with the application class and going through to
912 the I<most> specific class. I<This is the reverse of the order in which
913 the normal built-ins override each other>.
915 Here are some examples of the order in which the various built-ins
920 =item for a request for C</foo/foo>
924 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
927 =item for a request for C</foo/bar/foo>
929 MyApp::Controller::Foo::Bar::begin
931 MyApp::Controller::Foo::auto
932 MyApp::Controller::Foo::Bar::auto
933 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
934 MyApp::Controller::Foo::Bar::end
938 The C<auto> action is also distinguished by the fact that you can break
939 out of the processing chain by returning 0. If an C<auto> action returns
940 0, any remaining actions will be skipped, except for C<end>. So, for the
941 request above, if the first auto returns false, the chain would look
946 =item for a request for C</foo/bar/foo> where first C<auto> returns
949 MyApp::Controller::Foo::Bar::begin
951 MyApp::Controller::Foo::Bar::end
955 An example of why one might use this is an authentication action: you
956 could set up a C<auto> action to handle authentication in your
957 application class (which will always be called first), and if
958 authentication fails, returning 0 would skip any remaining methods
961 B<Note:> Looking at it another way, C<auto> actions have to return a
962 true value to continue processing! You can also C<die> in the auto
963 action; in that case, the request will go straight to the finalize
964 stage, without processing further actions.
966 =head4 URL Path Handling
968 You can pass variable arguments as part of the URL path, separated with
969 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
970 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
971 where C<$bar> and C<$baz> may vary:
973 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
975 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
977 sub boo : Path('foo/boo') { .. }
978 sub hoo : Path('foo/boo/hoo') { .. }
980 Catalyst matches actions in most specific to least specific order:
984 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
986 So Catalyst would never mistakenly dispatch the first two URLs to the
989 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
990 still match a URL containing arguments, however the arguments won't be
993 =head4 Parameter Processing
995 Parameters passed in the URL query string are handled with methods in
996 the L<Catalyst::Request> class. The C<param> method is functionally
997 equivalent to the C<param> method of C<CGI.pm> and can be used in
998 modules that require this.
1000 # http://localhost:3000/catalog/view/?category=hardware&page=3
1001 my $category = $c->req->param('category');
1002 my $current_page = $c->req->param('page') || 1;
1004 # multiple values for single parameter name
1005 my @values = $c->req->param('scrolling_list');
1007 # DFV requires a CGI.pm-like input hash
1008 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1012 You control the application flow with the C<forward> method, which
1013 accepts the key of an action to execute. This can be an action in the
1014 same or another Catalyst controller, or a Class name, optionally
1015 followed by a method name. After a C<forward>, the control flow will
1016 return to the method from which the C<forward> was issued.
1018 A C<forward> is similar to a method call. The main differences are that
1019 it wraps the call in an C<eval> to allow exception handling; it
1020 automatically passes along the context object (C<$c> or C<$context>);
1021 and it allows profiling of each call (displayed in the log with
1024 sub hello : Global {
1025 my ( $self, $c ) = @_;
1026 $c->stash->{message} = 'Hello World!';
1027 $c->forward('check_message'); # $c is automatically included
1030 sub check_message : Private {
1031 my ( $self, $c ) = @_;
1032 return unless $c->stash->{message};
1033 $c->forward('show_message');
1036 sub show_message : Private {
1037 my ( $self, $c ) = @_;
1038 $c->res->body( $c->stash->{message} );
1041 A C<forward> does not create a new request, so your request object
1042 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1043 using C<forward> and issuing a redirect.
1045 You can pass new arguments to a C<forward> by adding them
1046 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1047 will be changed for the duration of the C<forward> only; upon
1048 return, the original value of C<$c-E<gt>req-E<gt>args> will
1051 sub hello : Global {
1052 my ( $self, $c ) = @_;
1053 $c->stash->{message} = 'Hello World!';
1054 $c->forward('check_message',[qw/test1/]);
1055 # now $c->req->args is back to what it was before
1058 sub check_message : Private {
1059 my ( $self, $c ) = @_;
1060 my $first_argument = $c->req->args->[0]; # now = 'test1'
1064 As you can see from these examples, you can just use the method name as
1065 long as you are referring to methods in the same controller. If you want
1066 to forward to a method in another controller, or the main application,
1067 you will have to refer to the method by absolute path.
1069 $c->forward('/my/controller/action');
1070 $c->forward('/default'); # calls default in main application
1072 Here are some examples of how to forward to classes and methods.
1074 sub hello : Global {
1075 my ( $self, $c ) = @_;
1076 $c->forward(qw/MyApp::Model::Hello say_hello/);
1080 my ( $self, $c ) = @_;
1081 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1084 package MyApp::Model::Hello;
1087 my ( $self, $c ) = @_;
1088 $c->res->body('Hello World!');
1092 my ( $self, $c ) = @_;
1093 $c->res->body('Goodbye World!');
1096 Note that C<forward> returns to the calling action and continues
1097 processing after the action finishes. If you want all further processing
1098 in the calling action to stop, use C<detach> instead, which will execute
1099 the C<detach>ed action and not return to the calling sub. In both cases,
1100 Catalyst will automatically try to call process() if you omit the
1106 Catalyst has a built-in http server for testing or local
1107 deployment. (Later, you can easily use a more powerful server, for
1108 example Apache/mod_perl or FastCGI, in a production environment.)
1110 Start your application on the command line...
1112 script/myapp_server.pl
1114 ...then visit http://localhost:3000/ in a browser to view the output.
1116 You can also do it all from the command line:
1118 script/myapp_test.pl http://localhost/
1120 Catalyst has a number of tools for actual regression testing of
1121 applications. The helper scripts will automatically generate basic tests
1122 that can be extended as you develop your project. To write your own
1123 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1126 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1132 =item * L<Catalyst::Manual::About>
1134 =item * L<Catalyst::Manual::Tutorial>
1142 Join #catalyst on irc.perl.org.
1143 Join #catalyst-dev on irc.perl.org to help with development.
1147 http://lists.rawmode.org/mailman/listinfo/catalyst
1148 http://lists.rawmode.org/mailman/listinfo/catalyst-dev
1152 Sebastian Riedel, C<sri@oook.de>
1153 David Naughton, C<naughton@umn.edu>
1154 Marcus Ramberg, C<mramberg@cpan.org>
1155 Jesse Sheidlower, C<jester@panix.com>
1156 Danijel Milicevic, C<me@danijel.de>
1157 Kieren Diment, C<kd@totaldatasolution.com>
1158 Yuval Kogman, C<nothingmuch@woobling.org>
1162 This program is free software. You can redistribute it and/or modify it
1163 under the same terms as Perl itself.