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