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