Commit | Line | Data |
11876a3b |
1 | =head1 NAME |
cb93c9d7 |
2 | |
3 | Catalyst::Manual::Intro - Introduction to Catalyst |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | This is a brief introduction to Catalyst. It explains the most important |
8 | features of how Catalyst works and shows how to get a simple application |
9 | up and running quickly. For an introduction (without code) to Catalyst |
10 | itself, and why you should be using it, see L<Catalyst::Manual::About>. |
11 | For a systematic step-by-step introduction to writing an application |
12 | with Catalyst, see L<Catalyst::Manual::Tutorial>. |
13 | |
14 | =head2 What is Catalyst? |
15 | |
16 | Catalyst is an elegant web application framework, extremely flexible |
792ad331 |
17 | yet extremely simple. It's similar to Ruby on Rails, Spring (Java), and |
388f66e0 |
18 | L<Maypole>, upon which it was originally based. Its most |
5336f546 |
19 | important design philosophy is to provide easy access to all the tools |
792ad331 |
20 | you need to develop web applications, with few restrictions on how you |
21 | need to use these tools. However, this does mean that it is always |
22 | possible to do things in a different way. Other web frameworks are |
23 | I<initially> simpler to use, but achieve this by locking the programmer |
24 | into a single set of tools. Catalyst's emphasis on flexibility means |
25 | that you have to think more to use it. We view this as a feature. For |
f577e42d |
26 | example, this leads to Catalyst being better suited to system integration |
792ad331 |
27 | tasks than other web frameworks. |
cb93c9d7 |
28 | |
29 | =head3 MVC |
30 | |
31 | Catalyst follows the Model-View-Controller (MVC) design pattern, |
32 | allowing you to easily separate concerns, like content, presentation, |
33 | and flow control, into separate modules. This separation allows you to |
34 | modify code that handles one concern without affecting code that handles |
35 | the others. Catalyst promotes the re-use of existing Perl modules that |
36 | already handle common web application concerns well. |
37 | |
38 | Here's how the Model, View, and Controller map to those concerns, with |
39 | examples of well-known Perl modules you may want to use for each. |
40 | |
41 | =over 4 |
42 | |
43 | =item * B<Model> |
44 | |
45 | Access and modify content (data). L<DBIx::Class>, L<Class::DBI>, |
46 | L<Xapian>, L<Net::LDAP>... |
47 | |
48 | =item * B<View> |
49 | |
50 | Present content to the user. L<Template Toolkit|Template>, |
51 | L<Mason|HTML::Mason>, L<HTML::Template>... |
52 | |
53 | =item * B<Controller> |
54 | |
55 | Control the whole request phase, check parameters, dispatch actions, flow |
f577e42d |
56 | control. This is the meat of where Catalyst works. |
cb93c9d7 |
57 | |
58 | =back |
59 | |
60 | If you're unfamiliar with MVC and design patterns, you may want to |
61 | check out the original book on the subject, I<Design Patterns>, by |
62 | Gamma, Helm, Johnson, and Vlissides, also known as the Gang of Four |
63 | (GoF). Many, many web application frameworks are based on MVC, which |
64 | is becoming a popular design paradigm for the world wide web. |
65 | |
66 | =head3 Flexibility |
67 | |
68 | Catalyst is much more flexible than many other frameworks. Rest assured |
69 | you can use your favorite Perl modules with Catalyst. |
70 | |
71 | =over 4 |
72 | |
73 | =item * B<Multiple Models, Views, and Controllers> |
74 | |
75 | To build a Catalyst application, you handle each type of concern inside |
76 | special modules called L</Components>. Often this code will be very |
77 | simple, just calling out to Perl modules like those listed above under |
78 | L</MVC>. Catalyst handles these components in a very flexible way. Use |
79 | as many Models, Views, and Controllers as you like, using as many |
80 | different Perl modules as you like, all in the same application. Want to |
81 | manipulate multiple databases, and retrieve some data via LDAP? No |
82 | problem. Want to present data from the same Model using L<Template |
83 | Toolkit|Template> and L<PDF::Template>? Easy. |
84 | |
85 | =item * B<Reuseable Components> |
86 | |
87 | Not only does Catalyst promote the re-use of already existing Perl |
88 | modules, it also allows you to re-use your Catalyst components in |
89 | multiple Catalyst applications. |
90 | |
91 | =item * B<Unrestrained URL-to-Action Dispatching> |
92 | |
93 | Catalyst allows you to dispatch any URLs to any application L</Actions>, |
94 | even through regular expressions! Unlike most other frameworks, it |
95 | doesn't require mod_rewrite or class and method names in URLs. |
96 | |
97 | With Catalyst you register your actions and address them directly. For |
98 | example: |
99 | |
a8df13c3 |
100 | sub hello : Local { |
cb93c9d7 |
101 | my ( $self, $context ) = @_; |
102 | $context->response->body('Hello World!'); |
103 | } |
104 | |
105 | Now http://localhost:3000/hello prints "Hello World!". |
106 | |
1b2f9849 |
107 | Note that actions with the C< :Local > attribute are equivalent to |
a8df13c3 |
108 | using a C<:Path('action_name') > attribute, so our action could be |
109 | equivalently: |
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 |
119 | Use L<Catalyst::Engine::Apache> or L<Catalyst::Engine::CGI>. Another |
120 | interesting engine is L<Catalyst::Engine::HTTP::Prefork> - available from CPAN |
121 | separately - which will turn the built server into a fully fledged production |
122 | ready server (although you'll probably want to run it behind a front end proxy |
123 | if you end up using it). |
cb93c9d7 |
124 | |
eb09ba22 |
125 | =item * PSGI Support |
126 | |
127 | Starting with Catalyst version 5.9 Catalyst ships with L<PSGI> integration |
128 | for even more powerful and flexible testing and deployment options. See |
129 | L<Catalyst::PSGI> for details. |
130 | |
8e728a18 |
131 | =back |
132 | |
cb93c9d7 |
133 | =head3 Simplicity |
134 | |
135 | The best part is that Catalyst implements all this flexibility in a very |
136 | simple way. |
137 | |
138 | =over 4 |
139 | |
140 | =item * B<Building Block Interface> |
141 | |
142 | Components interoperate very smoothly. For example, Catalyst |
143 | automatically makes a L</Context> object available to every |
144 | component. Via the context, you can access the request object, share |
145 | data between components, and control the flow of your |
146 | application. Building a Catalyst application feels a lot like snapping |
147 | together toy building blocks, and everything just works. |
148 | |
149 | =item * B<Component Auto-Discovery> |
150 | |
151 | No need to C<use> all of your components. Catalyst automatically finds |
152 | and loads them. |
153 | |
154 | =item * B<Pre-Built Components for Popular Modules> |
155 | |
156 | See L<Catalyst::Model::DBIC::Schema> for L<DBIx::Class>, or |
157 | L<Catalyst::View::TT> for L<Template Toolkit|Template>. |
158 | |
159 | =item * B<Built-in Test Framework> |
160 | |
161 | Catalyst comes with a built-in, lightweight http server and test |
162 | framework, making it easy to test applications from the web browser, |
163 | and the command line. |
164 | |
165 | =item * B<Helper Scripts> |
166 | |
167 | Catalyst provides helper scripts to quickly generate running starter |
168 | code for components and unit tests. Install L<Catalyst::Devel> and see |
169 | L<Catalyst::Helper>. |
170 | |
171 | =back |
172 | |
173 | =head2 Quickstart |
174 | |
175 | Here's how to install Catalyst and get a simple application up and |
176 | running, using the helper scripts described above. |
177 | |
178 | =head3 Install |
179 | |
b1a08fe1 |
180 | Installation 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 | |
195 | There are currently two flavors of publicly available Amazon Machine |
196 | Images (AMI) that include all the elements you'd need to begin |
197 | developing in a fully functional Catalyst environment within |
198 | minutes. See |
388f66e0 |
199 | L<Catalyst::Manual::Installation> for |
0c51850e |
200 | more details. |
201 | |
202 | |
cb93c9d7 |
203 | =head3 Run |
204 | |
205 | $ script/myapp_server.pl |
206 | |
207 | Now visit these locations with your favorite browser or user agent to see |
208 | Catalyst in action: |
209 | |
210 | (NOTE: Although we create a controller here, we don't actually use it. |
211 | Both 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 | |
224 | Let's see how Catalyst works, by taking a closer look at the components |
225 | and other parts of a Catalyst application. |
226 | |
227 | =head3 Components |
228 | |
229 | Catalyst has an uncommonly flexible component system. You can define as |
230 | many L</Models>, L</Views>, and L</Controllers> as you like. As discussed |
231 | previously, the general idea is that the View is responsible for the |
232 | output of data to the user (typically via a web browser, but a View can |
b1a08fe1 |
233 | also generate PDFs or e-mails, for example); the Model is responsible |
cb93c9d7 |
234 | for providing data (typically from a relational database); and the |
235 | Controller is responsible for interacting with the user and deciding |
236 | how user input determines what actions the application takes. |
237 | |
238 | In the world of MVC, there are frequent discussions and disagreements |
239 | about the nature of each element - whether certain types of logic |
240 | belong in the Model or the Controller, etc. Catalyst's flexibility |
b1a08fe1 |
241 | means that this decision is entirely up to you, the programmer; |
cb93c9d7 |
242 | Catalyst doesn't enforce anything. See L<Catalyst::Manual::About> for |
243 | a general discussion of these issues. |
244 | |
b2aea8fe |
245 | Model, View and Controller components must inherit from L<Catalyst::Model>, |
47a79274 |
246 | L<Catalyst::View> and L<Catalyst::Controller>, respectively. These, in turn, inherit |
b2aea8fe |
247 | from L<Catalyst::Component> which provides a simple class structure and some |
248 | common 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 | |
260 | You don't have to C<use> or otherwise register Models, Views, and |
261 | Controllers. Catalyst automatically discovers and instantiates them |
262 | when you call C<setup> in the main application. All you need to do is |
263 | put them in directories named for each Component type. You can use a |
264 | short 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 | |
278 | To show how to define views, we'll use an already-existing base class for the |
279 | L<Template Toolkit|Template>, L<Catalyst::View::TT>. All we need to do is |
280 | inherit 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 | |
293 | where the first C<TT> tells the script that the name of the view should |
294 | be C<TT>, and the second that it should be a Template Toolkit view.) |
295 | |
296 | This gives us a process() method and we can now just do |
080bb620 |
297 | C<< $c->forward('MyApp::View::TT') >> to render our templates. The base class |
cb93c9d7 |
298 | makes process() implicit, so we don't have to say |
429d1caf |
299 | C<< $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 | |
311 | You normally render templates at the end of a request, so it's a perfect |
312 | use for the global C<end> action. |
313 | |
314 | In practice, however, you would use a default C<end> action as supplied |
315 | by L<Catalyst::Action::RenderView>. |
316 | |
317 | Also, be sure to put the template under the directory specified in |
429d1caf |
318 | C<< $c->config->{root} >>, or you'll end up looking at the debug |
cb93c9d7 |
319 | screen. |
320 | |
321 | =head4 Models |
322 | |
323 | Models are providers of data. This data could come from anywhere - a |
324 | search engine index, a spreadsheet, the file system - but typically a |
325 | Model represents a database table. The data source does not |
326 | intrinsically have much to do with web applications or Catalyst - it |
327 | could just as easily be used to write an offline report generator or a |
328 | command-line tool. |
329 | |
330 | To show how to define models, again we'll use an already-existing base |
331 | class, this time for L<DBIx::Class>: L<Catalyst::Model::DBIC::Schema>. |
332 | We'll also need L<DBIx::Class::Schema::Loader>. |
333 | |
334 | But 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 | |
352 | Now 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 |
356 | L<DBIx::Class::Schema::Loader> can automatically load table layouts and |
4299d9f5 |
357 | relationships, and convert them into a static schema definition |
358 | C<MySchema>, which you can edit later. |
cb93c9d7 |
359 | |
360 | Use the stash to pass data to your templates. |
361 | |
362 | We 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 | |
379 | We then create a new template file "root/index.tt" containing: |
380 | |
381 | The Id's data is [% item.data %] |
382 | |
383 | Models do not have to be part of your Catalyst application; you |
384 | can 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 | |
400 | But by using a Model that is part of your Catalyst application, you |
401 | gain several things: you don't have to C<use> each component, Catalyst |
402 | will find and load it automatically at compile-time; you can |
403 | C<forward> to the module, which can only be done to Catalyst |
404 | components. Only Catalyst components can be fetched with |
429d1caf |
405 | C<< $c->model('SomeModel') >>. |
cb93c9d7 |
406 | |
407 | Happily, since many people have existing Model classes that they |
408 | would like to use with Catalyst (or, conversely, they want to |
409 | write Catalyst models that can be used outside of Catalyst, e.g. |
410 | in a cron job), it's trivial to write a simple component in |
411 | Catalyst 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 | |
421 | and that's it! Now C<Some::DBIC::Schema> is part of your |
422 | Cat app as C<MyApp::Model::DB>. |
423 | |
424 | Within Catalyst, the common approach to writing a model for your |
425 | application is wrapping a generic model (e.g. L<DBIx::Class::Schema>, a |
426 | bunch of XMLs, or anything really) with an object that contains |
427 | configuration data, convenience methods, and so forth. Thus you |
428 | will in effect have two models - a wrapper model that knows something |
429 | about Catalyst and your web application, and a generic model that is |
430 | totally independent of these needs. |
431 | |
432 | Technically, within Catalyst a model is a B<component> - an instance of |
433 | the model's class belonging to the application. It is important to |
434 | stress that the lifetime of these objects is per application, not per |
435 | request. |
436 | |
437 | While the model base class (L<Catalyst::Model>) provides things like |
438 | C<config> to better integrate the model into the application, sometimes |
439 | this is not enough, and the model requires access to C<$c> itself. |
440 | |
441 | Situations where this need might arise include: |
442 | |
443 | =over 4 |
444 | |
445 | =item * |
446 | |
447 | Interacting with another model |
448 | |
449 | =item * |
450 | |
451 | Using per-request data to control behavior |
452 | |
453 | =item * |
454 | |
455 | Using plugins from a Model (for example L<Catalyst::Plugin::Cache>). |
456 | |
457 | =back |
458 | |
459 | From a style perspective it's usually considered bad form to make your |
460 | model "too smart" about things - it should worry about business logic |
461 | and leave the integration details to the controllers. If, however, you |
5336f546 |
462 | find that it does not make sense at all to use an auxiliary controller |
cb93c9d7 |
463 | around the model, and the model's need to access C<$c> cannot be |
464 | sidestepped, there exists a power tool called L</ACCEPT_CONTEXT>. |
465 | |
466 | =head4 Controllers |
467 | |
468 | Multiple controllers are a good way to separate logical domains of your |
469 | application. |
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 | |
494 | Note that you can also supply attributes via the Controller's config so |
495 | long 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 |
497 | equivalent 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 |
517 | Whenever you call C<< $c->component("Foo") >> you get back an object - the |
cb93c9d7 |
518 | instance of the model. If the component supports the C<ACCEPT_CONTEXT> |
519 | method instead of returning the model itself, the return value of C<< |
520 | $model->ACCEPT_CONTEXT( $c ) >> will be used. |
521 | |
0cc6ab50 |
522 | This means that whenever your model/view/controller needs to talk to |
523 | C<$c> it gets a chance to do this when it's needed. |
cb93c9d7 |
524 | |
525 | A typical C<ACCEPT_CONTEXT> method will either clone the model and return one |
526 | with the context object set, or it will return a thin wrapper that contains |
527 | C<$c> and delegates to the per-application model object. |
528 | |
0cc6ab50 |
529 | Generally it's a bad idea to expose the context object (C<$c>) in your |
530 | model or view code. Instead you use the C<ACCEPT_CONTEXT> subroutine |
531 | to grab the bits of the context object that you need, and provide |
532 | accessors to them in the model. This ensures that C<$c> is only in |
7fcc54f3 |
533 | scope where it is needed which reduces maintenance and debugging |
0cc6ab50 |
534 | headaches. So, if for example you needed two |
535 | L<Catalyst::Model::DBIC::Schema> models in the same Catalyst model |
536 | code, 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 | |
548 | This effectively treats $self as a B<prototype object> that gets a new |
549 | parameter. C<@extra_arguments> comes from any trailing arguments to |
550 | C<< $c->component( $bah, @extra_arguments ) >> (or C<< $c->model(...) |
551 | >>, C<< $c->view(...) >> etc). |
552 | |
553 | In 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 | |
562 | Note that we still want the Catalyst models to be a thin wrapper |
563 | around classes that will work independently of the Catalyst |
564 | application to promote reusability of code. Here we might just want |
080bb620 |
565 | to grab the C<< $c->model('DB')->schema >> so as to get the connection |
0cc6ab50 |
566 | information from the Catalyst application's configuration for example. |
567 | |
568 | The life time of this value is B<per usage>, and not per request. To |
569 | make this per request you can use the following technique: |
cb93c9d7 |
570 | |
571 | Add a field to C<$c>, like C<my_model_instance>. Then write your |
572 | C<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 |
587 | For a similar technique to grab a new component instance on each |
588 | request, see L<Catalyst::Component::InstancePerContext>. |
589 | |
cb93c9d7 |
590 | =head3 Application Class |
591 | |
592 | In addition to the Model, View, and Controller components, there's a |
593 | single class that represents your application itself. This is where you |
594 | configure 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 | |
609 | In older versions of Catalyst, the application class was where you put |
610 | global actions. However, as of version 5.66, the recommended practice is |
611 | to place such actions in a special Root controller (see L</Actions>, |
612 | below), to avoid namespace collisions. |
613 | |
614 | =over 4 |
615 | |
616 | =item * B<name> |
617 | |
618 | The name of your application. |
619 | |
620 | =back |
621 | |
622 | Optionally, you can specify a B<root> parameter for templates and static |
623 | data. If omitted, Catalyst will try to auto-detect the directory's |
624 | location. You can define as many parameters as you want for plugins or |
625 | whatever you need. You can access them anywhere in your application via |
429d1caf |
626 | C<< $context->config->{$param_name} >>. |
cb93c9d7 |
627 | |
628 | =head3 Context |
629 | |
630 | Catalyst automatically blesses a Context object into your application |
631 | class and makes it available everywhere in your application. Use the |
632 | Context to directly interact with Catalyst and glue your L</Components> |
633 | together. For example, if you need to use the Context from within a |
634 | Template Toolkit template, it's already there: |
635 | |
636 | <h1>Welcome to [% c.config.name %]!</h1> |
637 | |
638 | As illustrated in our URL-to-Action dispatching example, the Context is |
639 | always the second method parameter, behind the Component object |
640 | reference or class name itself. Previously we called it C<$context> for |
641 | clarity, 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 | |
648 | The Context contains several important objects: |
649 | |
650 | =over 4 |
651 | |
652 | =item * L<Catalyst::Request> |
653 | |
654 | $c->request |
655 | $c->req # alias |
656 | |
657 | The request object contains all kinds of request-specific information, like |
658 | query 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 | |
671 | The response is like the request, but contains just response-specific |
672 | information. |
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 | |
697 | and so on. |
698 | |
699 | =back |
700 | |
701 | The last of these, the stash, is a universal hash for sharing data among |
702 | application 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 | |
715 | Note that the stash should be used only for passing data in an |
716 | individual request cycle; it gets cleared at a new request. If you need |
717 | to maintain persistent data, use a session. See |
718 | L<Catalyst::Plugin::Session> for a comprehensive set of |
719 | Catalyst-friendly session-handling tools. |
720 | |
721 | =head3 Actions |
722 | |
d6ea2bcb |
723 | You've already seen some examples of actions in this document: |
724 | subroutines with C<:Path> and C<:Local> attributes attached. |
725 | Here, we explain what actions are and how these attributes affect |
726 | what's happening. |
727 | |
728 | When Catalyst processes a webpage request, it looks for actions to |
729 | take that will deal with the incoming request and produce a response |
730 | such as a webpage. You create these actions for your application by |
731 | writing subroutines within your controller and marking them with |
732 | special attributes. The attributes, the namespace, and the function |
733 | name determine when Catalyst will call the subroutine. |
734 | |
735 | These action subroutines call certain functions to say what response |
736 | the webserver will give to the web request. They can also tell |
737 | Catalyst to run other actions on the request (one example of this is |
738 | called forwarding the request; this is discussed later). |
739 | |
740 | Action subroutines must have a special attribute on to show that they |
741 | are actions - as well as marking when to call them, this shows that |
742 | they take a specific set of arguments and behave in a specific way. |
743 | At startup, Catalyst looks for all the actions in controllers, |
744 | registers them and creates L<Catalyst::Action> objects describing |
745 | them. When requests come in, Catalyst chooses which actions should be |
746 | called to handle the request. |
747 | |
748 | (Occasionally, you might use the action objects directly, but in |
749 | general, when we talk about actions, we're talking about the |
750 | subroutines in your application that do things to process a request.) |
751 | |
752 | You can choose one of several attributes for action subroutines; these |
753 | specify which requests are processed by that subroutine. Catalyst |
754 | will look at the URL it is processing, and the actions that it has |
755 | found, and automatically call the actions it finds that match the |
756 | circumstances of the request. |
757 | |
7dae1813 |
758 | The URL (for example C<http://localhost:3000/foo/bar>) consists of two |
d6ea2bcb |
759 | parts, the base, describing how to connect to the server |
7dae1813 |
760 | (C<http://localhost:3000/> in this example) and the path, which the |
761 | server uses to decide what to return (C<foo/bar>). Please note that the |
d6ea2bcb |
762 | trailing slash after the hostname[:port] always belongs to base and |
763 | not to the path. Catalyst uses only the path part when trying to find |
764 | actions to process. |
765 | |
766 | Depending on the type of action used, the URLs may match a combination |
767 | of the controller namespace, the arguments passed to the action |
768 | attribute, and the name of the subroutine. |
cb93c9d7 |
769 | |
770 | =over 4 |
771 | |
d6ea2bcb |
772 | =item * B<Controller namespaces> |
773 | |
774 | The namespace is a modified form of the component's class (package) |
775 | name. This modified class name excludes the parts that have a |
776 | pre-defined meaning in Catalyst ("MyApp::Controller" in the above |
777 | example), replaces "::" with "/", and converts the name to lower case. |
778 | See L</Components> for a full explanation of the pre-defined meaning |
779 | of Catalyst component class names. |
780 | |
781 | =item * B<Overriding the namespace> |
782 | |
030e99c1 |
783 | Note that C<< __PACKAGE__->config->(namespace => ... ) >> can be used to override the |
d6ea2bcb |
784 | current namespace when matching. So: |
785 | |
786 | package MyApp::Controller::Example; |
787 | |
788 | would normally use 'example' as its namespace for matching, but if |
789 | this is specially overridden with |
790 | |
19a5b486 |
791 | __PACKAGE__->config( namespace => 'thing' ); |
d6ea2bcb |
792 | |
793 | it matches using the namespace 'thing' instead. |
794 | |
7dae1813 |
795 | =item * B<Application-Wide Actions> |
cb93c9d7 |
796 | |
d6ea2bcb |
797 | MyApp::Controller::Root, as created by the catalyst.pl script, will |
798 | typically contain actions which are called for the top level of the |
7dae1813 |
799 | application (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 | |
818 | The code |
819 | |
19a5b486 |
820 | __PACKAGE__->config( namespace => '' ); |
d6ea2bcb |
821 | |
822 | makes the controller act as if its namespace is empty. As you'll see |
f577e42d |
823 | below, an empty namespace makes many of the URL-matching attributes, such |
824 | as :Path and :Local match at the start of the URL path (i.e. the |
825 | application root). |
d6ea2bcb |
826 | |
cb93c9d7 |
827 | =back |
828 | |
829 | =head4 Action types |
830 | |
d6ea2bcb |
831 | Catalyst supports several types of actions. These mainly correspond |
832 | to ways of matching a URL to an action subroutine. Internally, these |
833 | matching types are implemented by L<Catalyst::DispatchType>-derived |
834 | classes; the documentation there can be helpful in seeing how they |
835 | work. |
836 | |
837 | They will all attempt to match the start of the path. The remainder |
838 | of 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 |
847 | Matches any URL beginning with> C<http://localhost:3000/my/controller/foo>. The namespace and |
d6ea2bcb |
848 | subroutine 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 |
861 | 1; |
d6ea2bcb |
862 | |
7dae1813 |
863 | Matches C<http://localhost:3000/bar> - that is, the action is mapped |
70101578 |
864 | directly to the method name, ignoring the controller namespace. |
d6ea2bcb |
865 | |
f577e42d |
866 | C<:Global> always matches from the application root: it is simply |
5336f546 |
867 | shorthand for C<:Path('/methodname')>. C<:Local> is shorthand for |
f577e42d |
868 | C<:Path('methodname')>, which takes the controller namespace as described |
869 | above. |
870 | |
871 | Usage of the C<Global> handler is rare in all but very old Catalyst |
872 | applications (e.g. before Catalyst 5.7). The use cases where C<Global> |
873 | used to make sense are now largely replaced by the C<Chained> dispatch |
874 | type, or by empty C<Path> declarations on an controller action. C<Global> |
875 | is still included in Catalyst for backwards compatibility, although |
7c8f8c03 |
876 | legitimate use-cases for it may still exist. |
d6ea2bcb |
877 | |
845ef405 |
878 | =item * Changing handler behaviour: eating arguments (C<:Args>) |
d6ea2bcb |
879 | |
7dae1813 |
880 | C<:Args> is not an action type per se, but an action modifier - it adds a |
d6ea2bcb |
881 | match restriction to any action it's provided to, additionally |
882 | requiring as many path parts as are specified for the action to be |
883 | matched. For example, in MyApp::Controller::Foo, |
884 | |
885 | sub bar :Local |
886 | |
887 | would match any URL starting /foo/bar. To restrict this you can do |
888 | |
889 | sub bar :Local :Args(1) |
890 | |
891 | to only match URLs starting /foo/bar/* - with one additional path |
892 | element required after 'bar'. |
893 | |
7dae1813 |
894 | NOTE that adding C<:Args(0)> and omitting C<:Args> are B<not> |
845ef405 |
895 | the same thing. |
896 | |
b1a08fe1 |
897 | C<:Args(0)> means that no arguments are taken. Thus, the URL and path must |
845ef405 |
898 | match precisely. |
899 | |
7dae1813 |
900 | No C<:Args> at all means that B<any number> of arguments are taken. Thus, any |
0a52c718 |
901 | URL that B<starts with> the controller's path will match. Obviously, this means |
902 | you cannot chain from an action that does not specify args, as the next action |
903 | in the chain will be swallowed as an arg to the first! |
845ef405 |
904 | |
905 | |
d6ea2bcb |
906 | =item * Literal match (C<:Path>) |
907 | |
908 | C<Path> actions match things starting with a precise specified path, |
909 | and nothing else. |
910 | |
911 | C<Path> actions without a leading forward slash match a specified path |
912 | relative to their current namespace. This example matches URLs |
7dae1813 |
913 | starting 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 |
918 | C<Path> actions B<with> a leading slash ignore their namespace, and |
919 | match from the start of the URL path. Example: |
cb93c9d7 |
920 | |
921 | package MyApp::Controller::My::Controller; |
922 | sub bar : Path('/foo/bar') { } |
923 | |
7dae1813 |
924 | This matches URLs beginning with C<http://localhost:3000/foo/bar>. |
d6ea2bcb |
925 | |
926 | Empty C<Path> definitions match on the namespace only, exactly like |
927 | C<:Global>. |
cb93c9d7 |
928 | |
929 | package MyApp::Controller::My::Controller; |
930 | sub bar : Path { } |
931 | |
7dae1813 |
932 | The above code matches C<http://localhost:3000/my/controller>. |
d6ea2bcb |
933 | |
934 | Actions with the C<:Local> attribute are similarly equivalent to |
935 | C<:Path('action_name')>: |
cb93c9d7 |
936 | |
b1a08fe1 |
937 | sub foo : Local { } |
cb93c9d7 |
938 | |
b1a08fe1 |
939 | is equivalent to |
d6ea2bcb |
940 | |
941 | sub foo : Path('foo') { } |
942 | |
7dae1813 |
943 | =item * Pattern match (C<:Regex> and C<:LocalRegex>) |
b1a08fe1 |
944 | |
3656a65d |
945 | B<Status: deprecated.> Use Chained methods or other techniques. |
946 | If you really depend on this, install the standalone |
947 | L<Catalyst::DispatchType::Regex> distribution. |
948 | |
d6ea2bcb |
949 | package MyApp::Controller::My::Controller; |
cb93c9d7 |
950 | sub bar : Regex('^item(\d+)/order(\d+)$') { } |
951 | |
d6ea2bcb |
952 | This matches any URL that matches the pattern in the action key, e.g. |
7dae1813 |
953 | C<http://localhost:3000/item23/order42>. The '' around the regexp is |
cb93c9d7 |
954 | optional, but perltidy likes it. :) |
955 | |
d6ea2bcb |
956 | C<:Regex> matches act globally, i.e. without reference to the namespace |
957 | from which they are called. So the above will B<not> match |
7dae1813 |
958 | C<http://localhost:3000/my/controller/item23/order42> - use a |
d6ea2bcb |
959 | C<:LocalRegex> action instead. |
cb93c9d7 |
960 | |
d6ea2bcb |
961 | package MyApp::Controller::My::Controller; |
cb93c9d7 |
962 | sub bar : LocalRegex('^widget(\d+)$') { } |
963 | |
d6ea2bcb |
964 | C<:LocalRegex> actions act locally, i.e. the namespace is matched |
965 | first. The above example would match urls like |
7dae1813 |
966 | C<http://localhost:3000/my/controller/widget23>. |
cb93c9d7 |
967 | |
d6ea2bcb |
968 | If you omit the "C<^>" from either sort of regex, then it will match any depth |
969 | from the base path: |
cb93c9d7 |
970 | |
971 | package MyApp::Controller::Catalog; |
972 | sub bar : LocalRegex('widget(\d+)$') { } |
973 | |
d6ea2bcb |
974 | This differs from the previous example in that it will match |
7dae1813 |
975 | C<http://localhost:3000/my/controller/foo/widget23> - and a number of |
d6ea2bcb |
976 | other paths. |
cb93c9d7 |
977 | |
d6ea2bcb |
978 | For both C<:LocalRegex> and C<:Regex> actions, if you use capturing |
979 | parentheses to extract values within the matching URL, those values |
429d1caf |
980 | are available in the C<< $c->req->captures >> array. In the above |
d6ea2bcb |
981 | example, "widget23" would capture "23" in the above example, and |
429d1caf |
982 | C<< $c->req->captures->[0] >> would be "23". If you want to |
d6ea2bcb |
983 | pass arguments at the end of your URL, you must use regex action |
984 | keys. See L</URL Path Handling> below. |
cb93c9d7 |
985 | |
d6ea2bcb |
986 | =item * Chained handlers (C<:Chained>) |
cb93c9d7 |
987 | |
988 | Catalyst also provides a method to build and dispatch chains of actions, |
989 | like |
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 |
1001 | to handle a C</catalog/*/item/*> path. Matching actions are called |
1002 | one after another - C<catalog()> gets called and handed one path |
1003 | element, then C<item()> gets called with another one. For further |
1004 | information about this dispatch type, please see |
1005 | L<Catalyst::DispatchType::Chained>. |
cb93c9d7 |
1006 | |
1007 | =item * B<Private> |
1008 | |
1009 | sub foo : Private { } |
1010 | |
d6ea2bcb |
1011 | This will never match a URL - it provides a private action which can |
1012 | be called programmatically from within Catalyst, but is never called |
1013 | automatically due to the URL being requested. |
1014 | |
1015 | Catalyst's C<:Private> attribute is exclusive and doesn't work with other |
1016 | attributes (so will not work combined with C<:Path> or C<:Chained> |
1017 | attributes, for instance). |
1018 | |
1019 | Private actions can only be executed explicitly from inside a Catalyst |
1020 | application. You might do this in your controllers by calling |
1021 | catalyst 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 |
1027 | See L</Flow Control> for a full explanation of how you can pass |
1028 | requests on to other actions. Note that, as discussed there, when |
1029 | forwarding from another component, you must use the absolute path to |
1030 | the method, so that a private C<bar> method in your |
1031 | C<MyApp::Controller::Catalog::Order::Process> controller must, if |
1032 | called from elsewhere, be reached with |
429d1caf |
1033 | C<< $c->forward('/catalog/order/process/bar') >>. |
cb93c9d7 |
1034 | |
cb93c9d7 |
1035 | =back |
1036 | |
d6ea2bcb |
1037 | B<Note:> After seeing these examples, you probably wonder what the |
1038 | point is of defining subroutine names for regex and path |
1039 | actions. However, every public action is also a private one with a |
1040 | path corresponding to its namespace and subroutine name, so you have |
1041 | one unified way of addressing components in your C<forward>s. |
1042 | |
1043 | =head4 Built-in special actions |
cb93c9d7 |
1044 | |
d6ea2bcb |
1045 | If present, the special actions C< index >, C< auto >, C<begin>, |
1046 | C<end> and C< default > are called at certain points in the request |
1047 | cycle. |
cb93c9d7 |
1048 | |
1049 | In response to specific application states, Catalyst will automatically |
d6ea2bcb |
1050 | call these built-in actions in your application class: |
cb93c9d7 |
1051 | |
1052 | =over 4 |
1053 | |
4299d9f5 |
1054 | =item * B<default : Path> |
cb93c9d7 |
1055 | |
d6ea2bcb |
1056 | This is called when no other action matches. It could be used, for |
1057 | example, for displaying a generic frontpage for the main app, or an |
1058 | error page for individual controllers. B<Note>: in older Catalyst |
1059 | applications you will see C<default : Private> which is roughly |
1060 | speaking equivalent. |
cb93c9d7 |
1061 | |
cb93c9d7 |
1062 | |
4299d9f5 |
1063 | =item * B<index : Path : Args (0) > |
cb93c9d7 |
1064 | |
4299d9f5 |
1065 | C<index> is much like C<default> except that it takes no arguments and |
1066 | it is weighted slightly higher in the matching process. It is useful |
1067 | as a static entry point to a controller, e.g. to have a static welcome |
1068 | page. Note that it's also weighted higher than Path. Actually the sub |
1069 | name C<index> can be called anything you want. The sub attributes are |
955bdf3d |
1070 | what determines the behaviour of the action. B<Note>: in older |
1071 | Catalyst applications, you will see C<index : Private> used, which is |
1072 | roughly speaking equivalent. |
cb93c9d7 |
1073 | |
1074 | =item * B<begin : Private> |
1075 | |
d6ea2bcb |
1076 | Called at the beginning of a request, once the controller that will |
1077 | run has been identified, but before any URL-matching actions are |
1078 | called. Catalyst will call the C<begin> function in the controller |
1079 | which contains the action matching the URL. |
cb93c9d7 |
1080 | |
1081 | =item * B<end : Private> |
1082 | |
d6ea2bcb |
1083 | Called at the end of a request, after all URL-matching actions are called. |
1084 | Catalyst will call the C<end> function in the controller |
1085 | which contains the action matching the URL. |
1086 | |
1087 | =item * B<auto : Private> |
1088 | |
1089 | In addition to the normal built-in actions, you have a special action |
1090 | for making chains, C<auto>. C<auto> actions will be run after any |
1091 | C<begin>, but before your URL-matching action is processed. Unlike the other |
1092 | built-ins, multiple C<auto> actions can be called; they will be |
1093 | called in turn, starting with the application class and going through |
1094 | to 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 | |
1105 | You can define built-in actions within your controllers as well as on |
1106 | your application class. In other words, for each of the three built-in |
1107 | actions above, only one will be run in any request cycle. Thus, if |
1108 | C<MyApp::Controller::Catalog::begin> exists, it will be run in place |
1109 | of C<MyApp::begin> if you're in the C<catalog> namespace, and |
1110 | C<MyApp::Controller::Catalog::Order::begin> would override this in |
cb93c9d7 |
1111 | turn. |
1112 | |
d6ea2bcb |
1113 | sub auto : Private { } |
cb93c9d7 |
1114 | |
d6ea2bcb |
1115 | C<auto>, however, doesn't override like this: providing they exist, |
a696baf6 |
1116 | C<MyApp::Controller::Root::auto>, C<MyApp::Controller::Catalog::auto> and |
d6ea2bcb |
1117 | C<MyApp::Catalog::Order::auto> would be called in turn. |
cb93c9d7 |
1118 | |
1119 | Here are some examples of the order in which the various built-ins |
1120 | would 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 | |
1140 | The C<auto> action is also distinguished by the fact that you can break |
1141 | out of the processing chain by returning 0. If an C<auto> action returns |
1142 | 0, any remaining actions will be skipped, except for C<end>. So, for the |
1143 | request above, if the first auto returns false, the chain would look |
1144 | like this: |
1145 | |
1146 | =over 4 |
1147 | |
1148 | =item for a request for C</foo/bar/foo> where first C<auto> returns |
1149 | false |
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 |
1157 | You can also C<die> in the auto action; in that case, the request will |
1158 | go straight to the finalize stage, without processing further |
1159 | actions. So in the above example, C<MyApp::Controller::Foo::Bar::end> |
1160 | is skipped as well. |
1161 | |
cb93c9d7 |
1162 | =back |
1163 | |
d6ea2bcb |
1164 | An example of why one might use C<auto> is an authentication action: |
1165 | you could set up a C<auto> action to handle authentication in your |
cb93c9d7 |
1166 | application class (which will always be called first), and if |
d6ea2bcb |
1167 | authentication fails, returning 0 would skip any remaining methods for |
1168 | that URL. |
cb93c9d7 |
1169 | |
1170 | B<Note:> Looking at it another way, C<auto> actions have to return a |
b1a08fe1 |
1171 | true value to continue processing! |
cb93c9d7 |
1172 | |
1173 | =head4 URL Path Handling |
1174 | |
d6ea2bcb |
1175 | You can pass arguments as part of the URL path, separated with forward |
1176 | slashes (/). If the action is a Regex or LocalRegex, the '$' anchor |
1177 | must be used. For example, suppose you want to handle |
1178 | C</foo/$bar/$baz>, where C<$bar> and C<$baz> may vary: |
cb93c9d7 |
1179 | |
1180 | sub foo : Regex('^foo$') { my ($self, $context, $bar, $baz) = @_; } |
1181 | |
1182 | But 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 |
1187 | Catalyst 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 | |
1193 | So Catalyst would never mistakenly dispatch the first two URLs to the |
1194 | '^foo$' action. |
1195 | |
b1a08fe1 |
1196 | If a Regex or LocalRegex action doesn't use the '$' anchor, the action will |
1197 | still match a URL containing arguments; however the arguments won't be |
d6ea2bcb |
1198 | available via C<@_>, because the Regex will 'eat' them. |
1199 | |
1200 | Beware! If you write two matchers, that match the same path, with the |
1201 | same specificity (that is, they match the same quantity of the path), |
1202 | there's no guarantee which will actually get called. Non-regex |
1203 | matchers get tried first, followed by regex ones, but if you have, for |
1204 | instance: |
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 | |
1214 | then Catalyst will call the one it finds first. In summary, Don't Do |
1215 | This. |
cb93c9d7 |
1216 | |
d6ea2bcb |
1217 | =head4 Query Parameter Processing |
cb93c9d7 |
1218 | |
1219 | Parameters passed in the URL query string are handled with methods in |
1220 | the L<Catalyst::Request> class. The C<param> method is functionally |
cacb3819 |
1221 | equivalent to the C<param> method of L<CGI.pm|CGI> and can be used in |
cb93c9d7 |
1222 | modules 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 | |
1236 | You control the application flow with the C<forward> method, which |
1237 | accepts the key of an action to execute. This can be an action in the |
1238 | same or another Catalyst controller, or a Class name, optionally |
1239 | followed by a method name. After a C<forward>, the control flow will |
1240 | return to the method from which the C<forward> was issued. |
1241 | |
1242 | A C<forward> is similar to a method call. The main differences are that |
1243 | it wraps the call in an C<eval> to allow exception handling; it |
1244 | automatically passes along the context object (C<$c> or C<$context>); |
1245 | and it allows profiling of each call (displayed in the log with |
1246 | debugging 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 | |
1265 | A 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 |
1267 | using C<forward> and issuing a redirect. |
1268 | |
1269 | You can pass new arguments to a C<forward> by adding them |
429d1caf |
1270 | in an anonymous array. In this case C<< $c->req->args >> |
cb93c9d7 |
1271 | will be changed for the duration of the C<forward> only; upon |
429d1caf |
1272 | return, the original value of C<< $c->req->args >> will |
cb93c9d7 |
1273 | be 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 | |
1288 | As you can see from these examples, you can just use the method name as |
1289 | long as you are referring to methods in the same controller. If you want |
1290 | to forward to a method in another controller, or the main application, |
1291 | you 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 |
1296 | You 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 |
1320 | This mechanism is used by L<Catalyst::Action::RenderView> to forward |
1321 | to the C<process> method in a view class. |
1322 | |
1323 | It should be noted that whilst forward is useful, it is not the only way |
1324 | of calling other code in Catalyst. Forward just gives you stats in the debug |
1325 | screen, wraps the code you're calling in an exception handler and localises |
1326 | C<< $c->request->args >>. |
1327 | |
1328 | If 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 |
1342 | Note that C<forward> returns to the calling action and continues |
1343 | processing after the action finishes. If you want all further processing |
1344 | in the calling action to stop, use C<detach> instead, which will execute |
1345 | the C<detach>ed action and not return to the calling sub. In both cases, |
1346 | Catalyst will automatically try to call process() if you omit the |
1347 | method. |
1348 | |
cb93c9d7 |
1349 | =head3 Testing |
1350 | |
1351 | Catalyst has a built-in http server for testing or local |
1352 | deployment. (Later, you can easily use a more powerful server, for |
1353 | example Apache/mod_perl or FastCGI, in a production environment.) |
1354 | |
1355 | Start 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 | |
1361 | You can also do it all from the command line: |
1362 | |
1363 | script/myapp_test.pl http://localhost/ |
1364 | |
1365 | Catalyst has a number of tools for actual regression testing of |
1366 | applications. The helper scripts will automatically generate basic tests |
1367 | that can be extended as you develop your project. To write your own |
1368 | comprehensive test scripts, L<Test::WWW::Mechanize::Catalyst> is an |
1369 | invaluable tool. |
1370 | |
b86fa467 |
1371 | For more testing ideas, see L<Catalyst::Manual::Tutorial::08_Testing>. |
cb93c9d7 |
1372 | |
1373 | Have 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 | |
1389 | IRC: |
1390 | |
1391 | Join #catalyst on irc.perl.org. |
1392 | Join #catalyst-dev on irc.perl.org to help with development. |
1393 | |
1394 | Mailing 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 |
1399 | Wiki: |
1400 | |
1401 | http://dev.catalystframework.org/wiki |
1402 | |
1403 | FAQ: |
1404 | |
1405 | http://dev.catalystframework.org/wiki/faq |
1406 | |
bbddff00 |
1407 | =head1 AUTHORS |
cb93c9d7 |
1408 | |
bbddff00 |
1409 | Catalyst Contributors, see Catalyst.pm |
cb93c9d7 |
1410 | |
1411 | =head1 COPYRIGHT |
1412 | |
bbddff00 |
1413 | This library is free software. You can redistribute it and/or modify it under |
1414 | the same terms as Perl itself. |
b1a08fe1 |
1415 | |
1416 | =cut |