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 | |
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 | |
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 | |
028b4e1a |
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/>. |
5e602627 |
64 | |
65 | |
66 | =head1 Detailed Table of Contents |
67 | |
3533daff |
68 | |
5e602627 |
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 | |
3533daff |
102 | HELLO WORLD |
103 | |
104 | =over 4 |
5e602627 |
105 | |
106 | =item * |
107 | |
3533daff |
108 | The Simplest Way |
5e602627 |
109 | |
110 | =item * |
111 | |
3533daff |
112 | Hello, World! Using a View and a Template |
5e602627 |
113 | |
3533daff |
114 | =back |
5e602627 |
115 | |
116 | =item * |
117 | |
3533daff |
118 | CREATE A SIMPLE CONTROLLER AND AN ACTION |
119 | |
120 | =back |
5e602627 |
121 | |
5e602627 |
122 | |
3533daff |
123 | =head2 L<Part 3: More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics> |
124 | |
125 | |
126 | =over 4 |
5e602627 |
127 | |
128 | =item * |
129 | |
3533daff |
130 | CREATE A NEW APPLICATION |
5e602627 |
131 | |
3533daff |
132 | =item * |
5e602627 |
133 | |
3533daff |
134 | EDIT THE LIST OF CATALYST PLUGINS |
5e602627 |
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 | |
3533daff |
153 | Globally Customize Every View |
5e602627 |
154 | |
155 | =item * |
156 | |
3533daff |
157 | Create a TT Template Page |
158 | |
159 | =back |
5e602627 |
160 | |
161 | =item * |
162 | |
3533daff |
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 |
5e602627 |
174 | |
175 | =back |
176 | |
3533daff |
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 |
5e602627 |
196 | |
197 | =item * |
198 | |
199 | RUN THE APPLICATION |
200 | |
201 | =item * |
202 | |
3533daff |
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 |
5e602627 |
224 | |
225 | =back |
226 | |
3533daff |
227 | |
228 | =head2 L<Part 4: Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD> |
5e602627 |
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 | |
3533daff |
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 | |
5e602627 |
310 | =back |
311 | |
312 | =back |
313 | |
3533daff |
314 | |
315 | =head2 L<Part 5: Authentication|Catalyst::Manual::Tutorial::Authentication> |
5e602627 |
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 | |
5e602627 |
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 | |
3533daff |
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 | |
5e602627 |
405 | =back |
406 | |
3533daff |
407 | =back |
408 | |
409 | |
410 | =head2 L<Part 6: Authorization|Catalyst::Manual::Tutorial::Authorization> |
5e602627 |
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 | |
3533daff |
464 | |
465 | =head2 L<Part 7: Debugging|Catalyst::Manual::Tutorial::Debugging> |
5e602627 |
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 | |
3533daff |
483 | |
484 | =head2 L<Part 8: Testing|Catalyst::Manual::Tutorial::Testing> |
5e602627 |
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 | |
5e602627 |
506 | |
3533daff |
507 | =head2 L<Part 9: Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD> |
5e602627 |
508 | |
509 | =over 4 |
510 | |
511 | =item * |
512 | |
3533daff |
513 | ADVANCED CRUD OPTIONS |
5e602627 |
514 | |
515 | =back |
516 | |
5e602627 |
517 | |
3533daff |
518 | =head2 L<Part 10: Appendices|Catalyst::Manual::Tutorial::Appendices> |
5e602627 |
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 |
3533daff |
590 | tutorial). |
591 | |
592 | =item * |
593 | |
474c24ba |
594 | Kieren Diment for his oversite of Catalyst-related documentation. |
5e602627 |
595 | |
596 | =item * |
597 | |
598 | Everyone on #catalyst and #catalyst-dev. |
599 | |
600 | =item * |
601 | |
3533daff |
602 | Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the |
603 | PostgreSQL content in the Appendix. |
604 | |
605 | =item * |
606 | |
5e602627 |
607 | People who have emailed me with corrections and suggestions on the |
608 | tutorial. As of the most recent release, this include: Florian Ragwitz, |
474c24ba |
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). |
5e602627 |
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 |
d712b826 |
624 | L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>. |
5e602627 |
625 | |
45c7830f |
626 | Copyright 2006-2008, Kennedy Clark, under Creative Commons License |
5e602627 |
627 | (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>). |