Commit | Line | Data |
83cea649 |
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" |
501b6190 |
50 | created "My-App/script/cgi.pl" |
51 | created "My-App/script/nph-cgi.pl" |
52 | created "My-App/script/fcgi.pl" |
83cea649 |
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. |