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