moving to use parent stuff for docs
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Intro.pod
1 =head1 NAME
2
3 Catalyst::Manual::Intro - Introduction to Catalyst
4
5 =head1 DESCRIPTION
6
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>.
13
14 =head2 What is Catalyst?
15
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.
28
29 =head3 MVC
30
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.
37
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.
40
41 =over 4
42
43 =item * B<Model>
44
45 Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
46 L<Xapian>, L<Net::LDAP>...
47
48 =item * B<View>
49
50 Present content to the user. L<Template Toolkit|Template>,
51 L<Mason|HTML::Mason>, L<HTML::Template>...
52
53 =item * B<Controller>
54
55 Control the whole request phase, check parameters, dispatch actions, flow
56 control. Catalyst itself!
57
58 =back
59
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.
65
66 =head3 Flexibility
67
68 Catalyst is much more flexible than many other frameworks. Rest assured
69 you can use your favorite Perl modules with Catalyst.
70
71 =over 4
72
73 =item * B<Multiple Models, Views, and Controllers>
74
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.
84
85 =item * B<Reuseable Components>
86
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.
90
91 =item * B<Unrestrained URL-to-Action Dispatching>
92
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.
96
97 With Catalyst you register your actions and address them directly. For
98 example:
99
100     sub hello : Global {
101         my ( $self, $context ) = @_;
102         $context->response->body('Hello World!');
103     }
104
105 Now http://localhost:3000/hello prints "Hello World!".
106
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:
110
111     sub hello : Path('/hello') {
112         my ( $self, $context ) = @_;
113         $context->response->body('Hello World!');
114     }
115
116
117 =item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
118
119 Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Other
120 engines are also available.
121
122 =back
123
124 =head3 Simplicity
125
126 The best part is that Catalyst implements all this flexibility in a very
127 simple way.
128
129 =over 4
130
131 =item * B<Building Block Interface>
132
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.
139
140 =item * B<Component Auto-Discovery>
141
142 No need to C<use> all of your components. Catalyst automatically finds
143 and loads them.
144
145 =item * B<Pre-Built Components for Popular Modules>
146
147 See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
148 L<Catalyst::View::TT> for L<Template Toolkit|Template>.
149
150 =item * B<Built-in Test Framework>
151
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.
155
156 =item * B<Helper Scripts>
157
158 Catalyst provides helper scripts to quickly generate running starter
159 code for components and unit tests. Install L<Catalyst::Devel> and see
160 L<Catalyst::Helper>.
161
162 =back
163
164 =head2 Quickstart
165
166 Here's how to install Catalyst and get a simple application up and
167 running, using the helper scripts described above.
168
169 =head3 Install
170
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>.
176
177     # perl cat-install
178     # perl -MCPAN -e 'install Catalyst::Devel'
179
180 =head3 Setup
181
182     $ catalyst.pl MyApp
183     # output omitted
184     $ cd MyApp
185     $ script/myapp_create.pl controller Library::Login
186
187 =head3 Run
188
189     $ script/myapp_server.pl
190
191 Now visit these locations with your favorite browser or user agent to see
192 Catalyst in action:
193
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.)
196
197
198 =over 4
199
200 =item http://localhost:3000/
201
202 =item http://localhost:3000/library/login/
203
204 =back
205
206 =head2 How It Works
207
208 Let's see how Catalyst works, by taking a closer look at the components
209 and other parts of a Catalyst application.
210
211 =head3 Components
212
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.
221
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.
228
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).
233
234     package MyApp::Controller::Catalog;
235
236     use strict;
237     use base 'Catalyst::Controller';
238
239     __PACKAGE__->config( foo => 'bar' );
240
241     1;
242
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.
248
249 =over 4
250
251 =item * B<MyApp/Model/> 
252
253 =item * B<MyApp/M/>
254
255 =item * B<MyApp/View/>
256
257 =item * B<MyApp/V/>
258
259 =item * B<MyApp/Controller/>
260
261 =item * B<MyApp/C/>
262
263 =back
264
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.
269
270 =head4 Views
271
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:
275
276     package MyApp::View::TT;
277
278     use strict;
279     use base 'Catalyst::View::TT';
280
281     1;
282
283 (You can also generate this automatically by using the helper script:
284
285     script/myapp_create.pl view TT TT
286
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.)
289
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/)>.
294
295     sub hello : Global {
296         my ( $self, $c ) = @_;
297         $c->stash->{template} = 'hello.tt';
298     }
299
300     sub end : Private {
301         my ( $self, $c ) = @_;
302         $c->forward( $c->view('TT') );
303     }
304
305 You normally render templates at the end of a request, so it's a perfect
306 use for the global C<end> action.
307
308 In practice, however, you would use a default C<end> action as supplied
309 by L<Catalyst::Action::RenderView>.
310
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
313 screen.
314
315 =head4 Models
316
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
322 command-line tool.
323
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>.
327
328 But first, we need a database.
329
330     -- myapp.sql
331     CREATE TABLE foo (
332         id INTEGER PRIMARY KEY,
333         data TEXT
334     );
335
336     CREATE TABLE bar (
337         id INTEGER PRIMARY KEY,
338         foo INTEGER REFERENCES foo,
339         data TEXT
340     );
341
342     INSERT INTO foo (data) VALUES ('TEST!');
343
344     % sqlite3 /tmp/myapp.db < myapp.sql
345
346 Now we can create a DBIC::Schema model for this database.
347
348     script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
349
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.
353
354 Use the stash to pass data to your templates.
355
356 We add the following to MyApp/Controller/Root.pm
357
358     sub view : Global {
359         my ( $self, $c, $id ) = @_;
360         
361         $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
362     }
363
364     1;
365     
366     sub end : Private {
367         my ( $self, $c ) = @_;
368         
369         $c->stash->{template} ||= 'index.tt';
370         $c->forward( $c->view('TT') );
371     }
372
373 We then create a new template file "root/index.tt" containing:
374
375     The Id's data is [% item.data %]
376
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:
379
380     # in a Controller
381     sub list : Local {
382       my ( $self, $c ) = @_;
383       
384       $c->stash->{template} = 'list.tt';
385       
386       use Some::Outside::Database::Module;
387       my @records = Some::Outside::Database::Module->search({
388         artist => 'Led Zeppelin',
389         });
390       
391       $c->stash->{records} = \@records;
392     }
393
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')>.
400
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:
406
407     package MyApp::Model::DB;
408     use base qw/Catalyst::Model::DBIC::Schema/;
409     __PACKAGE__->config(
410         schema_class => 'Some::DBIC::Schema',
411         connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
412     );
413     1;
414
415 and that's it! Now C<Some::DBIC::Schema> is part of your
416 Cat app as C<MyApp::Model::DB>.
417
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.
425
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
429 request.
430
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.
434
435 Situations where this need might arise include:
436
437 =over 4
438
439 =item *
440
441 Interacting with another model
442
443 =item *
444
445 Using per-request data to control behavior
446
447 =item *
448
449 Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
450
451 =back
452
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>.
459
460 =head4 Controllers
461
462 Multiple controllers are a good way to separate logical domains of your
463 application.
464
465     package MyApp::Controller::Login;
466
467     use base qw/Catalyst::Controller/;
468
469     sub login : Path("login") { }
470     sub new_password : Path("new-password") { }
471     sub logout : Path("logout") { }
472
473     package MyApp::Controller::Catalog;
474
475     use base qw/Catalyst::Controller/;
476
477     sub view : Local { }
478     sub list : Local { }
479
480     package MyApp::Controller::Cart;
481
482     use base qw/Catalyst::Controller/;
483
484     sub add : Local { }
485     sub update : Local { }
486     sub order : Local { }
487
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:
492
493     package MyApp::Controller::Login;
494
495     use base qw/Catalyst::Controller/;
496
497     __PACKAGE__->config(
498       actions => {
499         'sign_in' => { Path => 'sign-in' },
500         'new_password' => { Path => 'new-password' },
501         'sign_out' => { Path => 'sign-out' },
502       },
503     );
504
505     sub sign_in : Action { }
506     sub new_password : Action { }
507     sub sign_out : Action { }
508
509 =head3 ACCEPT_CONTEXT
510
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.
515
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.
518
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.
522
523 A typical C<ACCEPT_CONTEXT> method could look like this:
524
525     sub ACCEPT_CONTEXT {
526       my ( $self, $c, @extra_arguments ) = @_;
527       bless { %$self, c => $c }, ref($self);
528     }
529
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).
534
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:
537
538 Add a field to C<$c>, like C<my_model_instance>. Then write your
539 C<ACCEPT_CONTEXT> method to look like this:
540
541     sub ACCEPT_CONTEXT {
542       my ( $self, $c ) = @_;
543
544       if ( my $per_request = $c->my_model_instance ) {
545         return $per_request;
546       } else {
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;
551       }
552     }
553
554 =head3 Application Class
555
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.
559
560     package MyApp;
561
562     use strict;
563     use parent qw/Catalyst/;
564     __PACKAGE__->setup(qw/-Debug ConfigLoader Static::Simple/);
565     # note you can still use use Catalyst qw/@plugins/ instead of the
566     # above two lines
567     MyApp->config(
568         name => 'My Application',
569
570         # You can put anything else you want in here:
571         my_configuration_variable => 'something',
572     );
573     1;
574
575 In older versions of Catalyst, the application class was where you put
576 global actions. However, as of version 5.66, the recommended practice is
577 to place such actions in a special Root controller (see L</Actions>,
578 below), to avoid namespace collisions.
579
580 =over 4
581
582 =item * B<name>
583
584 The name of your application.
585
586 =back
587
588 Optionally, you can specify a B<root> parameter for templates and static
589 data.  If omitted, Catalyst will try to auto-detect the directory's
590 location. You can define as many parameters as you want for plugins or
591 whatever you need. You can access them anywhere in your application via
592 C<$context-E<gt>config-E<gt>{$param_name}>.
593
594 =head3 Context
595
596 Catalyst automatically blesses a Context object into your application
597 class and makes it available everywhere in your application. Use the
598 Context to directly interact with Catalyst and glue your L</Components>
599 together. For example, if you need to use the Context from within a
600 Template Toolkit template, it's already there:
601
602     <h1>Welcome to [% c.config.name %]!</h1>
603
604 As illustrated in our URL-to-Action dispatching example, the Context is
605 always the second method parameter, behind the Component object
606 reference or class name itself. Previously we called it C<$context> for
607 clarity, but most Catalyst developers just call it C<$c>:
608
609     sub hello : Global {
610         my ( $self, $c ) = @_;
611         $c->res->body('Hello World!');
612     }
613
614 The Context contains several important objects:
615
616 =over 4
617
618 =item * L<Catalyst::Request>
619
620     $c->request
621     $c->req # alias
622
623 The request object contains all kinds of request-specific information, like
624 query parameters, cookies, uploads, headers, and more.
625
626     $c->req->params->{foo};
627     $c->req->cookies->{sessionid};
628     $c->req->headers->content_type;
629     $c->req->base;
630     $c->req->uri_with( { page = $pager->next_page } );
631
632 =item * L<Catalyst::Response>
633
634     $c->response
635     $c->res # alias
636
637 The response is like the request, but contains just response-specific
638 information.
639
640     $c->res->body('Hello World');
641     $c->res->status(404);
642     $c->res->redirect('http://oook.de');
643
644 =item * L<Catalyst::Config>
645
646     $c->config
647     $c->config->{root};
648     $c->config->{name};
649
650 =item * L<Catalyst::Log>
651
652     $c->log
653     $c->log->debug('Something happened');
654     $c->log->info('Something you should know');
655
656 =item * B<Stash>
657
658     $c->stash
659     $c->stash->{foo} = 'bar';
660     $c->stash->{baz} = {baz => 'qox'};
661     $c->stash->{fred} = [qw/wilma pebbles/];
662
663 and so on.
664
665 =back
666
667 The last of these, the stash, is a universal hash for sharing data among
668 application components. For an example, we return to our 'hello' action:
669
670     sub hello : Global {
671         my ( $self, $c ) = @_;
672         $c->stash->{message} = 'Hello World!';
673         $c->forward('show_message');
674     }
675
676     sub show_message : Private {
677         my ( $self, $c ) = @_;
678         $c->res->body( $c->stash->{message} );
679     }
680
681 Note that the stash should be used only for passing data in an
682 individual request cycle; it gets cleared at a new request. If you need
683 to maintain persistent data, use a session. See
684 L<Catalyst::Plugin::Session> for a comprehensive set of
685 Catalyst-friendly session-handling tools.
686
687 =head3 Actions
688
689 A Catalyst controller is defined by its actions. An action is a
690 subroutine with a special attribute. You've already seen some examples
691 of actions in this document. The URL (for example
692 http://localhost.3000/foo/bar) consists of two parts, the base
693 (http://localhost:3000/ in this example) and the path (foo/bar).  Please
694 note that the trailing slash after the hostname[:port] always belongs to
695 base and not to the action.
696
697 =over 4
698
699 =item * B<Application Wide Actions>
700
701 Actions which are called at the root level of the application
702 (e.g. http://localhost:3000/ ) go in MyApp::Controller::Root, like
703 this:
704
705     package MyApp::Controller::Root;
706     use base 'Catalyst::Controller';
707     # Sets the actions in this controller to be registered with no prefix
708     # so they function identically to actions created in MyApp.pm
709     __PACKAGE__->config->{namespace} = '';
710     sub default : Path  {
711         my ( $self, $context ) = @_;
712         $context->response->status(404);
713         $context->response->body('404 not found');
714     }
715     1;
716
717 =back
718
719 =head4 Action types
720
721 Catalyst supports several types of actions:
722
723 =over 4
724
725 =item * B<Literal> (B<Path> actions)
726
727     package MyApp::Controller::My::Controller;
728     sub bar : Path('foo/bar') { }
729
730 Literal C<Path> actions will act relative to their current
731 namespace. The above example matches only
732 http://localhost:3000/my/controller/foo/bar. If you start your path with
733 a forward slash, it will match from the root. Example:
734
735     package MyApp::Controller::My::Controller;
736     sub bar : Path('/foo/bar') { }
737
738 Matches only http://localhost:3000/foo/bar.
739
740     package MyApp::Controller::My::Controller;
741     sub bar : Path { }
742
743 By leaving the C<Path> definition empty, it will match on the namespace
744 root. The above code matches http://localhost:3000/my/controller.
745
746 =item * B<Regex>
747
748     sub bar : Regex('^item(\d+)/order(\d+)$') { }
749
750 Matches any URL that matches the pattern in the action key, e.g.
751 http://localhost:3000/item23/order42. The '' around the regexp is
752 optional, but perltidy likes it. :)
753
754 Regex matches act globally, i.e. without reference to the namespace from
755 which it is called, so that a C<bar> method in the
756 C<MyApp::Controller::Catalog::Order::Process> namespace won't match any
757 form of C<bar>, C<Catalog>, C<Order>, or C<Process> unless you
758 explicitly put this in the regex. To achieve the above, you should
759 consider using a C<LocalRegex> action.
760
761 =item * B<LocalRegex>
762
763     sub bar : LocalRegex('^widget(\d+)$') { }
764
765 LocalRegex actions act locally. If you were to use C<bar> in
766 C<MyApp::Controller::Catalog>, the above example would match urls like
767 http://localhost:3000/catalog/widget23.
768
769 If you omit the "C<^>" from your regex, then it will match any depth
770 from the controller and not immediately off of the controller name. The
771 following example differs from the above code in that it will match
772 http://localhost:3000/catalog/foo/widget23 as well.
773
774     package MyApp::Controller::Catalog;
775     sub bar : LocalRegex('widget(\d+)$') { }
776
777 For both LocalRegex and Regex actions, if you use capturing parentheses
778 to extract values within the matching URL, those values are available in
779 the C<$c-E<gt>req-E<gt>captures> array. In the above example, "widget23"
780 would capture "23" in the above example, and
781 C<$c-E<gt>req-E<gt>captures-E<gt>[0]> would be "23". If you want to pass
782 arguments at the end of your URL, you must use regex action keys. See
783 L</URL Path Handling> below.
784
785 =item * B<Top-level> (B<Global>)
786
787     package MyApp::Controller::Foo;
788     sub foo : Global { }
789
790 Matches http://localhost:3000/foo. The function name is mapped
791 directly to the application base.  You can provide an equivalent
792 function in this case  by doing the following:
793
794     package MyApp::Controller::Root
795     sub foo : Local { }
796
797 =item * B<Namespace-Prefixed> (B<Local>)
798
799     package MyApp::Controller::My::Controller; 
800     sub foo : Local { }
801
802 Matches http://localhost:3000/my/controller/foo. 
803
804 This action type indicates that the matching URL must be prefixed with a
805 modified form of the component's class (package) name. This modified
806 class name excludes the parts that have a pre-defined meaning in
807 Catalyst ("MyApp::Controller" in the above example), replaces "::" with
808 "/", and converts the name to lower case.  See L</Components> for a full
809 explanation of the pre-defined meaning of Catalyst component class
810 names.
811
812 Note that actions with the C< :Local > attribute are equivalent to the
813 <:Path('action_name') > so sub foo : Local { } is equivalent to -
814
815     sub foo : Path('foo') { }
816
817 =item * B<Chained>
818
819 Catalyst also provides a method to build and dispatch chains of actions,
820 like
821
822     sub catalog : Chained : CaptureArgs(1) {
823         my ( $self, $c, $arg ) = @_;
824         ...
825     }
826
827     sub item : Chained('catalog') : Args(1) {
828         my ( $self, $c, $arg ) = @_;
829         ...
830     }
831
832 to handle a C</catalog/*/item/*> path. For further information about this
833 dispatch type, please see L<Catalyst::DispatchType::Chained>.
834
835 =item * B<Private>
836
837     sub foo : Private { }
838
839 Matches no URL, and cannot be executed by requesting a URL that
840 corresponds to the action key. Catalyst's :Private attribute is
841 exclusive and doesn't work with other attributes (so will not work
842 combined with Path or Chained attributes). With the exception of the
843 C< index >, C< auto > and C< default > actions, Private actions can
844 only be executed from inside a Catalyst application, by calling the
845 C<forward> or C<detach> methods:
846
847     $c->forward('foo');
848     # or
849     $c->detach('foo');
850
851 See L</Flow Control> for a full explanation of C<forward>. Note that, as
852 discussed there, when forwarding from another component, you must use
853 the absolute path to the method, so that a private C<bar> method in your
854 C<MyApp::Controller::Catalog::Order::Process> controller must, if called
855 from elsewhere, be reached with
856 C<$c-E<gt>forward('/catalog/order/process/bar')>.
857
858 =item * B<Args>
859
860 Args is not an action type per se, but an action modifier - it adds a
861 match restriction to any action it's provided to, requiring only as many
862 path parts as are specified for the action to be valid - for example in
863 MyApp::Controller::Foo,
864
865   sub bar :Local
866
867 would match any URL starting /foo/bar/. To restrict this you can do
868
869   sub bar :Local :Args(1)
870
871 to only match /foo/bar/*/
872
873 =back
874
875 B<Note:> After seeing these examples, you probably wonder what the point
876 is of defining names for regex and path actions. Every public action is
877 also a private one, so you have one unified way of addressing components
878 in your C<forward>s.
879
880 =head4 Built-in Private Actions
881
882 In response to specific application states, Catalyst will automatically
883 call these built-in private actions in your application class:
884
885 =over 4
886
887 =item * B<default : Path>
888
889 Called when no other action matches. Could be used, for example, for
890 displaying a generic frontpage for the main app, or an error page for
891 individual controllers. B<Note>: in older Catalyst applications you
892 will see C<default : Private> which is roughly speaking equivalent.
893
894
895 =item * B<index : Path : Args (0) >
896
897 C<index> is much like C<default> except that it takes no arguments and
898 it is weighted slightly higher in the matching process. It is useful
899 as a static entry point to a controller, e.g. to have a static welcome
900 page. Note that it's also weighted higher than Path.  Actually the sub
901 name C<index> can be called anything you want.  The sub attributes are
902 what determines the behaviour of the action.  B<Note>: in older
903 Catalyst applications, you will see C<index : Private> used, which is
904 roughly speaking equivalent.
905
906 =item * B<begin : Private>
907
908 Called at the beginning of a request, before any matching actions are
909 called.
910
911 =item * B<end : Private>
912
913 Called at the end of a request, after all matching actions are called.
914
915 =back
916
917 =head4 Built-in actions in controllers/autochaining
918
919     Package MyApp::Controller::Foo;
920     sub begin : Private { }
921     sub default : Path  { }
922     sub auto : Private { }
923
924 You can define built-in private actions within your controllers as
925 well. The actions will override the ones in less-specific controllers,
926 or your application class. In other words, for each of the three
927 built-in private actions, only one will be run in any request
928 cycle. Thus, if C<MyApp::Controller::Catalog::begin> exists, it will be
929 run in place of C<MyApp::begin> if you're in the C<catalog> namespace,
930 and C<MyApp::Controller::Catalog::Order::begin> would override this in
931 turn.
932
933 =over 4
934
935 =item * B<auto : Private>
936
937 In addition to the normal built-in actions, you have a special action
938 for making chains, C<auto>. Such C<auto> actions will be run after any
939 C<begin>, but before your action is processed. Unlike the other
940 built-ins, C<auto> actions I<do not> override each other; they will be
941 called in turn, starting with the application class and going through to
942 the I<most> specific class. I<This is the reverse of the order in which
943 the normal built-ins override each other>.
944
945 =back
946
947 Here are some examples of the order in which the various built-ins
948 would be called:
949
950 =over 4
951
952 =item for a request for C</foo/foo>
953
954   MyApp::begin
955   MyApp::auto
956   MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
957   MyApp::end
958
959 =item for a request for C</foo/bar/foo>
960
961   MyApp::Controller::Foo::Bar::begin
962   MyApp::auto
963   MyApp::Controller::Foo::auto
964   MyApp::Controller::Foo::Bar::auto
965   MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
966   MyApp::Controller::Foo::Bar::end
967
968 =back
969
970 The C<auto> action is also distinguished by the fact that you can break
971 out of the processing chain by returning 0. If an C<auto> action returns
972 0, any remaining actions will be skipped, except for C<end>. So, for the
973 request above, if the first auto returns false, the chain would look
974 like this:
975
976 =over 4
977
978 =item for a request for C</foo/bar/foo> where first C<auto> returns
979 false
980
981   MyApp::Controller::Foo::Bar::begin
982   MyApp::auto
983   MyApp::Controller::Foo::Bar::end
984
985 =back
986
987 An example of why one might use this is an authentication action: you
988 could set up a C<auto> action to handle authentication in your
989 application class (which will always be called first), and if
990 authentication fails, returning 0 would skip any remaining methods
991 for that URL.
992
993 B<Note:> Looking at it another way, C<auto> actions have to return a
994 true value to continue processing! You can also C<die> in the auto
995 action; in that case, the request will go straight to the finalize
996 stage, without processing further actions.
997
998 =head4 URL Path Handling
999
1000 You can pass variable arguments as part of the URL path, separated with 
1001 forward slashes (/). If the action is a Regex or LocalRegex, the '$' anchor 
1002 must be used. For example, suppose you want to handle C</foo/$bar/$baz>, 
1003 where C<$bar> and C<$baz> may vary:
1004
1005     sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1006
1007 But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1008
1009     sub boo : Path('foo/boo') { .. }
1010     sub hoo : Path('foo/boo/hoo') { .. }
1011
1012 Catalyst matches actions in most specific to least specific order:
1013
1014     /foo/boo/hoo
1015     /foo/boo
1016     /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1017
1018 So Catalyst would never mistakenly dispatch the first two URLs to the
1019 '^foo$' action.
1020
1021 If a Regex or LocalRegex action doesn't use the '$' anchor, the action will 
1022 still match a URL containing arguments, however the arguments won't be 
1023 available via C<@_>.
1024
1025 =head4 Parameter Processing
1026
1027 Parameters passed in the URL query string are handled with methods in
1028 the L<Catalyst::Request> class. The C<param> method is functionally
1029 equivalent to the C<param> method of C<CGI.pm> and can be used in
1030 modules that require this.
1031
1032     # http://localhost:3000/catalog/view/?category=hardware&page=3
1033     my $category = $c->req->param('category');
1034     my $current_page = $c->req->param('page') || 1;
1035
1036     # multiple values for single parameter name
1037     my @values = $c->req->param('scrolling_list');          
1038
1039     # DFV requires a CGI.pm-like input hash
1040     my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1041
1042 =head3 Flow Control
1043
1044 You control the application flow with the C<forward> method, which
1045 accepts the key of an action to execute. This can be an action in the
1046 same or another Catalyst controller, or a Class name, optionally
1047 followed by a method name. After a C<forward>, the control flow will
1048 return to the method from which the C<forward> was issued.
1049
1050 A C<forward> is similar to a method call. The main differences are that
1051 it wraps the call in an C<eval> to allow exception handling; it
1052 automatically passes along the context object (C<$c> or C<$context>);
1053 and it allows profiling of each call (displayed in the log with
1054 debugging enabled).
1055
1056     sub hello : Global {
1057         my ( $self, $c ) = @_;
1058         $c->stash->{message} = 'Hello World!';
1059         $c->forward('check_message'); # $c is automatically included
1060     }
1061
1062     sub check_message : Private {
1063         my ( $self, $c ) = @_;
1064         return unless $c->stash->{message};
1065         $c->forward('show_message');
1066     }
1067
1068     sub show_message : Private {
1069         my ( $self, $c ) = @_;
1070         $c->res->body( $c->stash->{message} );
1071     }
1072
1073 A C<forward> does not create a new request, so your request object
1074 (C<$c-E<gt>req>) will remain unchanged. This is a key difference between
1075 using C<forward> and issuing a redirect.
1076
1077 You can pass new arguments to a C<forward> by adding them
1078 in an anonymous array. In this case C<$c-E<gt>req-E<gt>args>
1079 will be changed for the duration of the C<forward> only; upon
1080 return, the original value of C<$c-E<gt>req-E<gt>args> will
1081 be reset.
1082
1083     sub hello : Global {
1084         my ( $self, $c ) = @_;
1085         $c->stash->{message} = 'Hello World!';
1086         $c->forward('check_message',[qw/test1/]);
1087         # now $c->req->args is back to what it was before
1088     }
1089
1090     sub check_message : Private {
1091         my ( $self, $c ) = @_;
1092         my $first_argument = $c->req->args->[0]; # now = 'test1'
1093         # do something...
1094     }
1095
1096 As you can see from these examples, you can just use the method name as
1097 long as you are referring to methods in the same controller. If you want
1098 to forward to a method in another controller, or the main application,
1099 you will have to refer to the method by absolute path.
1100
1101   $c->forward('/my/controller/action');
1102   $c->forward('/default'); # calls default in main application
1103
1104 Here are some examples of how to forward to classes and methods.
1105
1106     sub hello : Global {
1107         my ( $self, $c ) = @_;
1108         $c->forward(qw/MyApp::Model::Hello say_hello/);
1109     }
1110
1111     sub bye : Global {
1112         my ( $self, $c ) = @_;
1113         $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1114     }
1115
1116     package MyApp::Model::Hello;
1117
1118     sub say_hello {
1119         my ( $self, $c ) = @_;
1120         $c->res->body('Hello World!');
1121     }
1122
1123     sub process {
1124         my ( $self, $c ) = @_;
1125         $c->res->body('Goodbye World!');
1126     }
1127
1128 Note that C<forward> returns to the calling action and continues
1129 processing after the action finishes. If you want all further processing
1130 in the calling action to stop, use C<detach> instead, which will execute
1131 the C<detach>ed action and not return to the calling sub. In both cases,
1132 Catalyst will automatically try to call process() if you omit the
1133 method.
1134
1135
1136 =head3 Testing
1137
1138 Catalyst has a built-in http server for testing or local
1139 deployment. (Later, you can easily use a more powerful server, for
1140 example Apache/mod_perl or FastCGI, in a production environment.)
1141
1142 Start your application on the command line...
1143
1144     script/myapp_server.pl
1145
1146 ...then visit http://localhost:3000/ in a browser to view the output.
1147
1148 You can also do it all from the command line:
1149
1150     script/myapp_test.pl http://localhost/
1151
1152 Catalyst has a number of tools for actual regression testing of
1153 applications. The helper scripts will automatically generate basic tests
1154 that can be extended as you develop your project. To write your own
1155 comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1156 invaluable tool.
1157
1158 For more testing ideas, see L<Catalyst::Manual::Tutorial::Testing>.
1159
1160 Have fun!
1161
1162 =head1 SEE ALSO
1163
1164 =over 4
1165
1166 =item * L<Catalyst::Manual::About>
1167
1168 =item * L<Catalyst::Manual::Tutorial>
1169
1170 =item * L<Catalyst>
1171
1172 =back
1173
1174 =head1 SUPPORT
1175
1176 IRC:
1177
1178     Join #catalyst on irc.perl.org.
1179     Join #catalyst-dev on irc.perl.org to help with development.
1180
1181 Mailing lists:
1182
1183     http://lists.scsys.co.uk/mailman/listinfo/catalyst
1184     http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
1185
1186 =head1 AUTHOR
1187
1188 Sebastian Riedel, C<sri@oook.de> 
1189 David Naughton, C<naughton@umn.edu>
1190 Marcus Ramberg, C<mramberg@cpan.org>
1191 Jesse Sheidlower, C<jester@panix.com>
1192 Danijel Milicevic, C<me@danijel.de>
1193 Kieren Diment, C<kd@totaldatasolution.com>
1194 Yuval Kogman, C<nothingmuch@woobling.org>
1195
1196 =head1 COPYRIGHT
1197
1198 This program is free software. You can redistribute it and/or modify it
1199 under the same terms as Perl itself.