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