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 Note that actions with the C< :Local > attribute are equivalent to
108 using a C<:Path('/action_name') > attribute (note the leading slash).
109 So our action could be equivalently:
111 sub hello : Path('/hello') {
112 my ( $self, $context ) = @_;
113 $context->response->body('Hello World!');
117 =item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
119 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
120 engines are also available.
126 The best part is that Catalyst implements all this flexibility in a very
131 =item * B<Building Block Interface>
133 Components interoperate very smoothly. For example, Catalyst
134 automatically makes a L</Context> object available to every
135 component. Via the context, you can access the request object, share
136 data between components, and control the flow of your
137 application. Building a Catalyst application feels a lot like snapping
138 together toy building blocks, and everything just works.
140 =item * B<Component Auto-Discovery>
142 No need to C<use> all of your components. Catalyst automatically finds
145 =item * B<Pre-Built Components for Popular Modules>
147 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
148 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
150 =item * B<Built-in Test Framework>
152 Catalyst comes with a built-in, lightweight http server and test
153 framework, making it easy to test applications from the web browser,
154 and the command line.
156 =item * B<Helper Scripts>
158 Catalyst provides helper scripts to quickly generate running starter
159 code for components and unit tests. Install L<Catalyst::Devel> and see
166 Here's how to install Catalyst and get a simple application up and
167 running, using the helper scripts described above.
171 Installation of Catalyst can be a time-consuming and frustrating
172 effort, due to its large number of dependencies. The easiest way
173 to get up and running is to use Matt Trout's C<cat-install>
174 script, from L<http://www.shadowcatsystems.co.uk/static/cat-install>,
175 and then install L<Catalyst::Devel>.
178 # perl -MCPAN -e 'install Catalyst::Devel'
185 $ script/myapp_create.pl controller Library::Login
189 $ script/myapp_server.pl
191 Now visit these locations with your favorite browser or user agent to see
194 (NOTE: Although we create a controller here, we don't actually use it.
195 Both of these URLs should take you to the welcome page.)
200 =item http://localhost:3000/
202 =item http://localhost:3000/library/login/
208 Let's see how Catalyst works, by taking a closer look at the components
209 and other parts of a Catalyst application.
213 Catalyst has an uncommonly flexible component system. You can define as
214 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
215 previously, the general idea is that the View is responsible for the
216 output of data to the user (typically via a web browser, but a View can
217 also generate PDFs or e-mails, for example); the Model is responsible
218 for providing data (typically from a relational database); and the
219 Controller is responsible for interacting with the user and deciding
220 how user input determines what actions the application takes.
222 In the world of MVC, there are frequent discussions and disagreements
223 about the nature of each element - whether certain types of logic
224 belong in the Model or the Controller, etc. Catalyst's flexibility
225 means that this decision is entirely up to you, the programmer;
226 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
227 a general discussion of these issues.
229 Model, View and Controller components must inherit from L<Catalyst::Model>,
230 L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
231 from L<Catalyst::Component> which provides a simple class structure and some
232 common class methods like C<config> and C<new> (constructor).
234 package MyApp::Controller::Catalog;
237 use base 'Catalyst::Controller';
239 __PACKAGE__->config( foo => 'bar' );
243 You don't have to C<use> or otherwise register Models, Views, and
244 Controllers. Catalyst automatically discovers and instantiates them
245 when you call C<setup> in the main application. All you need to do is
246 put them in directories named for each Component type. You can use a
247 short alias for each one.
251 =item * B<MyApp/Model/>
255 =item * B<MyApp/View/>
259 =item * B<MyApp/Controller/>
265 In older versions of Catalyst, the recommended practice (and the one
266 automatically created by helper scripts) was to name the directories
267 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
268 the use of the full names.
272 To show how to define views, we'll use an already-existing base class for the
273 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
274 inherit from this class:
276 package MyApp::View::TT;
279 use base 'Catalyst::View::TT';
283 (You can also generate this automatically by using the helper script:
285 script/myapp_create.pl view TT TT
287 where the first C<TT> tells the script that the name of the view should
288 be C<TT>, and the second that it should be a Template Toolkit view.)
290 This gives us a process() method and we can now just do
291 $c->forward('MyApp::View::TT') to render our templates. The base class
292 makes process() implicit, so we don't have to say
293 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
296 my ( $self, $c ) = @_;
297 $c->stash->{template} = 'hello.tt';
301 my ( $self, $c ) = @_;
302 $c->forward( $c->view('TT') );
305 You normally render templates at the end of a request, so it's a perfect
306 use for the global C<end> action.
308 In practice, however, you would use a default C<end> action as supplied
309 by L<Catalyst::Action::RenderView>.
311 Also, be sure to put the template under the directory specified in
312 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
317 Models are providers of data. This data could come from anywhere - a
318 search engine index, a spreadsheet, the file system - but typically a
319 Model represents a database table. The data source does not
320 intrinsically have much to do with web applications or Catalyst - it
321 could just as easily be used to write an offline report generator or a
324 To show how to define models, again we'll use an already-existing base
325 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
326 We'll also need L<DBIx::Class::Schema::Loader>.
328 But first, we need a database.
332 id INTEGER PRIMARY KEY,
337 id INTEGER PRIMARY KEY,
338 foo INTEGER REFERENCES foo,
342 INSERT INTO foo (data) VALUES ('TEST!');
344 % sqlite3 /tmp/myapp.db < myapp.sql
346 Now we can create a DBIC::Schema model for this database.
348 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
350 L<DBIx::Class::Schema::Loader> can automaticall load table layouts and
351 relationships, and convert them into a static schema definition
352 C<MySchema>, which you can edit later.
354 Use the stash to pass data to your templates.
356 We add the following to MyApp/Controller/Root.pm
359 my ( $self, $c, $id ) = @_;
361 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
367 my ( $self, $c ) = @_;
369 $c->stash->{template} ||= 'index.tt';
370 $c->forward( $c->view('TT') );
373 We then create a new template file "root/index.tt" containing:
375 The Id's data is [% item.data %]
377 Models do not have to be part of your Catalyst application; you
378 can always call an outside module that serves as your Model:
382 my ( $self, $c ) = @_;
384 $c->stash->{template} = 'list.tt';
386 use Some::Outside::Database::Module;
387 my @records = Some::Outside::Database::Module->search({
388 artist => 'Led Zeppelin',
391 $c->stash->{records} = \@records;
394 But by using a Model that is part of your Catalyst application, you
395 gain several things: you don't have to C<use> each component, Catalyst
396 will find and load it automatically at compile-time; you can
397 C<forward> to the module, which can only be done to Catalyst
398 components. Only Catalyst components can be fetched with
399 C<$c-E<gt>model('SomeModel')>.
401 Happily, since many people have existing Model classes that they
402 would like to use with Catalyst (or, conversely, they want to
403 write Catalyst models that can be used outside of Catalyst, e.g.
404 in a cron job), it's trivial to write a simple component in
405 Catalyst that slurps in an outside Model:
407 package MyApp::Model::DB;
408 use base qw/Catalyst::Model::DBIC::Schema/;
410 schema_class => 'Some::DBIC::Schema',
411 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
415 and that's it! Now C<Some::DBIC::Schema> is part of your
416 Cat app as C<MyApp::Model::DB>.
418 Within Catalyst, the common approach to writing a model for your
419 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
420 bunch of XMLs, or anything really) with an object that contains
421 configuration data, convenience methods, and so forth. Thus you
422 will in effect have two models - a wrapper model that knows something
423 about Catalyst and your web application, and a generic model that is
424 totally independent of these needs.
426 Technically, within Catalyst a model is a B<component> - an instance of
427 the model's class belonging to the application. It is important to
428 stress that the lifetime of these objects is per application, not per
431 While the model base class (L<Catalyst::Model>) provides things like
432 C<config> to better integrate the model into the application, sometimes
433 this is not enough, and the model requires access to C<$c> itself.
435 Situations where this need might arise include:
441 Interacting with another model
445 Using per-request data to control behavior
449 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
453 From a style perspective it's usually considered bad form to make your
454 model "too smart" about things - it should worry about business logic
455 and leave the integration details to the controllers. If, however, you
456 find that it does not make sense at all to use an auxillary controller
457 around the model, and the model's need to access C<$c> cannot be
458 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
462 Multiple controllers are a good way to separate logical domains of your
465 package MyApp::Controller::Login;
467 use base qw/Catalyst::Controller/;
469 sub login : Path("login") { }
470 sub new_password : Path("new-password") { }
471 sub logout : Path("logout") { }
473 package MyApp::Controller::Catalog;
475 use base qw/Catalyst::Controller/;
480 package MyApp::Controller::Cart;
482 use base qw/Catalyst::Controller/;
485 sub update : Local { }
486 sub order : Local { }
488 Note that you can also supply attributes via the Controller's config so
489 long as you have at least one attribute on a subref to be exported
490 (:Action is commonly used for this) - for example the following is
491 equivalent to the same controller above:
493 package MyApp::Controller::Login;
495 use base qw/Catalyst::Controller/;
499 'sign_in' => { Path => 'sign-in' },
500 'new_password' => { Path => 'new-password' },
501 'sign_out' => { Path => 'sign-out' },
505 sub sign_in : Action { }
506 sub new_password : Action { }
507 sub sign_out : Action { }
509 =head3 ACCEPT_CONTEXT
511 Whenever you call $c->component("Foo") you get back an object - the
512 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
513 method instead of returning the model itself, the return value of C<<
514 $model->ACCEPT_CONTEXT( $c ) >> will be used.
516 This means that whenever your model/view/controller needs to talk to C<$c> it
517 gets a chance to do this when it's needed.
519 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
520 with the context object set, or it will return a thin wrapper that contains
521 C<$c> and delegates to the per-application model object.
523 A typical C<ACCEPT_CONTEXT> method could look like this:
526 my ( $self, $c, @extra_arguments ) = @_;
527 bless { %$self, c => $c }, ref($self);
530 effectively treating $self as a B<prototype object> that gets a new parameter.
531 C<@extra_arguments> comes from any trailing arguments to
532 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) >>,
533 C<< $c->view(...) >> etc).
535 The life time of this value is B<per usage>, and not per request. To make this
536 per request you can use the following technique:
538 Add a field to C<$c>, like C<my_model_instance>. Then write your
539 C<ACCEPT_CONTEXT> method to look like this:
542 my ( $self, $c ) = @_;
544 if ( my $per_request = $c->my_model_instance ) {
547 my $new_instance = bless { %$self, c => $c }, ref($self);
548 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
549 $c->my_model_instance( $new_instance );
550 return $new_instance;
554 =head3 Application Class
556 In addition to the Model, View, and Controller components, there's a
557 single class that represents your application itself. This is where you
558 configure your application, load plugins, and extend Catalyst.
563 use Catalyst qw/-Debug/; # Add other plugins here, e.g.
564 # for session support
567 name => 'My Application',
569 # You can put anything else you want in here:
570 my_configuration_variable => 'something',
574 In older versions of Catalyst, the application class was where you put
575 global actions. However, as of version 5.66, the recommended practice is
576 to place such actions in a special Root controller (see L</Actions>,
577 below), to avoid namespace collisions.
583 The name of your application.
587 Optionally, you can specify a B<root> parameter for templates and static
588 data. If omitted, Catalyst will try to auto-detect the directory's
589 location. You can define as many parameters as you want for plugins or
590 whatever you need. You can access them anywhere in your application via
591 C<$context-E<gt>config-E<gt>{$param_name}>.
595 Catalyst automatically blesses a Context object into your application
596 class and makes it available everywhere in your application. Use the
597 Context to directly interact with Catalyst and glue your L</Components>
598 together. For example, if you need to use the Context from within a
599 Template Toolkit template, it's already there:
601 <h1>Welcome to [% c.config.name %]!</h1>
603 As illustrated in our URL-to-Action dispatching example, the Context is
604 always the second method parameter, behind the Component object
605 reference or class name itself. Previously we called it C<$context> for
606 clarity, but most Catalyst developers just call it C<$c>:
609 my ( $self, $c ) = @_;
610 $c->res->body('Hello World!');
613 The Context contains several important objects:
617 =item * L<Catalyst::Request>
622 The request object contains all kinds of request-specific information, like
623 query parameters, cookies, uploads, headers, and more.
625 $c->req->params->{foo};
626 $c->req->cookies->{sessionid};
627 $c->req->headers->content_type;
629 $c->req->uri_with( { page = $pager->next_page } );
631 =item * L<Catalyst::Response>
636 The response is like the request, but contains just response-specific
639 $c->res->body('Hello World');
640 $c->res->status(404);
641 $c->res->redirect('http://oook.de');
643 =item * L<Catalyst::Config>
649 =item * L<Catalyst::Log>
652 $c->log->debug('Something happened');
653 $c->log->info('Something you should know');
658 $c->stash->{foo} = 'bar';
659 $c->stash->{baz} = {baz => 'qox'};
660 $c->stash->{fred} = [qw/wilma pebbles/];
666 The last of these, the stash, is a universal hash for sharing data among
667 application components. For an example, we return to our 'hello' action:
670 my ( $self, $c ) = @_;
671 $c->stash->{message} = 'Hello World!';
672 $c->forward('show_message');
675 sub show_message : Private {
676 my ( $self, $c ) = @_;
677 $c->res->body( $c->stash->{message} );
680 Note that the stash should be used only for passing data in an
681 individual request cycle; it gets cleared at a new request. If you need
682 to maintain persistent data, use a session. See
683 L<Catalyst::Plugin::Session> for a comprehensive set of
684 Catalyst-friendly session-handling tools.
688 A Catalyst controller is defined by its actions. An action is a
689 subroutine with a special attribute. You've already seen some examples
690 of actions in this document. The URL (for example
691 http://localhost.3000/foo/bar) consists of two parts, the base
692 (http://localhost:3000/ in this example) and the path (foo/bar). Please
693 note that the trailing slash after the hostname[:port] always belongs to
694 base and not to the action.
698 =item * B<Application Wide Actions>
700 Actions which are called at the root level of the application
701 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
704 package MyApp::Controller::Root;
705 use base 'Catalyst::Controller';
706 # Sets the actions in this controller to be registered with no prefix
707 # so they function identically to actions created in MyApp.pm
708 __PACKAGE__->config->{namespace} = '';
710 my ( $self, $context ) = @_;
711 $context->response->status(404);
712 $context->response->body('404 not found');
720 Catalyst supports several types of actions:
724 =item * B<Literal> (B<Path> actions)
726 package MyApp::Controller::My::Controller;
727 sub bar : Path('foo/bar') { }
729 Literal C<Path> actions will act relative to their current
730 namespace. The above example matches only
731 http://localhost:3000/my/controller/foo/bar. If you start your path with
732 a forward slash, it will match from the root. Example:
734 package MyApp::Controller::My::Controller;
735 sub bar : Path('/foo/bar') { }
737 Matches only http://localhost:3000/foo/bar.
739 package MyApp::Controller::My::Controller;
742 By leaving the C<Path> definition empty, it will match on the namespace
743 root. The above code matches http://localhost:3000/my/controller.
747 sub bar : Regex('^item(\d+)/order(\d+)$') { }
749 Matches any URL that matches the pattern in the action key, e.g.
750 http://localhost:3000/item23/order42. The '' around the regexp is
751 optional, but perltidy likes it. :)
753 Regex matches act globally, i.e. without reference to the namespace from
754 which it is called, so that a C<bar> method in the
755 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
756 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
757 explicitly put this in the regex. To achieve the above, you should
758 consider using a C<LocalRegex> action.
760 =item * B<LocalRegex>
762 sub bar : LocalRegex('^widget(\d+)$') { }
764 LocalRegex actions act locally. If you were to use C<bar> in
765 C<MyApp::Controller::Catalog>, the above example would match urls like
766 http://localhost:3000/catalog/widget23.
768 If you omit the "C<^>" from your regex, then it will match any depth
769 from the controller and not immediately off of the controller name. The
770 following example differs from the above code in that it will match
771 http://localhost:3000/catalog/foo/widget23 as well.
773 package MyApp::Controller::Catalog;
774 sub bar : LocalRegex('widget(\d+)$') { }
776 For both LocalRegex and Regex actions, if you use capturing parentheses
777 to extract values within the matching URL, those values are available in
778 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
779 would capture "23" in the above example, and
780 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
781 arguments at the end of your URL, you must use regex action keys. See
782 L</URL Path Handling> below.
784 =item * B<Top-level> (B<Global>)
786 package MyApp::Controller::Foo;
789 Matches http://localhost:3000/foo. The function name is mapped
790 directly to the application base. You can provide an equivalent
791 function in this case by doing the following:
793 package MyApp::Controller::Root
796 =item * B<Namespace-Prefixed> (B<Local>)
798 package MyApp::Controller::My::Controller;
801 Matches http://localhost:3000/my/controller/foo.
803 This action type indicates that the matching URL must be prefixed with a
804 modified form of the component's class (package) name. This modified
805 class name excludes the parts that have a pre-defined meaning in
806 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
807 "/", and converts the name to lower case. See L</Components> for a full
808 explanation of the pre-defined meaning of Catalyst component class
811 Note that actions with the C< :Local > attribute are equivalent to the
812 <:Path('action_name') > so sub foo : Local { } is equivalent to -
814 sub foo : Path('foo') { }
818 Catalyst also provides a method to build and dispatch chains of actions,
821 sub catalog : Chained : CaptureArgs(1) {
822 my ( $self, $c, $arg ) = @_;
826 sub item : Chained('catalog') : Args(1) {
827 my ( $self, $c, $arg ) = @_;
831 to handle a C</catalog/*/item/*> path. For further information about this
832 dispatch type, please see L<Catalyst::DispatchType::Chained>.
836 sub foo : Private { }
838 Matches no URL, and cannot be executed by requesting a URL that
839 corresponds to the action key. Catalyst's :Private attribute is
840 exclusive and doesn't work with other attributes (so will not work
841 combined with Path or Chained attributes). With the exception of the
842 C< index >, C< auto > and C< default > actions, Private actions can
843 only be executed from inside a Catalyst application, by calling the
844 C<forward> or C<detach> methods:
850 See L</Flow Control> for a full explanation of C<forward>. Note that, as
851 discussed there, when forwarding from another component, you must use
852 the absolute path to the method, so that a private C<bar> method in your
853 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
854 from elsewhere, be reached with
855 C<$c-E<gt>forward('/catalog/order/process/bar')>.
859 Args is not an action type per se, but an action modifier - it adds a
860 match restriction to any action it's provided to, requiring only as many
861 path parts as are specified for the action to be valid - for example in
862 MyApp::Controller::Foo,
866 would match any URL starting /foo/bar/. To restrict this you can do
868 sub bar :Local :Args(1)
870 to only match /foo/bar/*/
874 B<Note:> After seeing these examples, you probably wonder what the point
875 is of defining names for regex and path actions. Every public action is
876 also a private one, so you have one unified way of addressing components
879 =head4 Built-in Private Actions
881 In response to specific application states, Catalyst will automatically
882 call these built-in private actions in your application class:
886 =item * B<default : Path>
888 Called when no other action matches. Could be used, for example, for
889 displaying a generic frontpage for the main app, or an error page for
890 individual controllers.
893 =item * B<index : Path : Args (0) >
895 C<index> is much like C<default> except that it takes no arguments and
896 it is weighted slightly higher in the matching process. It is useful
897 as a static entry point to a controller, e.g. to have a static welcome
898 page. Note that it's also weighted higher than Path. Actually the sub
899 name C<index> can be called anything you want. The sub attributes are
900 what determines the behaviour of the action.
902 =item * B<begin : Private>
904 Called at the beginning of a request, before any matching actions are
907 =item * B<end : Private>
909 Called at the end of a request, after all matching actions are called.
913 =head4 Built-in actions in controllers/autochaining
915 Package MyApp::Controller::Foo;
916 sub begin : Private { }
917 sub default : Path { }
918 sub auto : Private { }
920 You can define built-in private actions within your controllers as
921 well. The actions will override the ones in less-specific controllers,
922 or your application class. In other words, for each of the three
923 built-in private actions, only one will be run in any request
924 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
925 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
926 and C<MyApp::Controller::Catalog::Order::begin> would override this in
931 =item * B<auto : Private>
933 In addition to the normal built-in actions, you have a special action
934 for making chains, C<auto>. Such C<auto> actions will be run after any
935 C<begin>, but before your action is processed. Unlike the other
936 built-ins, C<auto> actions I<do not> override each other; they will be
937 called in turn, starting with the application class and going through to
938 the I<most> specific class. I<This is the reverse of the order in which
939 the normal built-ins override each other>.
943 Here are some examples of the order in which the various built-ins
948 =item for a request for C</foo/foo>
952 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
955 =item for a request for C</foo/bar/foo>
957 MyApp::Controller::Foo::Bar::begin
959 MyApp::Controller::Foo::auto
960 MyApp::Controller::Foo::Bar::auto
961 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
962 MyApp::Controller::Foo::Bar::end
966 The C<auto> action is also distinguished by the fact that you can break
967 out of the processing chain by returning 0. If an C<auto> action returns
968 0, any remaining actions will be skipped, except for C<end>. So, for the
969 request above, if the first auto returns false, the chain would look
974 =item for a request for C</foo/bar/foo> where first C<auto> returns
977 MyApp::Controller::Foo::Bar::begin
979 MyApp::Controller::Foo::Bar::end
983 An example of why one might use this is an authentication action: you
984 could set up a C<auto> action to handle authentication in your
985 application class (which will always be called first), and if
986 authentication fails, returning 0 would skip any remaining methods
989 B<Note:> Looking at it another way, C<auto> actions have to return a
990 true value to continue processing! You can also C<die> in the auto
991 action; in that case, the request will go straight to the finalize
992 stage, without processing further actions.
994 =head4 URL Path Handling
996 You can pass variable arguments as part of the URL path, separated with
997 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
998 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
999 where C<$bar> and C<$baz> may vary:
1001 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1003 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1005 sub boo : Path('foo/boo') { .. }
1006 sub hoo : Path('foo/boo/hoo') { .. }
1008 Catalyst matches actions in most specific to least specific order:
1012 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1014 So Catalyst would never mistakenly dispatch the first two URLs to the
1017 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1018 still match a URL containing arguments, however the arguments won't be
1019 available via C<@_>.
1021 =head4 Parameter Processing
1023 Parameters passed in the URL query string are handled with methods in
1024 the L<Catalyst::Request> class. The C<param> method is functionally
1025 equivalent to the C<param> method of C<CGI.pm> and can be used in
1026 modules that require this.
1028 # http://localhost:3000/catalog/view/?category=hardware&page=3
1029 my $category = $c->req->param('category');
1030 my $current_page = $c->req->param('page') || 1;
1032 # multiple values for single parameter name
1033 my @values = $c->req->param('scrolling_list');
1035 # DFV requires a CGI.pm-like input hash
1036 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1040 You control the application flow with the C<forward> method, which
1041 accepts the key of an action to execute. This can be an action in the
1042 same or another Catalyst controller, or a Class name, optionally
1043 followed by a method name. After a C<forward>, the control flow will
1044 return to the method from which the C<forward> was issued.
1046 A C<forward> is similar to a method call. The main differences are that
1047 it wraps the call in an C<eval> to allow exception handling; it
1048 automatically passes along the context object (C<$c> or C<$context>);
1049 and it allows profiling of each call (displayed in the log with
1052 sub hello : Global {
1053 my ( $self, $c ) = @_;
1054 $c->stash->{message} = 'Hello World!';
1055 $c->forward('check_message'); # $c is automatically included
1058 sub check_message : Private {
1059 my ( $self, $c ) = @_;
1060 return unless $c->stash->{message};
1061 $c->forward('show_message');
1064 sub show_message : Private {
1065 my ( $self, $c ) = @_;
1066 $c->res->body( $c->stash->{message} );
1069 A C<forward> does not create a new request, so your request object
1070 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1071 using C<forward> and issuing a redirect.
1073 You can pass new arguments to a C<forward> by adding them
1074 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1075 will be changed for the duration of the C<forward> only; upon
1076 return, the original value of C<$c-E<gt>req-E<gt>args> will
1079 sub hello : Global {
1080 my ( $self, $c ) = @_;
1081 $c->stash->{message} = 'Hello World!';
1082 $c->forward('check_message',[qw/test1/]);
1083 # now $c->req->args is back to what it was before
1086 sub check_message : Private {
1087 my ( $self, $c ) = @_;
1088 my $first_argument = $c->req->args->[0]; # now = 'test1'
1092 As you can see from these examples, you can just use the method name as
1093 long as you are referring to methods in the same controller. If you want
1094 to forward to a method in another controller, or the main application,
1095 you will have to refer to the method by absolute path.
1097 $c->forward('/my/controller/action');
1098 $c->forward('/default'); # calls default in main application
1100 Here are some examples of how to forward to classes and methods.
1102 sub hello : Global {
1103 my ( $self, $c ) = @_;
1104 $c->forward(qw/MyApp::Model::Hello say_hello/);
1108 my ( $self, $c ) = @_;
1109 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1112 package MyApp::Model::Hello;
1115 my ( $self, $c ) = @_;
1116 $c->res->body('Hello World!');
1120 my ( $self, $c ) = @_;
1121 $c->res->body('Goodbye World!');
1124 Note that C<forward> returns to the calling action and continues
1125 processing after the action finishes. If you want all further processing
1126 in the calling action to stop, use C<detach> instead, which will execute
1127 the C<detach>ed action and not return to the calling sub. In both cases,
1128 Catalyst will automatically try to call process() if you omit the
1134 Catalyst has a built-in http server for testing or local
1135 deployment. (Later, you can easily use a more powerful server, for
1136 example Apache/mod_perl or FastCGI, in a production environment.)
1138 Start your application on the command line...
1140 script/myapp_server.pl
1142 ...then visit http://localhost:3000/ in a browser to view the output.
1144 You can also do it all from the command line:
1146 script/myapp_test.pl http://localhost/
1148 Catalyst has a number of tools for actual regression testing of
1149 applications. The helper scripts will automatically generate basic tests
1150 that can be extended as you develop your project. To write your own
1151 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1154 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1162 =item * L<Catalyst::Manual::About>
1164 =item * L<Catalyst::Manual::Tutorial>
1174 Join #catalyst on irc.perl.org.
1175 Join #catalyst-dev on irc.perl.org to help with development.
1179 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1180 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1184 Sebastian Riedel, C<sri@oook.de>
1185 David Naughton, C<naughton@umn.edu>
1186 Marcus Ramberg, C<mramberg@cpan.org>
1187 Jesse Sheidlower, C<jester@panix.com>
1188 Danijel Milicevic, C<me@danijel.de>
1189 Kieren Diment, C<kd@totaldatasolution.com>
1190 Yuval Kogman, C<nothingmuch@woobling.org>
1194 This program is free software. You can redistribute it and/or modify it
1195 under the same terms as Perl itself.