Commit | Line | Data |
fc7ec1d9 |
1 | NAME |
2 | Catalyst - The Elegant MVC Web Application Framework |
3 | |
4 | SYNOPSIS |
5 | # use the helper to start a new application |
d01df17d |
6 | catalyst.pl MyApp |
fc7ec1d9 |
7 | cd MyApp |
8 | |
9 | # add models, views, controllers |
f56990fa |
10 | script/myapp_create.pl model Something |
11 | script/myapp_create.pl view Stuff |
12 | script/myapp_create.pl controller Yada |
fc7ec1d9 |
13 | |
14 | # built in testserver |
f56990fa |
15 | script/myapp_server.pl |
fc7ec1d9 |
16 | |
17 | # command line interface |
f56990fa |
18 | script/myapp_test.pl /yada |
fc7ec1d9 |
19 | |
fc7ec1d9 |
20 | use Catalyst; |
21 | |
22 | use Catalyst qw/My::Module My::OtherModule/; |
23 | |
24 | use Catalyst '-Debug'; |
25 | |
26 | use Catalyst qw/-Debug -Engine=CGI/; |
27 | |
4be6aea7 |
28 | sub default : Private { $_[1]->res->output('Hello') } ); |
29 | |
30 | sub index : Path('/index.html') { |
31 | my ( $self, $c ) = @_; |
32 | $c->res->output('Hello'); |
6f6e1bb4 |
33 | $c->forward('foo'); |
4be6aea7 |
34 | } |
35 | |
6f6e1bb4 |
36 | sub product : Regex('^product[_]*(\d*).html$') { |
4be6aea7 |
37 | my ( $self, $c ) = @_; |
38 | $c->stash->{template} = 'product.tt'; |
39 | $c->stash->{product} = $c->req->snippets->[0]; |
40 | } |
fc7ec1d9 |
41 | |
92af75fc |
42 | See also Catalyst::Manual::Intro |
43 | |
fc7ec1d9 |
44 | DESCRIPTION |
fc7ec1d9 |
45 | The key concept of Catalyst is DRY (Don't Repeat Yourself). |
46 | |
47 | See Catalyst::Manual for more documentation. |
48 | |
4be6aea7 |
49 | Catalyst plugins can be loaded by naming them as arguments to the "use |
50 | Catalyst" statement. Omit the "Catalyst::Plugin::" prefix from the |
51 | plugin name, so "Catalyst::Plugin::My::Module" becomes "My::Module". |
fc7ec1d9 |
52 | |
53 | use Catalyst 'My::Module'; |
54 | |
01ba879f |
55 | Special flags like -Debug and -Engine can also be specified as arguments |
4be6aea7 |
56 | when Catalyst is loaded: |
fc7ec1d9 |
57 | |
58 | use Catalyst qw/-Debug My::Module/; |
59 | |
60 | The position of plugins and flags in the chain is important, because |
4be6aea7 |
61 | they are loaded in exactly the order that they appear. |
fc7ec1d9 |
62 | |
4be6aea7 |
63 | The following flags are supported: |
fc7ec1d9 |
64 | |
4be6aea7 |
65 | -Debug |
66 | enables debug output, i.e.: |
fc7ec1d9 |
67 | |
4be6aea7 |
68 | use Catalyst '-Debug'; |
69 | |
70 | this is equivalent to: |
71 | |
72 | use Catalyst; |
73 | sub debug { 1 } |
fc7ec1d9 |
74 | |
fbcc39ad |
75 | -Dispatcher |
76 | Force Catalyst to use a specific dispatcher. |
77 | |
4be6aea7 |
78 | -Engine |
79 | Force Catalyst to use a specific engine. Omit the |
80 | "Catalyst::Engine::" prefix of the engine name, i.e.: |
fc7ec1d9 |
81 | |
4be6aea7 |
82 | use Catalyst '-Engine=CGI'; |
fc7ec1d9 |
83 | |
fbcc39ad |
84 | -Home |
85 | Force Catalyst to use a specific home directory. |
86 | |
87 | -Log |
88 | Specify log level. |
89 | |
4be6aea7 |
90 | METHODS |
01ba879f |
91 | $c->action |
92 | Accessor for the current action |
93 | |
fbcc39ad |
94 | $c->comp($name) |
95 | $c->component($name) |
96 | Get a component object by name. |
97 | |
98 | $c->comp('MyApp::Model::MyModel')->do_stuff; |
fc7ec1d9 |
99 | |
4be6aea7 |
100 | config |
101 | Returns a hashref containing your applications settings. |
102 | |
acd95255 |
103 | $c->controller($name) |
104 | Get a Catalyst::Controller instance by name. |
105 | |
106 | $c->controller('Foo')->do_stuff; |
107 | |
fbcc39ad |
108 | debug |
109 | Overload to enable debug messages. |
110 | |
111 | $c->detach( $command [, \@arguments ] ) |
112 | Like "forward" but doesn't return. |
113 | |
114 | $c->dispatcher |
115 | Contains the dispatcher instance. Stringifies to class. |
116 | |
117 | $c->forward( $command [, \@arguments ] ) |
118 | Forward processing to a private action or a method from a class. If |
119 | you define a class without method it will default to process(). also |
120 | takes an optional arrayref containing arguments to be passed to the |
121 | new function. $c->req->args will be reset upon returning from the |
122 | function. |
123 | |
124 | $c->forward('/foo'); |
125 | $c->forward('index'); |
126 | $c->forward(qw/MyApp::Model::CDBI::Foo do_stuff/); |
127 | $c->forward('MyApp::View::TT'); |
128 | |
acd95255 |
129 | $c->model($name) |
130 | Get a Catalyst::Model instance by name. |
131 | |
132 | $c->model('Foo')->do_stuff; |
133 | |
01ba879f |
134 | $c->namespace |
135 | Accessor to the namespace of the current action |
136 | |
137 | $c->path_to(@path) |
138 | Merges @path with $c->config->{home} and returns a Path::Class |
139 | object. |
140 | |
141 | For example: |
142 | |
143 | $c->path_to( 'db', 'sqlite.db' ); |
144 | |
fbcc39ad |
145 | $c->setup |
146 | Setup. |
147 | |
148 | $c->setup; |
149 | |
01ba879f |
150 | $c->uri_for($path,[@args]) |
fbcc39ad |
151 | Merges path with $c->request->base for absolute uri's and with |
152 | $c->request->match for relative uri's, then returns a normalized URI |
01ba879f |
153 | object. If any args are passed, they are added at the end of the |
154 | path. |
fbcc39ad |
155 | |
156 | $c->error |
157 | $c->error($error, ...) |
158 | $c->error($arrayref) |
159 | Returns an arrayref containing error messages. |
160 | |
161 | my @error = @{ $c->error }; |
162 | |
163 | Add a new error. |
164 | |
165 | $c->error('Something bad happened'); |
166 | |
01ba879f |
167 | Clean errors. |
168 | |
169 | $c->error(0); |
170 | |
4be6aea7 |
171 | $c->engine |
fbcc39ad |
172 | Contains the engine instance. Stringifies to the class. |
4be6aea7 |
173 | |
174 | $c->log |
175 | Contains the logging object. Unless it is already set Catalyst sets |
176 | this up with a "Catalyst::Log" object. To use your own log class: |
177 | |
178 | $c->log( MyLogger->new ); |
179 | $c->log->info("now logging with my own logger!"); |
180 | |
181 | Your log class should implement the methods described in the |
182 | "Catalyst::Log" man page. |
fc7ec1d9 |
183 | |
6f6e1bb4 |
184 | $c->plugin( $name, $class, @args ) |
185 | Instant plugins for Catalyst. Classdata accessor/mutator will be |
186 | created, class loaded and instantiated. |
187 | |
188 | MyApp->plugin( 'prototype', 'HTML::Prototype' ); |
189 | |
190 | $c->prototype->define_javascript_functions; |
d1a31ac6 |
191 | |
fbcc39ad |
192 | $c->request |
193 | $c->req |
194 | Returns a "Catalyst::Request" object. |
195 | |
196 | my $req = $c->req; |
197 | |
198 | $c->response |
199 | $c->res |
200 | Returns a "Catalyst::Response" object. |
201 | |
202 | my $res = $c->res; |
203 | |
204 | $c->state |
205 | Contains the return value of the last executed action. |
206 | |
207 | $c->stash |
208 | Returns a hashref containing all your data. |
209 | |
fbcc39ad |
210 | print $c->stash->{foo}; |
211 | |
01ba879f |
212 | Keys may be set in the stash by assigning to the hash reference, or |
213 | by passing either a single hash reference or a list of key/value |
214 | pairs as arguments. |
215 | |
216 | For example: |
217 | |
218 | $c->stash->{foo} ||= 'yada'; |
219 | $c->stash( { moose => 'majestic', qux => 0 } ); |
220 | $c->stash( bar => 1, gorch => 2 ); |
221 | |
acd95255 |
222 | $c->view($name) |
223 | Get a Catalyst::View instance by name. |
224 | |
225 | $c->view('Foo')->do_stuff; |
226 | |
01ba879f |
227 | $c->welcome_message |
228 | Returns the Catalyst welcome HTML page. |
229 | |
fbcc39ad |
230 | INTERNAL METHODS |
231 | $c->benchmark($coderef) |
232 | Takes a coderef with arguments and returns elapsed time as float. |
233 | |
234 | my ( $elapsed, $status ) = $c->benchmark( sub { return 1 } ); |
235 | $c->log->info( sprintf "Processing took %f seconds", $elapsed ); |
236 | |
237 | $c->components |
238 | Contains the components. |
239 | |
acd95255 |
240 | $c->context_class($class) |
241 | Contains the context class. |
242 | |
fbcc39ad |
243 | $c->counter |
244 | Returns a hashref containing coderefs and execution counts. (Needed |
245 | for deep recursion detection) |
246 | |
247 | $c->depth |
248 | Returns the actual forward depth. |
249 | |
250 | $c->dispatch |
251 | Dispatch request to actions. |
252 | |
acd95255 |
253 | $c->dispatcher_class($class) |
254 | Contains the dispatcher class. |
255 | |
60b53d07 |
256 | dump_these |
257 | Returns a list of 2-element array references (name, structure) pairs |
258 | that will be dumped on the error page in debug mode. |
259 | |
acd95255 |
260 | $c->engine_class($class) |
261 | Contains the engine class. |
262 | |
fbcc39ad |
263 | $c->execute($class, $coderef) |
264 | Execute a coderef in given class and catch exceptions. Errors are |
265 | available via $c->error. |
266 | |
267 | $c->finalize |
268 | Finalize request. |
269 | |
270 | $c->finalize_body |
271 | Finalize body. |
272 | |
273 | $c->finalize_cookies |
274 | Finalize cookies. |
275 | |
276 | $c->finalize_error |
277 | Finalize error. |
278 | |
279 | $c->finalize_headers |
280 | Finalize headers. |
281 | |
282 | $c->finalize_output |
283 | An alias for finalize_body. |
284 | |
285 | $c->finalize_read |
286 | Finalize the input after reading is complete. |
287 | |
288 | $c->finalize_uploads |
289 | Finalize uploads. Cleans up any temporary files. |
290 | |
60b53d07 |
291 | $c->get_action( $action, $namespace ) |
fbcc39ad |
292 | Get an action in a given namespace. |
293 | |
60b53d07 |
294 | $c->get_actions( $action, $namespace ) |
295 | Get all actions of a given name in a namespace and all base |
296 | namespaces. |
297 | |
fbcc39ad |
298 | handle_request( $class, @arguments ) |
299 | Handles the request. |
300 | |
301 | $c->prepare(@arguments) |
302 | Turns the engine-specific request( Apache, CGI ... ) into a Catalyst |
303 | context . |
304 | |
305 | $c->prepare_action |
306 | Prepare action. |
307 | |
308 | $c->prepare_body |
309 | Prepare message body. |
310 | |
01ba879f |
311 | $c->prepare_body_chunk( $chunk ) |
312 | Prepare a chunk of data before sending it to HTTP::Body. |
313 | |
fbcc39ad |
314 | $c->prepare_body_parameters |
315 | Prepare body parameters. |
316 | |
317 | $c->prepare_connection |
318 | Prepare connection. |
319 | |
320 | $c->prepare_cookies |
321 | Prepare cookies. |
322 | |
323 | $c->prepare_headers |
324 | Prepare headers. |
325 | |
326 | $c->prepare_parameters |
327 | Prepare parameters. |
328 | |
329 | $c->prepare_path |
330 | Prepare path and base. |
331 | |
332 | $c->prepare_query_parameters |
333 | Prepare query parameters. |
334 | |
335 | $c->prepare_read |
336 | Prepare the input for reading. |
337 | |
338 | $c->prepare_request |
339 | Prepare the engine request. |
340 | |
341 | $c->prepare_uploads |
342 | Prepare uploads. |
343 | |
344 | $c->prepare_write |
345 | Prepare the output for writing. |
346 | |
acd95255 |
347 | $c->request_class($class) |
348 | Contains the request class. |
349 | |
350 | $c->response_class($class) |
351 | Contains the response class. |
352 | |
fbcc39ad |
353 | $c->read( [$maxlength] ) |
354 | Read a chunk of data from the request body. This method is designed |
355 | to be used in a while loop, reading $maxlength bytes on every call. |
356 | $maxlength defaults to the size of the request if not specified. |
357 | |
358 | You have to set MyApp->config->{parse_on_demand} to use this |
359 | directly. |
360 | |
361 | $c->run |
362 | Starts the engine. |
363 | |
364 | $c->set_action( $action, $code, $namespace, $attrs ) |
365 | Set an action in a given namespace. |
366 | |
367 | $c->setup_actions($component) |
368 | Setup actions for a component. |
369 | |
370 | $c->setup_components |
371 | Setup components. |
372 | |
373 | $c->setup_dispatcher |
374 | $c->setup_engine |
375 | $c->setup_home |
376 | $c->setup_log |
377 | $c->setup_plugins |
acd95255 |
378 | $c->stack |
379 | Contains the stack. |
380 | |
fbcc39ad |
381 | $c->write( $data ) |
382 | Writes $data to the output stream. When using this method directly, |
383 | you will need to manually set the Content-Length header to the |
384 | length of your output data, if known. |
385 | |
01ba879f |
386 | version |
387 | Returns the Catalyst version number. mostly useful for powered by |
388 | messages in template systems. |
389 | |
60b53d07 |
390 | INTERNAL ACTIONS |
391 | Catalyst uses internal actions like "_DISPATCH", "_BEGIN", "_AUTO" |
392 | "_ACTION" and "_END", these are by default not shown in the private |
393 | action table. |
394 | |
395 | But you can deactivate this with a config parameter. |
396 | |
397 | MyApp->config->{show_internal_actions} = 1; |
398 | |
f56990fa |
399 | CASE SENSITIVITY |
400 | By default Catalyst is not case sensitive, so "MyApp::C::FOO::Bar" |
401 | becomes "/foo/bar". |
402 | |
403 | But you can activate case sensitivity with a config parameter. |
404 | |
405 | MyApp->config->{case_sensitive} = 1; |
406 | |
fbcc39ad |
407 | So "MyApp::C::Foo::Bar" becomes "/Foo/Bar". |
408 | |
409 | ON-DEMAND PARSER |
410 | The request body is usually parsed at the beginning of a request, but if |
411 | you want to handle input yourself or speed things up a bit you can |
412 | enable on-demand parsing with a config parameter. |
413 | |
414 | MyApp->config->{parse_on_demand} = 1; |
415 | |
416 | PROXY SUPPORT |
417 | Many production servers operate using the common double-server approach, |
418 | with a lightweight frontend web server passing requests to a larger |
419 | backend server. An application running on the backend server must deal |
420 | with two problems: the remote user always appears to be '127.0.0.1' and |
421 | the server's hostname will appear to be 'localhost' regardless of the |
422 | virtual host the user connected through. |
423 | |
424 | Catalyst will automatically detect this situation when you are running |
425 | both the frontend and backend servers on the same machine. The following |
426 | changes are made to the request. |
427 | |
428 | $c->req->address is set to the user's real IP address, as read from the |
429 | HTTP_X_FORWARDED_FOR header. |
430 | |
431 | The host value for $c->req->base and $c->req->uri is set to the real host, |
432 | as read from the HTTP_X_FORWARDED_HOST header. |
433 | |
434 | Obviously, your web server must support these 2 headers for this to |
435 | work. |
436 | |
437 | In a more complex server farm environment where you may have your |
438 | frontend proxy server(s) on different machines, you will need to set a |
439 | configuration option to tell Catalyst to read the proxied data from the |
440 | headers. |
441 | |
442 | MyApp->config->{using_frontend_proxy} = 1; |
443 | |
444 | If you do not wish to use the proxy support at all, you may set: |
445 | |
446 | MyApp->config->{ignore_frontend_proxy} = 1; |
447 | |
448 | THREAD SAFETY |
449 | Catalyst has been tested under Apache 2's threading mpm_worker, |
450 | mpm_winnt, and the standalone forking HTTP server on Windows. We believe |
451 | the Catalyst core to be thread-safe. |
452 | |
453 | If you plan to operate in a threaded environment, remember that all |
454 | other modules you are using must also be thread-safe. Some modules, most |
455 | notably DBD::SQLite, are not thread-safe. |
d1a31ac6 |
456 | |
92af75fc |
457 | SUPPORT |
458 | IRC: |
459 | |
460 | Join #catalyst on irc.perl.org. |
461 | |
462 | Mailing-Lists: |
463 | |
464 | http://lists.rawmode.org/mailman/listinfo/catalyst |
465 | http://lists.rawmode.org/mailman/listinfo/catalyst-dev |
4be6aea7 |
466 | |
6f6e1bb4 |
467 | Web: |
468 | |
469 | http://catalyst.perl.org |
470 | |
fc7ec1d9 |
471 | SEE ALSO |
4be6aea7 |
472 | Catalyst::Manual - The Catalyst Manual |
473 | Catalyst::Engine - Core Engine |
474 | Catalyst::Log - The Log Class. |
475 | Catalyst::Request - The Request Object |
476 | Catalyst::Response - The Response Object |
477 | Catalyst::Test - The test suite. |
fc7ec1d9 |
478 | |
4e449be9 |
479 | CREDITS |
480 | Andy Grundman |
481 | |
fbcc39ad |
482 | Andy Wardley |
483 | |
01ba879f |
484 | Andreas Marienborg |
485 | |
486 | Andrew Bramble |
487 | |
4e449be9 |
488 | Andrew Ford |
489 | |
490 | Andrew Ruthven |
491 | |
fbcc39ad |
492 | Arthur Bergman |
493 | |
4e449be9 |
494 | Autrijus Tang |
495 | |
acd95255 |
496 | Brian Cassidy |
497 | |
4e449be9 |
498 | Christian Hansen |
499 | |
500 | Christopher Hicks |
501 | |
502 | Dan Sully |
503 | |
504 | Danijel Milicevic |
505 | |
506 | David Naughton |
507 | |
508 | Gary Ashton Jones |
509 | |
510 | Geoff Richards |
511 | |
512 | Jesse Sheidlower |
513 | |
fbcc39ad |
514 | Jesse Vincent |
515 | |
4e449be9 |
516 | Jody Belka |
517 | |
518 | Johan Lindstrom |
519 | |
520 | Juan Camacho |
521 | |
522 | Leon Brocard |
523 | |
524 | Marcus Ramberg |
525 | |
526 | Matt S Trout |
527 | |
528 | Robert Sedlacek |
529 | |
60b53d07 |
530 | Sam Vilain |
531 | |
acd95255 |
532 | Sascha Kiefer |
533 | |
4e449be9 |
534 | Tatsuhiko Miyagawa |
535 | |
536 | Ulf Edvinsson |
537 | |
01ba879f |
538 | Yuval Kogman |
539 | |
fc7ec1d9 |
540 | AUTHOR |
541 | Sebastian Riedel, "sri@oook.de" |
542 | |
fc7ec1d9 |
543 | LICENSE |
01ba879f |
544 | This library is free software, you can redistribute it and/or modify it |
545 | under the same terms as Perl itself. |
fc7ec1d9 |
546 | |