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