lib/Catalyst/Manual/Tutorial/Intro.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Part 1 of 10> for the Catalyst tutorial.
   9
  10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
  11
  12 =over 4
  13
  14 =item 1
  15
  16 B<Introduction>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
  21
  22 =item 3
  23
  24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
  25
  26 =item 4
  27
  28 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
  29
  30 =item 5
  31
  32 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
  33
  34 =item 6
  35
  36 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
  37
  38 =item 7
  39
  40 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
  41
  42 =item 8
  43
  44 L<Testing|Catalyst::Manual::Tutorial::Testing>
  45
  46 =item 9
  47
  48 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
  49
  50 =item 10
  51
  52 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
  53
  54 =back
  55
  56
  57 =head1 DESCRIPTION
  58
  59 This tutorial provides a multipart introduction to the Catalyst web
  60 framework. It seeks to provide a rapid overview of many of its most
  61 commonly used features. The focus is on the real-world best practices
  62 required in the construction of nearly all Catalyst applications.
  63
  64 Although the primary target of the tutorial is users new to the Catalyst
  65 framework, experienced users may wish to review specific sections (for
  66 example, how to use DBIC for their model classes, how to add
  67 authentication and authorization to an existing application, or form
  68 management).
  69
  70 You can obtain the code for all the tutorial examples from the
  71 catalyst subversion repository by issuing the command:
  72
  73     svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/ CatalystTutorial
  74
  75 This will download the current code for each tutorial chapter in the
  76 CatalystTutorial directory.  Each example application directory has
  77 the same name as the tutorial chapter.
  78
  79 B<These reference implementations are provided so that when you follow
  80 the tutorial, you can use the code from the subversion repository to
  81 ensure that your system is set up correctly, and that you have not
  82 inadvertently made any typographic errors, or accidentally skipped
  83 part of the tutorial.>
  84
  85 Additionally, if you're reading this manual online, you can download
  86 the example program and all the necessary dependencies to
  87 your local machine by installing the C<Task::Catalyst::Tutorial>
  88 distribution from CPAN:
  89
  90      cpan Task::Catalyst::Tutorial
  91
  92 This will also test to make sure the dependencies are working.  If you
  93 have trouble installing these, please ask for help on the #catalyst
  94 IRC channel, or the Catalyst mailing list.
  95
  96 Subjects covered include:
  97
  98 =over 4
  99
 100 =item *
 101
 102 A simple application that lists and adds books.
 103
 104 =item *
 105
 106 The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model.
 107
 108 =item *
 109
 110 How to write CRUD (Create, Read, Update, and Delete) operations in
 111 Catalyst.
 112
 113 =item *
 114
 115 Authentication ("auth").
 116
 117 =item *
 118
 119 Role-based authorization ("authz").
 120
 121 =item *
 122
 123 Attempts to provide an example showing current (5.7XXX) Catalyst
 124 practices. For example, the use of
 125 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>,
 126 DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
 127 with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm>
 128 vs. C<lib/MyApp.pm>, etc.
 129
 130 =item *
 131
 132 The use of Template Toolkit (TT) and the
 133 L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>
 134 view helper.
 135
 136 =item *
 137
 138 Useful techniques for troubleshooting and debugging Catalyst
 139 applications.
 140
 141 =item *
 142
 143 The use of SQLite as a database (with code also provided for MySQL and
 144 PostgreSQL).
 145
 146 =item *
 147
 148 The use of L<HTML::FormFu|HTML::FormFu> for automated form processing
 149 and validation.
 150
 151 =back
 152
 153 This tutorial makes the learning process its main priority.  For
 154 example, the level of comments in the code found here would likely be
 155 considered excessive in a "normal project."  Because of their contextual
 156 value, this tutorial will generally favor inline comments over a
 157 separate discussion in the text.  It also deliberately tries to
 158 demonstrate multiple approaches to various features (in general, you
 159 should try to be as consistent as possible with your own production
 160 code).
 161
 162 Furthermore, this tutorial tries to minimize the number of controllers,
 163 models, TT templates, and database tables.  Although this does result in
 164 things being a bit contrived at times, the concepts should be applicable
 165 to more complex environments.  More complete and complicated example
 166 applications can be found in the C<examples> area of the Catalyst
 167 Subversion repository at
 168 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
 169
 170 B<Note:> There are a variety of other introductory materials available
 171 through the Catalyst web site and at
 172 L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and
 173 L<http://dev.catalyst.perl.org/>.
 174
 175 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
 176
 177 This tutorial was built using the following resources. Please note that
 178 you may need to make adjustments for different environments and
 179 versions:
 180
 181 =over 4
 182
 183 =item *
 184
 185 Ubuntu 8.04 Hardy Heron
 186
 187 =item *
 188
 189 Catalyst v5.7011
 190
 191 =item *
 192
 193 Catalyst::Devel v1.03
 194
 195 =item *
 196
 197 DBIx::Class v0.08008
 198
 199 =item *
 200
 201 Catalyst Plugins
 202
 203 The plugins used in this tutorial all have sufficiently stable APIs that
 204 you shouldn't need to worry about versions. However, there could be
 205 cases where the tutorial is affected by what version of plugins you
 206 use. This tutorial has been tested against the following set of plugins:
 207
 208 =over 4
 209
 210 =item *
 211
 212 Catalyst::Plugin::Authentication -- v0.10002
 213
 214 =item *
 215
 216 Catalyst::Plugin::Authentication::Store::DBIC -- v0.09
 217
 218 =item *
 219
 220 Catalyst::Plugin::Authorization::ACL -- v0.08
 221
 222 =item *
 223
 224 Catalyst::Plugin::Authorization::Roles -- v0.05
 225
 226 =item *
 227
 228 Catalyst::Plugin::ConfigLoader -- v0.17
 229
 230 =item *
 231
 232 Catalyst::Plugin::Session -- v0.18
 233
 234 =item *
 235
 236 Catalyst::Plugin::Session::State::Cookie -- v0.08
 237
 238 =item *
 239
 240 Catalyst::Plugin::Session::Store::FastMmap -- v0.03
 241
 242 =item *
 243
 244 Catalyst::Plugin::StackTrace -- v0.06
 245
 246 =item *
 247
 248 Catalyst::Plugin::Static::Simple -- v0.20
 249
 250 =back
 251
 252 =item *
 253
 254 Since the web browser is being used on the same box where Perl and the
 255 Catalyst development server is running, the URL of
 256 C<http://localhost:3000> will be used (the Catalyst development server
 257 defaults to port 3000).  If you are running Perl on a different box than
 258 where your web browser is located (or using a different port number via
 259 the C<-p> I<port_number> option to the development server), then you
 260 will need to update the URL you use accordingly.
 261
 262 =item *
 263
 264 Depending on the web browser you are using, you might need to hit
 265 C<Shift+Reload> to pull a fresh page when testing your application at
 266 various points.  Also, the C<-k> keepalive option to the development
 267 server can be necessary with some browsers (especially Internet
 268 Explorer).
 269
 270 =back
 271
 272 =head1 CATALYST INSTALLATION
 273
 274 If approach in the wrong manner, it can be a daunting tasks to get
 275 Catalyst initally installed.  Although a compelling strength of
 276 Catalyst is that it makes use of many of the modules in the
 277 vast repository that is CPAN, this can complicate the installation
 278 process.  However, there are a growing number of methods
 279 that can dramatically ease this undertaking.  Of these, the following
 280 are likely to be applicable to the largest number of potential new
 281 users:
 282
 283 =over 4
 284
 285 =item *
 286
 287 Ubuntu
 288
 289 Given the popularity of Ubuntu and it's ease of use, Ubuntu can be
 290 a great way for newcomers to experiment with Catalyst.  Because it
 291 is a "live CD," you can simply boot from the CD, run a few commands,
 292 and you should have a fully functional environment in which to do
 293 this tutorial in a matter of minutes.
 294
 295 =over 4
 296
 297 =item *
 298
 299 Download Ubuntu 8.04 (aka, Hardy Heron) and boot from the CD and/or
 300 image file, select your language, and then "Try Ubuntu without any
 301 changes to your computer."
 302
 303 =item *
 304
 305 Open a terminal session.
 306
 307 =item *
 308
 309 Add the 'universe' repositories:
 310
 311     sudo vi /etc/apt/sources.list
 312
 313 And remove the comments from the lines under the comments about the
 314 'universe' repositories.
 315
 316 =item *
 317
 318 Install Catalyst:
 319
 320     sudo apt-get update
 321     sudo apt-get upgrade
 322     sudo apt-get install sqlite3 libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl
 323
 324 Accept all of the dependencies.  Done.
 325
 326 =back
 327
 328 =item *
 329
 330 Matt Trout's C<cat-install>
 331
 332 Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
 333 C<cat-install> can be a quick and painless way to get Catalyst up and
 334 running.  Just download the script from the link above and type C<perl
 335 cat-install>.
 336
 337 =item *
 338
 339 Chris Laco's CatInABox
 340
 341 Download the tarball from
 342 L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
 343 on your machine.  Depending on your OS platform, either run C<start.bat>
 344 or C<start.sh>.
 345
 346 =item *
 347
 348 Pre-Built VMWare Images
 349
 350 Under the VMWare community program, work is ongoing to develop a number
 351 of VMWare images where an entire Catalyst development environment has
 352 already been installed, complete with database engines and a full
 353 complement of Catalyst plugins.
 354
 355 =back
 356
 357 For additional information and recommendations on Catalyst installation,
 358 please refer to
 359 L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
 360
 361 B<NOTE:> Step-by-step instructions to replicate the environment on
 362 which this tutorial was developed can be found at
 363 L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>.
 364 Using these instructions, you should be able to build a complete CentOS
 365 4.X server with Catalyst and all the plugins required to run this
 366 tutorial.
 367
 368 =head1 DATABASES
 369
 370 This tutorial will primarily focus on SQLite because of its simplicity
 371 of installation and use; however, modifications in the script required
 372 to support MySQL and PostgreSQL will be presented in Appendix 2.
 373
 374 B<Note:> One of the advantages of the MVC design patterns is that
 375 applications become much more database independent.  As such, you will
 376 notice that only the C<.sql> files used to initialize the database
 377 change between database systems: the Catalyst code generally remains the
 378 same.
 379
 380 =head1 WHERE TO GET WORKING CODE
 381
 382 Each part of the tutorial has complete code available in the main
 383 Catalyst Subversion repository (see the note at the beginning of each
 384 part for the appropriate svn command to use).  Additionally, the final
 385 code is available as a ready-to-run tarball at
 386 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz>.
 387
 388 B<NOTE:> You can run the test cases for the final code with the following
 389 commands:
 390
 391     wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz
 392     tar zxvf MyApp.tgz
 393     cd MyApp
 394     CATALYST_DEBUG=0 prove --lib lib  t
 395
 396
 397 =head1 AUTHOR
 398
 399 Kennedy Clark, C<hkclark@gmail.com>
 400
 401 Please report any errors, issues or suggestions to the author.  The
 402 most recent version of the Catalyst Tutorial can be found at
 403 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
 404
 405 Copyright 2006, Kennedy Clark, under Creative Commons License
 406 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).
 407
 408