7793f03536e97ed7a70f012ab32c14492a7b4df5
[catagits/Catalyst-Manual.git] / lib / Catalyst / Manual / Tutorial.pod
1 =head1 NAME
2
3 Catalyst::Manual::Tutorial - Catalyst Tutorial: Overview
4
5 =head1 DESCRIPTION
6
7 The Catalyst framework is a flexible and comprehensive environment for
8 quickly building high-functionality web applications.  This tutorial is
9 designed to provide a rapid introduction to its basics and its most
10 commonly used features while focusing on real-world best practices.
11
12 The tutorial is divided into the following sections:
13
14 B<NOTE:> CLICK THESE LINKS TO JUMP TO CHAPTERS (the index links above
15 only navigate inside this page).
16
17 =over 4
18
19 =item 1
20
21 L<Introduction|Catalyst::Manual::Tutorial::Intro>
22
23 =item 2
24
25 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
26
27 =item 3
28
29 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
30
31 =item 4
32
33 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
34
35 =item 5
36
37 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
38
39 =item 6
40
41 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
42
43 =item 7
44
45 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
46
47 =item 8
48
49 L<Testing|Catalyst::Manual::Tutorial::Testing>
50
51 =item 9
52
53 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
54
55 =item 10
56
57 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
58
59 =back
60
61 Tarballs for the final code for each part of the tutorial is available 
62 at
63 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/>.
64
65
66 =head1 Detailed Table of Contents
67
68
69 =head2 L<Part 1: Introduction|Catalyst::Manual::Tutorial::Intro>
70
71 =over 4
72
73 =item *
74
75 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
76
77 =item *
78
79 CATALYST INSTALLATION
80
81 =item *
82
83 DATABASES
84
85 =item *
86
87 WHERE TO GET WORKING CODE
88
89 =back
90
91
92 =head2 L<Part 2: Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
93
94 =over 4
95
96 =item *
97
98 CREATE A CATALYST PROJECT
99
100 =item *
101
102 HELLO WORLD
103
104 =over 4
105
106 =item *
107
108 The Simplest Way
109
110 =item *
111
112 Hello, World! Using a View and a Template
113
114 =back
115
116 =item *
117
118 CREATE A SIMPLE CONTROLLER AND AN ACTION
119
120 =back
121
122
123 =head2 L<Part 3: More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
124
125
126 =over 4
127
128 =item *
129
130 CREATE A NEW APPLICATION
131
132 =item *
133
134 EDIT THE LIST OF CATALYST PLUGINS
135
136 =item *
137
138 CREATE A CATALYST CONTROLLER
139
140 =item *
141
142 CATALYST VIEWS
143
144
145 =over 4
146
147 =item *
148
149 Create a Catalyst View Using TTSite
150
151 =item *
152
153 Globally Customize Every View
154
155 =item *
156
157 Create a TT Template Page
158
159 =back
160
161 =item *
162
163 CREATE A SQLITE DATABASE
164
165 =item *
166
167 DATABASE ACCESS WITH DBIx::Class
168
169 =over 4
170
171 =item *
172
173 Create a Dynamic DBIC Model
174
175 =back
176
177 =item *
178
179 RUN THE APPLICATION
180
181 =item *
182
183 A STATIC DATABASE MODEL WITH DBIx::Class
184
185 =over 4
186
187 =item *
188
189 Create Static DBIC Schema Files
190
191 =item *
192
193 Updating the Generated DBIC Schema Files
194
195 =back
196
197 =item *
198
199 RUN THE APPLICATION
200
201 =item *
202
203 RUNNING THE APPLICATION FROM THE COMMAND LINE
204
205 =item *
206
207 UPDATING THE VIEW
208
209 =over 4
210
211 =item *
212
213 Using RenderView for the Default View
214
215 =item *
216
217 Using The Default Template Name
218
219 =item *
220
221 Return To A Manually-Specified Template
222
223 =back
224
225 =back
226
227
228 =head2 L<Part 4: Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
229
230 =over 4
231
232 =item *
233
234 FORMLESS SUBMISSION
235
236 =over 4
237
238 =item *
239
240 Include a Create Action in the Books Controller
241
242 =item *
243
244 Include a Template for the url_create Action:
245
246 =item *
247
248 Try the url_create Feature
249
250 =back
251
252 =item *
253
254 MANUALLY BUILDING A CREATE FORM
255
256 =over 4
257
258 =item *
259
260 Add a Method to Display the Form
261
262 =item *
263
264 Add a Template for the Form
265
266 =item *
267
268 Add Method to Process Form Values and Update Database
269
270 =item *
271
272 Test Out the Form
273
274 =back
275
276 =item *
277
278 A SIMPLE DELETE FEATURE
279
280 =over 4
281
282 =item *
283
284 Include a Delete Link in the List
285
286 =item *
287
288 Add a Delete Action to the Controller
289
290 =item *
291
292 Try the Delete Feature
293
294 =item *
295
296 Fixing a Dangerous URL
297
298 =item *
299
300 Try the Delete and Redirect Logic
301
302 =item *
303
304 Using uri_for to Pass Query Parameters
305
306 =item *
307
308 Try the Delete and Redirect With Query Param Logic
309
310 =back
311
312 =back
313
314
315 =head2 L<Part 5: Authentication|Catalyst::Manual::Tutorial::Authentication>
316
317 =over 4
318
319 =item *
320
321 BASIC AUTHENTICATION
322
323 =over 4
324
325 =item *
326
327 Add Users and Roles to the Database
328
329 =item *
330
331 Add User and Role Information to DBIC Schema
332
333 =item *
334
335 Sanity-Check Reload of Development Server
336
337 =item *
338
339 Include Authentication and Session Plugins
340
341 =item *
342
343 Configure Authentication
344
345 =item *
346
347 Add Login and Logout Controllers
348
349 =item *
350
351 Add a Login Form TT Template Page
352
353 =item *
354
355 Add Valid User Check
356
357 =item *
358
359 Displaying Content Only to Authenticated Users
360
361 =item *
362
363 Try Out Authentication
364
365 =back
366
367 =item *
368
369 USING PASSWORD HASHES
370
371 =over 4
372
373 =item *
374
375 Get a SHA-1 Hash for the Password
376
377 =item *
378
379 Switch to SHA-1 Password Hashes in the Database
380
381 =item *
382
383 Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
384
385 =item *
386
387 Try Out the Hashed Passwords
388
389 =back
390
391 =item *
392
393 USING THE SESSION FOR FLASH
394
395 =over 4
396
397 =item *
398
399 Try Out Flash
400
401 =item *
402
403 Switch To Flash-To-Stash
404
405 =back
406
407 =back
408
409
410 =head2 L<Part 6: Authorization|Catalyst::Manual::Tutorial::Authorization>
411
412 =over 4
413
414 =item *
415
416 BASIC AUTHORIZATION
417
418 =over 4
419
420 =item *
421
422 Update Plugins to Include Support for Authorization
423
424 =item *
425
426 Add Config Information for Authorization
427
428 =item *
429
430 Add Role-Specific Logic to the ``Book List'' Template
431
432 =item *
433
434 Limit Books::add to admin Users
435
436 =item *
437
438 Try Out Authentication And Authorization
439
440 =back
441
442 =item *
443
444 ENABLE ACL-BASED AUTHORIZATION
445
446 =over 4
447
448 =item *
449
450 Add the Catalyst::Plugin::Authorization::ACL Plugin
451
452 =item *
453
454 Add ACL Rules to the Application Class
455
456 =item *
457
458 Add a Method to Handle Access Violations
459
460 =back
461
462 =back
463
464
465 =head2 L<Part 7: Debugging|Catalyst::Manual::Tutorial::Debugging>
466
467 =over 4
468
469 =item *
470
471 LOG STATEMENTS
472
473 =item *
474
475 RUNNING CATALYST UNDER THE PERL DEBUGGER
476
477 =item *
478
479 DEBUGGING MODULES FROM CPAN
480
481 =back
482
483
484 =head2 L<Part 8: Testing|Catalyst::Manual::Tutorial::Testing>
485
486 =over 4
487
488 =item *
489
490 RUNNING THE "CANNED" CATALYST TESTS
491
492 =item *
493
494 RUNNING A SINGLE TEST
495
496 =item *
497
498 ADDING YOUR OWN TEST SCRIPT
499
500 =item *
501
502 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
503
504 =back
505
506
507 =head2 L<Part 9: Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
508
509 =over 4
510
511 =item *
512
513 ADVANCED CRUD OPTIONS
514
515 =back
516
517
518 =head2 L<Part 10: Appendices|Catalyst::Manual::Tutorial::Appendices>
519
520 =over 4
521
522 =item *
523
524 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
525
526 =over 4
527
528 =item *
529
530 "Un-indenting" with Vi/Vim
531
532 =item *
533
534 "Un-indenting" with Emacs
535
536 =back
537
538 =item *
539
540 APPENDIX 2: USING MYSQL AND POSTGRESQL
541
542 =over 4
543
544 =item *
545
546 MySQL
547
548 =item *
549
550 PostgreSQL
551
552 =back
553
554 =item *
555
556 APPENDIX 3: IMPROVED HASHING SCRIPT
557
558 =back
559
560
561 =head1 THANKS
562
563 This tutorial would not have been possible without the input of many 
564 different people in the Catalyst community.  In particular, the 
565 primary author would like to thank:
566
567 =over 4
568
569 =item *
570
571 Sebastian Riedel for founding the Catalyst project.
572
573 =item *
574
575 The members of the Catalyst Core Team for their tireless efforts to
576 advance the Catalyst project.  Although all of the Core Team members
577 have played a key role in this tutorial, it would have never been
578 possible without the critical contributions of: Matt Trout, for his
579 unfathomable knowledge of all things Perl and Catalyst (and his
580 willingness to answer lots of my questions); Jesse Sheidlower, for his
581 incredible skill with the written word and dedication to improving the
582 Catalyst documentation; and Yuval Kogman, for his work on the Catalyst
583 "Auth & Authz" plugins (the original focus of the tutorial) and other
584 key Catalyst modules.
585
586 =item *
587
588 Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
589 and Jess Robinson (including their work on the original Catalyst
590 tutorial).  
591
592 =item *
593
594 Kieren Diment for his oversite of Catalyst-related documentation.
595
596 =item *
597
598 Everyone on #catalyst and #catalyst-dev.
599
600 =item *
601
602 Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the
603 PostgreSQL content in the Appendix.
604
605 =item *
606
607 People who have emailed me with corrections and suggestions on the 
608 tutorial.  As of the most recent release, this include: Florian Ragwitz, 
609 Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno,  Bryan 
610 Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, Jeremy 
611 Jones, David Kurtz, Ingo Wichmann, and Shlomi Fish.  Also, thanks to 
612 Devin Austin for coming up with an initial version of a non-TTSite 
613 wrapper page.  I'm sure I am missing some names here... apologies for 
614 that (please let me know if you name should be here).
615
616 =back
617
618 =head1 AUTHOR
619
620 Kennedy Clark, C<hkclark@gmail.com>
621
622 Please report any errors, issues or suggestions to the author.  The
623 most recent version of the Catalyst Tutorial can be found at
624 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
625
626 Copyright 2006-2008, Kennedy Clark, under Creative Commons License
627 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).