lib/Catalyst/Manual/Tutorial.pod

   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
  19 =item *
  20
  21 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  22
  23 =item *
  24
  25 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  26
  27 =item *
  28
  29 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  30
  31 =item *
  32
  33 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  34
  35 =item *
  36
  37 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  38
  39 =item *
  40
  41 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  42
  43 =item *
  44
  45 L<Testing|Catalyst::Manual::Tutorial::Testing>
  46
  47 =item *
  48
  49 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  50
  51 =item *
  52
  53 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  54
  55 =back
  56
  57 A tarball of the final application is available at
  58 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz>.
  59
  60
  61 =head1 Detailed Table of Contents
  62
  63 =head2 L<Part 1: Introduction|Catalyst::Manual::Tutorial::Intro>
  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
  86 =head2 L<Part 2: Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  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
 106
 107 =over 4
 108
 109 =item *
 110
 111 Create a DBIC Schema File
 112
 113 =item *
 114
 115 Create the DBIC ``Result Source'' Files
 116
 117 =item *
 118
 119 Use Catalyst::Model::DBIC::Schema to Load the Model Class
 120
 121 =back
 122
 123
 124 =item *
 125
 126 CREATE A CATALYST CONTROLLER
 127
 128 =item *
 129
 130 CATALYST VIEWS
 131
 132
 133 =over 4
 134
 135 =item *
 136
 137 Create a Catalyst View Using TTSite
 138
 139 =item *
 140
 141 Using RenderView for the Default View
 142
 143 =item *
 144
 145 Globally Customize Every View
 146
 147 =item *
 148
 149 Create a TT Template Page
 150
 151 =back
 152
 153
 154 =item *
 155
 156 RUN THE APPLICATION
 157
 158 =item *
 159
 160 USING THE DEFAULT TEMPLATE NAME
 161
 162 =back
 163
 164 =head2 L<Part 3: Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
 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
 196 Add a Method to Display the Form
 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
 208 Test Out the Form
 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
 234 =head2 L<Part 4: Authentication|Catalyst::Manual::Tutorial::Authentication>
 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
 250 Add User and Role Information to DBIC Schema
 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
 316 =head2 L<Part 5: Authorization|Catalyst::Manual::Tutorial::Authorization>
 317
 318 =over 4
 319
 320 =item *
 321
 322 BASIC AUTHORIZATION
 323
 324 =over 4
 325
 326 =item *
 327
 328 Update Plugins to Include Support for Authorization
 329
 330 =item *
 331
 332 Add Config Information for Authorization
 333
 334 =item *
 335
 336 Add Role-Specific Logic to the ``Book List'' Template
 337
 338 =item *
 339
 340 Limit Books::add to admin Users
 341
 342 =item *
 343
 344 Try Out Authentication And Authorization
 345
 346 =back
 347
 348 =item *
 349
 350 ENABLE ACL-BASED AUTHORIZATION
 351
 352 =over 4
 353
 354 =item *
 355
 356 Add the Catalyst::Plugin::Authorization::ACL Plugin
 357
 358 =item *
 359
 360 Add ACL Rules to the Application Class
 361
 362 =item *
 363
 364 Add a Method to Handle Access Violations
 365
 366 =back
 367
 368 =back
 369
 370 =head2 L<Part 6: Debugging|Catalyst::Manual::Tutorial::Debugging>
 371
 372 =over 4
 373
 374 =item *
 375
 376 LOG STATEMENTS
 377
 378 =item *
 379
 380 RUNNING CATALYST UNDER THE PERL DEBUGGER
 381
 382 =item *
 383
 384 DEBUGGING MODULES FROM CPAN
 385
 386 =back
 387
 388 =head2 L<Part 7: Testing|Catalyst::Manual::Tutorial::Testing>
 389
 390 =over 4
 391
 392 =item *
 393
 394 RUNNING THE "CANNED" CATALYST TESTS
 395
 396 =item *
 397
 398 RUNNING A SINGLE TEST
 399
 400 =item *
 401
 402 ADDING YOUR OWN TEST SCRIPT
 403
 404 =item *
 405
 406 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
 407
 408 =back
 409
 410 =head2 L<Part 8: Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
 411
 412 =over 4
 413
 414 =item *
 415
 416 HTML::WIDGET FORM CREATION
 417
 418 =over 4
 419
 420 =item *
 421
 422 Add the HTML::Widget Plugin
 423
 424 =item *
 425
 426 Add a Form Creation Helper Method
 427
 428 =item *
 429
 430 Add Actions to Display and Save the Form
 431
 432 =item *
 433
 434 Update the CSS
 435
 436 =item *
 437
 438 Create a Template Page To Display The Form
 439
 440 =item *
 441
 442 Add Links for Create and Update via HTML::Widget
 443
 444 =item *
 445
 446 Test The <HTML::Widget> Create Form
 447
 448 =back
 449
 450 =item *
 451
 452 HTML::WIDGET VALIDATION AND FILTERING
 453
 454 =over 4
 455
 456 =item *
 457
 458 Add Constraints and Filters to the Widget Creation Method
 459
 460 =item *
 461
 462 Rebuild the Form Submission Method to Include Validation
 463
 464 =item *
 465
 466 Try Out the Form
 467
 468 =back
 469
 470 =item *
 471
 472 Enable DBIx::Class::HTMLWidget Support
 473
 474 =over 4
 475
 476 =item *
 477
 478 Add DBIx::Class::HTMLWidget to DBIC Model
 479
 480 =item *
 481
 482 Use populate_from_widget in hw_create_do
 483
 484 =back
 485
 486 =back
 487
 488 =head2 L<Part 9: Appendices|Catalyst::Manual::Tutorial::Appendices>
 489
 490 =over 4
 491
 492 =item *
 493
 494 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
 495
 496 =over 4
 497
 498 =item *
 499
 500 "Un-indenting" with Vi/Vim
 501
 502 =item *
 503
 504 "Un-indenting" with Emacs
 505
 506 =back
 507
 508 =item *
 509
 510 APPENDIX 2: USING MYSQL AND POSTGRESQL
 511
 512 =over 4
 513
 514 =item *
 515
 516 MySQL
 517
 518 =item *
 519
 520 PostgreSQL
 521
 522 =back
 523
 524 =item *
 525
 526 APPENDIX 3: IMPROVED HASHING SCRIPT
 527
 528 =back
 529
 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
 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
 554 key Catalyst modules.
 555
 556 =item *
 557
 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
 564 Everyone on #catalyst and #catalyst-dev.
 565
 566 =item *
 567
 568 People who have emailed me with corrections and suggestions on the
 569 tutorial.  As of the most recent release, this include: Florian Ragwitz,
 570 Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno,
 571 Bryan Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang,
 572 Jeremy Jones, David Kurtz, and Ingo Wichmann.
 573
 574 =back
 575
 576 =head1 AUTHOR
 577
 578 Kennedy Clark, C<hkclark@gmail.com>
 579
 580 Please report any errors, issues or suggestions to the author.  The
 581 most recent version of the Catalyst Tutorial can be found at
 582 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
 583
 584 Copyright 2006, Kennedy Clark, under Creative Commons License
 585 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).