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