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 =back
 159
 160 =head2 L<Part 3: Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
 161
 162 =over 4
 163
 164 =item *
 165
 166 FORMLESS SUBMISSION
 167
 168 =over 4
 169
 170 =item *
 171
 172 Include a Create Action in the Books Controller
 173
 174 =item *
 175
 176 Include a Template for the url_create Action:
 177
 178 =item *
 179
 180 Try the url_create Feature
 181
 182 =back
 183
 184 =item *
 185
 186 MANUALLY BUILDING A CREATE FORM
 187
 188 =over 4
 189
 190 =item *
 191
 192 Add a Method to Display the Form
 193
 194 =item *
 195
 196 Add a Template for the Form
 197
 198 =item *
 199
 200 Add Method to Process Form Values and Update Database
 201
 202 =item *
 203
 204 Test Out the Form
 205
 206 =back
 207
 208 =item *
 209
 210 A SIMPLE DELETE FEATURE
 211
 212 =over 4
 213
 214 =item *
 215
 216 Include a Delete Link in the List
 217
 218 =item *
 219
 220 Add a Delete Action to the Controller
 221
 222 =item *
 223
 224 Try the Delete Feature
 225
 226 =back
 227
 228 =back
 229
 230 =head2 L<Part 4: Authentication|Catalyst::Manual::Tutorial::Authentication>
 231
 232 =over 4
 233
 234 =item *
 235
 236 BASIC AUTHENTICATION
 237
 238 =over 4
 239
 240 =item *
 241
 242 Add Users and Roles to the Database
 243
 244 =item *
 245
 246 Add User and Role Information to DBIC Schema
 247
 248 =item *
 249
 250 Create New ``Result Source Objects''
 251
 252 =item *
 253
 254 Sanity-Check Reload of Development Server
 255
 256 =item *
 257
 258 Include Authentication and Session Plugins
 259
 260 =item *
 261
 262 Configure Authentication
 263
 264 =item *
 265
 266 Add Login and Logout Controllers
 267
 268 =item *
 269
 270 Add a Login Form TT Template Page
 271
 272 =item *
 273
 274 Add Valid User Check
 275
 276 =item *
 277
 278 Displaying Content Only to Authenticated Users
 279
 280 =item *
 281
 282 Try Out Authentication
 283
 284 =back
 285
 286 =item *
 287
 288 USING PASSWORD HASHES
 289
 290 =over 4
 291
 292 =item *
 293
 294 Get a SHA-1 Hash for the Password
 295
 296 =item *
 297
 298 Switch to SHA-1 Password Hashes in the Database
 299
 300 =item *
 301
 302 Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
 303
 304 =item *
 305
 306 Try Out the Hashed Passwords
 307
 308 =back
 309
 310 =back
 311
 312 =head2 L<Part 5: Authorization|Catalyst::Manual::Tutorial::Authorization>
 313
 314 =over 4
 315
 316 =item *
 317
 318 BASIC AUTHORIZATION
 319
 320 =over 4
 321
 322 =item *
 323
 324 Update Plugins to Include Support for Authorization
 325
 326 =item *
 327
 328 Add Config Information for Authorization
 329
 330 =item *
 331
 332 Add Role-Specific Logic to the ``Book List'' Template
 333
 334 =item *
 335
 336 Limit Books::add to admin Users
 337
 338 =item *
 339
 340 Try Out Authentication And Authorization
 341
 342 =back
 343
 344 =item *
 345
 346 ENABLE ACL-BASED AUTHORIZATION
 347
 348 =over 4
 349
 350 =item *
 351
 352 Add the Catalyst::Plugin::Authorization::ACL Plugin
 353
 354 =item *
 355
 356 Add ACL Rules to the Application Class
 357
 358 =item *
 359
 360 Add a Method to Handle Access Violations
 361
 362 =back
 363
 364 =back
 365
 366 =head2 L<Part 6: Debugging|Catalyst::Manual::Tutorial::Debugging>
 367
 368 =over 4
 369
 370 =item *
 371
 372 LOG STATEMENTS
 373
 374 =item *
 375
 376 RUNNING CATALYST UNDER THE PERL DEBUGGER
 377
 378 =item *
 379
 380 DEBUGGING MODULES FROM CPAN
 381
 382 =back
 383
 384 =head2 L<Part 7: Testing|Catalyst::Manual::Tutorial::Testing>
 385
 386 =over 4
 387
 388 =item *
 389
 390 RUNNING THE "CANNED" CATALYST TESTS
 391
 392 =item *
 393
 394 RUNNING A SINGLE TEST
 395
 396 =item *
 397
 398 ADDING YOUR OWN TEST SCRIPT
 399
 400 =item *
 401
 402 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
 403
 404 =back
 405
 406 =head2 L<Part 8: Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
 407
 408 =over 4
 409
 410 =item *
 411
 412 HTML::WIDGET FORM CREATION
 413
 414 =over 4
 415
 416 =item *
 417
 418 Add the HTML::Widget Plugin
 419
 420 =item *
 421
 422 Add a Form Creation Helper Method
 423
 424 =item *
 425
 426 Add Actions to Display and Save the Form
 427
 428 =item *
 429
 430 Update the CSS
 431
 432 =item *
 433
 434 Create a Template Page To Display The Form
 435
 436 =item *
 437
 438 Add Links for Create and Update via HTML::Widget
 439
 440 =item *
 441
 442 Test The <HTML::Widget> Create Form
 443
 444 =back
 445
 446 =item *
 447
 448 HTML::WIDGET VALIDATION AND FILTERING
 449
 450 =over 4
 451
 452 =item *
 453
 454 Add Constraints and Filters to the Widget Creation Method
 455
 456 =item *
 457
 458 Rebuild the Form Submission Method to Include Validation
 459
 460 =item *
 461
 462 Try Out the Form
 463
 464 =back
 465
 466 =item *
 467
 468 Enable DBIx::Class::HTMLWidget Support
 469
 470 =over 4
 471
 472 =item *
 473
 474 Add DBIx::Class::HTMLWidget to DBIC Model
 475
 476 =item *
 477
 478 Use populate_from_widget in hw_create_do
 479
 480 =back
 481
 482 =back
 483
 484 =head2 L<Part 9: Appendices|Catalyst::Manual::Tutorial::Appendices>
 485
 486 =over 4
 487
 488 =item *
 489
 490 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
 491
 492 =over 4
 493
 494 =item *
 495
 496 "Un-indenting" with Vi/Vim
 497
 498 =item *
 499
 500 "Un-indenting" with Emacs
 501
 502 =back
 503
 504 =item *
 505
 506 APPENDIX 2: USING MYSQL AND POSTGRESQL
 507
 508 =over 4
 509
 510 =item *
 511
 512 MySQL
 513
 514 =item *
 515
 516 PostgreSQL
 517
 518 =back
 519
 520 =item *
 521
 522 APPENDIX 3: IMPROVED HASHING SCRIPT
 523
 524 =back
 525
 526
 527 =head1 THANKS
 528
 529 This tutorial would not have been possible without the input of many
 530 different people in the Catalyst community.  In particular, the
 531 primary author would like to thank:
 532
 533 =over 4
 534
 535 =item *
 536
 537 Sebastian Riedel for founding the Catalyst project.
 538
 539 =item *
 540
 541 The members of the Catalyst Core Team for their tireless efforts to
 542 advance the Catalyst project.  Although all of the Core Team members
 543 have played a key role in this tutorial, it would have never been
 544 possible without the critical contributions of: Matt Trout, for his
 545 unfathomable knowledge of all things Perl and Catalyst (and his
 546 willingness to answer lots of my questions); Jesse Sheidlower, for his
 547 incredible skill with the written word and dedication to improving the
 548 Catalyst documentation; and Yuval Kogman, for his work on the Catalyst
 549 "Auth & Authz" plugins (the original focus of the tutorial) and other
 550 key Catalyst modules.
 551
 552 =item *
 553
 554 Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
 555 and Jess Robinson (including their work on the original Catalyst
 556 tutorial).
 557
 558 =item *
 559
 560 Everyone on #catalyst and #catalyst-dev.
 561
 562 =item *
 563
 564 People who have emailed me with corrections and suggestions on the
 565 tutorial.  As of the most recent release, this include: Florian Ragwitz,
 566 Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno,
 567 Bryan Roach, Ashley Berlin, David Kamholz, and Kevin Old.
 568
 569 =back
 570
 571
 572
 573 =head1 AUTHOR
 574
 575 Kennedy Clark, C<hkclark@gmail.com>
 576
 577 Please report any errors, issues or suggestions to the author.  The
 578 most recent version of the Catalyst Tutorial can be found at
 579 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Runtime/lib/Catalyst/Manual/Tutorial/>.
 580
 581 Copyright 2006, Kennedy Clark, under Creative Commons License
 582 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).