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:
30 created "My-App/script"
37 created "My-App/lib/My/App"
38 created "My-App/lib/My/App/M"
39 created "My-App/lib/My/App/V"
40 created "My-App/lib/My/App/C"
41 created "My-App/lib/My/App.pm"
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/02podcoverage.t"
47 created "My-App/script/cgi.pl"
48 created "My-App/script/nph-cgi.pl"
49 created "My-App/script/fcgi.pl"
50 created "My-App/script/server.pl"
51 created "My-App/script/test.pl"
52 created "My-App/script/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
66 [...] [catalyst] [debug] Debug messages enabled
67 [...] [catalyst] [debug] Loaded engine "Catalyst::Engine::HTTP"
68 [...] [catalyst] [debug] Loaded private actions
69 .=----------------------+----------------------+---------------=.
70 | Private | Class | Code |
71 |=----------------------+----------------------+---------------=|
72 | /default | MyApp | CODE(0x86f08ac)|
73 '=----------------------+----------------------+---------------='
74 "My::App" defined "!default" as "CODE(0x83fd570)"
75 [...] [catalyst] [info] My::App powered by Catalyst 5.00
76 You can connect to your server at http://localhost:3000
78 (Note that each line logged by Catalyst includes a timestamp, which has
79 been replaced here with "C<...>" so that the text fits onto the lines.)
81 The server is now waiting for you to make requests of it. Try using
82 telnet to manually make a simple GET request of the server (when
83 telnet responds with "Escape character is '^]'.", type "GET / HTTP/1.0"
84 and hit return twice):
86 $ telnet localhost 3000
88 Connected to localhost.
89 Escape character is '^]'.
95 Date: Sun, 20 Mar 2005 12:31:55 GMT
98 Content-Type: text/html; charset=ISO-8859-1
100 Congratulations, My::App is on Catalyst!
101 Connection closed by foreign host.
104 More trace messages will appear in the original terminal window:
106 [...] [catalyst] [debug] ********************************
107 [...] [catalyst] [debug] * Request 1 (0.027/s) [9818]
108 [...] [catalyst] [debug] ********************************
109 [...] [catalyst] [debug] "GET" request for "" from localhost
110 [...] [catalyst] [info] Request took 0.051399s (19.456/s)
111 .=--------------------------------------------------+----------=.
113 |=--------------------------------------------------+----------=|
114 | /default | 0.000026s |
115 '=--------------------------------------------------+----------='
117 The server will continue running until you interrupt it.
119 The application can also be tested from the command line using the generated
120 helper script, C<script/test.pl>.
123 =head2 Getting your application invoked
125 Catalyst applications are usually run from mod_perl, but can also be
126 run as CGI or FastCGI scripts. Running under mod_perl gives better
127 performance, but for development purposes you may want to run your
128 application as a CGI script, especially as changes to your application
129 code take effect under CGI without having to restart the web server.
131 To run from mod_perl you need to add something like this to your Apache
135 SetHandler perl-script
139 To run as a CGI script you need a wrapper script like:
144 use lib '/path/to/My/App/lib';
151 =head2 Examining the generated code
153 The generated application code is quite simple and looks something
159 use Catalyst qw/-Debug/;
161 our $VERSION = '0.01';
165 root => '/home/andrew/My-App/root',
168 __PACKAGE__->setup();
170 sub default : Private {
171 my ( $self, $c ) = @_;
172 $c->res->output('Congratulations, My::App is on Catalyst!');
178 When the C<Catalyst> module is imported by the application code,
179 Catalyst performs the first stage of its initialization. This includes
180 loading the appropriate Engine module for the environment in which the
181 application is running, loading any plugins and ensuring that the
182 calling module (the application module) inherits from C<Catalyst>
183 (which makes the Catalyst methods C<config> and C<setup> available to
184 the application module).
186 The call to C<config> sets up configuration data for the application.
187 The C<name> and C<root> items are the minimum required, and specify
188 the name of the application and the path to the root directory where
189 documents, images, and templates can be found.
191 Catalyst associates I<actions> with URLs and on receiving a request
192 dispatches to the action that matches to request URL. The call to
193 C<setup> in the code above registers a default action. With just
194 this action registered the application will respond to all requests
195 with the same message "Congratulations, My::App is on Catalyst!".
197 As you see, the default action is defined as a Private action.
198 Most private actions are not directly available from a web url. This
199 also includes the built-in actions, 'default','begin','end', and
200 'auto', although they will be called as part of some chains.
201 The rest can only be reached by using C<forward>.
203 The call to the C<setup> method also triggers the second stage of
204 Catalyst's initialization process. In this phase Catalyst searches
205 for any component modules, locating and registering any actions it
206 finds in those modules.
208 Component modules have names prefixed with the application module name,
209 followed by C<Model>, C<View> or C<Controller> (or the default short
210 forms: C<M>, C<V> or C<C>) followed by the component name, for example:
212 My::App::Controller::ShoppingCart # long version
213 My::App::C::ShoppingCart # short version
217 =head2 Extending the generated code
220 You can start extending the application by adding new actions:
223 my ( $self, $c ) = @_;
224 $c->res->output('In a new test action #1');
226 sub default : Private {
227 my ( $self, $c ) = @_;
228 $c->res->output('Congratulations, My::App is on Catalyst!');
232 TODO: explain briefly about plugins, actions, and components
234 regex actions passed subexpression matches in $c->req->snippets
238 =head2 Hooking in to Template Toolkit
240 One of the first things you will probably want to add to your
241 application is a templating system for generating your output.
242 Catalyst works well with Template Toolkit. If you are unfamiliar with
243 Template Toolkit then I suggest you look at L<http://tt2.org>, install
244 C<Template>, read the documentation and play around with it, and have
245 a look at the I<Badger Book> (I<Template Toolkit> by Darren
246 Chamberlain, Dave Cross, and Andy Wardley, O'Reilly & Associates, 2004).
248 You can create a stub Template Toolkit view component using the create
249 script that Catalyst set up as part of the skeleton application:
251 $ script/create.pl view TT TT
253 this generates a view component named C<My::App::V::TT>, which you
254 might use by forwarding from your C<end> action:
256 # In My::App or My::App::Controller::SomeController
260 $c->forward('My::App::V::TT');
263 The generated TT view component simply subclasses the
264 C<Catalyst::View::TT> class. It looks like this (with the POD
267 package My::App::V::TT;
270 use base 'Catalyst::View::TT';
274 C<Catalyst::View::TT> initializes a Template Toolkit object with an
275 options hash initialized with built-in default settings followed by
276 the contents of the hash C<<%{__PACKAGE__->config()}>>. You can
277 configure TT more to your needs by adding a C<new> method to the
278 generated TT component:
282 $self->config->{PRE_PROCESS} = 'config/main';
283 $self->config->{WRAPPER} = 'site/wrapper';
284 return $self->SUPER::new(@_);
291 Andrew Ford, C<A.Ford@ford-mason.co.uk>
292 Marcus Ramberg, C<mramberg@cpan.org>
294 As noted above, this document is at an alpha stage. My plan for this
295 document is as follows:
301 Expand this document fairly rapidly to cover topics relevant to
302 a newcomer to Catalyst, in an order that can be read sequentially
314 Placeholders are indicated by the words: TODO or CHECK
316 Please send comments, corrections and suggestions for improvements to
317 A.Ford@ford-mason.co.uk
322 This program is free software, you can redistribute it and/or modify
323 it under the same terms as Perl itself.