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< :Global > attribute are equivalent to
108 using a C<:Path('action_name') > attribute, so our action could be
111 sub hi : 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 effort, due to its
172 large number of dependencies. Although most of the frustrations
173 associated with this are now ironed out and a simple C<cpan
174 Catalyst::Devel> or C<cpan Catalyst::Runtime> are now usually
175 straightforward, if you still have problems, you can use use Matt
176 Trout's C<cat-install> script, from
177 L<http://www.shadowcatsystems.co.uk/static/cat-install>, and then
178 install L<Catalyst::Devel>.
181 # perl -MCPAN -e 'install Catalyst::Devel'
188 $ script/myapp_create.pl controller Library::Login
190 =head4 Frank Speiser's Amazon EC2 Catalyst SDK
192 There are currently two flavors of publicly available Amazon Machine
193 Images (AMI) that include all the elements you'd need to begin
194 developing in a fully functional Catalyst environment within
196 L<Catalyst::Manual::Installation|Catalyst::Manual::Installation> for
202 $ script/myapp_server.pl
204 Now visit these locations with your favorite browser or user agent to see
207 (NOTE: Although we create a controller here, we don't actually use it.
208 Both of these URLs should take you to the welcome page.)
213 =item http://localhost:3000/
215 =item http://localhost:3000/library/login/
221 Let's see how Catalyst works, by taking a closer look at the components
222 and other parts of a Catalyst application.
226 Catalyst has an uncommonly flexible component system. You can define as
227 many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
228 previously, the general idea is that the View is responsible for the
229 output of data to the user (typically via a web browser, but a View can
230 also generate PDFs or e-mails, for example); the Model is responsible
231 for providing data (typically from a relational database); and the
232 Controller is responsible for interacting with the user and deciding
233 how user input determines what actions the application takes.
235 In the world of MVC, there are frequent discussions and disagreements
236 about the nature of each element - whether certain types of logic
237 belong in the Model or the Controller, etc. Catalyst's flexibility
238 means that this decision is entirely up to you, the programmer;
239 Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
240 a general discussion of these issues.
242 Model, View and Controller components must inherit from L<Catalyst::Model>,
243 L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
244 from L<Catalyst::Component> which provides a simple class structure and some
245 common class methods like C<config> and C<new> (constructor).
247 package MyApp::Controller::Catalog;
250 use base 'Catalyst::Controller';
252 __PACKAGE__->config( foo => 'bar' );
256 You don't have to C<use> or otherwise register Models, Views, and
257 Controllers. Catalyst automatically discovers and instantiates them
258 when you call C<setup> in the main application. All you need to do is
259 put them in directories named for each Component type. You can use a
260 short alias for each one.
264 =item * B<MyApp/Model/>
268 =item * B<MyApp/View/>
272 =item * B<MyApp/Controller/>
278 In older versions of Catalyst, the recommended practice (and the one
279 automatically created by helper scripts) was to name the directories
280 C<M/>, C<V/>, and C<C/>. Though these still work, we now recommend
281 the use of the full names.
285 To show how to define views, we'll use an already-existing base class for the
286 L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
287 inherit from this class:
289 package MyApp::View::TT;
292 use base 'Catalyst::View::TT';
296 (You can also generate this automatically by using the helper script:
298 script/myapp_create.pl view TT TT
300 where the first C<TT> tells the script that the name of the view should
301 be C<TT>, and the second that it should be a Template Toolkit view.)
303 This gives us a process() method and we can now just do
304 $c->forward('MyApp::View::TT') to render our templates. The base class
305 makes process() implicit, so we don't have to say
306 C<$c-E<gt>forward(qw/MyApp::View::TT process/)>.
309 my ( $self, $c ) = @_;
310 $c->stash->{template} = 'hello.tt';
314 my ( $self, $c ) = @_;
315 $c->forward( $c->view('TT') );
318 You normally render templates at the end of a request, so it's a perfect
319 use for the global C<end> action.
321 In practice, however, you would use a default C<end> action as supplied
322 by L<Catalyst::Action::RenderView>.
324 Also, be sure to put the template under the directory specified in
325 C<$c-E<gt>config-E<gt>{root}>, or you'll end up looking at the debug
330 Models are providers of data. This data could come from anywhere - a
331 search engine index, a spreadsheet, the file system - but typically a
332 Model represents a database table. The data source does not
333 intrinsically have much to do with web applications or Catalyst - it
334 could just as easily be used to write an offline report generator or a
337 To show how to define models, again we'll use an already-existing base
338 class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
339 We'll also need L<DBIx::Class::Schema::Loader>.
341 But first, we need a database.
345 id INTEGER PRIMARY KEY,
350 id INTEGER PRIMARY KEY,
351 foo INTEGER REFERENCES foo,
355 INSERT INTO foo (data) VALUES ('TEST!');
357 % sqlite3 /tmp/myapp.db < myapp.sql
359 Now we can create a DBIC::Schema model for this database.
361 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
363 L<DBIx::Class::Schema::Loader> can automaticall load table layouts and
364 relationships, and convert them into a static schema definition
365 C<MySchema>, which you can edit later.
367 Use the stash to pass data to your templates.
369 We add the following to MyApp/Controller/Root.pm
372 my ( $self, $c, $id ) = @_;
374 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
380 my ( $self, $c ) = @_;
382 $c->stash->{template} ||= 'index.tt';
383 $c->forward( $c->view('TT') );
386 We then create a new template file "root/index.tt" containing:
388 The Id's data is [% item.data %]
390 Models do not have to be part of your Catalyst application; you
391 can always call an outside module that serves as your Model:
395 my ( $self, $c ) = @_;
397 $c->stash->{template} = 'list.tt';
399 use Some::Outside::Database::Module;
400 my @records = Some::Outside::Database::Module->search({
401 artist => 'Led Zeppelin',
404 $c->stash->{records} = \@records;
407 But by using a Model that is part of your Catalyst application, you
408 gain several things: you don't have to C<use> each component, Catalyst
409 will find and load it automatically at compile-time; you can
410 C<forward> to the module, which can only be done to Catalyst
411 components. Only Catalyst components can be fetched with
412 C<$c-E<gt>model('SomeModel')>.
414 Happily, since many people have existing Model classes that they
415 would like to use with Catalyst (or, conversely, they want to
416 write Catalyst models that can be used outside of Catalyst, e.g.
417 in a cron job), it's trivial to write a simple component in
418 Catalyst that slurps in an outside Model:
420 package MyApp::Model::DB;
421 use base qw/Catalyst::Model::DBIC::Schema/;
423 schema_class => 'Some::DBIC::Schema',
424 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
428 and that's it! Now C<Some::DBIC::Schema> is part of your
429 Cat app as C<MyApp::Model::DB>.
431 Within Catalyst, the common approach to writing a model for your
432 application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
433 bunch of XMLs, or anything really) with an object that contains
434 configuration data, convenience methods, and so forth. Thus you
435 will in effect have two models - a wrapper model that knows something
436 about Catalyst and your web application, and a generic model that is
437 totally independent of these needs.
439 Technically, within Catalyst a model is a B<component> - an instance of
440 the model's class belonging to the application. It is important to
441 stress that the lifetime of these objects is per application, not per
444 While the model base class (L<Catalyst::Model>) provides things like
445 C<config> to better integrate the model into the application, sometimes
446 this is not enough, and the model requires access to C<$c> itself.
448 Situations where this need might arise include:
454 Interacting with another model
458 Using per-request data to control behavior
462 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
466 From a style perspective it's usually considered bad form to make your
467 model "too smart" about things - it should worry about business logic
468 and leave the integration details to the controllers. If, however, you
469 find that it does not make sense at all to use an auxillary controller
470 around the model, and the model's need to access C<$c> cannot be
471 sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
475 Multiple controllers are a good way to separate logical domains of your
478 package MyApp::Controller::Login;
480 use base qw/Catalyst::Controller/;
482 sub login : Path("login") { }
483 sub new_password : Path("new-password") { }
484 sub logout : Path("logout") { }
486 package MyApp::Controller::Catalog;
488 use base qw/Catalyst::Controller/;
493 package MyApp::Controller::Cart;
495 use base qw/Catalyst::Controller/;
498 sub update : Local { }
499 sub order : Local { }
501 Note that you can also supply attributes via the Controller's config so
502 long as you have at least one attribute on a subref to be exported
503 (:Action is commonly used for this) - for example the following is
504 equivalent to the same controller above:
506 package MyApp::Controller::Login;
508 use base qw/Catalyst::Controller/;
512 'sign_in' => { Path => 'sign-in' },
513 'new_password' => { Path => 'new-password' },
514 'sign_out' => { Path => 'sign-out' },
518 sub sign_in : Action { }
519 sub new_password : Action { }
520 sub sign_out : Action { }
522 =head3 ACCEPT_CONTEXT
524 Whenever you call $c->component("Foo") you get back an object - the
525 instance of the model. If the component supports the C<ACCEPT_CONTEXT>
526 method instead of returning the model itself, the return value of C<<
527 $model->ACCEPT_CONTEXT( $c ) >> will be used.
529 This means that whenever your model/view/controller needs to talk to
530 C<$c> it gets a chance to do this when it's needed.
532 A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
533 with the context object set, or it will return a thin wrapper that contains
534 C<$c> and delegates to the per-application model object.
536 Generally it's a bad idea to expose the context object (C<$c>) in your
537 model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
538 to grab the bits of the context object that you need, and provide
539 accessors to them in the model. This ensures that C<$c> is only in
540 scope where it is neaded which reduces maintenance and debugging
541 headaches. So, if for example you needed two
542 L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
543 code, you might do something like this:
545 __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
547 my ( $self, $c, @extra_arguments ) = @_;
548 $self = bless({ %$self,
549 model1_schema => $c->model('Model1')->schema,
550 model2_schema => $c->model('Model2')->schema
555 This effectively treats $self as a B<prototype object> that gets a new
556 parameter. C<@extra_arguments> comes from any trailing arguments to
557 C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
558 >>, C<< $c->view(...) >> etc).
560 In a subroutine in the model code, we can then do this:
564 my $schema1 = $self->model1_schema;
565 my $schema2 = $self->model2_schema;
569 Note that we still want the Catalyst models to be a thin wrapper
570 around classes that will work independently of the Catalyst
571 application to promote reusability of code. Here we might just want
572 to grab the $c->model('DB')->schema so as to get the connection
573 information from the Catalyst application's configuration for example.
575 The life time of this value is B<per usage>, and not per request. To
576 make this per request you can use the following technique:
578 Add a field to C<$c>, like C<my_model_instance>. Then write your
579 C<ACCEPT_CONTEXT> method to look like this:
582 my ( $self, $c ) = @_;
584 if ( my $per_request = $c->my_model_instance ) {
587 my $new_instance = bless { %$self, c => $c }, ref($self);
588 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
589 $c->my_model_instance( $new_instance );
590 return $new_instance;
594 For a similar technique to grab a new component instance on each
595 request, see L<Catalyst::Component::InstancePerContext>.
597 =head3 Application Class
599 In addition to the Model, View, and Controller components, there's a
600 single class that represents your application itself. This is where you
601 configure your application, load plugins, and extend Catalyst.
606 use parent qw/Catalyst/;
607 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
609 name => 'My Application',
611 # You can put anything else you want in here:
612 my_configuration_variable => 'something',
616 In older versions of Catalyst, the application class was where you put
617 global actions. However, as of version 5.66, the recommended practice is
618 to place such actions in a special Root controller (see L</Actions>,
619 below), to avoid namespace collisions.
625 The name of your application.
629 Optionally, you can specify a B<root> parameter for templates and static
630 data. If omitted, Catalyst will try to auto-detect the directory's
631 location. You can define as many parameters as you want for plugins or
632 whatever you need. You can access them anywhere in your application via
633 C<$context-E<gt>config-E<gt>{$param_name}>.
637 Catalyst automatically blesses a Context object into your application
638 class and makes it available everywhere in your application. Use the
639 Context to directly interact with Catalyst and glue your L</Components>
640 together. For example, if you need to use the Context from within a
641 Template Toolkit template, it's already there:
643 <h1>Welcome to [% c.config.name %]!</h1>
645 As illustrated in our URL-to-Action dispatching example, the Context is
646 always the second method parameter, behind the Component object
647 reference or class name itself. Previously we called it C<$context> for
648 clarity, but most Catalyst developers just call it C<$c>:
651 my ( $self, $c ) = @_;
652 $c->res->body('Hello World!');
655 The Context contains several important objects:
659 =item * L<Catalyst::Request>
664 The request object contains all kinds of request-specific information, like
665 query parameters, cookies, uploads, headers, and more.
667 $c->req->params->{foo};
668 $c->req->cookies->{sessionid};
669 $c->req->headers->content_type;
671 $c->req->uri_with( { page = $pager->next_page } );
673 =item * L<Catalyst::Response>
678 The response is like the request, but contains just response-specific
681 $c->res->body('Hello World');
682 $c->res->status(404);
683 $c->res->redirect('http://oook.de');
685 =item * L<Catalyst::Config>
691 =item * L<Catalyst::Log>
694 $c->log->debug('Something happened');
695 $c->log->info('Something you should know');
700 $c->stash->{foo} = 'bar';
701 $c->stash->{baz} = {baz => 'qox'};
702 $c->stash->{fred} = [qw/wilma pebbles/];
708 The last of these, the stash, is a universal hash for sharing data among
709 application components. For an example, we return to our 'hello' action:
712 my ( $self, $c ) = @_;
713 $c->stash->{message} = 'Hello World!';
714 $c->forward('show_message');
717 sub show_message : Private {
718 my ( $self, $c ) = @_;
719 $c->res->body( $c->stash->{message} );
722 Note that the stash should be used only for passing data in an
723 individual request cycle; it gets cleared at a new request. If you need
724 to maintain persistent data, use a session. See
725 L<Catalyst::Plugin::Session> for a comprehensive set of
726 Catalyst-friendly session-handling tools.
730 A Catalyst controller is defined by its actions. An action is a
731 subroutine with a special attribute. You've already seen some examples
732 of actions in this document. The URL (for example
733 http://localhost.3000/foo/bar) consists of two parts, the base
734 (http://localhost:3000/ in this example) and the path (foo/bar). Please
735 note that the trailing slash after the hostname[:port] always belongs to
736 base and not to the action.
740 =item * B<Application Wide Actions>
742 Actions which are called at the root level of the application
743 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
746 package MyApp::Controller::Root;
747 use base 'Catalyst::Controller';
748 # Sets the actions in this controller to be registered with no prefix
749 # so they function identically to actions created in MyApp.pm
750 __PACKAGE__->config->{namespace} = '';
752 my ( $self, $context ) = @_;
753 $context->response->status(404);
754 $context->response->body('404 not found');
762 Catalyst supports several types of actions:
766 =item * B<Literal> (B<Path> actions)
768 package MyApp::Controller::My::Controller;
769 sub bar : Path('foo/bar') { }
771 Literal C<Path> actions will act relative to their current
772 namespace. The above example matches only
773 http://localhost:3000/my/controller/foo/bar. If you start your path with
774 a forward slash, it will match from the root. Example:
776 package MyApp::Controller::My::Controller;
777 sub bar : Path('/foo/bar') { }
779 Matches only http://localhost:3000/foo/bar.
781 package MyApp::Controller::My::Controller;
784 By leaving the C<Path> definition empty, it will match on the namespace
785 root. The above code matches http://localhost:3000/my/controller.
789 sub bar : Regex('^item(\d+)/order(\d+)$') { }
791 Matches any URL that matches the pattern in the action key, e.g.
792 http://localhost:3000/item23/order42. The '' around the regexp is
793 optional, but perltidy likes it. :)
795 Regex matches act globally, i.e. without reference to the namespace from
796 which it is called, so that a C<bar> method in the
797 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
798 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
799 explicitly put this in the regex. To achieve the above, you should
800 consider using a C<LocalRegex> action.
802 =item * B<LocalRegex>
804 sub bar : LocalRegex('^widget(\d+)$') { }
806 LocalRegex actions act locally. If you were to use C<bar> in
807 C<MyApp::Controller::Catalog>, the above example would match urls like
808 http://localhost:3000/catalog/widget23.
810 If you omit the "C<^>" from your regex, then it will match any depth
811 from the controller and not immediately off of the controller name. The
812 following example differs from the above code in that it will match
813 http://localhost:3000/catalog/foo/widget23 as well.
815 package MyApp::Controller::Catalog;
816 sub bar : LocalRegex('widget(\d+)$') { }
818 For both LocalRegex and Regex actions, if you use capturing parentheses
819 to extract values within the matching URL, those values are available in
820 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
821 would capture "23" in the above example, and
822 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
823 arguments at the end of your URL, you must use regex action keys. See
824 L</URL Path Handling> below.
826 =item * B<Top-level> (B<Global>)
828 package MyApp::Controller::Foo;
831 Matches http://localhost:3000/foo. The function name is mapped
832 directly to the application base. You can provide an equivalent
833 function in this case by doing the following:
835 package MyApp::Controller::Root
838 =item * B<Namespace-Prefixed> (B<Local>)
840 package MyApp::Controller::My::Controller;
843 Matches http://localhost:3000/my/controller/foo.
845 This action type indicates that the matching URL must be prefixed with a
846 modified form of the component's class (package) name. This modified
847 class name excludes the parts that have a pre-defined meaning in
848 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
849 "/", and converts the name to lower case. See L</Components> for a full
850 explanation of the pre-defined meaning of Catalyst component class
853 Note that actions with the C< :Local > attribute are equivalent to the
854 <:Path('action_name') > so sub foo : Local { } is equivalent to -
856 sub foo : Path('foo') { }
860 Catalyst also provides a method to build and dispatch chains of actions,
863 sub catalog : Chained : CaptureArgs(1) {
864 my ( $self, $c, $arg ) = @_;
868 sub item : Chained('catalog') : Args(1) {
869 my ( $self, $c, $arg ) = @_;
873 to handle a C</catalog/*/item/*> path. For further information about this
874 dispatch type, please see L<Catalyst::DispatchType::Chained>.
878 sub foo : Private { }
880 Matches no URL, and cannot be executed by requesting a URL that
881 corresponds to the action key. Catalyst's :Private attribute is
882 exclusive and doesn't work with other attributes (so will not work
883 combined with Path or Chained attributes). With the exception of the
884 C< index >, C< auto > and C< default > actions, Private actions can
885 only be executed from inside a Catalyst application, by calling the
886 C<forward> or C<detach> methods:
892 See L</Flow Control> for a full explanation of C<forward>. Note that, as
893 discussed there, when forwarding from another component, you must use
894 the absolute path to the method, so that a private C<bar> method in your
895 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
896 from elsewhere, be reached with
897 C<$c-E<gt>forward('/catalog/order/process/bar')>.
901 Args is not an action type per se, but an action modifier - it adds a
902 match restriction to any action it's provided to, requiring only as many
903 path parts as are specified for the action to be valid - for example in
904 MyApp::Controller::Foo,
908 would match any URL starting /foo/bar/. To restrict this you can do
910 sub bar :Local :Args(1)
912 to only match /foo/bar/*/
916 B<Note:> After seeing these examples, you probably wonder what the point
917 is of defining names for regex and path actions. Every public action is
918 also a private one, so you have one unified way of addressing components
921 =head4 Built-in Private Actions
923 In response to specific application states, Catalyst will automatically
924 call these built-in private actions in your application class:
928 =item * B<default : Path>
930 Called when no other action matches. Could be used, for example, for
931 displaying a generic frontpage for the main app, or an error page for
932 individual controllers. B<Note>: in older Catalyst applications you
933 will see C<default : Private> which is roughly speaking equivalent.
936 =item * B<index : Path : Args (0) >
938 C<index> is much like C<default> except that it takes no arguments and
939 it is weighted slightly higher in the matching process. It is useful
940 as a static entry point to a controller, e.g. to have a static welcome
941 page. Note that it's also weighted higher than Path. Actually the sub
942 name C<index> can be called anything you want. The sub attributes are
943 what determines the behaviour of the action. B<Note>: in older
944 Catalyst applications, you will see C<index : Private> used, which is
945 roughly speaking equivalent.
947 =item * B<begin : Private>
949 Called at the beginning of a request, before any matching actions are
952 =item * B<end : Private>
954 Called at the end of a request, after all matching actions are called.
958 =head4 Built-in actions in controllers/autochaining
960 package MyApp::Controller::Foo;
961 sub begin : Private { }
962 sub default : Path { }
963 sub auto : Private { }
965 You can define built-in private actions within your controllers as
966 well. The actions will override the ones in less-specific controllers,
967 or your application class. In other words, for each of the three
968 built-in private actions, only one will be run in any request
969 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
970 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
971 and C<MyApp::Controller::Catalog::Order::begin> would override this in
976 =item * B<auto : Private>
978 In addition to the normal built-in actions, you have a special action
979 for making chains, C<auto>. Such C<auto> actions will be run after any
980 C<begin>, but before your action is processed. Unlike the other
981 built-ins, C<auto> actions I<do not> override each other; they will be
982 called in turn, starting with the application class and going through to
983 the I<most> specific class. I<This is the reverse of the order in which
984 the normal built-ins override each other>.
988 Here are some examples of the order in which the various built-ins
993 =item for a request for C</foo/foo>
995 MyApp::Controller::Foo::auto
996 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
997 MyApp::Controller::Foo::end
999 =item for a request for C</foo/bar/foo>
1001 MyApp::Controller::Foo::Bar::begin
1002 MyApp::Controller::Foo::auto
1003 MyApp::Controller::Foo::Bar::auto
1004 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
1005 MyApp::Controller::Foo::Bar::end
1009 The C<auto> action is also distinguished by the fact that you can break
1010 out of the processing chain by returning 0. If an C<auto> action returns
1011 0, any remaining actions will be skipped, except for C<end>. So, for the
1012 request above, if the first auto returns false, the chain would look
1017 =item for a request for C</foo/bar/foo> where first C<auto> returns
1020 MyApp::Controller::Foo::Bar::begin
1021 MyApp::Controller::Foo::Bar::end
1025 An example of why one might use this is an authentication action: you
1026 could set up a C<auto> action to handle authentication in your
1027 application class (which will always be called first), and if
1028 authentication fails, returning 0 would skip any remaining methods
1031 B<Note:> Looking at it another way, C<auto> actions have to return a
1032 true value to continue processing! You can also C<die> in the auto
1033 action; in that case, the request will go straight to the finalize
1034 stage, without processing further actions.
1036 =head4 URL Path Handling
1038 You can pass variable arguments as part of the URL path, separated with
1039 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
1040 must be used. For example, suppose you want to handle C</foo/$bar/$baz>,
1041 where C<$bar> and C<$baz> may vary:
1043 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1045 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1047 sub boo : Path('foo/boo') { .. }
1048 sub hoo : Path('foo/boo/hoo') { .. }
1050 Catalyst matches actions in most specific to least specific order:
1054 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1056 So Catalyst would never mistakenly dispatch the first two URLs to the
1059 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1060 still match a URL containing arguments, however the arguments won't be
1061 available via C<@_>.
1063 =head4 Parameter Processing
1065 Parameters passed in the URL query string are handled with methods in
1066 the L<Catalyst::Request> class. The C<param> method is functionally
1067 equivalent to the C<param> method of C<CGI.pm> and can be used in
1068 modules that require this.
1070 # http://localhost:3000/catalog/view/?category=hardware&page=3
1071 my $category = $c->req->param('category');
1072 my $current_page = $c->req->param('page') || 1;
1074 # multiple values for single parameter name
1075 my @values = $c->req->param('scrolling_list');
1077 # DFV requires a CGI.pm-like input hash
1078 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1082 You control the application flow with the C<forward> method, which
1083 accepts the key of an action to execute. This can be an action in the
1084 same or another Catalyst controller, or a Class name, optionally
1085 followed by a method name. After a C<forward>, the control flow will
1086 return to the method from which the C<forward> was issued.
1088 A C<forward> is similar to a method call. The main differences are that
1089 it wraps the call in an C<eval> to allow exception handling; it
1090 automatically passes along the context object (C<$c> or C<$context>);
1091 and it allows profiling of each call (displayed in the log with
1094 sub hello : Global {
1095 my ( $self, $c ) = @_;
1096 $c->stash->{message} = 'Hello World!';
1097 $c->forward('check_message'); # $c is automatically included
1100 sub check_message : Private {
1101 my ( $self, $c ) = @_;
1102 return unless $c->stash->{message};
1103 $c->forward('show_message');
1106 sub show_message : Private {
1107 my ( $self, $c ) = @_;
1108 $c->res->body( $c->stash->{message} );
1111 A C<forward> does not create a new request, so your request object
1112 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1113 using C<forward> and issuing a redirect.
1115 You can pass new arguments to a C<forward> by adding them
1116 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1117 will be changed for the duration of the C<forward> only; upon
1118 return, the original value of C<$c-E<gt>req-E<gt>args> will
1121 sub hello : Global {
1122 my ( $self, $c ) = @_;
1123 $c->stash->{message} = 'Hello World!';
1124 $c->forward('check_message',[qw/test1/]);
1125 # now $c->req->args is back to what it was before
1128 sub check_message : Private {
1129 my ( $self, $c ) = @_;
1130 my $first_argument = $c->req->args->[0]; # now = 'test1'
1134 As you can see from these examples, you can just use the method name as
1135 long as you are referring to methods in the same controller. If you want
1136 to forward to a method in another controller, or the main application,
1137 you will have to refer to the method by absolute path.
1139 $c->forward('/my/controller/action');
1140 $c->forward('/default'); # calls default in main application
1142 Here are some examples of how to forward to classes and methods.
1144 sub hello : Global {
1145 my ( $self, $c ) = @_;
1146 $c->forward(qw/MyApp::Model::Hello say_hello/);
1150 my ( $self, $c ) = @_;
1151 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1154 package MyApp::Model::Hello;
1157 my ( $self, $c ) = @_;
1158 $c->res->body('Hello World!');
1162 my ( $self, $c ) = @_;
1163 $c->res->body('Goodbye World!');
1166 Note that C<forward> returns to the calling action and continues
1167 processing after the action finishes. If you want all further processing
1168 in the calling action to stop, use C<detach> instead, which will execute
1169 the C<detach>ed action and not return to the calling sub. In both cases,
1170 Catalyst will automatically try to call process() if you omit the
1176 Catalyst has a built-in http server for testing or local
1177 deployment. (Later, you can easily use a more powerful server, for
1178 example Apache/mod_perl or FastCGI, in a production environment.)
1180 Start your application on the command line...
1182 script/myapp_server.pl
1184 ...then visit http://localhost:3000/ in a browser to view the output.
1186 You can also do it all from the command line:
1188 script/myapp_test.pl http://localhost/
1190 Catalyst has a number of tools for actual regression testing of
1191 applications. The helper scripts will automatically generate basic tests
1192 that can be extended as you develop your project. To write your own
1193 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1196 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1204 =item * L<Catalyst::Manual::About>
1206 =item * L<Catalyst::Manual::Tutorial>
1216 Join #catalyst on irc.perl.org.
1217 Join #catalyst-dev on irc.perl.org to help with development.
1221 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1222 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1226 Sebastian Riedel, C<sri@oook.de>
1227 David Naughton, C<naughton@umn.edu>
1228 Marcus Ramberg, C<mramberg@cpan.org>
1229 Jesse Sheidlower, C<jester@panix.com>
1230 Danijel Milicevic, C<me@danijel.de>
1231 Kieren Diment, C<kd@totaldatasolution.com>
1232 Yuval Kogman, C<nothingmuch@woobling.org>
1236 This program is free software. You can redistribute it and/or modify it
1237 under the same terms as Perl itself.