Release commit for 5.9010
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Intro.pod
CommitLineData
11876a3b 1=head1 NAME
cb93c9d7 2
3Catalyst::Manual::Intro - Introduction to Catalyst
4
5=head1 DESCRIPTION
6
7This is a brief introduction to Catalyst. It explains the most important
8features of how Catalyst works and shows how to get a simple application
9up and running quickly. For an introduction (without code) to Catalyst
10itself, and why you should be using it, see L<Catalyst::Manual::About>.
11For a systematic step-by-step introduction to writing an application
12with Catalyst, see L<Catalyst::Manual::Tutorial>.
13
14=head2 What is Catalyst?
15
16Catalyst is an elegant web application framework, extremely flexible
792ad331 17yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and
388f66e0 18L<Maypole>, upon which it was originally based. Its most
5336f546 19important design philosophy is to provide easy access to all the tools
792ad331 20you need to develop web applications, with few restrictions on how you
21need to use these tools. However, this does mean that it is always
22possible to do things in a different way. Other web frameworks are
23I<initially> simpler to use, but achieve this by locking the programmer
24into a single set of tools. Catalyst's emphasis on flexibility means
25that you have to think more to use it. We view this as a feature. For
f577e42d 26example, this leads to Catalyst being better suited to system integration
792ad331 27tasks than other web frameworks.
cb93c9d7 28
29=head3 MVC
30
31Catalyst follows the Model-View-Controller (MVC) design pattern,
32allowing you to easily separate concerns, like content, presentation,
33and flow control, into separate modules. This separation allows you to
34modify code that handles one concern without affecting code that handles
35the others. Catalyst promotes the re-use of existing Perl modules that
36already handle common web application concerns well.
37
38Here's how the Model, View, and Controller map to those concerns, with
39examples of well-known Perl modules you may want to use for each.
40
41=over 4
42
43=item * B<Model>
44
45Access and modify content (data). L<DBIx::Class>, L<Class::DBI>,
46L<Xapian>, L<Net::LDAP>...
47
48=item * B<View>
49
50Present content to the user. L<Template Toolkit|Template>,
51L<Mason|HTML::Mason>, L<HTML::Template>...
52
53=item * B<Controller>
54
55Control the whole request phase, check parameters, dispatch actions, flow
f577e42d 56control. This is the meat of where Catalyst works.
cb93c9d7 57
58=back
59
60If you're unfamiliar with MVC and design patterns, you may want to
61check out the original book on the subject, I<Design Patterns>, by
62Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four
63(GoF). Many, many web application frameworks are based on MVC, which
64is becoming a popular design paradigm for the world wide web.
65
66=head3 Flexibility
67
68Catalyst is much more flexible than many other frameworks. Rest assured
69you can use your favorite Perl modules with Catalyst.
70
71=over 4
72
73=item * B<Multiple Models, Views, and Controllers>
74
75To build a Catalyst application, you handle each type of concern inside
76special modules called L</Components>. Often this code will be very
77simple, just calling out to Perl modules like those listed above under
78L</MVC>. Catalyst handles these components in a very flexible way. Use
79as many Models, Views, and Controllers as you like, using as many
80different Perl modules as you like, all in the same application. Want to
81manipulate multiple databases, and retrieve some data via LDAP? No
82problem. Want to present data from the same Model using L<Template
83Toolkit|Template> and L<PDF::Template>? Easy.
84
85=item * B<Reuseable Components>
86
87Not only does Catalyst promote the re-use of already existing Perl
88modules, it also allows you to re-use your Catalyst components in
89multiple Catalyst applications.
90
91=item * B<Unrestrained URL-to-Action Dispatching>
92
93Catalyst allows you to dispatch any URLs to any application L</Actions>,
94even through regular expressions! Unlike most other frameworks, it
95doesn't require mod_rewrite or class and method names in URLs.
96
97With Catalyst you register your actions and address them directly. For
98example:
99
a8df13c3 100 sub hello : Local {
cb93c9d7 101 my ( $self, $context ) = @_;
102 $context->response->body('Hello World!');
103 }
104
105Now http://localhost:3000/hello prints "Hello World!".
106
1b2f9849 107Note that actions with the C< :Local > attribute are equivalent to
a8df13c3 108using a C<:Path('action_name') > attribute, so our action could be
109equivalently:
4299d9f5 110
a8df13c3 111 sub hi : Path('hello') {
4299d9f5 112 my ( $self, $context ) = @_;
113 $context->response->body('Hello World!');
114 }
115
116
cb93c9d7 117=item * B<Support for CGI, mod_perl, Apache::Request, FastCGI>
118
492f2dd5 119Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Another
120interesting engine is L<Catalyst::Engine::HTTP::Prefork> - available from CPAN
121separately - which will turn the built server into a fully fledged production
122ready server (although you'll probably want to run it behind a front end proxy
123if you end up using it).
cb93c9d7 124
eb09ba22 125=item * PSGI Support
126
127Starting with Catalyst version 5.9 Catalyst ships with L<PSGI> integration
128for even more powerful and flexible testing and deployment options. See
129L<Catalyst::PSGI> for details.
130
8e728a18 131=back
132
cb93c9d7 133=head3 Simplicity
134
135The best part is that Catalyst implements all this flexibility in a very
136simple way.
137
138=over 4
139
140=item * B<Building Block Interface>
141
142Components interoperate very smoothly. For example, Catalyst
143automatically makes a L</Context> object available to every
144component. Via the context, you can access the request object, share
145data between components, and control the flow of your
146application. Building a Catalyst application feels a lot like snapping
147together toy building blocks, and everything just works.
148
149=item * B<Component Auto-Discovery>
150
151No need to C<use> all of your components. Catalyst automatically finds
152and loads them.
153
154=item * B<Pre-Built Components for Popular Modules>
155
156See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or
157L<Catalyst::View::TT> for L<Template Toolkit|Template>.
158
159=item * B<Built-in Test Framework>
160
161Catalyst comes with a built-in, lightweight http server and test
162framework, making it easy to test applications from the web browser,
163and the command line.
164
165=item * B<Helper Scripts>
166
167Catalyst provides helper scripts to quickly generate running starter
168code for components and unit tests. Install L<Catalyst::Devel> and see
169L<Catalyst::Helper>.
170
171=back
172
173=head2 Quickstart
174
175Here's how to install Catalyst and get a simple application up and
176running, using the helper scripts described above.
177
178=head3 Install
179
b1a08fe1 180Installation of Catalyst should be straightforward:
181
182 # perl -MCPAN -e 'install Catalyst::Runtime'
cb93c9d7 183 # perl -MCPAN -e 'install Catalyst::Devel'
d07ce799 184 # perl -MCPAN -e 'install Catalyst::View::TT'
cb93c9d7 185
186=head3 Setup
187
188 $ catalyst.pl MyApp
189 # output omitted
190 $ cd MyApp
191 $ script/myapp_create.pl controller Library::Login
192
0c51850e 193=head4 Frank Speiser's Amazon EC2 Catalyst SDK
194
195There are currently two flavors of publicly available Amazon Machine
196Images (AMI) that include all the elements you'd need to begin
197developing in a fully functional Catalyst environment within
198minutes. See
388f66e0 199L<Catalyst::Manual::Installation> for
0c51850e 200more details.
201
202
cb93c9d7 203=head3 Run
204
205 $ script/myapp_server.pl
206
207Now visit these locations with your favorite browser or user agent to see
208Catalyst in action:
209
210(NOTE: Although we create a controller here, we don't actually use it.
211Both of these URLs should take you to the welcome page.)
212
213
214=over 4
215
216=item http://localhost:3000/
217
218=item http://localhost:3000/library/login/
219
220=back
221
222=head2 How It Works
223
224Let's see how Catalyst works, by taking a closer look at the components
225and other parts of a Catalyst application.
226
227=head3 Components
228
229Catalyst has an uncommonly flexible component system. You can define as
230many L</Models>, L</Views>, and L</Controllers> as you like. As discussed
231previously, the general idea is that the View is responsible for the
232output of data to the user (typically via a web browser, but a View can
b1a08fe1 233also generate PDFs or e-mails, for example); the Model is responsible
cb93c9d7 234for providing data (typically from a relational database); and the
235Controller is responsible for interacting with the user and deciding
236how user input determines what actions the application takes.
237
238In the world of MVC, there are frequent discussions and disagreements
239about the nature of each element - whether certain types of logic
240belong in the Model or the Controller, etc. Catalyst's flexibility
b1a08fe1 241means that this decision is entirely up to you, the programmer;
cb93c9d7 242Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for
243a general discussion of these issues.
244
b2aea8fe 245Model, View and Controller components must inherit from L<Catalyst::Model>,
47a79274 246L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit
b2aea8fe 247from L<Catalyst::Component> which provides a simple class structure and some
248common class methods like C<config> and C<new> (constructor).
cb93c9d7 249
250 package MyApp::Controller::Catalog;
b1a08fe1 251 use Moose;
252 use namespace::autoclean;
cb93c9d7 253
b1a08fe1 254 BEGIN { extends 'Catalyst::Controller' }
cb93c9d7 255
256 __PACKAGE__->config( foo => 'bar' );
257
258 1;
259
260You don't have to C<use> or otherwise register Models, Views, and
261Controllers. Catalyst automatically discovers and instantiates them
262when you call C<setup> in the main application. All you need to do is
263put them in directories named for each Component type. You can use a
264short alias for each one.
265
266=over 4
267
b1a08fe1 268=item * B<MyApp/Model/>
cb93c9d7 269
cb93c9d7 270=item * B<MyApp/View/>
271
cb93c9d7 272=item * B<MyApp/Controller/>
273
cb93c9d7 274=back
275
cb93c9d7 276=head4 Views
277
278To show how to define views, we'll use an already-existing base class for the
279L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is
280inherit from this class:
281
282 package MyApp::View::TT;
283
284 use strict;
285 use base 'Catalyst::View::TT';
286
287 1;
288
289(You can also generate this automatically by using the helper script:
290
291 script/myapp_create.pl view TT TT
292
293where the first C<TT> tells the script that the name of the view should
294be C<TT>, and the second that it should be a Template Toolkit view.)
295
296This gives us a process() method and we can now just do
080bb620 297C<< $c->forward('MyApp::View::TT') >> to render our templates. The base class
cb93c9d7 298makes process() implicit, so we don't have to say
429d1caf 299C<< $c->forward(qw/MyApp::View::TT process/) >>.
cb93c9d7 300
301 sub hello : Global {
302 my ( $self, $c ) = @_;
303 $c->stash->{template} = 'hello.tt';
304 }
305
306 sub end : Private {
307 my ( $self, $c ) = @_;
308 $c->forward( $c->view('TT') );
309 }
310
311You normally render templates at the end of a request, so it's a perfect
312use for the global C<end> action.
313
314In practice, however, you would use a default C<end> action as supplied
315by L<Catalyst::Action::RenderView>.
316
317Also, be sure to put the template under the directory specified in
429d1caf 318C<< $c->config->{root} >>, or you'll end up looking at the debug
cb93c9d7 319screen.
320
321=head4 Models
322
323Models are providers of data. This data could come from anywhere - a
324search engine index, a spreadsheet, the file system - but typically a
325Model represents a database table. The data source does not
326intrinsically have much to do with web applications or Catalyst - it
327could just as easily be used to write an offline report generator or a
328command-line tool.
329
330To show how to define models, again we'll use an already-existing base
331class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>.
332We'll also need L<DBIx::Class::Schema::Loader>.
333
334But first, we need a database.
335
336 -- myapp.sql
337 CREATE TABLE foo (
338 id INTEGER PRIMARY KEY,
339 data TEXT
340 );
341
342 CREATE TABLE bar (
343 id INTEGER PRIMARY KEY,
344 foo INTEGER REFERENCES foo,
345 data TEXT
346 );
347
348 INSERT INTO foo (data) VALUES ('TEST!');
349
9d49ae04 350 % sqlite3 /tmp/myapp.db < myapp.sql
cb93c9d7 351
352Now we can create a DBIC::Schema model for this database.
353
354 script/myapp_create.pl model MyModel DBIC::Schema MySchema create=static 'dbi:SQLite:/tmp/myapp.db'
355
54550e13 356L<DBIx::Class::Schema::Loader> can automatically load table layouts and
4299d9f5 357relationships, and convert them into a static schema definition
358C<MySchema>, which you can edit later.
cb93c9d7 359
360Use the stash to pass data to your templates.
361
362We add the following to MyApp/Controller/Root.pm
363
364 sub view : Global {
365 my ( $self, $c, $id ) = @_;
b1a08fe1 366
cb93c9d7 367 $c->stash->{item} = $c->model('MyModel::Foo')->find($id);
368 }
369
370 1;
b1a08fe1 371
cb93c9d7 372 sub end : Private {
373 my ( $self, $c ) = @_;
b1a08fe1 374
cb93c9d7 375 $c->stash->{template} ||= 'index.tt';
376 $c->forward( $c->view('TT') );
377 }
378
379We then create a new template file "root/index.tt" containing:
380
381 The Id's data is [% item.data %]
382
383Models do not have to be part of your Catalyst application; you
384can always call an outside module that serves as your Model:
385
386 # in a Controller
387 sub list : Local {
388 my ( $self, $c ) = @_;
b1a08fe1 389
cb93c9d7 390 $c->stash->{template} = 'list.tt';
b1a08fe1 391
cb93c9d7 392 use Some::Outside::Database::Module;
393 my @records = Some::Outside::Database::Module->search({
394 artist => 'Led Zeppelin',
395 });
b1a08fe1 396
cb93c9d7 397 $c->stash->{records} = \@records;
398 }
399
400But by using a Model that is part of your Catalyst application, you
401gain several things: you don't have to C<use> each component, Catalyst
402will find and load it automatically at compile-time; you can
403C<forward> to the module, which can only be done to Catalyst
404components. Only Catalyst components can be fetched with
429d1caf 405C<< $c->model('SomeModel') >>.
cb93c9d7 406
407Happily, since many people have existing Model classes that they
408would like to use with Catalyst (or, conversely, they want to
409write Catalyst models that can be used outside of Catalyst, e.g.
410in a cron job), it's trivial to write a simple component in
411Catalyst that slurps in an outside Model:
412
413 package MyApp::Model::DB;
414 use base qw/Catalyst::Model::DBIC::Schema/;
415 __PACKAGE__->config(
416 schema_class => 'Some::DBIC::Schema',
417 connect_info => ['dbi:SQLite:foo.db', '', '', {AutoCommit=>1}]
418 );
419 1;
420
421and that's it! Now C<Some::DBIC::Schema> is part of your
422Cat app as C<MyApp::Model::DB>.
423
424Within Catalyst, the common approach to writing a model for your
425application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a
426bunch of XMLs, or anything really) with an object that contains
427configuration data, convenience methods, and so forth. Thus you
428will in effect have two models - a wrapper model that knows something
429about Catalyst and your web application, and a generic model that is
430totally independent of these needs.
431
432Technically, within Catalyst a model is a B<component> - an instance of
433the model's class belonging to the application. It is important to
434stress that the lifetime of these objects is per application, not per
435request.
436
437While the model base class (L<Catalyst::Model>) provides things like
438C<config> to better integrate the model into the application, sometimes
439this is not enough, and the model requires access to C<$c> itself.
440
441Situations where this need might arise include:
442
443=over 4
444
445=item *
446
447Interacting with another model
448
449=item *
450
451Using per-request data to control behavior
452
453=item *
454
455Using plugins from a Model (for example L<Catalyst::Plugin::Cache>).
456
457=back
458
459From a style perspective it's usually considered bad form to make your
460model "too smart" about things - it should worry about business logic
461and leave the integration details to the controllers. If, however, you
5336f546 462find that it does not make sense at all to use an auxiliary controller
cb93c9d7 463around the model, and the model's need to access C<$c> cannot be
464sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>.
465
466=head4 Controllers
467
468Multiple controllers are a good way to separate logical domains of your
469application.
470
471 package MyApp::Controller::Login;
472
473 use base qw/Catalyst::Controller/;
474
be3349e1 475 sub sign_in : Path("sign-in") { }
cb93c9d7 476 sub new_password : Path("new-password") { }
be3349e1 477 sub sign_out : Path("sign-out") { }
cb93c9d7 478
479 package MyApp::Controller::Catalog;
480
481 use base qw/Catalyst::Controller/;
482
483 sub view : Local { }
484 sub list : Local { }
485
486 package MyApp::Controller::Cart;
487
488 use base qw/Catalyst::Controller/;
489
490 sub add : Local { }
491 sub update : Local { }
492 sub order : Local { }
493
494Note that you can also supply attributes via the Controller's config so
495long as you have at least one attribute on a subref to be exported
496(:Action is commonly used for this) - for example the following is
497equivalent to the same controller above:
498
499 package MyApp::Controller::Login;
500
501 use base qw/Catalyst::Controller/;
502
503 __PACKAGE__->config(
504 actions => {
505 'sign_in' => { Path => 'sign-in' },
506 'new_password' => { Path => 'new-password' },
507 'sign_out' => { Path => 'sign-out' },
508 },
509 );
510
511 sub sign_in : Action { }
512 sub new_password : Action { }
513 sub sign_out : Action { }
514
515=head3 ACCEPT_CONTEXT
516
080bb620 517Whenever you call C<< $c->component("Foo") >> you get back an object - the
cb93c9d7 518instance of the model. If the component supports the C<ACCEPT_CONTEXT>
519method instead of returning the model itself, the return value of C<<
520$model->ACCEPT_CONTEXT( $c ) >> will be used.
521
0cc6ab50 522This means that whenever your model/view/controller needs to talk to
523C<$c> it gets a chance to do this when it's needed.
cb93c9d7 524
525A typical C<ACCEPT_CONTEXT> method will either clone the model and return one
526with the context object set, or it will return a thin wrapper that contains
527C<$c> and delegates to the per-application model object.
528
0cc6ab50 529Generally it's a bad idea to expose the context object (C<$c>) in your
530model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine
531to grab the bits of the context object that you need, and provide
532accessors to them in the model. This ensures that C<$c> is only in
7fcc54f3 533scope where it is needed which reduces maintenance and debugging
0cc6ab50 534headaches. So, if for example you needed two
535L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model
536code, you might do something like this:
537
538 __PACKAGE__->mk_accessors(qw(model1_schema model2_schema));
539 sub ACCEPT_CONTEXT {
540 my ( $self, $c, @extra_arguments ) = @_;
541 $self = bless({ %$self,
542 model1_schema => $c->model('Model1')->schema,
543 model2_schema => $c->model('Model2')->schema
544 }, ref($self));
545 return $self;
546 }
547
548This effectively treats $self as a B<prototype object> that gets a new
549parameter. C<@extra_arguments> comes from any trailing arguments to
550C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...)
551>>, C<< $c->view(...) >> etc).
552
553In a subroutine in the model code, we can then do this:
554
555 sub whatever {
556 my ($self) = @_;
557 my $schema1 = $self->model1_schema;
558 my $schema2 = $self->model2_schema;
559 ...
560 }
561
562Note that we still want the Catalyst models to be a thin wrapper
563around classes that will work independently of the Catalyst
564application to promote reusability of code. Here we might just want
080bb620 565to grab the C<< $c->model('DB')->schema >> so as to get the connection
0cc6ab50 566information from the Catalyst application's configuration for example.
567
568The life time of this value is B<per usage>, and not per request. To
569make this per request you can use the following technique:
cb93c9d7 570
571Add a field to C<$c>, like C<my_model_instance>. Then write your
572C<ACCEPT_CONTEXT> method to look like this:
573
574 sub ACCEPT_CONTEXT {
575 my ( $self, $c ) = @_;
576
577 if ( my $per_request = $c->my_model_instance ) {
578 return $per_request;
579 } else {
580 my $new_instance = bless { %$self, c => $c }, ref($self);
581 Scalar::Util::weaken($new_instance->{c}); # or we have a circular reference
582 $c->my_model_instance( $new_instance );
583 return $new_instance;
584 }
585 }
586
0cc6ab50 587For a similar technique to grab a new component instance on each
588request, see L<Catalyst::Component::InstancePerContext>.
589
cb93c9d7 590=head3 Application Class
591
592In addition to the Model, View, and Controller components, there's a
593single class that represents your application itself. This is where you
594configure your application, load plugins, and extend Catalyst.
595
596 package MyApp;
597
598 use strict;
ca7528df 599 use parent qw/Catalyst/;
b411df01 600 use Catalyst qw/-Debug ConfigLoader Static::Simple/;
cb93c9d7 601 MyApp->config(
602 name => 'My Application',
603
604 # You can put anything else you want in here:
605 my_configuration_variable => 'something',
606 );
607 1;
608
609In older versions of Catalyst, the application class was where you put
610global actions. However, as of version 5.66, the recommended practice is
611to place such actions in a special Root controller (see L</Actions>,
612below), to avoid namespace collisions.
613
614=over 4
615
616=item * B<name>
617
618The name of your application.
619
620=back
621
622Optionally, you can specify a B<root> parameter for templates and static
623data. If omitted, Catalyst will try to auto-detect the directory's
624location. You can define as many parameters as you want for plugins or
625whatever you need. You can access them anywhere in your application via
429d1caf 626C<< $context->config->{$param_name} >>.
cb93c9d7 627
628=head3 Context
629
630Catalyst automatically blesses a Context object into your application
631class and makes it available everywhere in your application. Use the
632Context to directly interact with Catalyst and glue your L</Components>
633together. For example, if you need to use the Context from within a
634Template Toolkit template, it's already there:
635
636 <h1>Welcome to [% c.config.name %]!</h1>
637
638As illustrated in our URL-to-Action dispatching example, the Context is
639always the second method parameter, behind the Component object
640reference or class name itself. Previously we called it C<$context> for
641clarity, but most Catalyst developers just call it C<$c>:
642
643 sub hello : Global {
644 my ( $self, $c ) = @_;
645 $c->res->body('Hello World!');
646 }
647
648The Context contains several important objects:
649
650=over 4
651
652=item * L<Catalyst::Request>
653
654 $c->request
655 $c->req # alias
656
657The request object contains all kinds of request-specific information, like
658query parameters, cookies, uploads, headers, and more.
659
660 $c->req->params->{foo};
661 $c->req->cookies->{sessionid};
662 $c->req->headers->content_type;
663 $c->req->base;
664 $c->req->uri_with( { page = $pager->next_page } );
665
666=item * L<Catalyst::Response>
667
668 $c->response
669 $c->res # alias
670
671The response is like the request, but contains just response-specific
672information.
673
674 $c->res->body('Hello World');
675 $c->res->status(404);
676 $c->res->redirect('http://oook.de');
677
709ea2fc 678=item * config
cb93c9d7 679
680 $c->config
681 $c->config->{root};
682 $c->config->{name};
683
684=item * L<Catalyst::Log>
685
686 $c->log
687 $c->log->debug('Something happened');
688 $c->log->info('Something you should know');
689
690=item * B<Stash>
691
692 $c->stash
693 $c->stash->{foo} = 'bar';
694 $c->stash->{baz} = {baz => 'qox'};
695 $c->stash->{fred} = [qw/wilma pebbles/];
696
697and so on.
698
699=back
700
701The last of these, the stash, is a universal hash for sharing data among
702application components. For an example, we return to our 'hello' action:
703
704 sub hello : Global {
705 my ( $self, $c ) = @_;
706 $c->stash->{message} = 'Hello World!';
707 $c->forward('show_message');
708 }
709
710 sub show_message : Private {
711 my ( $self, $c ) = @_;
712 $c->res->body( $c->stash->{message} );
713 }
714
715Note that the stash should be used only for passing data in an
716individual request cycle; it gets cleared at a new request. If you need
717to maintain persistent data, use a session. See
718L<Catalyst::Plugin::Session> for a comprehensive set of
719Catalyst-friendly session-handling tools.
720
721=head3 Actions
722
d6ea2bcb 723You've already seen some examples of actions in this document:
724subroutines with C<:Path> and C<:Local> attributes attached.
725Here, we explain what actions are and how these attributes affect
726what's happening.
727
728When Catalyst processes a webpage request, it looks for actions to
729take that will deal with the incoming request and produce a response
730such as a webpage. You create these actions for your application by
731writing subroutines within your controller and marking them with
732special attributes. The attributes, the namespace, and the function
733name determine when Catalyst will call the subroutine.
734
735These action subroutines call certain functions to say what response
736the webserver will give to the web request. They can also tell
737Catalyst to run other actions on the request (one example of this is
738called forwarding the request; this is discussed later).
739
740Action subroutines must have a special attribute on to show that they
741are actions - as well as marking when to call them, this shows that
742they take a specific set of arguments and behave in a specific way.
743At startup, Catalyst looks for all the actions in controllers,
744registers them and creates L<Catalyst::Action> objects describing
745them. When requests come in, Catalyst chooses which actions should be
746called to handle the request.
747
748(Occasionally, you might use the action objects directly, but in
749general, when we talk about actions, we're talking about the
750subroutines in your application that do things to process a request.)
751
752You can choose one of several attributes for action subroutines; these
753specify which requests are processed by that subroutine. Catalyst
754will look at the URL it is processing, and the actions that it has
755found, and automatically call the actions it finds that match the
756circumstances of the request.
757
7dae1813 758The URL (for example C<http://localhost:3000/foo/bar>) consists of two
d6ea2bcb 759parts, the base, describing how to connect to the server
7dae1813 760(C<http://localhost:3000/> in this example) and the path, which the
761server uses to decide what to return (C<foo/bar>). Please note that the
d6ea2bcb 762trailing slash after the hostname[:port] always belongs to base and
763not to the path. Catalyst uses only the path part when trying to find
764actions to process.
765
766Depending on the type of action used, the URLs may match a combination
767of the controller namespace, the arguments passed to the action
768attribute, and the name of the subroutine.
cb93c9d7 769
770=over 4
771
d6ea2bcb 772=item * B<Controller namespaces>
773
774The namespace is a modified form of the component's class (package)
775name. This modified class name excludes the parts that have a
776pre-defined meaning in Catalyst ("MyApp::Controller" in the above
777example), replaces "::" with "/", and converts the name to lower case.
778See L</Components> for a full explanation of the pre-defined meaning
779of Catalyst component class names.
780
781=item * B<Overriding the namespace>
782
030e99c1 783Note that C<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the
d6ea2bcb 784current namespace when matching. So:
785
786 package MyApp::Controller::Example;
787
788would normally use 'example' as its namespace for matching, but if
789this is specially overridden with
790
19a5b486 791 __PACKAGE__->config( namespace => 'thing' );
d6ea2bcb 792
793it matches using the namespace 'thing' instead.
794
7dae1813 795=item * B<Application-Wide Actions>
cb93c9d7 796
d6ea2bcb 797MyApp::Controller::Root, as created by the catalyst.pl script, will
798typically contain actions which are called for the top level of the
7dae1813 799application (e.g. C<http://localhost:3000/>):
cb93c9d7 800
801 package MyApp::Controller::Root;
802 use base 'Catalyst::Controller';
f577e42d 803
cb93c9d7 804 # Sets the actions in this controller to be registered with no prefix
805 # so they function identically to actions created in MyApp.pm
f577e42d 806
19a5b486 807 __PACKAGE__->config( namespace => '');
f577e42d 808
4299d9f5 809 sub default : Path {
cb93c9d7 810 my ( $self, $context ) = @_;
4299d9f5 811 $context->response->status(404);
812 $context->response->body('404 not found');
cb93c9d7 813 }
f577e42d 814
cb93c9d7 815 1;
816
d6ea2bcb 817
818The code
819
19a5b486 820 __PACKAGE__->config( namespace => '' );
d6ea2bcb 821
822makes the controller act as if its namespace is empty. As you'll see
f577e42d 823below, an empty namespace makes many of the URL-matching attributes, such
824as :Path and :Local match at the start of the URL path (i.e. the
825application root).
d6ea2bcb 826
cb93c9d7 827=back
828
829=head4 Action types
830
d6ea2bcb 831Catalyst supports several types of actions. These mainly correspond
832to ways of matching a URL to an action subroutine. Internally, these
833matching types are implemented by L<Catalyst::DispatchType>-derived
834classes; the documentation there can be helpful in seeing how they
835work.
836
837They will all attempt to match the start of the path. The remainder
838of the path is passed as arguments.
cb93c9d7 839
840=over 4
841
d6ea2bcb 842=item * Namespace-prefixed (C<:Local>)
843
b1a08fe1 844 package MyApp::Controller::My::Controller;
d6ea2bcb 845 sub foo : Local { }
846
7dae1813 847Matches any URL beginning with> C<http://localhost:3000/my/controller/foo>. The namespace and
d6ea2bcb 848subroutine name together determine the path.
849
0a52c718 850=item * Root-level (C<:Global>)
d6ea2bcb 851
852 package MyApp::Controller::Foo;
d6ea2bcb 853
f577e42d 854 sub bar : Global {
855 my ($self, $c) = @_;
856 $c->res->body(
857 $c->res->body('sub bar in Controller::Foo triggered on a request for '
858 . $c->req->uri));
859 }
d6ea2bcb 860
f577e42d 8611;
d6ea2bcb 862
7dae1813 863Matches C<http://localhost:3000/bar> - that is, the action is mapped
70101578 864directly to the method name, ignoring the controller namespace.
d6ea2bcb 865
f577e42d 866C<:Global> always matches from the application root: it is simply
5336f546 867shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for
f577e42d 868C<:Path('methodname')>, which takes the controller namespace as described
869above.
870
871Usage of the C<Global> handler is rare in all but very old Catalyst
872applications (e.g. before Catalyst 5.7). The use cases where C<Global>
873used to make sense are now largely replaced by the C<Chained> dispatch
874type, or by empty C<Path> declarations on an controller action. C<Global>
875is still included in Catalyst for backwards compatibility, although
7c8f8c03 876legitimate use-cases for it may still exist.
d6ea2bcb 877
845ef405 878=item * Changing handler behaviour: eating arguments (C<:Args>)
d6ea2bcb 879
7dae1813 880C<:Args> is not an action type per se, but an action modifier - it adds a
d6ea2bcb 881match restriction to any action it's provided to, additionally
882requiring as many path parts as are specified for the action to be
883matched. For example, in MyApp::Controller::Foo,
884
885 sub bar :Local
886
887would match any URL starting /foo/bar. To restrict this you can do
888
889 sub bar :Local :Args(1)
890
891to only match URLs starting /foo/bar/* - with one additional path
892element required after 'bar'.
893
7dae1813 894NOTE that adding C<:Args(0)> and omitting C<:Args> are B<not>
845ef405 895the same thing.
896
b1a08fe1 897C<:Args(0)> means that no arguments are taken. Thus, the URL and path must
845ef405 898match precisely.
899
7dae1813 900No C<:Args> at all means that B<any number> of arguments are taken. Thus, any
0a52c718 901URL that B<starts with> the controller's path will match. Obviously, this means
902you cannot chain from an action that does not specify args, as the next action
903in the chain will be swallowed as an arg to the first!
845ef405 904
905
d6ea2bcb 906=item * Literal match (C<:Path>)
907
908C<Path> actions match things starting with a precise specified path,
909and nothing else.
910
911C<Path> actions without a leading forward slash match a specified path
912relative to their current namespace. This example matches URLs
7dae1813 913starting with C<http://localhost:3000/my/controller/foo/bar>:
cb93c9d7 914
915 package MyApp::Controller::My::Controller;
916 sub bar : Path('foo/bar') { }
917
d6ea2bcb 918C<Path> actions B<with> a leading slash ignore their namespace, and
919match from the start of the URL path. Example:
cb93c9d7 920
921 package MyApp::Controller::My::Controller;
922 sub bar : Path('/foo/bar') { }
923
7dae1813 924This matches URLs beginning with C<http://localhost:3000/foo/bar>.
d6ea2bcb 925
926Empty C<Path> definitions match on the namespace only, exactly like
927C<:Global>.
cb93c9d7 928
929 package MyApp::Controller::My::Controller;
930 sub bar : Path { }
931
7dae1813 932The above code matches C<http://localhost:3000/my/controller>.
d6ea2bcb 933
934Actions with the C<:Local> attribute are similarly equivalent to
935C<:Path('action_name')>:
cb93c9d7 936
b1a08fe1 937 sub foo : Local { }
cb93c9d7 938
b1a08fe1 939is equivalent to
d6ea2bcb 940
941 sub foo : Path('foo') { }
942
7dae1813 943=item * Pattern match (C<:Regex> and C<:LocalRegex>)
b1a08fe1 944
3656a65d 945B<Status: deprecated.> Use Chained methods or other techniques.
946If you really depend on this, install the standalone
947L<Catalyst::DispatchType::Regex> distribution.
948
d6ea2bcb 949 package MyApp::Controller::My::Controller;
cb93c9d7 950 sub bar : Regex('^item(\d+)/order(\d+)$') { }
951
d6ea2bcb 952This matches any URL that matches the pattern in the action key, e.g.
7dae1813 953C<http://localhost:3000/item23/order42>. The '' around the regexp is
cb93c9d7 954optional, but perltidy likes it. :)
955
d6ea2bcb 956C<:Regex> matches act globally, i.e. without reference to the namespace
957from which they are called. So the above will B<not> match
7dae1813 958C<http://localhost:3000/my/controller/item23/order42> - use a
d6ea2bcb 959C<:LocalRegex> action instead.
cb93c9d7 960
d6ea2bcb 961 package MyApp::Controller::My::Controller;
cb93c9d7 962 sub bar : LocalRegex('^widget(\d+)$') { }
963
d6ea2bcb 964C<:LocalRegex> actions act locally, i.e. the namespace is matched
965first. The above example would match urls like
7dae1813 966C<http://localhost:3000/my/controller/widget23>.
cb93c9d7 967
d6ea2bcb 968If you omit the "C<^>" from either sort of regex, then it will match any depth
969from the base path:
cb93c9d7 970
971 package MyApp::Controller::Catalog;
972 sub bar : LocalRegex('widget(\d+)$') { }
973
d6ea2bcb 974This differs from the previous example in that it will match
7dae1813 975C<http://localhost:3000/my/controller/foo/widget23> - and a number of
d6ea2bcb 976other paths.
cb93c9d7 977
d6ea2bcb 978For both C<:LocalRegex> and C<:Regex> actions, if you use capturing
979parentheses to extract values within the matching URL, those values
429d1caf 980are available in the C<< $c->req->captures >> array. In the above
d6ea2bcb 981example, "widget23" would capture "23" in the above example, and
429d1caf 982C<< $c->req->captures->[0] >> would be "23". If you want to
d6ea2bcb 983pass arguments at the end of your URL, you must use regex action
984keys. See L</URL Path Handling> below.
cb93c9d7 985
d6ea2bcb 986=item * Chained handlers (C<:Chained>)
cb93c9d7 987
988Catalyst also provides a method to build and dispatch chains of actions,
989like
990
991 sub catalog : Chained : CaptureArgs(1) {
992 my ( $self, $c, $arg ) = @_;
993 ...
994 }
995
996 sub item : Chained('catalog') : Args(1) {
997 my ( $self, $c, $arg ) = @_;
998 ...
999 }
1000
d6ea2bcb 1001to handle a C</catalog/*/item/*> path. Matching actions are called
1002one after another - C<catalog()> gets called and handed one path
1003element, then C<item()> gets called with another one. For further
1004information about this dispatch type, please see
1005L<Catalyst::DispatchType::Chained>.
cb93c9d7 1006
1007=item * B<Private>
1008
1009 sub foo : Private { }
1010
d6ea2bcb 1011This will never match a URL - it provides a private action which can
1012be called programmatically from within Catalyst, but is never called
1013automatically due to the URL being requested.
1014
1015Catalyst's C<:Private> attribute is exclusive and doesn't work with other
1016attributes (so will not work combined with C<:Path> or C<:Chained>
1017attributes, for instance).
1018
1019Private actions can only be executed explicitly from inside a Catalyst
1020application. You might do this in your controllers by calling
1021catalyst methods such as C<forward> or C<detach> to fire them:
cb93c9d7 1022
1023 $c->forward('foo');
09f13e1d 1024 # or
1025 $c->detach('foo');
cb93c9d7 1026
d6ea2bcb 1027See L</Flow Control> for a full explanation of how you can pass
1028requests on to other actions. Note that, as discussed there, when
1029forwarding from another component, you must use the absolute path to
1030the method, so that a private C<bar> method in your
1031C<MyApp::Controller::Catalog::Order::Process> controller must, if
1032called from elsewhere, be reached with
429d1caf 1033C<< $c->forward('/catalog/order/process/bar') >>.
cb93c9d7 1034
cb93c9d7 1035=back
1036
d6ea2bcb 1037B<Note:> After seeing these examples, you probably wonder what the
1038point is of defining subroutine names for regex and path
1039actions. However, every public action is also a private one with a
1040path corresponding to its namespace and subroutine name, so you have
1041one unified way of addressing components in your C<forward>s.
1042
1043=head4 Built-in special actions
cb93c9d7 1044
d6ea2bcb 1045If present, the special actions C< index >, C< auto >, C<begin>,
1046C<end> and C< default > are called at certain points in the request
1047cycle.
cb93c9d7 1048
1049In response to specific application states, Catalyst will automatically
d6ea2bcb 1050call these built-in actions in your application class:
cb93c9d7 1051
1052=over 4
1053
4299d9f5 1054=item * B<default : Path>
cb93c9d7 1055
d6ea2bcb 1056This is called when no other action matches. It could be used, for
1057example, for displaying a generic frontpage for the main app, or an
1058error page for individual controllers. B<Note>: in older Catalyst
1059applications you will see C<default : Private> which is roughly
1060speaking equivalent.
cb93c9d7 1061
cb93c9d7 1062
4299d9f5 1063=item * B<index : Path : Args (0) >
cb93c9d7 1064
4299d9f5 1065C<index> is much like C<default> except that it takes no arguments and
1066it is weighted slightly higher in the matching process. It is useful
1067as a static entry point to a controller, e.g. to have a static welcome
1068page. Note that it's also weighted higher than Path. Actually the sub
1069name C<index> can be called anything you want. The sub attributes are
955bdf3d 1070what determines the behaviour of the action. B<Note>: in older
1071Catalyst applications, you will see C<index : Private> used, which is
1072roughly speaking equivalent.
cb93c9d7 1073
1074=item * B<begin : Private>
1075
d6ea2bcb 1076Called at the beginning of a request, once the controller that will
1077run has been identified, but before any URL-matching actions are
1078called. Catalyst will call the C<begin> function in the controller
1079which contains the action matching the URL.
cb93c9d7 1080
1081=item * B<end : Private>
1082
d6ea2bcb 1083Called at the end of a request, after all URL-matching actions are called.
1084Catalyst will call the C<end> function in the controller
1085which contains the action matching the URL.
1086
1087=item * B<auto : Private>
1088
1089In addition to the normal built-in actions, you have a special action
1090for making chains, C<auto>. C<auto> actions will be run after any
1091C<begin>, but before your URL-matching action is processed. Unlike the other
1092built-ins, multiple C<auto> actions can be called; they will be
1093called in turn, starting with the application class and going through
1094to the most specific class.
cb93c9d7 1095
1096=back
1097
1098=head4 Built-in actions in controllers/autochaining
1099
f76813a2 1100 package MyApp::Controller::Foo;
cb93c9d7 1101 sub begin : Private { }
4299d9f5 1102 sub default : Path { }
d6ea2bcb 1103 sub end : Path { }
1104
1105You can define built-in actions within your controllers as well as on
1106your application class. In other words, for each of the three built-in
1107actions above, only one will be run in any request cycle. Thus, if
1108C<MyApp::Controller::Catalog::begin> exists, it will be run in place
1109of C<MyApp::begin> if you're in the C<catalog> namespace, and
1110C<MyApp::Controller::Catalog::Order::begin> would override this in
cb93c9d7 1111turn.
1112
d6ea2bcb 1113 sub auto : Private { }
cb93c9d7 1114
d6ea2bcb 1115C<auto>, however, doesn't override like this: providing they exist,
a696baf6 1116C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and
d6ea2bcb 1117C<MyApp::Catalog::Order::auto> would be called in turn.
cb93c9d7 1118
1119Here are some examples of the order in which the various built-ins
1120would be called:
1121
1122=over 4
1123
1124=item for a request for C</foo/foo>
1125
f76813a2 1126 MyApp::Controller::Foo::auto
cb93c9d7 1127 MyApp::Controller::Foo::default # in the absence of MyApp::Controller::Foo::Foo
f76813a2 1128 MyApp::Controller::Foo::end
cb93c9d7 1129
1130=item for a request for C</foo/bar/foo>
1131
1132 MyApp::Controller::Foo::Bar::begin
cb93c9d7 1133 MyApp::Controller::Foo::auto
1134 MyApp::Controller::Foo::Bar::auto
1135 MyApp::Controller::Foo::Bar::default # for MyApp::Controller::Foo::Bar::foo
1136 MyApp::Controller::Foo::Bar::end
1137
1138=back
1139
1140The C<auto> action is also distinguished by the fact that you can break
1141out of the processing chain by returning 0. If an C<auto> action returns
11420, any remaining actions will be skipped, except for C<end>. So, for the
1143request above, if the first auto returns false, the chain would look
1144like this:
1145
1146=over 4
1147
1148=item for a request for C</foo/bar/foo> where first C<auto> returns
1149false
1150
1151 MyApp::Controller::Foo::Bar::begin
d6ea2bcb 1152 MyApp::Controller::Foo::auto # returns false, skips some calls:
1153 # MyApp::Controller::Foo::Bar::auto - never called
1154 # MyApp::Controller::Foo::Bar::foo - never called
cb93c9d7 1155 MyApp::Controller::Foo::Bar::end
1156
d6ea2bcb 1157You can also C<die> in the auto action; in that case, the request will
1158go straight to the finalize stage, without processing further
1159actions. So in the above example, C<MyApp::Controller::Foo::Bar::end>
1160is skipped as well.
1161
cb93c9d7 1162=back
1163
d6ea2bcb 1164An example of why one might use C<auto> is an authentication action:
1165you could set up a C<auto> action to handle authentication in your
cb93c9d7 1166application class (which will always be called first), and if
d6ea2bcb 1167authentication fails, returning 0 would skip any remaining methods for
1168that URL.
cb93c9d7 1169
1170B<Note:> Looking at it another way, C<auto> actions have to return a
b1a08fe1 1171true value to continue processing!
cb93c9d7 1172
1173=head4 URL Path Handling
1174
d6ea2bcb 1175You can pass arguments as part of the URL path, separated with forward
1176slashes (/). If the action is a Regex or LocalRegex, the '$' anchor
1177must be used. For example, suppose you want to handle
1178C</foo/$bar/$baz>, where C<$bar> and C<$baz> may vary:
cb93c9d7 1179
1180 sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; }
1181
1182But what if you also defined actions for C</foo/boo> and C</foo/boo/hoo>?
1183
1184 sub boo : Path('foo/boo') { .. }
1185 sub hoo : Path('foo/boo/hoo') { .. }
1186
d6ea2bcb 1187Catalyst matches actions in most specific to least specific order - that is, whatever matches the most pieces of the path wins:
cb93c9d7 1188
1189 /foo/boo/hoo
1190 /foo/boo
1191 /foo # might be /foo/bar/baz but won't be /foo/boo/hoo
1192
1193So Catalyst would never mistakenly dispatch the first two URLs to the
1194'^foo$' action.
1195
b1a08fe1 1196If a Regex or LocalRegex action doesn't use the '$' anchor, the action will
1197still match a URL containing arguments; however the arguments won't be
d6ea2bcb 1198available via C<@_>, because the Regex will 'eat' them.
1199
1200Beware! If you write two matchers, that match the same path, with the
1201same specificity (that is, they match the same quantity of the path),
1202there's no guarantee which will actually get called. Non-regex
1203matchers get tried first, followed by regex ones, but if you have, for
1204instance:
1205
1206 package MyApp::Controller::Root;
1207
1208 sub match1 :Path('/a/b') { }
1209
1210 package MyApp::Controller::A;
1211
1212 sub b :Local { } # Matches /a/b
1213
1214then Catalyst will call the one it finds first. In summary, Don't Do
1215This.
cb93c9d7 1216
d6ea2bcb 1217=head4 Query Parameter Processing
cb93c9d7 1218
1219Parameters passed in the URL query string are handled with methods in
1220the L<Catalyst::Request> class. The C<param> method is functionally
cacb3819 1221equivalent to the C<param> method of L<CGI.pm|CGI> and can be used in
cb93c9d7 1222modules that require this.
1223
1224 # http://localhost:3000/catalog/view/?category=hardware&page=3
1225 my $category = $c->req->param('category');
1226 my $current_page = $c->req->param('page') || 1;
1227
1228 # multiple values for single parameter name
b1a08fe1 1229 my @values = $c->req->param('scrolling_list');
cb93c9d7 1230
1231 # DFV requires a CGI.pm-like input hash
1232 my $results = Data::FormValidator->check($c->req->params, \%dfv_profile);
1233
1234=head3 Flow Control
1235
1236You control the application flow with the C<forward> method, which
1237accepts the key of an action to execute. This can be an action in the
1238same or another Catalyst controller, or a Class name, optionally
1239followed by a method name. After a C<forward>, the control flow will
1240return to the method from which the C<forward> was issued.
1241
1242A C<forward> is similar to a method call. The main differences are that
1243it wraps the call in an C<eval> to allow exception handling; it
1244automatically passes along the context object (C<$c> or C<$context>);
1245and it allows profiling of each call (displayed in the log with
1246debugging enabled).
1247
1248 sub hello : Global {
1249 my ( $self, $c ) = @_;
1250 $c->stash->{message} = 'Hello World!';
1251 $c->forward('check_message'); # $c is automatically included
1252 }
1253
1254 sub check_message : Private {
1255 my ( $self, $c ) = @_;
1256 return unless $c->stash->{message};
1257 $c->forward('show_message');
1258 }
1259
1260 sub show_message : Private {
1261 my ( $self, $c ) = @_;
1262 $c->res->body( $c->stash->{message} );
1263 }
1264
1265A C<forward> does not create a new request, so your request object
429d1caf 1266(C<< $c->req >>) will remain unchanged. This is a key difference between
cb93c9d7 1267using C<forward> and issuing a redirect.
1268
1269You can pass new arguments to a C<forward> by adding them
429d1caf 1270in an anonymous array. In this case C<< $c->req->args >>
cb93c9d7 1271will be changed for the duration of the C<forward> only; upon
429d1caf 1272return, the original value of C<< $c->req->args >> will
cb93c9d7 1273be reset.
1274
1275 sub hello : Global {
1276 my ( $self, $c ) = @_;
1277 $c->stash->{message} = 'Hello World!';
1278 $c->forward('check_message',[qw/test1/]);
1279 # now $c->req->args is back to what it was before
1280 }
1281
eecdf6ee 1282 sub check_message : Action {
1283 my ( $self, $c, $first_argument ) = @_;
1284 my $also_first_argument = $c->req->args->[0]; # now = 'test1'
cb93c9d7 1285 # do something...
1286 }
1287
1288As you can see from these examples, you can just use the method name as
1289long as you are referring to methods in the same controller. If you want
1290to forward to a method in another controller, or the main application,
1291you will have to refer to the method by absolute path.
1292
1293 $c->forward('/my/controller/action');
1294 $c->forward('/default'); # calls default in main application
1295
eecdf6ee 1296You can also forward to classes and methods.
08cb655f 1297
cb93c9d7 1298 sub hello : Global {
1299 my ( $self, $c ) = @_;
eecdf6ee 1300 $c->forward(qw/MyApp::View:Hello say_hello/);
cb93c9d7 1301 }
1302
1303 sub bye : Global {
1304 my ( $self, $c ) = @_;
1305 $c->forward('MyApp::Model::Hello'); # no method: will try 'process'
1306 }
1307
eecdf6ee 1308 package MyApp::View::Hello;
cb93c9d7 1309
1310 sub say_hello {
1311 my ( $self, $c ) = @_;
1312 $c->res->body('Hello World!');
1313 }
1314
1315 sub process {
1316 my ( $self, $c ) = @_;
1317 $c->res->body('Goodbye World!');
1318 }
1319
eecdf6ee 1320This mechanism is used by L<Catalyst::Action::RenderView> to forward
1321to the C<process> method in a view class.
1322
1323It should be noted that whilst forward is useful, it is not the only way
1324of calling other code in Catalyst. Forward just gives you stats in the debug
1325screen, wraps the code you're calling in an exception handler and localises
1326C<< $c->request->args >>.
1327
1328If you don't want or need these features then it's perfectly acceptable
1329(and faster) to do something like this:
1330
e8556dab 1331 sub hello : Global {
1332 my ( $self, $c ) = @_;
1333 $c->stash->{message} = 'Hello World!';
1334 $self->check_message( $c, 'test1' );
1335 }
7ce05098 1336
e8556dab 1337 sub check_message {
1338 my ( $self, $c, $first_argument ) = @_;
1339 # do something...
1340 }
eecdf6ee 1341
cb93c9d7 1342Note that C<forward> returns to the calling action and continues
1343processing after the action finishes. If you want all further processing
1344in the calling action to stop, use C<detach> instead, which will execute
1345the C<detach>ed action and not return to the calling sub. In both cases,
1346Catalyst will automatically try to call process() if you omit the
1347method.
1348
cb93c9d7 1349=head3 Testing
1350
1351Catalyst has a built-in http server for testing or local
1352deployment. (Later, you can easily use a more powerful server, for
1353example Apache/mod_perl or FastCGI, in a production environment.)
1354
1355Start your application on the command line...
1356
1357 script/myapp_server.pl
1358
1359...then visit http://localhost:3000/ in a browser to view the output.
1360
1361You can also do it all from the command line:
1362
1363 script/myapp_test.pl http://localhost/
1364
1365Catalyst has a number of tools for actual regression testing of
1366applications. The helper scripts will automatically generate basic tests
1367that can be extended as you develop your project. To write your own
1368comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an
1369invaluable tool.
1370
b86fa467 1371For more testing ideas, see L<Catalyst::Manual::Tutorial::08_Testing>.
cb93c9d7 1372
1373Have fun!
1374
1375=head1 SEE ALSO
1376
1377=over 4
1378
1379=item * L<Catalyst::Manual::About>
1380
1381=item * L<Catalyst::Manual::Tutorial>
1382
1383=item * L<Catalyst>
1384
1385=back
1386
1387=head1 SUPPORT
1388
1389IRC:
1390
1391 Join #catalyst on irc.perl.org.
1392 Join #catalyst-dev on irc.perl.org to help with development.
1393
1394Mailing lists:
1395
392906f2 1396 http://lists.scsys.co.uk/mailman/listinfo/catalyst
1397 http://lists.scsys.co.uk/mailman/listinfo/catalyst-dev
cb93c9d7 1398
fed95b6c 1399Wiki:
1400
1401 http://dev.catalystframework.org/wiki
1402
1403FAQ:
1404
1405 http://dev.catalystframework.org/wiki/faq
1406
bbddff00 1407=head1 AUTHORS
cb93c9d7 1408
bbddff00 1409Catalyst Contributors, see Catalyst.pm
cb93c9d7 1410
1411=head1 COPYRIGHT
1412
bbddff00 1413This library is free software. You can redistribute it and/or modify it under
1414the same terms as Perl itself.
b1a08fe1 1415
1416=cut