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 | ||
4d583dd8 | 98 | =item * |
99 | ||
100 | Create a DBIC Schema File | |
101 | ||
102 | =item * | |
103 | ||
104 | Create the DBIC ``Result Source'' Files | |
105 | ||
106 | =item * | |
107 | ||
653f4595 | 108 | Use Catalyst::Model::DBIC::Schema to Load the Model Class |
4d583dd8 | 109 | |
0d201f15 | 110 | =item * |
4d583dd8 | 111 | |
112 | CREATE A CATALYST CONTROLLER | |
113 | ||
114 | =item * | |
115 | ||
116 | CATALYST VIEWS | |
117 | ||
118 | =over 4 | |
119 | ||
120 | =item * | |
121 | ||
653f4595 | 122 | Create a Catalyst View Using TTSite |
4d583dd8 | 123 | |
124 | =item * | |
125 | ||
126 | Globally Customize Every View | |
127 | ||
128 | =item * | |
129 | ||
130 | Create a TT Template Page | |
131 | ||
132 | =back | |
133 | ||
134 | =item * | |
135 | ||
136 | RUN THE APPLICATION | |
137 | ||
138 | =back | |
139 | ||
4d583dd8 | 140 | =head2 Part 3: Basic CRUD |
141 | ||
142 | =over 4 | |
143 | ||
144 | =item * | |
145 | ||
146 | FORMLESS SUBMISSION | |
147 | ||
148 | =over 4 | |
149 | ||
150 | =item * | |
151 | ||
152 | Include a Create Action in the Books Controller | |
153 | ||
154 | =item * | |
155 | ||
156 | Include a Template for the url_create Action: | |
157 | ||
158 | =item * | |
159 | ||
160 | Try the url_create Feature | |
161 | ||
162 | =back | |
163 | ||
164 | =item * | |
165 | ||
166 | MANUALLY BUILDING A CREATE FORM | |
167 | ||
168 | =over 4 | |
169 | ||
170 | =item * | |
171 | ||
653f4595 | 172 | Add a Method to Display the Form |
4d583dd8 | 173 | |
174 | =item * | |
175 | ||
176 | Add a Template for the Form | |
177 | ||
178 | =item * | |
179 | ||
180 | Add Method to Process Form Values and Update Database | |
181 | ||
182 | =item * | |
183 | ||
653f4595 | 184 | Test Out the Form |
4d583dd8 | 185 | |
186 | =back | |
187 | ||
188 | =item * | |
189 | ||
190 | A SIMPLE DELETE FEATURE | |
191 | ||
192 | =over 4 | |
193 | ||
194 | =item * | |
195 | ||
196 | Include a Delete Link in the List | |
197 | ||
198 | =item * | |
199 | ||
200 | Add a Delete Action to the Controller | |
201 | ||
202 | =item * | |
203 | ||
204 | Try the Delete Feature | |
205 | ||
206 | =back | |
207 | ||
208 | =back | |
209 | ||
4d583dd8 | 210 | =head2 Part 4: Authentication |
211 | ||
212 | =over 4 | |
213 | ||
214 | =item * | |
215 | ||
216 | BASIC AUTHENTICATION | |
217 | ||
218 | =over 4 | |
219 | ||
220 | =item * | |
221 | ||
222 | Add Users and Roles to the Database | |
223 | ||
224 | =item * | |
225 | ||
64ccd8a8 | 226 | Add User and Role Information to DBIC Schema |
4d583dd8 | 227 | |
228 | =item * | |
229 | ||
230 | Create New ``Result Source Objects'' | |
231 | ||
232 | =item * | |
233 | ||
234 | Sanity-Check Reload of Development Server | |
235 | ||
236 | =item * | |
237 | ||
238 | Include Authentication and Session Plugins | |
239 | ||
240 | =item * | |
241 | ||
242 | Configure Authentication | |
243 | ||
244 | =item * | |
245 | ||
246 | Add Login and Logout Controllers | |
247 | ||
248 | =item * | |
249 | ||
250 | Add a Login Form TT Template Page | |
251 | ||
252 | =item * | |
253 | ||
254 | Add Valid User Check | |
255 | ||
256 | =item * | |
257 | ||
258 | Displaying Content Only to Authenticated Users | |
259 | ||
260 | =item * | |
261 | ||
262 | Try Out Authentication | |
263 | ||
264 | =back | |
265 | ||
266 | =item * | |
267 | ||
268 | USING PASSWORD HASHES | |
269 | ||
270 | =over 4 | |
271 | ||
272 | =item * | |
273 | ||
274 | Get a SHA-1 Hash for the Password | |
275 | ||
276 | =item * | |
277 | ||
278 | Switch to SHA-1 Password Hashes in the Database | |
279 | ||
280 | =item * | |
281 | ||
282 | Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC | |
283 | ||
284 | =item * | |
285 | ||
286 | Try Out the Hashed Passwords | |
287 | ||
288 | =back | |
289 | ||
290 | =back | |
291 | ||
4d583dd8 | 292 | =head2 Part 5: Authorization |
293 | ||
294 | =over 4 | |
295 | ||
296 | =item * | |
83cea649 | 297 | |
4d583dd8 | 298 | BASIC AUTHORIZATION |
83cea649 | 299 | |
4d583dd8 | 300 | =over 4 |
83cea649 | 301 | |
4d583dd8 | 302 | =item * |
83cea649 | 303 | |
653f4595 | 304 | Update Plugins to Include Support for Authorization |
83cea649 | 305 | |
4d583dd8 | 306 | =item * |
83cea649 | 307 | |
4d583dd8 | 308 | Add Config Information for Authorization |
83cea649 | 309 | |
4d583dd8 | 310 | =item * |
83cea649 | 311 | |
4d583dd8 | 312 | Add Role-Specific Logic to the ``Book List'' Template |
b248fa4a | 313 | |
4d583dd8 | 314 | =item * |
83cea649 | 315 | |
4d583dd8 | 316 | Limit Books::add to admin Users |
83cea649 | 317 | |
4d583dd8 | 318 | =item * |
83cea649 | 319 | |
4d583dd8 | 320 | Try Out Authentication And Authorization |
83cea649 | 321 | |
4d583dd8 | 322 | =back |
b33ed88c | 323 | |
4d583dd8 | 324 | =item * |
b248fa4a | 325 | |
4d583dd8 | 326 | ENABLE ACL-BASED AUTHORIZATION |
b33ed88c | 327 | |
4d583dd8 | 328 | =over 4 |
b460ad78 | 329 | |
4d583dd8 | 330 | =item * |
83cea649 | 331 | |
4d583dd8 | 332 | Add the Catalyst::Plugin::Authorization::ACL Plugin |
b248fa4a | 333 | |
4d583dd8 | 334 | =item * |
83cea649 | 335 | |
4d583dd8 | 336 | Add ACL Rules to the Application Class |
83cea649 | 337 | |
4d583dd8 | 338 | =item * |
387e4c50 | 339 | |
4d583dd8 | 340 | Add a Method to Handle Access Violations |
83cea649 | 341 | |
4d583dd8 | 342 | =back |
83cea649 | 343 | |
4d583dd8 | 344 | =back |
83cea649 | 345 | |
4d583dd8 | 346 | =head2 Part 6: Debugging |
83cea649 | 347 | |
4d583dd8 | 348 | =over 4 |
83cea649 | 349 | |
4d583dd8 | 350 | =item * |
83cea649 | 351 | |
4d583dd8 | 352 | LOG STATEMENTS |
83cea649 | 353 | |
4d583dd8 | 354 | =item * |
83cea649 | 355 | |
4d583dd8 | 356 | RUNNING CATALYST UNDER THE PERL DEBUGGER |
83cea649 | 357 | |
4d583dd8 | 358 | =back |
587d5860 | 359 | |
4d583dd8 | 360 | =head2 Part 7: Testing |
83cea649 | 361 | |
4d583dd8 | 362 | =over 4 |
83cea649 | 363 | |
4d583dd8 | 364 | =item * |
8d47005f | 365 | |
4d583dd8 | 366 | RUNNING THE "CANNED" CATALYST TESTS |
8d47005f | 367 | |
4d583dd8 | 368 | =item * |
8d47005f | 369 | |
4d583dd8 | 370 | RUNNING A SINGLE TEST |
c425bfeb | 371 | |
4d583dd8 | 372 | =item * |
c425bfeb | 373 | |
4d583dd8 | 374 | ADDING YOUR OWN TEST SCRIPT |
8d47005f | 375 | |
4d583dd8 | 376 | =item * |
8d47005f | 377 | |
4d583dd8 | 378 | SUPPORTING BOTH PRODUCTION AND TEST DATABASES |
de6fb80a | 379 | |
4d583dd8 | 380 | =back |
8d47005f | 381 | |
4d583dd8 | 382 | =head2 Part 8: Advanced CRUD |
8d47005f | 383 | |
4d583dd8 | 384 | =over 4 |
8d47005f | 385 | |
4d583dd8 | 386 | =item * |
8d47005f | 387 | |
4d583dd8 | 388 | HTML::WIDGET FORM CREATION |
de6fb80a | 389 | |
4d583dd8 | 390 | =over 4 |
8d47005f | 391 | |
4d583dd8 | 392 | =item * |
8d47005f | 393 | |
4d583dd8 | 394 | Add the HTML::Widget Plugin |
8d47005f | 395 | |
4d583dd8 | 396 | =item * |
8d47005f | 397 | |
4d583dd8 | 398 | Add a Form Creation Helper Method |
8d47005f | 399 | |
4d583dd8 | 400 | =item * |
8d47005f | 401 | |
4d583dd8 | 402 | Add Actions to Display and Save the Form |
8d47005f | 403 | |
4d583dd8 | 404 | =item * |
b460ad78 | 405 | |
4d583dd8 | 406 | Update the CSS |
b460ad78 | 407 | |
4d583dd8 | 408 | =item * |
b460ad78 | 409 | |
4d583dd8 | 410 | Create a Template Page To Display The Form |
b460ad78 | 411 | |
4d583dd8 | 412 | =item * |
b460ad78 | 413 | |
4d583dd8 | 414 | Add Links for Create and Update via HTML::Widget |
b460ad78 | 415 | |
4d583dd8 | 416 | =item * |
b460ad78 | 417 | |
4d583dd8 | 418 | Test The <HTML::Widget> Create Form |
b460ad78 | 419 | |
4d583dd8 | 420 | =back |
b460ad78 | 421 | |
4d583dd8 | 422 | =item * |
b460ad78 | 423 | |
4d583dd8 | 424 | HTML::WIDGET VALIDATION AND FILTERING |
b460ad78 | 425 | |
4d583dd8 | 426 | =over 4 |
b460ad78 | 427 | |
4d583dd8 | 428 | =item * |
83cea649 | 429 | |
4d583dd8 | 430 | Add Constraints and Filters to the Widget Creation Method |
8d47005f | 431 | |
4d583dd8 | 432 | =item * |
8d47005f | 433 | |
4d583dd8 | 434 | Rebuild the Form Submission Method to Include Validation |
8d47005f | 435 | |
4d583dd8 | 436 | =item * |
8d47005f | 437 | |
4d583dd8 | 438 | Try Out the Form |
8d47005f | 439 | |
4d583dd8 | 440 | =back |
8d47005f | 441 | |
4d583dd8 | 442 | =item * |
8d47005f | 443 | |
4d583dd8 | 444 | Enable DBIx::Class::HTMLWidget Support |
8d47005f | 445 | |
4d583dd8 | 446 | =over 4 |
8d47005f | 447 | |
4d583dd8 | 448 | =item * |
83cea649 | 449 | |
4d583dd8 | 450 | Add DBIx::Class::HTMLWidget to DBIC Model |
b460ad78 | 451 | |
4d583dd8 | 452 | =item * |
b460ad78 | 453 | |
4d583dd8 | 454 | Use populate_from_widget in hw_create_do |
b460ad78 | 455 | |
4d583dd8 | 456 | =back |
b460ad78 | 457 | |
4d583dd8 | 458 | =back |
b460ad78 | 459 | |
4d583dd8 | 460 | =head2 Part 9: Appendices |
b460ad78 | 461 | |
4d583dd8 | 462 | =over 4 |
b460ad78 | 463 | |
4d583dd8 | 464 | =item * |
8d47005f | 465 | |
4d583dd8 | 466 | APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES |
8d47005f | 467 | |
4d583dd8 | 468 | =over 4 |
8d47005f | 469 | |
4d583dd8 | 470 | =item * |
8d47005f | 471 | |
4d583dd8 | 472 | "Un-indenting" with Vi/Vim |
8d47005f | 473 | |
4d583dd8 | 474 | =item * |
8d47005f | 475 | |
4d583dd8 | 476 | "Un-indenting" with Emacs |
8d47005f | 477 | |
4d583dd8 | 478 | =back |
8d47005f | 479 | |
4d583dd8 | 480 | =item * |
8d47005f | 481 | |
4d583dd8 | 482 | APPENDIX 2: USING MYSQL AND POSTGRESQL |
8d47005f | 483 | |
4d583dd8 | 484 | =over 4 |
8d47005f | 485 | |
4d583dd8 | 486 | =item * |
b460ad78 | 487 | |
4d583dd8 | 488 | MySQL |
8d47005f | 489 | |
4d583dd8 | 490 | =item * |
8d47005f | 491 | |
4d583dd8 | 492 | PostgreSQL |
8d47005f | 493 | |
4d583dd8 | 494 | =back |
b460ad78 | 495 | |
4d583dd8 | 496 | =back |
83cea649 | 497 |