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), and
18 L<Maypole|Maypole>, upon which it was originally based. Its most
19 important design philosphy is to provide easy access to all the tools
20 you need to develop web applications, with few restrictions on how you
21 need to use these tools. However, this does mean that it is always
22 possible to do things in a different way. Other web frameworks are
23 I<initially> simpler to use, but achieve this by locking the programmer
24 into a single set of tools. Catalyst's emphasis on flexibility means
25 that you have to think more to use it. We view this as a feature. For
26 example, this leads to Catalyst being more suited to system integration
27 tasks 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 Model, View and Controller components must inherit from L<Catalyst::Model>,
220 L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
221 from L<Catalyst::Component> which provides a simple class structure and some
222 common class methods like C<config> and C<new> (constructor).
224 package MyApp::Controller::Catalog;
227 use base 'Catalyst::Controller';
229 __PACKAGE__->config( foo => 'bar' );
233 You don't have to C<use> or otherwise register Models, Views, and
234 Controllers. Catalyst automatically discovers and instantiates them
235 when you call C<setup> in the main application. All you need to do is
236 put them in directories named for each Component type. You can use a
237 short alias for each one.
241 =item * B<MyApp/Model/>
245 =item * B<MyApp/View/>
249 =item * B<MyApp/Controller/>
255 In older versions of Catalyst, the recommended practice (and the one
256 automatically created by helper scripts) was to name the directories
257 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
258 the use of the full names.
262 To show how to define views, we'll use an already-existing base class for the
263 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
264 inherit from this class:
266 package MyApp::View::TT;
269 use base 'Catalyst::View::TT';
273 (You can also generate this automatically by using the helper script:
275 script/myapp_create.pl view TT TT
277 where the first C<TT> tells the script that the name of the view should
278 be C<TT>, and the second that it should be a Template Toolkit view.)
280 This gives us a process() method and we can now just do
281 $c->forward('MyApp::View::TT') to render our templates. The base class
282 makes process() implicit, so we don't have to say
283 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
286 my ( $self, $c ) = @_;
287 $c->stash->{template} = 'hello.tt';
291 my ( $self, $c ) = @_;
292 $c->forward( $c->view('TT') );
295 You normally render templates at the end of a request, so it's a perfect
296 use for the global C<end> action.
298 In practice, however, you would use a default C<end> action as supplied
299 by L<Catalyst::Action::RenderView>.
301 Also, be sure to put the template under the directory specified in
302 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
307 Models are providers of data. This data could come from anywhere - a
308 search engine index, a spreadsheet, the file system - but typically a
309 Model represents a database table. The data source does not
310 intrinsically have much to do with web applications or Catalyst - it
311 could just as easily be used to write an offline report generator or a
314 To show how to define models, again we'll use an already-existing base
315 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
316 We'll also need L<DBIx::Class::Schema::Loader>.
318 But first, we need a database.
322 id INTEGER PRIMARY KEY,
327 id INTEGER PRIMARY KEY,
328 foo INTEGER REFERENCES foo,
332 INSERT INTO foo (data) VALUES ('TEST!');
334 % sqlite3 /tmp/myapp.db < myapp.sql
336 Now we can create a DBIC::Schema model for this database.
338 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
340 L<DBIx::Class::Schema::Loader> automatically loads table layouts and
341 relationships, and converts them into a static schema definition C<MySchema>,
342 which you can edit later.
344 Use the stash to pass data to your templates.
346 We add the following to MyApp/Controller/Root.pm
349 my ( $self, $c, $id ) = @_;
351 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
357 my ( $self, $c ) = @_;
359 $c->stash->{template} ||= 'index.tt';
360 $c->forward( $c->view('TT') );
363 We then create a new template file "root/index.tt" containing:
365 The Id's data is [% item.data %]
367 Models do not have to be part of your Catalyst application; you
368 can always call an outside module that serves as your Model:
372 my ( $self, $c ) = @_;
374 $c->stash->{template} = 'list.tt';
376 use Some::Outside::Database::Module;
377 my @records = Some::Outside::Database::Module->search({
378 artist => 'Led Zeppelin',
381 $c->stash->{records} = \@records;
384 But by using a Model that is part of your Catalyst application, you
385 gain several things: you don't have to C<use> each component, Catalyst
386 will find and load it automatically at compile-time; you can
387 C<forward> to the module, which can only be done to Catalyst
388 components. Only Catalyst components can be fetched with
389 C<$c-E<gt>model('SomeModel')>.
391 Happily, since many people have existing Model classes that they
392 would like to use with Catalyst (or, conversely, they want to
393 write Catalyst models that can be used outside of Catalyst, e.g.
394 in a cron job), it's trivial to write a simple component in
395 Catalyst that slurps in an outside Model:
397 package MyApp::Model::DB;
398 use base qw/Catalyst::Model::DBIC::Schema/;
400 schema_class => 'Some::DBIC::Schema',
401 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
405 and that's it! Now C<Some::DBIC::Schema> is part of your
406 Cat app as C<MyApp::Model::DB>.
408 Within Catalyst, the common approach to writing a model for your
409 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
410 bunch of XMLs, or anything really) with an object that contains
411 configuration data, convenience methods, and so forth. Thus you
412 will in effect have two models - a wrapper model that knows something
413 about Catalyst and your web application, and a generic model that is
414 totally independent of these needs.
416 Technically, within Catalyst a model is a B<component> - an instance of
417 the model's class belonging to the application. It is important to
418 stress that the lifetime of these objects is per application, not per
421 While the model base class (L<Catalyst::Model>) provides things like
422 C<config> to better integrate the model into the application, sometimes
423 this is not enough, and the model requires access to C<$c> itself.
425 Situations where this need might arise include:
431 Interacting with another model
435 Using per-request data to control behavior
439 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
443 From a style perspective it's usually considered bad form to make your
444 model "too smart" about things - it should worry about business logic
445 and leave the integration details to the controllers. If, however, you
446 find that it does not make sense at all to use an auxillary controller
447 around the model, and the model's need to access C<$c> cannot be
448 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
452 Multiple controllers are a good way to separate logical domains of your
455 package MyApp::Controller::Login;
457 use base qw/Catalyst::Controller/;
459 sub login : Path("login") { }
460 sub new_password : Path("new-password") { }
461 sub logout : Path("logout") { }
463 package MyApp::Controller::Catalog;
465 use base qw/Catalyst::Controller/;
470 package MyApp::Controller::Cart;
472 use base qw/Catalyst::Controller/;
475 sub update : Local { }
476 sub order : Local { }
478 Note that you can also supply attributes via the Controller's config so
479 long as you have at least one attribute on a subref to be exported
480 (:Action is commonly used for this) - for example the following is
481 equivalent to the same controller above:
483 package MyApp::Controller::Login;
485 use base qw/Catalyst::Controller/;
489 'sign_in' => { Path => 'sign-in' },
490 'new_password' => { Path => 'new-password' },
491 'sign_out' => { Path => 'sign-out' },
495 sub sign_in : Action { }
496 sub new_password : Action { }
497 sub sign_out : Action { }
499 =head3 ACCEPT_CONTEXT
501 Whenever you call $c->component("Foo") you get back an object - the
502 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
503 method instead of returning the model itself, the return value of C<<
504 $model->ACCEPT_CONTEXT( $c ) >> will be used.
506 This means that whenever your model/view/controller needs to talk to C<$c> it
507 gets a chance to do this when it's needed.
509 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
510 with the context object set, or it will return a thin wrapper that contains
511 C<$c> and delegates to the per-application model object.
513 A typical C<ACCEPT_CONTEXT> method could look like this:
516 my ( $self, $c, @extra_arguments ) = @_;
517 bless { %$self, c => $c }, ref($self);
520 effectively treating $self as a B<prototype object> that gets a new parameter.
521 C<@extra_arguments> comes from any trailing arguments to
522 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
523 C<< $c->view(...) >> etc).
525 The life time of this value is B<per usage>, and not per request. To make this
526 per request you can use the following technique:
528 Add a field to C<$c>, like C<my_model_instance>. Then write your
529 C<ACCEPT_CONTEXT> method to look like this:
532 my ( $self, $c ) = @_;
534 if ( my $per_request = $c->my_model_instance ) {
537 my $new_instance = bless { %$self, c => $c }, ref($self);
538 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
539 $c->my_model_instance( $new_instance );
540 return $new_instance;
544 =head3 Application Class
546 In addition to the Model, View, and Controller components, there's a
547 single class that represents your application itself. This is where you
548 configure your application, load plugins, and extend Catalyst.
553 use Catalyst qw/-Debug/; # Add other plugins here, e.g.
554 # for session support
557 name => 'My Application',
559 # You can put anything else you want in here:
560 my_configuration_variable => 'something',
564 In older versions of Catalyst, the application class was where you put
565 global actions. However, as of version 5.66, the recommended practice is
566 to place such actions in a special Root controller (see L</Actions>,
567 below), to avoid namespace collisions.
573 The name of your application.
577 Optionally, you can specify a B<root> parameter for templates and static
578 data. If omitted, Catalyst will try to auto-detect the directory's
579 location. You can define as many parameters as you want for plugins or
580 whatever you need. You can access them anywhere in your application via
581 C<$context-E<gt>config-E<gt>{$param_name}>.
585 Catalyst automatically blesses a Context object into your application
586 class and makes it available everywhere in your application. Use the
587 Context to directly interact with Catalyst and glue your L</Components>
588 together. For example, if you need to use the Context from within a
589 Template Toolkit template, it's already there:
591 <h1>Welcome to [% c.config.name %]!</h1>
593 As illustrated in our URL-to-Action dispatching example, the Context is
594 always the second method parameter, behind the Component object
595 reference or class name itself. Previously we called it C<$context> for
596 clarity, but most Catalyst developers just call it C<$c>:
599 my ( $self, $c ) = @_;
600 $c->res->body('Hello World!');
603 The Context contains several important objects:
607 =item * L<Catalyst::Request>
612 The request object contains all kinds of request-specific information, like
613 query parameters, cookies, uploads, headers, and more.
615 $c->req->params->{foo};
616 $c->req->cookies->{sessionid};
617 $c->req->headers->content_type;
619 $c->req->uri_with( { page = $pager->next_page } );
621 =item * L<Catalyst::Response>
626 The response is like the request, but contains just response-specific
629 $c->res->body('Hello World');
630 $c->res->status(404);
631 $c->res->redirect('http://oook.de');
633 =item * L<Catalyst::Config>
639 =item * L<Catalyst::Log>
642 $c->log->debug('Something happened');
643 $c->log->info('Something you should know');
648 $c->stash->{foo} = 'bar';
649 $c->stash->{baz} = {baz => 'qox'};
650 $c->stash->{fred} = [qw/wilma pebbles/];
656 The last of these, the stash, is a universal hash for sharing data among
657 application components. For an example, we return to our 'hello' action:
660 my ( $self, $c ) = @_;
661 $c->stash->{message} = 'Hello World!';
662 $c->forward('show_message');
665 sub show_message : Private {
666 my ( $self, $c ) = @_;
667 $c->res->body( $c->stash->{message} );
670 Note that the stash should be used only for passing data in an
671 individual request cycle; it gets cleared at a new request. If you need
672 to maintain persistent data, use a session. See
673 L<Catalyst::Plugin::Session> for a comprehensive set of
674 Catalyst-friendly session-handling tools.
678 A Catalyst controller is defined by its actions. An action is a
679 subroutine with a special attribute. You've already seen some examples
680 of actions in this document. The URL (for example
681 http://localhost.3000/foo/bar) consists of two parts, the base
682 (http://localhost:3000/ in this example) and the path (foo/bar). Please
683 note that the trailing slash after the hostname[:port] always belongs to
684 base and not to the action.
688 =item * B<Application Wide Actions>
690 Actions which are called at the root level of the application
691 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
694 package MyApp::Controller::Root;
695 use base 'Catalyst::Controller';
696 # Sets the actions in this controller to be registered with no prefix
697 # so they function identically to actions created in MyApp.pm
698 __PACKAGE__->config->{namespace} = '';
699 sub default : Private {
700 my ( $self, $context ) = @_;
701 $context->response->body('Catalyst rocks!');
709 Catalyst supports several types of actions:
713 =item * B<Literal> (B<Path> actions)
715 package MyApp::Controller::My::Controller;
716 sub bar : Path('foo/bar') { }
718 Literal C<Path> actions will act relative to their current
719 namespace. The above example matches only
720 http://localhost:3000/my/controller/foo/bar. If you start your path with
721 a forward slash, it will match from the root. Example:
723 package MyApp::Controller::My::Controller;
724 sub bar : Path('/foo/bar') { }
726 Matches only http://localhost:3000/foo/bar.
728 package MyApp::Controller::My::Controller;
731 By leaving the C<Path> definition empty, it will match on the namespace
732 root. The above code matches http://localhost:3000/my/controller.
736 sub bar : Regex('^item(\d+)/order(\d+)$') { }
738 Matches any URL that matches the pattern in the action key, e.g.
739 http://localhost:3000/item23/order42. The '' around the regexp is
740 optional, but perltidy likes it. :)
742 Regex matches act globally, i.e. without reference to the namespace from
743 which it is called, so that a C<bar> method in the
744 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
745 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
746 explicitly put this in the regex. To achieve the above, you should
747 consider using a C<LocalRegex> action.
749 =item * B<LocalRegex>
751 sub bar : LocalRegex('^widget(\d+)$') { }
753 LocalRegex actions act locally. If you were to use C<bar> in
754 C<MyApp::Controller::Catalog>, the above example would match urls like
755 http://localhost:3000/catalog/widget23.
757 If you omit the "C<^>" from your regex, then it will match any depth
758 from the controller and not immediately off of the controller name. The
759 following example differs from the above code in that it will match
760 http://localhost:3000/catalog/foo/widget23 as well.
762 package MyApp::Controller::Catalog;
763 sub bar : LocalRegex('widget(\d+)$') { }
765 For both LocalRegex and Regex actions, if you use capturing parentheses
766 to extract values within the matching URL, those values are available in
767 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
768 would capture "23" in the above example, and
769 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
770 arguments at the end of your URL, you must use regex action keys. See
771 L</URL Path Handling> below.
773 =item * B<Top-level> (B<Global>)
775 package MyApp::Controller::Foo;
778 Matches http://localhost:3000/foo. The function name is mapped
779 directly to the application base. You can provide an equivalent
780 function in this case by doing the following:
782 package MyApp::Controller::Root
785 =item * B<Namespace-Prefixed> (B<Local>)
787 package MyApp::Controller::My::Controller;
790 Matches http://localhost:3000/my/controller/foo.
792 This action type indicates that the matching URL must be prefixed with a
793 modified form of the component's class (package) name. This modified
794 class name excludes the parts that have a pre-defined meaning in
795 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
796 "/", and converts the name to lower case. See L</Components> for a full
797 explanation of the pre-defined meaning of Catalyst component class
802 Catalyst also provides a method to build and dispatch chains of actions,
805 sub catalog : Chained : CaptureArgs(1) {
806 my ( $self, $c, $arg ) = @_;
810 sub item : Chained('catalog') : Args(1) {
811 my ( $self, $c, $arg ) = @_;
815 to handle a C</catalog/*/item/*> path. For further information about this
816 dispatch type, please see L<Catalyst::DispatchType::Chained>.
820 sub foo : Private { }
822 Matches no URL, and cannot be executed by requesting a URL that
823 corresponds to the action key. Catalyst's :Private attribute is
824 exclusive and doesn't work with other attributes (so will not work
825 combined with Path or Chained attributes). With the exception of the
826 C< index >, C< auto > and C< default > actions, Private actions can
827 only be executed from inside a Catalyst application, by calling the
828 C<forward> or C<detach> methods:
834 See L</Flow Control> for a full explanation of C<forward>. Note that, as
835 discussed there, when forwarding from another component, you must use
836 the absolute path to the method, so that a private C<bar> method in your
837 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
838 from elsewhere, be reached with
839 C<$c-E<gt>forward('/catalog/order/process/bar')>.
843 Args is not an action type per se, but an action modifier - it adds a
844 match restriction to any action it's provided to, requiring only as many
845 path parts as are specified for the action to be valid - for example in
846 MyApp::Controller::Foo,
850 would match any URL starting /foo/bar/. To restrict this you can do
852 sub bar :Local :Args(1)
854 to only match /foo/bar/*/
858 B<Note:> After seeing these examples, you probably wonder what the point
859 is of defining names for regex and path actions. Every public action is
860 also a private one, so you have one unified way of addressing components
863 =head4 Built-in Private Actions
865 In response to specific application states, Catalyst will automatically
866 call these built-in private actions in your application class:
870 =item * B<default : Private>
872 Called when no other action matches. Could be used, for example, for
873 displaying a generic frontpage for the main app, or an error page for
874 individual controllers.
876 If C<default> isn't acting how you would expect, look at using a
877 L</Literal> C<Path> action (with an empty path string). The difference
878 is that C<Path> takes arguments relative from the namespace and
879 C<default> I<always> takes arguments relative from the root, regardless
880 of what controller it's in. Indeed, this is now the recommended way of
881 handling default situations; the C<default> private controller should
882 be considered deprecated.
884 =item * B<index : Private>
886 C<index> is much like C<default> except that it takes no arguments
887 and it is weighted slightly higher in the matching process. It is
888 useful as a static entry point to a controller, e.g. to have a static
889 welcome page. Note that it's also weighted higher than Path.
891 =item * B<begin : Private>
893 Called at the beginning of a request, before any matching actions are
896 =item * B<end : Private>
898 Called at the end of a request, after all matching actions are called.
902 =head4 Built-in actions in controllers/autochaining
904 Package MyApp::Controller::Foo;
905 sub begin : Private { }
906 sub default : Private { }
907 sub auto : Private { }
909 You can define built-in private actions within your controllers as
910 well. The actions will override the ones in less-specific controllers,
911 or your application class. In other words, for each of the three
912 built-in private actions, only one will be run in any request
913 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
914 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
915 and C<MyApp::Controller::Catalog::Order::begin> would override this in
920 =item * B<auto : Private>
922 In addition to the normal built-in actions, you have a special action
923 for making chains, C<auto>. Such C<auto> actions will be run after any
924 C<begin>, but before your action is processed. Unlike the other
925 built-ins, C<auto> actions I<do not> override each other; they will be
926 called in turn, starting with the application class and going through to
927 the I<most> specific class. I<This is the reverse of the order in which
928 the normal built-ins override each other>.
932 Here are some examples of the order in which the various built-ins
937 =item for a request for C</foo/foo>
941 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
944 =item for a request for C</foo/bar/foo>
946 MyApp::Controller::Foo::Bar::begin
948 MyApp::Controller::Foo::auto
949 MyApp::Controller::Foo::Bar::auto
950 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
951 MyApp::Controller::Foo::Bar::end
955 The C<auto> action is also distinguished by the fact that you can break
956 out of the processing chain by returning 0. If an C<auto> action returns
957 0, any remaining actions will be skipped, except for C<end>. So, for the
958 request above, if the first auto returns false, the chain would look
963 =item for a request for C</foo/bar/foo> where first C<auto> returns
966 MyApp::Controller::Foo::Bar::begin
968 MyApp::Controller::Foo::Bar::end
972 An example of why one might use this is an authentication action: you
973 could set up a C<auto> action to handle authentication in your
974 application class (which will always be called first), and if
975 authentication fails, returning 0 would skip any remaining methods
978 B<Note:> Looking at it another way, C<auto> actions have to return a
979 true value to continue processing! You can also C<die> in the auto
980 action; in that case, the request will go straight to the finalize
981 stage, without processing further actions.
983 =head4 URL Path Handling
985 You can pass variable arguments as part of the URL path, separated with
986 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
987 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
988 where C<$bar> and C<$baz> may vary:
990 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
992 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
994 sub boo : Path('foo/boo') { .. }
995 sub hoo : Path('foo/boo/hoo') { .. }
997 Catalyst matches actions in most specific to least specific order:
1001 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1003 So Catalyst would never mistakenly dispatch the first two URLs to the
1006 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1007 still match a URL containing arguments, however the arguments won't be
1008 available via C<@_>.
1010 =head4 Parameter Processing
1012 Parameters passed in the URL query string are handled with methods in
1013 the L<Catalyst::Request> class. The C<param> method is functionally
1014 equivalent to the C<param> method of C<CGI.pm> and can be used in
1015 modules that require this.
1017 # http://localhost:3000/catalog/view/?category=hardware&page=3
1018 my $category = $c->req->param('category');
1019 my $current_page = $c->req->param('page') || 1;
1021 # multiple values for single parameter name
1022 my @values = $c->req->param('scrolling_list');
1024 # DFV requires a CGI.pm-like input hash
1025 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1029 You control the application flow with the C<forward> method, which
1030 accepts the key of an action to execute. This can be an action in the
1031 same or another Catalyst controller, or a Class name, optionally
1032 followed by a method name. After a C<forward>, the control flow will
1033 return to the method from which the C<forward> was issued.
1035 A C<forward> is similar to a method call. The main differences are that
1036 it wraps the call in an C<eval> to allow exception handling; it
1037 automatically passes along the context object (C<$c> or C<$context>);
1038 and it allows profiling of each call (displayed in the log with
1041 sub hello : Global {
1042 my ( $self, $c ) = @_;
1043 $c->stash->{message} = 'Hello World!';
1044 $c->forward('check_message'); # $c is automatically included
1047 sub check_message : Private {
1048 my ( $self, $c ) = @_;
1049 return unless $c->stash->{message};
1050 $c->forward('show_message');
1053 sub show_message : Private {
1054 my ( $self, $c ) = @_;
1055 $c->res->body( $c->stash->{message} );
1058 A C<forward> does not create a new request, so your request object
1059 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1060 using C<forward> and issuing a redirect.
1062 You can pass new arguments to a C<forward> by adding them
1063 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1064 will be changed for the duration of the C<forward> only; upon
1065 return, the original value of C<$c-E<gt>req-E<gt>args> will
1068 sub hello : Global {
1069 my ( $self, $c ) = @_;
1070 $c->stash->{message} = 'Hello World!';
1071 $c->forward('check_message',[qw/test1/]);
1072 # now $c->req->args is back to what it was before
1075 sub check_message : Private {
1076 my ( $self, $c ) = @_;
1077 my $first_argument = $c->req->args->[0]; # now = 'test1'
1081 As you can see from these examples, you can just use the method name as
1082 long as you are referring to methods in the same controller. If you want
1083 to forward to a method in another controller, or the main application,
1084 you will have to refer to the method by absolute path.
1086 $c->forward('/my/controller/action');
1087 $c->forward('/default'); # calls default in main application
1089 Here are some examples of how to forward to classes and methods.
1091 sub hello : Global {
1092 my ( $self, $c ) = @_;
1093 $c->forward(qw/MyApp::Model::Hello say_hello/);
1097 my ( $self, $c ) = @_;
1098 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1101 package MyApp::Model::Hello;
1104 my ( $self, $c ) = @_;
1105 $c->res->body('Hello World!');
1109 my ( $self, $c ) = @_;
1110 $c->res->body('Goodbye World!');
1113 Note that C<forward> returns to the calling action and continues
1114 processing after the action finishes. If you want all further processing
1115 in the calling action to stop, use C<detach> instead, which will execute
1116 the C<detach>ed action and not return to the calling sub. In both cases,
1117 Catalyst will automatically try to call process() if you omit the
1123 Catalyst has a built-in http server for testing or local
1124 deployment. (Later, you can easily use a more powerful server, for
1125 example Apache/mod_perl or FastCGI, in a production environment.)
1127 Start your application on the command line...
1129 script/myapp_server.pl
1131 ...then visit http://localhost:3000/ in a browser to view the output.
1133 You can also do it all from the command line:
1135 script/myapp_test.pl http://localhost/
1137 Catalyst has a number of tools for actual regression testing of
1138 applications. The helper scripts will automatically generate basic tests
1139 that can be extended as you develop your project. To write your own
1140 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1143 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1151 =item * L<Catalyst::Manual::About>
1153 =item * L<Catalyst::Manual::Tutorial>
1163 Join #catalyst on irc.perl.org.
1164 Join #catalyst-dev on irc.perl.org to help with development.
1168 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1169 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1173 Sebastian Riedel, C<sri@oook.de>
1174 David Naughton, C<naughton@umn.edu>
1175 Marcus Ramberg, C<mramberg@cpan.org>
1176 Jesse Sheidlower, C<jester@panix.com>
1177 Danijel Milicevic, C<me@danijel.de>
1178 Kieren Diment, C<kd@totaldatasolution.com>
1179 Yuval Kogman, C<nothingmuch@woobling.org>
1183 This program is free software. You can redistribute it and/or modify it
1184 under the same terms as Perl itself.