Commit | Line | Data |
d442cc9f |
1 | =head1 NAME |
2 | |
3ab6187c |
3 | Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction |
d442cc9f |
4 | |
5 | |
6 | =head1 OVERVIEW |
7 | |
4b4d3884 |
8 | This is B<Chapter 1 of 10> for the Catalyst tutorial. |
d442cc9f |
9 | |
10 | L<Tutorial Overview|Catalyst::Manual::Tutorial> |
11 | |
12 | =over 4 |
13 | |
14 | =item 1 |
15 | |
3ab6187c |
16 | B<01_Introduction> |
d442cc9f |
17 | |
18 | =item 2 |
19 | |
3ab6187c |
20 | L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics> |
d442cc9f |
21 | |
22 | =item 3 |
23 | |
3ab6187c |
24 | L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics> |
d442cc9f |
25 | |
26 | =item 4 |
27 | |
3ab6187c |
28 | L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD> |
d442cc9f |
29 | |
30 | =item 5 |
31 | |
3ab6187c |
32 | L<Authentication|Catalyst::Manual::Tutorial::05_Authentication> |
d442cc9f |
33 | |
34 | =item 6 |
35 | |
3ab6187c |
36 | L<Authorization|Catalyst::Manual::Tutorial::06_Authorization> |
d442cc9f |
37 | |
38 | =item 7 |
39 | |
3ab6187c |
40 | L<Debugging|Catalyst::Manual::Tutorial::07_Debugging> |
d442cc9f |
41 | |
42 | =item 8 |
43 | |
3ab6187c |
44 | L<Testing|Catalyst::Manual::Tutorial::08_Testing> |
d442cc9f |
45 | |
46 | =item 9 |
47 | |
3ab6187c |
48 | L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD> |
1def4a20 |
49 | |
50 | =item 10 |
51 | |
3ab6187c |
52 | L<Appendices|Catalyst::Manual::Tutorial::10_Appendices> |
d442cc9f |
53 | |
54 | =back |
55 | |
1def4a20 |
56 | |
d442cc9f |
57 | =head1 DESCRIPTION |
58 | |
232da04a |
59 | This tutorial provides a multi-part introduction to the Catalyst Web |
60 | Framework. It seeks to provide a rapid overview of many of its most |
d442cc9f |
61 | commonly used features. The focus is on the real-world best practices |
62 | required in the construction of nearly all Catalyst applications. |
63 | |
64 | Although the primary target of the tutorial is users new to the Catalyst |
65 | framework, experienced users may wish to review specific sections (for |
1def4a20 |
66 | example, how to use DBIC for their model classes, how to add |
8168726b |
67 | authentication and authorization to an existing application, and/or |
68 | form management). |
d442cc9f |
69 | |
232da04a |
70 | The most recent code for the tutorial is included on the Tutorial Virtual |
71 | Machine you can download from: |
d442cc9f |
72 | |
028b4e1a |
73 | svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial |
d442cc9f |
74 | |
75b13da6 |
75 | This will download the most recent code for each chapter of the |
76 | tutorial into the CatalystTutorial directory on your machine. |
d442cc9f |
77 | |
3d9ae335 |
78 | B<These reference implementations are provided so that when you follow |
232da04a |
79 | the tutorial, you can use the code to ensure that your system is set up |
80 | correctly (which shouldn't be an issue if you use the Tutorial Virtual |
81 | Machine), :-) and that you have not inadvertently made any typographic |
82 | errors, or accidentally skipped part of the tutorial.> |
3d9ae335 |
83 | |
8168726b |
84 | B<NOTE: You can use any Perl-supported OS and environment to run |
85 | Catalyst.> It should make little or no difference to Catalyst's |
232da04a |
86 | operation, B<but this tutorial has been written using the Debian-based |
87 | Tutorial Virtual Machine that you can download and use to work through |
88 | the full tutorial step by step. B<WE STRONGLY RECOMMEND THAT YOU USE |
89 | THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues |
90 | that may crop up if you are working with a different configuration. We |
91 | have tested the Tutorial Virtual Machine to make sure all of the |
92 | examples work correctly, but it is hard to guarantee this on other |
93 | platforms and versions. |
94 | |
95 | If you would prefer to install directly from CPAN and not use the |
96 | Tutorial Virtual machine, you can download the example program and all |
97 | the necessary dependencies to your local machine by installing the |
98 | C<Task::Catalyst::Tutorial> distribution: |
d442cc9f |
99 | |
100 | cpan Task::Catalyst::Tutorial |
101 | |
102 | This will also test to make sure the dependencies are working. If you |
103 | have trouble installing these, please ask for help on the #catalyst |
104 | IRC channel, or the Catalyst mailing list. |
105 | |
3533daff |
106 | Subjects covered by the tutorial include: |
d442cc9f |
107 | |
108 | =over 4 |
109 | |
110 | =item * |
111 | |
112 | A simple application that lists and adds books. |
113 | |
114 | =item * |
115 | |
2217b252 |
116 | The use of L<DBIx::Class> (DBIC) for the model (including |
8168726b |
117 | some of the more advanced techniques you will probably want to use in |
acbd7bdd |
118 | your applications). |
d442cc9f |
119 | |
120 | =item * |
121 | |
122 | How to write CRUD (Create, Read, Update, and Delete) operations in |
123 | Catalyst. |
124 | |
125 | =item * |
126 | |
127 | Authentication ("auth"). |
128 | |
129 | =item * |
130 | |
131 | Role-based authorization ("authz"). |
132 | |
133 | =item * |
134 | |
8168726b |
135 | Attempts to provide an example showing current (5.9) Catalyst |
136 | practices. |
d442cc9f |
137 | |
138 | =item * |
139 | |
1390ef0e |
140 | The use of Template Toolkit (TT). |
d442cc9f |
141 | |
142 | =item * |
143 | |
144 | Useful techniques for troubleshooting and debugging Catalyst |
145 | applications. |
146 | |
147 | =item * |
148 | |
149 | The use of SQLite as a database (with code also provided for MySQL and |
8168726b |
150 | PostgreSQL). (Note: Because we make use of the DBIx::Class Object |
444d6b27 |
151 | Relational Mapping [ORM] layer, out our application will be database |
8168726b |
152 | agnostic and can easily be used by any of the databases supported by |
153 | DBIx::Class.) |
d442cc9f |
154 | |
155 | =item * |
156 | |
2217b252 |
157 | The use of L<HTML::FormFu> or L<HTML::FormHandler> |
0abc72ed |
158 | for automated form processing and validation. |
d442cc9f |
159 | |
160 | =back |
161 | |
162 | This tutorial makes the learning process its main priority. For |
163 | example, the level of comments in the code found here would likely be |
1def4a20 |
164 | considered excessive in a "normal project." Because of their contextual |
d442cc9f |
165 | value, this tutorial will generally favor inline comments over a |
166 | separate discussion in the text. It also deliberately tries to |
167 | demonstrate multiple approaches to various features (in general, you |
168 | should try to be as consistent as possible with your own production |
169 | code). |
170 | |
171 | Furthermore, this tutorial tries to minimize the number of controllers, |
172 | models, TT templates, and database tables. Although this does result in |
173 | things being a bit contrived at times, the concepts should be applicable |
174 | to more complex environments. More complete and complicated example |
232da04a |
175 | applications can be found at |
176 | L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and |
177 | in the C<examples> area of the Catalyst Subversion repository at |
d442cc9f |
178 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>. |
8168726b |
179 | ***Todo: update link above? |
d442cc9f |
180 | |
1390ef0e |
181 | |
2e73e2be |
182 | |
232da04a |
183 | =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE |
2e73e2be |
184 | |
2e73e2be |
185 | =over 4 |
186 | |
187 | =item 1 |
188 | |
8168726b |
189 | Download the C<debian-live-6.0.1-i386-rescue.iso> image from |
190 | L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>. |
2e73e2be |
191 | |
192 | =item 2 |
193 | |
232da04a |
194 | Uncompress the image: |
195 | |
196 | tar zxvf CatalystTutorial.tgz |
2e73e2be |
197 | |
198 | =item 3 |
199 | |
232da04a |
200 | Boot the virtual machine using a tool like VMWare Player |
201 | L<http://www.vmware.com/products/player> or VirtualBox |
202 | L<http://www.virtualbox.org/>. |
2e73e2be |
203 | |
204 | =item 4 |
205 | |
232da04a |
206 | Once you get a login prompt, enter the username B<root> and a password |
207 | for C<catalyst>. You should now be at a prompt that looks like: |
2e73e2be |
208 | |
3f97ca7b |
209 | catalyst login: root |
210 | Password: catalyst |
211 | ... |
232da04a |
212 | root@catalyst:~# |
2e73e2be |
213 | |
214 | =item 5 |
215 | |
232da04a |
216 | Type "C<ifconfig>" to get the IP address assigned to the virtual |
217 | machine. You should get output along the lines of: |
2e73e2be |
218 | |
232da04a |
219 | eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69 |
220 | inet addr:192.168.245.128 Bcast:192.168.245.255 Mask:255.255.255.0 |
2e73e2be |
221 | ... |
222 | |
232da04a |
223 | You want the IP address on the second line below the C<eth0> interface. |
224 | The image it design to automatically use a DHCP-assigned address. |
225 | |
226 | If DHCP is not working or is not available in your location, most |
227 | virtual machine "host" environments let's you select between one of |
228 | several different types of networking between the "guest" and the "host" |
229 | machine. |
230 | |
231 | 1) Bridged |
232 | 2) NAT |
233 | 3) Local host only |
2e73e2be |
234 | |
232da04a |
235 | The Tutorial Virtual Machine defaults to "Bridged" -- this should result |
236 | in the VM acting like another device on your network that will get a |
237 | different DHCP IP address than the host machine. The advantage of this |
238 | approach, is that you can easily SSH and web browse to the guest virtual |
239 | machine. |
2e73e2be |
240 | |
232da04a |
241 | In some environments, you might have better luck with "NAT" (Network |
242 | Address Translation) mode. With this configuration, the guest VM shares |
243 | the same IP address as the host machine. The downside of the approach |
244 | is that special configuration is required if you want to be able to SSH |
245 | or web browse to the guest VM (some virtual machine host environments |
246 | let you configure a "static NAT" or "port forwarding" to reach the guest |
247 | OS). |
2e73e2be |
248 | |
232da04a |
249 | "Local host only" mode let's the guest VM and the host machine talk on a |
250 | "private subnet" that other devices in your network cannot reach. |
2e73e2be |
251 | |
232da04a |
252 | Consult the documentation on your virtual machine host environment for |
253 | help configuring the options above. |
254 | |
255 | =item 6 |
256 | |
257 | B<From your main desktop machine>, open an SSH client and connect to |
258 | the IP address found in the previous step. You should get a login |
259 | prompt (accept the SSH key). Login with the same username and password: |
260 | B<root> / B<catalyst> |
2e73e2be |
261 | |
262 | =item 7 |
263 | |
232da04a |
264 | B<Using the SSH session>, change to the sample code directory for |
265 | Chapter 3 included with the Tutorial Virtual Machine and start the |
266 | Catalyst Development Server: |
2e73e2be |
267 | |
232da04a |
268 | $ cd Final/Chapter03 |
269 | $ perl scripts/myapp_server -r |
2e73e2be |
270 | |
271 | =item 8 |
272 | |
232da04a |
273 | B<From your main desktop machine>, open a web browser and go to |
274 | B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP address to your |
275 | virtual machine that you looked up in Step 5. For example, if your |
276 | virtual machine is using the IP address C<192.168.0.21>, you would put |
277 | the following URL into your web browser: |
278 | |
279 | http://192.168.0.21:3000/ |
280 | |
281 | Make sure you don't forget the B<:3000> to use port 3000 instead of the |
282 | usual port 80 that is used by HTTP by default. |
2e73e2be |
283 | |
232da04a |
284 | You should get a Catalyst Welcome Screen. If you do, feel free to jump |
285 | right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics> |
286 | of the tutorial. If you don't go get the Catalyst Welcome Screen, go |
287 | back and carefully check each of the steps above. |
288 | |
289 | =item 9 |
290 | |
291 | B<Optional:> The VI/VIM editor is already installed on the Tutorial |
292 | Virtual Machine. In order to reduce the size of the download, Emacs is |
293 | not pre-installed. Since people obviously have very strong opinions |
294 | about which editor is best, :-) Debian fortunately make it very easy to |
295 | install Emacs: |
296 | |
297 | $ aptitude install emacs |
2e73e2be |
298 | |
299 | =back |
300 | |
301 | |
d442cc9f |
302 | =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL |
303 | |
304 | This tutorial was built using the following resources. Please note that |
a6b4cff5 |
305 | you may need to make adjustments for different environments and versions |
306 | (note that trailing zeros in version numbers are not significant and may |
307 | get dropped with some techniques for viewing them; for example, Catalyst |
308 | v5.80020 might show up as 5.8002): |
d442cc9f |
309 | |
310 | =over 4 |
311 | |
312 | =item * |
313 | |
95968b61 |
314 | Debian 6 (Squeeze) |
d442cc9f |
315 | |
316 | =item * |
317 | |
232da04a |
318 | Catalyst v5.90002 |
dd88c3b6 |
319 | |
22a67212 |
320 | =item * |
dd88c3b6 |
321 | |
232da04a |
322 | Catalyst::Devel v1.34 |
d442cc9f |
323 | |
324 | =item * |
325 | |
232da04a |
326 | DBIx::Class v0.08195 |
d442cc9f |
327 | |
fce83e5f |
328 | =item * |
329 | |
232da04a |
330 | Catalyst::Model::DBIC::Schema v0.54 |
2e73e2be |
331 | |
332 | =item * |
333 | |
95968b61 |
334 | Template Toolkit v2.22 |
fce83e5f |
335 | |
2e73e2be |
336 | |
d442cc9f |
337 | =item * |
338 | |
232da04a |
339 | HTML::FormFu -- v0.09004 |
2e73e2be |
340 | |
d442cc9f |
341 | =item * |
342 | |
865d3efb |
343 | B<NOTE:> You can check the versions you have installed with the |
95968b61 |
344 | following command (note the slash before the space): |
345 | |
346 | perl -M<_mod_name_>\ 999 |
347 | |
348 | or: |
865d3efb |
349 | |
f63a9a2b |
350 | perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"' |
865d3efb |
351 | |
352 | For example: |
865d3efb |
353 | |
95968b61 |
354 | perl -MCatalyst::Devel\ 999 |
444d6b27 |
355 | |
356 | or: |
357 | |
358 | perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";' |
d442cc9f |
359 | |
360 | =item * |
361 | |
232da04a |
362 | This tutorial will show URLs in the format of C<http://localhost:3000>, |
363 | but if you are running your web browser from outside the Tutorial |
364 | Virtual Machine, you will want to substitute the IP address of your VM |
365 | for the C<localhost> in the URLs (again, you can get the IP address for |
366 | eth0 from the C<ifconfig> command). For example, if your VM has an |
367 | IP address of 192.168.245.128, you will want to use a base URL of |
368 | C<http://192.168.245.128:3000>. Note that the development server |
369 | defaults to port 3000 (you can change with with the "-p" option on the |
370 | command line. |
371 | |
372 | B<Please Note:> Depending on the web browser you are using, you might need |
8168726b |
373 | to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when |
374 | testing your application at various points (see |
375 | L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive |
376 | list of options for each browser). Also, the C<-k> keepalive option to |
377 | the development server can be necessary with some browsers (especially |
232da04a |
378 | Internet Explorer). |
0c51850e |
379 | |
d442cc9f |
380 | =back |
381 | |
1390ef0e |
382 | |
d442cc9f |
383 | =head1 DATABASES |
384 | |
385 | This tutorial will primarily focus on SQLite because of its simplicity |
386 | of installation and use; however, modifications in the script required |
a6b4cff5 |
387 | to support MySQL and PostgreSQL will be presented in the Appendix. |
d442cc9f |
388 | |
a6b4cff5 |
389 | B<Note:> One of the advantages of using tools like Catalyst and DBIC is |
390 | that applications become much more database independent. As such, you |
391 | will notice that only the C<.sql> files used to initialize the database |
392 | change between database systems: most of the code generally remains the |
d442cc9f |
393 | same. |
394 | |
1390ef0e |
395 | |
24acc5d7 |
396 | You can jump to the next chapter of the tutorial here: |
397 | L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics> |
398 | |
399 | |
d442cc9f |
400 | =head1 AUTHOR |
401 | |
402 | Kennedy Clark, C<hkclark@gmail.com> |
403 | |
8168726b |
404 | Please report any errors, issues or suggestions to the author. The |
405 | most recent version of the Catalyst Tutorial can be found at |
59884771 |
406 | L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>. |
d442cc9f |
407 | |
ec3ef4ad |
408 | Copyright 2006-2010, Kennedy Clark, under the |
409 | Creative Commons Attribution Share-Alike License Version 3.0 |
865d3efb |
410 | (L<http://creativecommons.org/licenses/by-sa/3.0/us/>). |