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