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 THE NOTES
10 AT THE BOTTOM OF THE DOCUMENT.
16 The first step is to install Catalyst, and the simplest way to do this is to
17 install the Catalyst bundle from CPAN:
19 $ perl -MCPAN -e 'install Bundle::Catalyst'
21 This will retrieve Catalyst and a number of useful extensions and install them
25 =head2 Setting up your application
27 Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
32 created "My-App/script"
39 created "My-App/lib/My/App"
40 created "My-App/lib/My/App/M"
41 created "My-App/lib/My/App/V"
42 created "My-App/lib/My/App/C"
43 created "My-App/lib/My/App.pm"
44 created "My-App/Makefile.PL"
45 created "My-App/README"
46 created "My-App/Changes"
47 created "My-App/t/01app.t"
48 created "My-App/t/02podcoverage.t"
49 created "My-App/script/cgi.pl"
50 created "My-App/script/nph-cgi.pl"
51 created "My-App/script/fcgi.pl"
52 created "My-App/script/server.pl"
53 created "My-App/script/test.pl"
54 created "My-App/script/create.pl"
56 This creates the directory structure shown, populated with skeleton files.
60 =head2 Testing out the sample application
62 You can test out your new application by running the server script that
67 [...] [catalyst] [debug] Debug messages enabled
68 [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
69 [...] [catalyst] [debug] Initialized components ""
70 [...] [catalyst] [info] My::App powered by Catalyst 4.26
71 [...] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
72 You can connect to your server at http://localhost:3000
74 (Note that each line logged by Catalyst includes a timestamp, which has been
75 replaced here with "C<...>" so that the text fits onto the lines.)
77 The server is now waiting for you to make requests of it. Try using telnet to
78 manually make a simple GET request of the server (when telnet responds with
79 "Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):
81 $ telnet localhost 3000
83 Connected to localhost.
84 Escape character is '^]'.
90 Date: Sun, 20 Mar 2005 12:31:55 GMT
93 Content-Type: text/html; charset=ISO-8859-1
95 Congratulations, My::App is on Catalyst!
96 Connection closed by foreign host.
99 More trace messages will appear in the original terminal window:
101 [...] [catalyst] [debug] ********************************
102 [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
103 [...] [catalyst] [debug] ********************************
104 [...] [catalyst] [debug] "GET" request for ""
105 [...] [catalyst] [debug] Using default action
106 [...] [catalyst] [info] Processing "!default" took 0.000033s
107 [...] [catalyst] [info] Request took 0.051399s (19.456/s)
109 The server will continue running until you interrupt it.
111 The application can also be tested from the command line using the generated
112 helper script, C<script/test.pl>.
115 =head2 Getting your application invoked
117 Catalyst applications are usually run from mod_perl, but can also be run as
118 CGI or FastCGI scripts. Running under mod_perl gives better performance, but
119 for development purposes you may want to run your application as a CGI script,
120 especially as changes to your application code take effect under CGI without
121 having to restart the web server.
123 To run from mod_perl you need to add something like this to your Apache
127 SetHandler perl-script
131 To run as a CGI script you need a wrapper script like:
136 use lib '/path/to/My/App/lib';
141 Catalyst outputs a complete HTTP response, which is not what is expected of a
142 CGI script. You need to configure the script as a so-called "Non-parsed
143 Headers" script for it to function properly. To do this in Apache just name
144 the script starting with C<nph->.
146 CHECK: is this statement still valid for Cat5?
149 =head2 Examining the generated code
151 The generated application code is quite simple and looks something like this:
156 use Catalyst qw/-Debug/;
158 our $VERSION = '0.01';
162 root => '/home/andrew/My-App/root',
167 my ( $self, $c ) = @_;
168 $c->res->output('Congratulations, My::App is on Catalyst!');
175 When the C<Catalyst> module is imported by the application code, Catalyst
176 performs the first stage of its initialization. This includes loading the
177 appropriate Engine module for the environment in which the application is
178 running, loading any plugins and ensuring that the calling module (the
179 application module) inherits from C<Catalyst> (which makes the Catalyst
180 methods C<config> and C<action> available to the application module).
182 The call to C<config> sets up configuration data for the application. The
183 C<name> and C<root> items are the minimum required, and specify the name of
184 the application and the path to the root directory where documents, images and
185 templates can be found.
187 Catalyst associates I<actions> with URLs and on receiving a request dispatches
188 to the action that matches to request URL. The call to C<action> in the code
189 above registers a default action. With just this action registered the
190 application will respond to all requests with the same message
191 "Congratulations, My::App is on Catalyst!".
193 TODO: mention private actions and attributes
196 The first call to the C<action> method triggers the second stage of Catalyst's
197 initialization process. In this phase Catalyst searches for any component
198 modules, locating and registering any actions it finds in those modules.
199 Component modules have names prefixed with the application module name,
200 followed by C<Model>, C<View> or C<Controller> (or the alternative short
201 forms: C<M>, C<V> or C<C>) followed by the component name, for example:
203 My::App::Controller::ShoppingCart
208 =head2 Extending the generated code
210 NOTE: this section is outdated by Cat5.
212 You can start extending the application by adding new actions:
216 my ( $self, $c ) = @_;
217 $c->res->output('In a new test action #1');
220 my ( $self, $c ) = @_;
221 $c->res->output('In a new test action #1');
224 my ( $self, $c ) = @_;
225 $c->res->output('Congratulations, My::App is on Catalyst!');
230 TODO: explain briefly about plugins, actions and components
232 regex actions passed subexpression matches in $c->req->snippets (array ref).
235 =head2 Hooking in to Template Toolkit
237 One of the first things you will probably want to add to your application is a
238 templating system for generating your output. Catalyst works well with
239 Template Toolkit. If you are unfamiliar with Template Toolkit then I suggest
240 you look at L<http://tt2.org>, install C<Template>, read the documentation and
241 play around with it, and have a look at the I<Badger Book> (I<Template
242 Toolkit> by Darren Chamberlain, Dave Cross and Andy Wardly, O'Reilly &
245 You can create a stub Template Toolkit view component using the create script
246 that Catalyst set up as part of the skeleton application:
248 $ script/create.pl view TT TT
250 this generates a view component named C<My::App::View::TT>, which you might
251 use by forwarding from your C<end> action:
253 # In My::App or My::App::Controller::SomeController
257 $c->forward('My::App::View::TT');
260 The generated TT view component simply subclasses the C<Catalyst::View::TT>
261 class. It looks like this (with the POD stripped out):
263 package My::App::V::TT;
266 use base 'Catalyst::View::TT';
270 C<Catalyst::View::TT> initializes a Template Toolkit object with an options
271 hash initialized with built-in default settings followed by the contents of
272 the hash C<<%{__PACKAGE__->config()}>>. You can configure TT more to your
273 needs by adding a C<new> method to the generated TT component:
277 $self->config->{PRE_PROCESS} = 'config/main';
278 $self->config->{WRAPPER} = 'site/wrapper';
279 return $self->SUPER::new(@_);
286 Andrew Ford, C<A.Ford@ford-mason.co.uk>
288 As noted above, this document is at an alpha stage. My plan for this document
295 expand this document fairly rapidly to cover topics relevant to
296 a newcomer to Catalyst in an order that can be read sequentially
308 Placeholders are indicated by the words: TODO or CHECK
310 Please send comments, corrections and suggestions for improvements to
311 A.Ford@ford-mason.co.uk
316 This program is free software, you can redistribute it and/or modify it under
317 the same terms as Perl itself.