3 Catalyst::Manual::Tutorial - Getting started with Catalyst
7 This document aims to get you up and running with Catalyst.
9 NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE. SEE
10 THE NOTES AT THE BOTTOM OF THE DOCUMENT.
14 The first step is to install Catalyst, and the simplest way to do this
15 is to install the Catalyst bundle from CPAN:
17 $ perl -MCPAN -e 'install Task::Catalyst'
19 This will retrieve Catalyst and a number of useful extensions and
23 =head2 Setting up your application
25 Catalyst includes a helper script, C<catalyst.pl>, that will set up a
26 skeleton application for you:
31 created "MyApp/script"
34 created "MyApp/root/static"
35 created "MyApp/root/static/images"
37 created "MyApp/t/Model"
38 created "MyApp/t/View"
39 created "MyApp/t/Controller"
40 created "MyApp/lib/MyApp"
41 created "MyApp/lib/MyApp/Model"
42 created "MyApp/lib/MyApp/View"
43 created "MyApp/lib/MyApp/Controller"
44 created "MyApp/lib/MyApp.pm"
45 created "MyApp/Build.PL"
46 created "MyApp/Makefile.PL"
47 created "MyApp/README"
48 created "MyApp/Changes"
49 created "MyApp/t/01app.t"
50 created "MyApp/t/02pod.t"
51 created "MyApp/t/03podcoverage.t"
52 created "MyApp/root/static/images/catalyst_logo.png"
53 created "MyApp/root/static/images/btn_120x50_built.png"
54 created "MyApp/root/static/images/btn_120x50_built_shadow.png"
55 created "MyApp/root/static/images/btn_120x50_powered.png"
56 created "MyApp/root/static/images/btn_120x50_powered_shadow.png"
57 created "MyApp/root/static/images/btn_88x31_built.png"
58 created "MyApp/root/static/images/btn_88x31_built_shadow.png"
59 created "MyApp/root/static/images/btn_88x31_powered.png"
60 created "MyApp/root/static/images/btn_88x31_powered_shadow.png"
61 created "MyApp/root/favicon.ico"
62 created "MyApp/script/myapp_cgi.pl"
63 created "MyApp/script/myapp_fastcgi.pl"
64 created "MyApp/script/myapp_server.pl"
65 created "MyApp/script/myapp_test.pl"
66 created "MyApp/script/myapp_create.pl"
68 This creates the directory structure shown, populated with skeleton
71 =head2 Testing out the sample application
73 You can test out your new application by running the server script that
77 $ script/myapp_server.pl
79 [...] [catalyst] [debug] Debug messages enabled
80 [...] [catalyst] [debug] Loaded plugins:
81 .------------------------------------------------------------------------------.
82 | Catalyst::Plugin::Static::Simple |
83 '------------------------------------------------------------------------------'
84 [...] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
85 [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
86 [...] [catalyst] [debug] Found home "/home/users/me/MyApp"
87 [...] [catalyst] [debug] Loaded Private actions:
88 .--------------------------------------+---------------------------------------.
90 +--------------------------------------+---------------------------------------+
92 '--------------------------------------+---------------------------------------'
94 [...] [catalyst] [info] MyApp powered by Catalyst 5.5
95 You can connect to your server at http://localhost:3000
97 (Note that each line logged by Catalyst begins with a timestamp, which has
98 been replaced here with "C<...>" so that the text fits onto the lines.)
100 The server is now waiting for you to make requests of it. Try using
101 telnet to manually make a simple GET request of the server (when
102 telnet responds with "Escape character is '^]'.", type "GET / HTTP/1.0"
103 and hit return twice):
105 $ telnet localhost 3000
107 Connected to localhost.
108 Escape character is '^]'.
112 Date: Mon, 07 Nov 2005 14:57:39 GMT
114 Content-Type: text/html; charset=utf-8
119 Connection closed by foreign host.
122 You can see the full welcome message by visting
123 http://localhost:3000/ with your browser.
125 More trace messages will appear in the original terminal window:
127 [...] [catalyst] [debug] **********************************
128 [...] [catalyst] [debug] * Request 1 (0.063/s) [2148]
129 [...] [catalyst] [debug] **********************************
130 [...] [catalyst] [debug] Arguments are ""
131 [...] [catalyst] [debug] "GET" request for "" from localhost
132 [...] [catalyst] [info] Request took 0.046883s (21.330/s)
133 .------------------------------------------------------------------+-----------.
135 +------------------------------------------------------------------+-----------+
136 | /default | 0.000000s |
137 '------------------------------------------------------------------+-----------'
139 The server will continue running until you interrupt it.
141 The application can also be tested from the command line using the generated
142 helper script, C<script/myapp_test.pl>.
144 =head2 Getting your application invoked
146 Catalyst applications are usually run from mod_perl, but can also be
147 run as CGI or FastCGI scripts. Running under mod_perl gives better
148 performance, but for development purposes you may want to run your
149 application as a CGI script, especially as changes to your application
150 code take effect under CGI without having to restart the web server.
152 To run from mod_perl you need to add something like this to your Apache
156 SetHandler perl-script
160 To run as a CGI script you need a wrapper script like:
165 use lib '/path/to/MyApp/lib';
170 =head2 Examining the generated code
172 The generated application code is quite simple and looks something
173 like this (comments removed):
180 use Catalyst qw/-Debug Static::Simple/;
182 our $VERSION = '0.01';
184 __PACKAGE__->config( name => 'MyApp' );
187 sub default : Private {
188 my ( $self, $c ) = @_;
190 $c->response->body( $c->welcome_message );
195 When the C<Catalyst> module is imported by the application code,
196 Catalyst performs the first stage of its initialization. This includes
197 loading the appropriate Engine module for the environment in which the
198 application is running, loading any plugins and ensuring that the
199 calling module (the application module) inherits from C<Catalyst>
200 (which makes the Catalyst methods C<config> and C<setup> available to
201 the application module).
203 The call to C<config> sets up configuration data for the application.
204 The C<name> parameter is the only required configuration parameter.
205 You may also specificy a C<root> parameter, which is the path to the
206 directory where documents, images, and templates can be found.
208 Catalyst associates I<actions> with URLs and on receiving a request
209 dispatches to the action that matches to request URL. The call to
210 C<setup> in the code above registers a default action. With just
211 this action registered the application will respond to all requests
212 with the same welcome page.
214 As you see, the default action is defined as a Private action.
215 Most private actions are not directly available from a web url. This
216 also includes the built-in actions, 'default', 'begin', 'end', and
217 'auto', although they will be called as part of some chains.
218 The rest can only be reached by using C<forward>.
220 The call to the C<setup> method also triggers the second stage of
221 Catalyst's initialization process. In this phase Catalyst searches
222 for any component modules, locating and registering any actions it
223 finds in those modules.
225 Component modules have names prefixed with the application module name,
226 followed by C<Model>, C<View> or C<Controller> (or the optional short
227 forms: C<M>, C<V> or C<C>) followed by the component
230 MyApp::Controller::ShoppingCart # long (default) version
231 MyApp::C::ShoppingCart # short version
233 MyApp::Model::User # long (default) version
234 MyApp::M::User # short version
236 =head2 Extending the generated code
238 You can start extending the application by adding new actions:
241 my ( $self, $c ) = @_;
242 $c->res->body('In a new test action #1');
244 sub default : Private {
245 my ( $self, $c ) = @_;
246 $c->res->body('Congratulations, MyApp is on Catalyst!');
249 # called like '/article/2005/06'
250 sub archive_month : Regex('^article/(\d{4})/(\d{2})$') {
251 my ( $self, $c ) = @_;
253 my $datetime = DateTime->new(
254 year => $c->request->snippets->[0],
255 month => $c->request->snippets->[1]
259 TODO: explain briefly about plugins, actions, and components
261 If the action is a Regex type, you can use capturing parentheses to
262 extract values within the matching URL (2005, 06 in the above
263 example). Those values are available in the $c->req->snippets
264 anonymous array. See L<Catalyst::Manual::Intro#Actions> for details.
266 =head2 Hooking in to Template Toolkit
268 One of the first things you will probably want to add to your
269 application is a templating system for generating your output.
270 Catalyst works well with Template Toolkit. If you are unfamiliar with
271 Template Toolkit then I suggest you look at L<http://tt2.org>, install
272 C<Template>, read the documentation and play around with it, and have
273 a look at the I<Badger Book> (I<Template Toolkit> by Darren
274 Chamberlain, Dave Cross, and Andy Wardley, O'Reilly & Associates, 2004).
276 You can create a stub Template Toolkit view component by installing
277 L<Catalyst::View::TT> and using the create script that Catalyst set
278 up as part of the skeleton application:
280 $ script/myapp_create.pl view TT TT
282 exists "MyApp/lib/MyApp/View"
283 exists "MyApp/t/View"
284 created "MyApp/lib/MyApp/View/TT.pm"
285 created "MyApp/t/View/TT.t"
287 this generates a view component named C<MyApp::View::TT>, which you
288 might use by forwarding from your C<end> action:
290 # In MyApp or MyApp::Controller::SomeController
294 $c->forward('MyApp::V::TT');
297 The generated TT view component simply subclasses the
298 C<Catalyst::View::TT> class. It looks like this (with the POD
301 package My::App::V::TT;
304 use base 'Catalyst::View::TT';
308 C<Catalyst::View::TT> initializes a Template Toolkit object with an
309 options hash initialized with built-in default settings followed by
310 the contents of the hash C<<%{__PACKAGE__->config()}>>. You can
311 configure TT more to your needs by adding a C<new> method to the
312 generated TT component:
316 $self->config->{PRE_PROCESS} = 'config/main';
317 $self->config->{WRAPPER} = 'site/wrapper';
318 return $self->SUPER::new(@_);
323 Andrew Ford, C<A.Ford@ford-mason.co.uk>
324 Marcus Ramberg, C<mramberg@cpan.org>
326 As noted above, this document is at an alpha stage. My plan for this
327 document is as follows:
333 Expand this document fairly rapidly to cover topics relevant to
334 a newcomer to Catalyst, in an order that can be read sequentially
346 Placeholders are indicated by the words: TODO or CHECK
348 Please send comments, corrections and suggestions for improvements to
349 A.Ford@ford-mason.co.uk
353 This program is free software, you can redistribute it and/or modify
354 it under the same terms as Perl itself.