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 Bundle::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:
29 created "My-App/script"
36 created "My-App/lib/My/App"
37 created "My-App/lib/My/App/M"
38 created "My-App/lib/My/App/V"
39 created "My-App/lib/My/App/C"
40 created "My-App/lib/My/App.pm"
41 created "My-App/Build.PL"
42 created "My-App/Makefile.PL"
43 created "My-App/README"
44 created "My-App/Changes"
45 created "My-App/t/01app.t"
46 created "My-App/t/02pod.t"
47 created "My-App/t/03podcoverage.t"
48 created "My-App/script/my_app_cgi.pl"
49 created "My-App/script/my_app_fastcgi.pl"
50 created "My-App/script/my_app_server.pl"
51 created "My-App/script/my_app_test.pl"
52 created "My-App/script/my_app_create.pl"
54 This creates the directory structure shown, populated with skeleton
59 =head2 Testing out the sample application
61 You can test out your new application by running the server script that
65 $ script/my_app_server.pl
67 [...] [catalyst] [debug] Debug messages enabled
68 [...] [catalyst] [debug] Loaded dispatcher "Catalyst::Dispatcher"
69 [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
70 [...] [catalyst] [debug] Found home "/usr/home/jester/foo/My-App/script/.."
71 [...] [catalyst] [debug] Loaded private actions
72 .=--------------------------------+------------------------------------=.
74 |=--------------------------------+------------------------------------=|
75 | /default | My::App |
76 '=--------------------------------+------------------------------------='
78 [....] [catalyst] [info] My::App powered by Catalyst 5.20
79 You can connect to your server at http://localhost:3000/
81 (Note that each line logged by Catalyst begins with a timestamp, which has
82 been replaced here with "C<...>" so that the text fits onto the lines.)
84 The server is now waiting for you to make requests of it. Try using
85 telnet to manually make a simple GET request of the server (when
86 telnet responds with "Escape character is '^]'.", type "GET / HTTP/1.0"
87 and hit return twice):
89 $ telnet localhost 3000
91 Connected to localhost.
92 Escape character is '^]'.
98 Date: Fri May 13 14:15:46 EDT 2005
101 Content-Type: text/html; charset=ISO-8859-1
103 Congratulations, My::App is on Catalyst!
104 Connection closed by foreign host.
107 More trace messages will appear in the original terminal window:
109 [...] [catalyst] [debug] ********************************
110 [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
111 [...] [catalyst] [debug] ********************************
112 [...] [catalyst] [debug] "GET" request for "" from localhost
113 [...] [catalyst] [info] Request took 0.051399s (19.456/s)
114 .=--------------------------------------------------+----------=.
116 |=--------------------------------------------------+----------=|
117 | /default | 0.000026s |
118 '=--------------------------------------------------+----------='
120 The server will continue running until you interrupt it.
122 The application can also be tested from the command line using the generated
123 helper script, C<script/my_app_test.pl>.
126 =head2 Getting your application invoked
128 Catalyst applications are usually run from mod_perl, but can also be
129 run as CGI or FastCGI scripts. Running under mod_perl gives better
130 performance, but for development purposes you may want to run your
131 application as a CGI script, especially as changes to your application
132 code take effect under CGI without having to restart the web server.
134 To run from mod_perl you need to add something like this to your Apache
138 SetHandler perl-script
142 To run as a CGI script you need a wrapper script like:
147 use lib '/path/to/My/App/lib';
154 =head2 Examining the generated code
156 The generated application code is quite simple and looks something
162 use Catalyst qw/-Debug/;
164 our $VERSION = '0.01';
168 root => '/home/andrew/My-App/root',
171 __PACKAGE__->setup();
173 sub default : Private {
174 my ( $self, $c ) = @_;
175 $c->res->output('Congratulations, My::App is on Catalyst!');
181 When the C<Catalyst> module is imported by the application code,
182 Catalyst performs the first stage of its initialization. This includes
183 loading the appropriate Engine module for the environment in which the
184 application is running, loading any plugins and ensuring that the
185 calling module (the application module) inherits from C<Catalyst>
186 (which makes the Catalyst methods C<config> and C<setup> available to
187 the application module).
189 The call to C<config> sets up configuration data for the application.
190 The C<name> and C<root> items are the minimum required, and specify
191 the name of the application and the path to the root directory where
192 documents, images, and templates can be found.
194 Catalyst associates I<actions> with URLs and on receiving a request
195 dispatches to the action that matches to request URL. The call to
196 C<setup> in the code above registers a default action. With just
197 this action registered the application will respond to all requests
198 with the same message "Congratulations, My::App is on Catalyst!".
200 As you see, the default action is defined as a Private action.
201 Most private actions are not directly available from a web url. This
202 also includes the built-in actions, 'default','begin','end', and
203 'auto', although they will be called as part of some chains.
204 The rest can only be reached by using C<forward>.
206 The call to the C<setup> method also triggers the second stage of
207 Catalyst's initialization process. In this phase Catalyst searches
208 for any component modules, locating and registering any actions it
209 finds in those modules.
211 Component modules have names prefixed with the application module name,
212 followed by C<M>, C<V> or C<C> (or the optional long
213 forms: C<Model>, C<View> or C<Controller>) followed by the component
216 My::App::C::ShoppingCart # short (default) version
217 My::App::Controller::ShoppingCart # long version
219 My::App::M::User # short (default) version
220 My::App::Model::User # long version
222 =head2 Extending the generated code
225 You can start extending the application by adding new actions:
228 my ( $self, $c ) = @_;
229 $c->res->output('In a new test action #1');
231 sub default : Private {
232 my ( $self, $c ) = @_;
233 $c->res->output('Congratulations, My::App is on Catalyst!');
236 # called like '/article/2005/06'
237 sub archive_month : Regex('^article/(\d{4})/(\d{2})$') {
238 my ( $self, $c ) = @_;
240 my $datetime = DateTime->new(
241 year => $c->request->snippets->[0],
242 month => $c->request->snippets->[1]
246 TODO: explain briefly about plugins, actions, and components
248 If the action is a Regex type, you can use capturing parentheses to
249 extract values within the matching URL (2005, 06 in the above
250 example). Those values are available in the $c->req->snippets
251 anonymous array. See L<Catalyst::Manual::Intro#Actions> for details.
254 =head2 Hooking in to Template Toolkit
256 One of the first things you will probably want to add to your
257 application is a templating system for generating your output.
258 Catalyst works well with Template Toolkit. If you are unfamiliar with
259 Template Toolkit then I suggest you look at L<http://tt2.org>, install
260 C<Template>, read the documentation and play around with it, and have
261 a look at the I<Badger Book> (I<Template Toolkit> by Darren
262 Chamberlain, Dave Cross, and Andy Wardley, O'Reilly & Associates, 2004).
264 You can create a stub Template Toolkit view component using the create
265 script that Catalyst set up as part of the skeleton application:
267 $ script/create.pl view TT TT
269 this generates a view component named C<My::App::V::TT>, which you
270 might use by forwarding from your C<end> action:
272 # In My::App or My::App::Controller::SomeController
276 $c->forward('My::App::V::TT');
279 The generated TT view component simply subclasses the
280 C<Catalyst::View::TT> class. It looks like this (with the POD
283 package My::App::V::TT;
286 use base 'Catalyst::View::TT';
290 C<Catalyst::View::TT> initializes a Template Toolkit object with an
291 options hash initialized with built-in default settings followed by
292 the contents of the hash C<<%{__PACKAGE__->config()}>>. You can
293 configure TT more to your needs by adding a C<new> method to the
294 generated TT component:
298 $self->config->{PRE_PROCESS} = 'config/main';
299 $self->config->{WRAPPER} = 'site/wrapper';
300 return $self->SUPER::new(@_);
307 Andrew Ford, C<A.Ford@ford-mason.co.uk>
308 Marcus Ramberg, C<mramberg@cpan.org>
310 As noted above, this document is at an alpha stage. My plan for this
311 document is as follows:
317 Expand this document fairly rapidly to cover topics relevant to
318 a newcomer to Catalyst, in an order that can be read sequentially
330 Placeholders are indicated by the words: TODO or CHECK
332 Please send comments, corrections and suggestions for improvements to
333 A.Ford@ford-mason.co.uk
338 This program is free software, you can redistribute it and/or modify
339 it under the same terms as Perl itself.