lib/Catalyst/Manual/Tutorial.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial - Getting started with Catalyst
   4
   5 =head1 DESCRIPTION
   6
   7 This document aims to get you up and running with Catalyst.
   8
   9 NOTE: THIS DOCUMENT IS STILL VERY MUCH IN AN EARLY DRAFT STATE.  SEE THE NOTES
  10 AT THE BOTTOM OF THE DOCUMENT.
  11
  12
  13
  14 =head2 Installation
  15
  16 The first step is to install Catalyst, and the simplest way to do this is to
  17 install the Catalyst bundle from CPAN:
  18
  19     $ perl -MCPAN -e 'install Bundle::Catalyst'
  20
  21 This will retrieve Catalyst and a number of useful extensions and install them
  22 for you.
  23
  24
  25 =head2 Setting up your application
  26
  27 Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
  28 application for you:
  29
  30     $ catalyst.pl My::App
  31     created "My-App"
  32     created "My-App/script"
  33     created "My-App/lib"
  34     created "My-App/root"
  35     created "My-App/t"
  36     created "My-App/t/m"
  37     created "My-App/t/v"
  38     created "My-App/t/c"
  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"
  55
  56 This creates the directory structure shown, populated with skeleton files.
  57
  58
  59
  60 =head2 Testing out the sample application
  61
  62 You can test out your new application by running the server script that
  63 catalyst provides:
  64
  65     $ cd My-App
  66     $ script/server.pl
  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
  73
  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.)
  76
  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):
  80
  81     $ telnet localhost 3000
  82     Trying 127.0.0.1...
  83     Connected to localhost.
  84     Escape character is '^]'.
  85     GET / HTTP/1.0
  86
  87     HTTP/1.0 200
  88     Server: Catalyst/4.26
  89     Status: 200
  90     Date: Sun, 20 Mar 2005 12:31:55 GMT
  91     X-catalyst: 4.26
  92     Content-length: 40
  93     Content-Type: text/html; charset=ISO-8859-1
  94
  95     Congratulations, My::App is on Catalyst!
  96     Connection closed by foreign host.
  97     $
  98
  99 More trace messages will appear in the original terminal window:
 100
 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)
 108
 109 The server will continue running until you interrupt it.
 110
 111 The application can also be tested from the command line using the generated
 112 helper script, C<script/test.pl>.
 113
 114
 115 =head2 Getting your application invoked
 116
 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.
 122
 123 To run from mod_perl you need to add something like this to your Apache
 124 configuration file:
 125
 126     <Location /my-app>
 127         SetHandler  perl-script
 128         PerlHandler My::App
 129     </Location>
 130
 131 To run as a CGI script you need a wrapper script like:
 132
 133     #!/usr/bin/perl -w
 134
 135     use strict;
 136     use lib '/path/to/My/App/lib';
 137     use My::App;
 138
 139     My::App->run;
 140
 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->.
 145
 146 CHECK: is this statement still valid for Cat5?
 147
 148
 149 =head2 Examining the generated code
 150
 151 The generated application code is quite simple and looks something like this:
 152
 153     package My::App;
 154
 155     use strict;
 156     use Catalyst qw/-Debug/;
 157
 158     our $VERSION = '0.01';
 159
 160     My::App->config(
 161         name => 'My::App',
 162         root => '/home/andrew/My-App/root',
 163     );
 164
 165     My::App->action(
 166         '!default' => sub {
 167             my ( $self, $c ) = @_;
 168             $c->res->output('Congratulations, My::App is on Catalyst!');
 169         },
 170     );
 171
 172     1;
 173
 174
 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).
 181
 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.
 186
 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!".
 192
 193 TODO: mention private actions and attributes
 194
 195
 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:
 202
 203     My::App::Controller::ShoppingCart
 204
 205
 206
 207
 208 =head2 Extending the generated code
 209
 210 NOTE: this section is outdated by Cat5.
 211
 212 You can start extending the application by adding new actions:
 213
 214     My::App->action(
 215         'test1' => sub {
 216             my ( $self, $c ) = @_;
 217             $c->res->output('In a new test action #1');
 218         },
 219         'test1' => sub {
 220             my ( $self, $c ) = @_;
 221             $c->res->output('In a new test action #1');
 222         },
 223         '!default' => sub {
 224             my ( $self, $c ) = @_;
 225             $c->res->output('Congratulations, My::App is on Catalyst!');
 226         },
 227     );
 228
 229
 230 TODO: explain briefly about plugins, actions and components
 231
 232 regex actions passed subexpression matches in $c->req->snippets (array ref).
 233
 234
 235 =head2 Hooking in to Template Toolkit
 236
 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 &
 243 Associates, 2004).
 244
 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:
 247
 248     $ script/create.pl view TT TT
 249
 250 this generates a view component named C<My::App::View::TT>, which you might
 251 use by forwarding from your C<end> action:
 252
 253     # In My::App or My::App::Controller::SomeController
 254
 255     sub end : Private {
 256         my($self, $c) = @_;
 257         $c->forward('My::App::View::TT');
 258     }
 259
 260 The generated TT view component simply subclasses the C<Catalyst::View::TT>
 261 class.  It looks like this (with the POD stripped out):
 262
 263     package My::App::V::TT;
 264
 265     use strict;
 266     use base 'Catalyst::View::TT';
 267
 268     1;
 269
 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:
 274
 275     sub new {
 276         my $self = shift;
 277         $self->config->{PRE_PROCESS} = 'config/main';
 278         $self->config->{WRAPPER}     = 'site/wrapper';
 279         return $self->SUPER::new(@_);
 280     }
 281
 282
 283
 284 =head1 AUTHOR
 285
 286 Andrew Ford, C<A.Ford@ford-mason.co.uk>
 287
 288 As noted above, this document is at an alpha stage.  My plan for this document
 289 is as follows:
 290
 291 =over 4
 292
 293 =item 1
 294
 295 expand this document fairly rapidly to cover topics relevant to
 296 a newcomer to Catalyst in an order that can be read sequentially
 297
 298 =item 2
 299
 300 incorporate feedback
 301
 302 =item 3
 303
 304 revise the text
 305
 306 =back
 307
 308 Placeholders are indicated by the words: TODO or CHECK
 309
 310 Please send comments, corrections and suggestions for improvements to
 311 A.Ford@ford-mason.co.uk
 312
 313
 314 =head1 COPYRIGHT
 315
 316 This program is free software, you can redistribute it and/or modify it under
 317 the same terms as Perl itself.