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" |
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. |