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