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 We suggest that you read this introduction on the web.  Make sure you are
  13 reading the latest version of the tutorial by visiting
  14 L<https://metacpan.org/module/Catalyst::Manual::Tutorial>.  Alternatively
  15 you can use CPAN modules like L<Pod::Webserver>, L<Pod::POM::Web>,
  16 L<Pod::Browser> (Catalyst based), or L<CPAN::Mini::Webserver> to read a local
  17 copy of the tutorial.
  18
  19 The tutorial is divided into the following sections:
  20
  21 B<NOTE: CLICK THESE LINKS TO JUMP TO CHAPTERS> (the index links above
  22 only navigate inside this page).
  23
  24 =over 4
  25
  26 =item 1
  27
  28 L<Introduction|Catalyst::Manual::Tutorial::01_Intro>
  29
  30 =item 2
  31
  32 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
  33
  34 =item 3
  35
  36 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
  37
  38 =item 4
  39
  40 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
  41
  42 =item 5
  43
  44 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
  45
  46 =item 6
  47
  48 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
  49
  50 =item 7
  51
  52 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
  53
  54 =item 8
  55
  56 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
  57
  58 =item 9
  59
  60 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
  61
  62 =item 10
  63
  64 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
  65
  66 =back
  67
  68 Final code tarballs for each chapter of the tutorial are available at
  69 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/>.
  70
  71
  72 =head1 Detailed Table of Contents
  73
  74
  75 =head2 L<Chapter 1: Intro|Catalyst::Manual::Tutorial::01_Intro>
  76
  77 Note: Click on the heading in the previous line to jump to the actual
  78 chapter. Below is a "table of contents" for this chapter.
  79
  80 =over 4
  81
  82 =item *
  83
  84 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
  85
  86 =item *
  87
  88 CATALYST INSTALLATION
  89
  90 =item *
  91
  92 DATABASES
  93
  94 =item *
  95
  96 WHERE TO GET WORKING CODE
  97
  98 =back
  99
 100
 101 =head2 L<Chapter 2: Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
 102
 103 Note: Click on the heading in the previous line to jump to the actual
 104 chapter. Below is a "table of contents" for this chapter.
 105
 106 =over 4
 107
 108 =item *
 109
 110 CREATE A CATALYST PROJECT
 111
 112 =item *
 113
 114 HELLO WORLD
 115
 116 =over 4
 117
 118 =item *
 119
 120 The Simplest Way
 121
 122 =item *
 123
 124 Hello, World! Using a View and a Template
 125
 126 =back
 127
 128 =item *
 129
 130 CREATE A SIMPLE CONTROLLER AND AN ACTION
 131
 132 =back
 133
 134
 135 =head2 L<Chapter 3: More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
 136
 137 Note: Click on the heading in the previous line to jump to the actual
 138 chapter. Below is a "table of contents" for this chapter.
 139
 140 =over 4
 141
 142 =item *
 143
 144 CREATE A NEW APPLICATION
 145
 146 =item *
 147
 148 EDIT THE LIST OF CATALYST PLUGINS
 149
 150 =item *
 151
 152 CREATE A CATALYST CONTROLLER
 153
 154 =item *
 155
 156 CATALYST VIEWS
 157
 158
 159 =over 4
 160
 161 =item *
 162
 163 Create a Catalyst View
 164
 165 =item *
 166
 167 Create a TT Template Page
 168
 169 =item *
 170
 171 Test Run The Application
 172
 173 =back
 174
 175 =item *
 176
 177 CREATE A SQLITE DATABASE
 178
 179 =item *
 180
 181 DATABASE ACCESS WITH DBIx::Class
 182
 183 =over 4
 184
 185 =item *
 186
 187 Create a Dynamic DBIC Model
 188
 189 =back
 190
 191 =item *
 192
 193 ENABLE THE MODEL IN THE CONTROLLER
 194
 195 =over 4
 196
 197 =item *
 198
 199 Test Run The Application
 200
 201 =back
 202
 203 =item *
 204
 205 CREATE A WRAPPER FOR THE VIEW
 206
 207 =over 4
 208
 209 =item *
 210
 211 Configure TT.pm For The Wrapper
 212
 213 =item *
 214
 215 Create the Wrapper Template File and Stylesheet
 216
 217 =item *
 218
 219 Test Run The Application
 220
 221 =back
 222
 223 =item *
 224
 225 A STATIC DATABASE MODEL WITH DBIx::Class
 226
 227 =over 4
 228
 229 =item *
 230
 231 Create Static DBIC Schema Files
 232
 233 =item *
 234
 235 Updating the Generated DBIC Schema Files
 236
 237 =item *
 238
 239 Run The Application
 240
 241 =back
 242
 243 =item *
 244
 245 UPDATING THE VIEW
 246
 247 =item *
 248
 249 RUNNING THE APPLICATION FROM THE COMMAND LINE
 250
 251 =item *
 252
 253 OPTIONAL INFORMATION
 254
 255 =over 4
 256
 257 =item *
 258
 259 Using RenderView for the Default View
 260
 261 =item *
 262
 263 Using The Default Template Name
 264
 265 =item *
 266
 267 Return To A Manually-Specified Template
 268
 269 =back
 270
 271 =back
 272
 273
 274 =head2 L<Chapter 4: Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
 275
 276 Note: Click on the heading in the previous line to jump to the actual
 277 chapter. Below is a "table of contents" for this chapter.
 278
 279 =over 4
 280
 281 =item *
 282
 283 FORMLESS SUBMISSION
 284
 285 =over 4
 286
 287 =item *
 288
 289 Include a Create Action in the Books Controller
 290
 291 =item *
 292
 293 Include a Template for the url_create Action:
 294
 295 =item *
 296
 297 Try the url_create Feature
 298
 299 =back
 300
 301 =item *
 302
 303 CONVERT TO A CHAINED ACTION
 304
 305 =over 4
 306
 307 =item *
 308
 309 Try the Chained Action
 310
 311 =item *
 312
 313 Refactor to Use a "Base" Method to Start the Chains
 314
 315 =back
 316
 317 =item *
 318
 319 MANUALLY BUILDING A CREATE FORM
 320
 321 =over 4
 322
 323 =item *
 324
 325 Add a Method to Display the Form
 326
 327 =item *
 328
 329 Add a Template for the Form
 330
 331 =item *
 332
 333 Add Method to Process Form Values and Update Database
 334
 335 =item *
 336
 337 Test Out the Form
 338
 339 =back
 340
 341 =item *
 342
 343 A SIMPLE DELETE FEATURE
 344
 345 =over 4
 346
 347 =item *
 348
 349 Include a Delete Link in the List
 350
 351 =item *
 352
 353 Add a Common Method to Retrieve a Book for the Chain
 354
 355 =item *
 356
 357 Add a Delete Action to the Controller
 358
 359 =item *
 360
 361 Try the Delete Feature
 362
 363 =item *
 364
 365 Fixing a Dangerous URL
 366
 367 =item *
 368
 369 Try the Delete and Redirect Logic
 370
 371 =item *
 372
 373 Using uri_for to Pass Query Parameters
 374
 375 =item *
 376
 377 Try the Delete and Redirect With Query Param Logic
 378
 379 =back
 380
 381 =item *
 382
 383 EXPLORING THE POWER OF DBIC
 384
 385 =over 4
 386
 387 =item *
 388
 389 Add Datetime Columns to Our Existing Books Table
 390
 391 =item *
 392
 393 Update DBIC to Automatically Handle the Datetime Columns
 394
 395 =item *
 396
 397 Create a ResultSet Class
 398
 399 =item *
 400
 401 Chaining ResultSets
 402
 403 =item *
 404
 405 Adding Methods to Result Classes
 406
 407 =back
 408
 409 =back
 410
 411
 412 =head2 L<Chapter 5: Authentication|Catalyst::Manual::Tutorial::05_Authentication>
 413
 414 Note: Click on the heading in the previous line to jump to the actual
 415 chapter. Below is a "table of contents" for this chapter.
 416
 417 =over 4
 418
 419 =item *
 420
 421 BASIC AUTHENTICATION
 422
 423 =over 4
 424
 425 =item *
 426
 427 Add Users and Roles to the Database
 428
 429 =item *
 430
 431 Add User and Role Information to DBIC Schema
 432
 433 =item *
 434
 435 Sanity-Check Reload of Development Server
 436
 437 =item *
 438
 439 Include Authentication and Session Plugins
 440
 441 =item *
 442
 443 Configure Authentication
 444
 445 =item *
 446
 447 Add Login and Logout Controllers
 448
 449 =item *
 450
 451 Add a Login Form TT Template Page
 452
 453 =item *
 454
 455 Add Valid User Check
 456
 457 =item *
 458
 459 Displaying Content Only to Authenticated Users
 460
 461 =item *
 462
 463 Try Out Authentication
 464
 465 =back
 466
 467 =item *
 468
 469 USING PASSWORD HASHES
 470
 471 =over 4
 472
 473 =item *
 474
 475 Get a SHA-1 Hash for the Password
 476
 477 =item *
 478
 479 Switch to SHA-1 Password Hashes in the Database
 480
 481 =item *
 482
 483 Enable SHA-1 Hash Passwords in Catalyst::Plugin::Authentication::Store::DBIC
 484
 485 =item *
 486
 487 Try Out the Hashed Passwords
 488
 489 =back
 490
 491 =item *
 492
 493 USING THE SESSION FOR FLASH
 494
 495 =over 4
 496
 497 =item *
 498
 499 Try Out Flash
 500
 501 =item *
 502
 503 Switch To Flash-To-Stash
 504
 505 =back
 506
 507 =back
 508
 509
 510 =head2 L<Chapter 6: Authorization|Catalyst::Manual::Tutorial::06_Authorization>
 511
 512 Note: Click on the heading in the previous line to jump to the actual
 513 chapter. Below is a "table of contents" for this chapter.
 514
 515 =over 4
 516
 517 =item *
 518
 519 BASIC AUTHORIZATION
 520
 521 =over 4
 522
 523 =item *
 524
 525 Update Plugins to Include Support for Authorization
 526
 527 =item *
 528
 529 Add Config Information for Authorization
 530
 531 =item *
 532
 533 Add Role-Specific Logic to the ``Book List'' Template
 534
 535 =item *
 536
 537 Limit Books::add to admin Users
 538
 539 =item *
 540
 541 Try Out Authentication And Authorization
 542
 543 =back
 544
 545 =item *
 546
 547 ENABLE MODEL-BASED AUTHORIZATION
 548
 549 =back
 550
 551
 552 =head2 L<Chapter 7: Debugging|Catalyst::Manual::Tutorial::07_Debugging>
 553
 554 Note: Click on the heading in the previous line to jump to the actual
 555 chapter. Below is a "table of contents" for this chapter.
 556
 557 =over 4
 558
 559 =item *
 560
 561 LOG STATEMENTS
 562
 563 =item *
 564
 565 RUNNING CATALYST UNDER THE PERL DEBUGGER
 566
 567 =item *
 568
 569 DEBUGGING MODULES FROM CPAN
 570
 571 =item *
 572
 573 TT DEBUGGING
 574
 575 =back
 576
 577
 578 =head2 L<Chapter 8: Testing|Catalyst::Manual::Tutorial::08_Testing>
 579
 580 Note: Click on the heading in the previous line to jump to the actual
 581 chapter. Below is a "table of contents" for this chapter.
 582
 583 =over 4
 584
 585 =item *
 586
 587 RUNNING THE "CANNED" CATALYST TESTS
 588
 589 =item *
 590
 591 RUNNING A SINGLE TEST
 592
 593 =item *
 594
 595 ADDING YOUR OWN TEST SCRIPT
 596
 597 =item *
 598
 599 SUPPORTING BOTH PRODUCTION AND TEST DATABASES
 600
 601 =back
 602
 603
 604 =head2 L<Chapter 9: Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
 605
 606 Note: Click on the heading in the previous line to jump to the actual
 607 chapter. Below is a "table of contents" for this chapter.
 608
 609 =over 4
 610
 611 =item *
 612
 613 ADVANCED CRUD OPTIONS
 614
 615 =back
 616
 617
 618 =head2 L<Chapter 10: Appendices|Catalyst::Manual::Tutorial::10_Appendices>
 619
 620 Note: Click on the heading in the previous line to jump to the actual
 621 chapter. Below is a "table of contents" for this chapter.
 622
 623 =over 4
 624
 625 =item *
 626
 627 APPENDIX 1: CUT AND PASTE FOR POD-BASED EXAMPLES
 628
 629 =over 4
 630
 631 =item *
 632
 633 "Un-indenting" with Vi/Vim
 634
 635 =item *
 636
 637 "Un-indenting" with Emacs
 638
 639 =back
 640
 641 =item *
 642
 643 APPENDIX 2: USING MYSQL AND POSTGRESQL
 644
 645 =over 4
 646
 647 =item *
 648
 649 MySQL
 650
 651 =item *
 652
 653 PostgreSQL
 654
 655 =back
 656
 657 =item *
 658
 659 APPENDIX 3: IMPROVED HASHING SCRIPT
 660
 661 =back
 662
 663
 664 =head1 THANKS
 665
 666 This tutorial would not have been possible without the input of many
 667 different people in the Catalyst community.  In particular, the
 668 primary author would like to thank:
 669
 670 =over 4
 671
 672 =item *
 673
 674 Sebastian Riedel for founding the Catalyst project.
 675
 676 =item *
 677
 678 The members of the Catalyst Core Team for their tireless efforts to
 679 advance the Catalyst project.  Although all of the Core Team members
 680 have played a key role in this tutorial, it would have never been
 681 possible without the critical contributions of: Matt Trout, for his
 682 unfathomable knowledge of all things Perl and Catalyst (and his
 683 willingness to answer lots of my questions); Jesse Sheidlower, for his
 684 incredible skill with the written word and dedication to improving the
 685 Catalyst documentation; and Yuval Kogman, for his work on the Catalyst
 686 "Auth & Authz" plugins (the original focus of the tutorial) and other
 687 key Catalyst modules.
 688
 689 =item *
 690
 691 Other Catalyst documentation folks like Kieren Diment, Gavin Henry,
 692 and Jess Robinson (including their work on the original Catalyst
 693 tutorial).
 694
 695 =item *
 696
 697 Kieren Diment for his oversight of Catalyst-related documentation.
 698
 699 =item *
 700
 701 Everyone on #catalyst and #catalyst-dev.
 702
 703 =item *
 704
 705 Louis Moore (who thanks Marcello Romani and Tom Lanyon) for the
 706 PostgreSQL content in the Appendix.
 707
 708 =item *
 709
 710 People who have emailed me with corrections and suggestions on the
 711 tutorial. As of the most recent release, this include: Florian Ragwitz,
 712 Mauro Andreolini, Jim Howard, Giovanni Gigante, William Moreno, Bryan
 713 Roach, Ashley Berlin, David Kamholz, Kevin Old, Henning Sprang, Jeremy
 714 Jones, David Kurtz, Ingo Wichmann, Shlomi Fish, Murray Walker, Adam
 715 Witney and xenoterracide (Caleb Cushing). Thanks to Devin Austin for
 716 coming up with an initial version of a non-TTSite wrapper page. Also, a
 717 huge thank you to Kiffin Gish for all the hard work on the "database
 718 depluralization" effort and Rafael Kitover for the work on updating the
 719 tutorial to include foreign key support for SQLite. I'm sure I am
 720 missing some names here... apologies for that (please let me know if you
 721 name should be here).
 722
 723 =back
 724
 725 =head1 AUTHOR
 726
 727 Kennedy Clark, C<hkclark@gmail.com>
 728
 729 Feel free to contact the author for any errors or suggestions, but the
 730 best way to report issues is via the CPAN RT Bug system at
 731 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
 732
 733 Copyright 2006-2010, Kennedy Clark, under the
 734 Creative Commons Attribution Share-Alike License Version 3.0
 735 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).