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 =over 4
  15
  16 =item *
  17
  18 L<Introduction|Catalyst::Manual::Tutorial::Intro>
  19
  20 =item *
  21
  22 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  23
  24 =item *
  25
  26 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  27
  28 =item *
  29
  30 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  31
  32 =item *
  33
  34 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  35
  36 =item *
  37
  38 L<Testing|Catalyst::Manual::Tutorial::Testing>
  39
  40 =item *
  41
  42 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  43
  44 =item *
  45
  46 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  47
  48 =back
  49
  50 A tarball of the final application is available at
  51 C<to_be_compled_in_final_version>.
  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
  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
  98
  99 =over 4
 100
 101 =item *
 102
 103 Create a DBIC Schema File
 104
 105 =item *
 106
 107 Create the DBIC ``Result Source'' Files
 108
 109 =item *
 110
 111 Use Catalyst::Model::DBIC::Schema to Load the Model Class
 112
 113 =back
 114
 115
 116 =item *
 117
 118 CREATE A CATALYST CONTROLLER
 119
 120 =item *
 121
 122 CATALYST VIEWS
 123
 124
 125 =over 4
 126
 127 =item *
 128
 129 Create a Catalyst View Using TTSite
 130
 131 =item *
 132
 133 Using RenderView for the Default View
 134
 135 =item *
 136
 137 Globally Customize Every View
 138
 139 =item *
 140
 141 Create a TT Template Page
 142
 143 =back
 144
 145
 146 =item *
 147
 148 RUN THE APPLICATION
 149
 150 =back
 151
 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
 184 Add a Method to Display the Form
 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
 196 Test Out the Form
 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
 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
 238 Add User and Role Information to DBIC Schema
 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
 304 =head2 Part 5: Authorization
 305
 306 =over 4
 307
 308 =item *
 309
 310 BASIC AUTHORIZATION
 311
 312 =over 4
 313
 314 =item *
 315
 316 Update Plugins to Include Support for Authorization
 317
 318 =item *
 319
 320 Add Config Information for Authorization
 321
 322 =item *
 323
 324 Add Role-Specific Logic to the ``Book List'' Template
 325
 326 =item *
 327
 328 Limit Books::add to admin Users
 329
 330 =item *
 331
 332 Try Out Authentication And Authorization
 333
 334 =back
 335
 336 =item *
 337
 338 ENABLE ACL-BASED AUTHORIZATION
 339
 340 =over 4
 341
 342 =item *
 343
 344 Add the Catalyst::Plugin::Authorization::ACL Plugin
 345
 346 =item *
 347
 348 Add ACL Rules to the Application Class
 349
 350 =item *
 351
 352 Add a Method to Handle Access Violations
 353
 354 =back
 355
 356 =back
 357
 358 =head2 Part 6: Debugging
 359
 360 =over 4
 361
 362 =item *
 363
 364 LOG STATEMENTS
 365
 366 =item *
 367
 368 RUNNING CATALYST UNDER THE PERL DEBUGGER
 369
 370 =item *
 371
 372 DEBUGGING MODULES FROM CPAN
 373
 374 =back
 375
 376 =head2 Part 7: Testing
 377
 378 =over 4
 379
 380 =item *
 381
 382 RUNNING THE "CANNED" CATALYST TESTS
 383
 384 =item *
 385
 386 RUNNING A SINGLE TEST
 387
 388 =item *
 389
 390 ADDING YOUR OWN TEST SCRIPT
 391
 392 =item *
 393
 394 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
 395
 396 =back
 397
 398 =head2 Part 8: Advanced CRUD
 399
 400 =over 4
 401
 402 =item *
 403
 404 HTML::WIDGET FORM CREATION
 405
 406 =over 4
 407
 408 =item *
 409
 410 Add the HTML::Widget Plugin
 411
 412 =item *
 413
 414 Add a Form Creation Helper Method
 415
 416 =item *
 417
 418 Add Actions to Display and Save the Form
 419
 420 =item *
 421
 422 Update the CSS
 423
 424 =item *
 425
 426 Create a Template Page To Display The Form
 427
 428 =item *
 429
 430 Add Links for Create and Update via HTML::Widget
 431
 432 =item *
 433
 434 Test The <HTML::Widget> Create Form
 435
 436 =back
 437
 438 =item *
 439
 440 HTML::WIDGET VALIDATION AND FILTERING
 441
 442 =over 4
 443
 444 =item *
 445
 446 Add Constraints and Filters to the Widget Creation Method
 447
 448 =item *
 449
 450 Rebuild the Form Submission Method to Include Validation
 451
 452 =item *
 453
 454 Try Out the Form
 455
 456 =back
 457
 458 =item *
 459
 460 Enable DBIx::Class::HTMLWidget Support
 461
 462 =over 4
 463
 464 =item *
 465
 466 Add DBIx::Class::HTMLWidget to DBIC Model
 467
 468 =item *
 469
 470 Use populate_from_widget in hw_create_do
 471
 472 =back
 473
 474 =back
 475
 476 =head2 Part 9: Appendices
 477
 478 =over 4
 479
 480 =item *
 481
 482 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
 483
 484 =over 4
 485
 486 =item *
 487
 488 "Un-indenting" with Vi/Vim
 489
 490 =item *
 491
 492 "Un-indenting" with Emacs
 493
 494 =back
 495
 496 =item *
 497
 498 APPENDIX 2: USING MYSQL AND POSTGRESQL
 499
 500 =over 4
 501
 502 =item *
 503
 504 MySQL
 505
 506 =item *
 507
 508 PostgreSQL
 509
 510 =back
 511
 512 =item *
 513
 514 APPENDIX 3: IMPROVED HASHING SCRIPT
 515
 516 =back
 517
 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
 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
 542 key Catalyst modules.
 543
 544 =item *
 545
 546 Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
 547 and Jess Robinson (including their work on the original Catalyst
 548 tutorial).
 549
 550 =item *
 551
 552 Everyone on #catalyst and #catalyst-dev.
 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,
 559 Bryan Roach, Ashley Berlin, and David Kamholz.
 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 Catalyst 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/>).