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
  10 THE NOTES AT THE BOTTOM OF THE DOCUMENT.
  11
  12 =head2 Installation
  13
  14 The first step is to install Catalyst, and the simplest way to do this
  15 is to install the Catalyst bundle from CPAN:
  16
  17     $ perl -MCPAN -e 'install Bundle::Catalyst'
  18
  19 This will retrieve Catalyst and a number of useful extensions and
  20 install them for you.
  21
  22
  23 =head2 Setting up your application
  24
  25 Catalyst includes a helper script, C<catalyst.pl>, that will set up a
  26 skeleton application for you:
  27
  28     $ catalyst.pl My::App
  29     created "My-App"
  30     created "My-App/script"
  31     created "My-App/lib"
  32     created "My-App/root"
  33     created "My-App/t"
  34     created "My-App/t/m"
  35     created "My-App/t/v"
  36     created "My-App/t/c"
  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"
  53
  54 This creates the directory structure shown, populated with skeleton
  55 files.
  56
  57
  58
  59 =head2 Testing out the sample application
  60
  61 You can test out your new application by running the server script that
  62 catalyst provides:
  63
  64     $ cd My-App
  65     $ script/server.pl
  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
  77
  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.)
  80
  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):
  85
  86     $ telnet localhost 3000
  87     Trying 127.0.0.1...
  88     Connected to localhost.
  89     Escape character is '^]'.
  90     GET / HTTP/1.0
  91
  92     HTTP/1.0 200
  93     Server: Catalyst/5.00
  94     Status: 200
  95     Date: Sun, 20 Mar 2005 12:31:55 GMT
  96     X-catalyst: 5.00
  97     Content-length: 40
  98     Content-Type: text/html; charset=ISO-8859-1
  99
 100     Congratulations, My::App is on Catalyst!
 101     Connection closed by foreign host.
 102     $
 103
 104 More trace messages will appear in the original terminal window:
 105
 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     .=--------------------------------------------------+----------=.
 112     | Action                                            | Time      |
 113     |=--------------------------------------------------+----------=|
 114     | /default                                          | 0.000026s |
 115     '=--------------------------------------------------+----------='
 116
 117 The server will continue running until you interrupt it.
 118
 119 The application can also be tested from the command line using the generated
 120 helper script, C<script/test.pl>.
 121
 122
 123 =head2 Getting your application invoked
 124
 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.
 130
 131 To run from mod_perl you need to add something like this to your Apache
 132 configuration file:
 133
 134     <Location /my-app>
 135         SetHandler  perl-script
 136         PerlHandler My::App
 137     </Location>
 138
 139 To run as a CGI script you need a wrapper script like:
 140
 141     #!/usr/bin/perl -w
 142
 143     use strict;
 144     use lib '/path/to/My/App/lib';
 145     use My::App;
 146
 147     My::App->run;
 148
 149
 150
 151 =head2 Examining the generated code
 152
 153 The generated application code is quite simple and looks something
 154 like this:
 155
 156     package My::App;
 157
 158     use strict;
 159     use Catalyst qw/-Debug/;
 160
 161     our $VERSION = '0.01';
 162
 163     My::App->config(
 164     name => 'My::App',
 165     root => '/home/andrew/My-App/root',
 166     );
 167
 168     __PACKAGE__->setup();
 169
 170     sub default : Private {
 171       my ( $self, $c ) = @_;
 172       $c->res->output('Congratulations, My::App is on Catalyst!');
 173     }
 174
 175     1;
 176
 177
 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).
 185
 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.
 190
 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!".
 196
 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>.
 202
 203
 204 The call to the C<setup> method also triggers the second stage of
 205 Catalyst's initialization process.  In this phase Catalyst searches
 206 for any component modules, locating and registering any actions it
 207 finds in those modules.
 208
 209 Component modules have names prefixed with the application module name,
 210 followed by C<Model>, C<View> or C<Controller> (or the default short
 211 forms: C<M>, C<V> or C<C>) followed by the component name, for example:
 212
 213     My::App::Controller::ShoppingCart  # long version
 214     My::App::C::ShoppingCart           # short version
 215
 216
 217
 218 =head2 Extending the generated code
 219
 220
 221 You can start extending the application by adding new actions:
 222
 223     sub test1 : Global {
 224       my ( $self, $c ) = @_;
 225       $c->res->output('In a new test action #1');
 226     }
 227     sub default : Private {
 228       my ( $self, $c ) = @_;
 229       $c->res->output('Congratulations, My::App is on Catalyst!');
 230     }
 231
 232
 233 TODO: explain briefly about plugins, actions and components
 234
 235 regex actions passed subexpression matches in $c->req->snippets
 236 (array ref).
 237
 238
 239 =head2 Hooking in to Template Toolkit
 240
 241 One of the first things you will probably want to add to your
 242 application is a templating system for generating your output.
 243 Catalyst works well with Template Toolkit.  If you are unfamiliar with
 244 Template Toolkit then I suggest you look at L<http://tt2.org>, install
 245 C<Template>, read the documentation and play around with it, and have
 246 a look at the I<Badger Book> (I<Template Toolkit> by Darren
 247 Chamberlain, Dave Cross and Andy Wardly, O'Reilly & Associates, 2004).
 248
 249 You can create a stub Template Toolkit view component using the create
 250 script that Catalyst set up as part of the skeleton application:
 251
 252     $ script/create.pl view TT TT
 253
 254 this generates a view component named C<My::App::V::TT>, which you
 255 might use by forwarding from your C<end> action:
 256
 257     # In My::App or My::App::Controller::SomeController
 258
 259     sub end : Private {
 260         my($self, $c) = @_;
 261         $c->forward('My::App::V::TT');
 262     }
 263
 264 The generated TT view component simply subclasses the
 265 C<Catalyst::View::TT> class.  It looks like this (with the POD
 266 stripped out):
 267
 268     package My::App::V::TT;
 269
 270     use strict;
 271     use base 'Catalyst::View::TT';
 272
 273     1;
 274
 275 C<Catalyst::View::TT> initializes a Template Toolkit object with an
 276 options hash initialized with built-in default settings followed by
 277 the contents of the hash C<<%{__PACKAGE__->config()}>>.  You can
 278 configure TT more to your needs by adding a C<new> method to the
 279 generated TT component:
 280
 281     sub new {
 282       my $self = shift;
 283       $self->config->{PRE_PROCESS} = 'config/main';
 284       $self->config->{WRAPPER}     = 'site/wrapper';
 285       return $self->SUPER::new(@_);
 286     }
 287
 288
 289
 290 =head1 AUTHOR
 291
 292 Andrew Ford, C<A.Ford@ford-mason.co.uk>
 293 Marcus Ramberg, C<mramberg@cpan.org>
 294
 295 As noted above, this document is at an alpha stage.  My plan for this
 296 document is as follows:
 297
 298 =over 4
 299
 300 =item 1
 301
 302 expand this document fairly rapidly to cover topics relevant to
 303 a newcomer to Catalyst in an order that can be read sequentially
 304
 305 =item 2
 306
 307 incorporate feedback
 308
 309 =item 3
 310
 311 revise the text
 312
 313 =back
 314
 315 Placeholders are indicated by the words: TODO or CHECK
 316
 317 Please send comments, corrections and suggestions for improvements to
 318 A.Ford@ford-mason.co.uk
 319
 320
 321 =head1 COPYRIGHT
 322
 323 This program is free software, you can redistribute it and/or modify
 324 it under the same terms as Perl itself.