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 AT AN ALPHA STAGE.
  10
  11 Please send comments, corrections and suggestions for improvements to
  12 A.Ford@ford-mason.co.uk
  13
  14
  15 =head2 Installation
  16
  17 The first step is to install Catalyst, and the simplest way to do this is to
  18 install the Catalyst bundle from CPAN:
  19
  20     $ perl -MCPAN -e 'install Bundle::Catalyst'
  21
  22 This will retrieve Catalyst and a number of useful extensions and install them
  23 for you.
  24
  25
  26 =head2 Setting up your application
  27
  28 Catalyst includes a helper script, C<catalyst.pl>, that will set up a skeleton
  29 application for you:
  30
  31     $ catalyst.pl My::App
  32     created "My-App"
  33     created "My-App/script"
  34     created "My-App/lib"
  35     created "My-App/root"
  36     created "My-App/t"
  37     created "My-App/t/m"
  38     created "My-App/t/v"
  39     created "My-App/t/c"
  40     created "My-App/lib/My/App"
  41     created "My-App/lib/My/App/M"
  42     created "My-App/lib/My/App/V"
  43     created "My-App/lib/My/App/C"
  44     created "My-App/lib/My/App.pm"
  45     created "My-App/Makefile.PL"
  46     created "My-App/README"
  47     created "My-App/Changes"
  48     created "My-App/t/01app.t"
  49     created "My-App/t/02podcoverage.t"
  50     created "My-App/script/cgi.pl"
  51     created "My-App/script/nph-cgi.pl"
  52     created "My-App/script/fcgi.pl"
  53     created "My-App/script/server.pl"
  54     created "My-App/script/test.pl"
  55     created "My-App/script/create.pl"
  56
  57 This creates the directory structure shown.
  58
  59
  60
  61 =head2 Testing out the sample application
  62
  63 You can test out your new application by running the server script that
  64 catalyst provides:
  65
  66     $ cd My-App
  67     $ script/server.pl
  68     [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Debug messages enabled
  69     [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Loaded engine "Catalyst::Engine::CGI"
  70     [Sun Mar 20 12:31:18 2005] [catalyst] [debug] Initialized components ""
  71     [Sun Mar 20 12:31:18 2005] [catalyst] [info] My::App powered by Catalyst 4.26
  72     [Sun Mar 20 12:31:18 2005] [catalyst] [debug] "My::App" defined "!default" as "CODE(0x83fd570)"
  73     You can connect to your server at http://localhost:3000
  74
  75 The server is now waiting for you to make requests of it.  Try using telnet to
  76 manually make a simple GET request of the server (when telnet responds with
  77 "Escape character is '^]'.", type "GET / HTTP/1.0" and hit return twice):
  78
  79     $ telnet localhost 3000
  80     Trying 127.0.0.1...
  81     Connected to localhost.
  82     Escape character is '^]'.
  83     GET / HTTP/1.0
  84
  85     HTTP/1.0 200
  86     Server: Catalyst/4.26
  87     Status: 200
  88     Date: Sun, 20 Mar 2005 12:31:55 GMT
  89     X-catalyst: 4.26
  90     Content-length: 40
  91     Content-Type: text/html; charset=ISO-8859-1
  92
  93     Congratulations, My::App is on Catalyst!
  94     Connection closed by foreign host.
  95     $
  96
  97 More trace messages will appear in the original terminal window:
  98
  99     [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
 100     [Sun Mar 20 12:31:55 2005] [catalyst] [debug] * Request 1 (0.027/s) [9818]
 101     [Sun Mar 20 12:31:55 2005] [catalyst] [debug] ********************************
 102     [Sun Mar 20 12:31:55 2005] [catalyst] [debug] "GET" request for ""
 103     [Sun Mar 20 12:31:55 2005] [catalyst] [debug] Using default action
 104     [Sun Mar 20 12:31:55 2005] [catalyst] [info] Processing "!default" took 0.000033s
 105     [Sun Mar 20 12:31:55 2005] [catalyst] [info] Request took 0.051399s (19.456/s)
 106
 107 The server will continue running until you interrupt it.
 108
 109 The application can also be tested from the command line using the generated
 110 helper script, C<script/test.pl>.
 111
 112
 113 =head2 Getting your application invoked
 114
 115 Catalyst applications are intended to be run from mod_perl, but can also be
 116 run as CGI scripts.  Running under mod_perl gives better performance, but for
 117 development purposes you may want to run your application as a CGI script,
 118 especially as each changes to your application code take effect under CGI
 119 without having to restart the web server.
 120
 121 To run from mod_perl you need to add something like this to your Apache
 122 configuration file:
 123
 124     <Location /myapp>
 125         SetHandler  perl-script
 126         PerlHandler MyApp
 127     </Location>
 128
 129 To run as a CGI script you need a wrapper script like:
 130
 131     #!/usr/bin/perl -w
 132
 133     use strict;
 134     use lib '/path/to/MyApp/lib';
 135     use MyApp;
 136
 137     MyApp->run;
 138
 139 Catalyst outputs a complete HTTP response, which is not what is expected of a
 140 CGI script.  You need to configure the script as a so-called "Non-parsed
 141 Headers" script for it to function properly.  To do this in Apache just name
 142 the script starting with C<nph->.
 143
 144
 145
 146
 147 =head2 Extending the generated code
 148
 149 The generated application code looks like this:
 150
 151     package My::App;
 152
 153     use strict;
 154     use Catalyst qw/-Debug/;
 155
 156     our $VERSION = '0.01';
 157
 158     My::App->config(
 159         name => 'My::App',
 160         root => '/home/andrew/My-App/root',
 161     );
 162
 163     My::App->action(
 164         '!default' => sub {
 165             my ( $self, $c ) = @_;
 166             $c->res->output('Congratulations, My::App is on Catalyst!');
 167         },
 168     );
 169
 170     1;
 171
 172
 173 You can start extending the application by adding new actions:
 174
 175     My::App->action(
 176         'test1' => sub {
 177             my ( $self, $c ) = @_;
 178             $c->res->output('In a new test action #1');
 179         },
 180         'test1' => sub {
 181             my ( $self, $c ) = @_;
 182             $c->res->output('In a new test action #1');
 183         },
 184         '!default' => sub {
 185             my ( $self, $c ) = @_;
 186             $c->res->output('Congratulations, My::App is on Catalyst!');
 187         },
 188     );
 189
 190
 191
 192
 193 =head1 AUTHOR
 194
 195 Andrew Ford, C<A.Ford@ford-mason.co.uk>
 196
 197 =head1 COPYRIGHT
 198
 199 This program is free software, you can redistribute it and/or modify it under
 200 the same terms as Perl itself.