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