lib/Catalyst/Manual/Tutorial/01_Intro.pod

   1 =head1 NAME
   2
   3 Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction
   4
   5
   6 =head1 OVERVIEW
   7
   8 This is B<Chapter 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<01_Introduction>
  17
  18 =item 2
  19
  20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
  21
  22 =item 3
  23
  24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
  25
  26 =item 4
  27
  28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
  29
  30 =item 5
  31
  32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
  33
  34 =item 6
  35
  36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
  37
  38 =item 7
  39
  40 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
  41
  42 =item 8
  43
  44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
  45
  46 =item 9
  47
  48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
  49
  50 =item 10
  51
  52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
  53
  54 =back
  55
  56
  57 =head1 DESCRIPTION
  58
  59 This tutorial provides a multi-part 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, and/or
  68 form management).
  69
  70 The most recent code for the tutorial is included on the Tutorial Virtual
  71 Machine you can download from:
  72
  73     svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
  74
  75 This will download the most recent code for each chapter of the
  76 tutorial into the CatalystTutorial directory on your machine.
  77
  78 B<These reference implementations are provided so that when you follow
  79 the tutorial, you can use the code to ensure that your system is set up
  80 correctly (which shouldn't be an issue if you use the Tutorial Virtual
  81 Machine), :-) and that you have not inadvertently made any typographic
  82 errors, or accidentally skipped part of the tutorial.>
  83
  84 B<NOTE: You can use any Perl-supported OS and environment to run
  85 Catalyst.> It should make little or no difference to Catalyst's
  86 operation, B<but this tutorial has been written using the Debian-based
  87 Tutorial Virtual Machine that you can download and use to work through
  88 the full tutorial step by step.  B<WE STRONGLY RECOMMEND THAT YOU USE
  89 THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
  90 that may crop up if you are working with a different configuration.  We
  91 have tested the Tutorial Virtual Machine to make sure all of the
  92 examples work correctly, but it is hard to guarantee this on other
  93 platforms and versions.
  94
  95 If you would prefer to install directly from CPAN and not use the
  96 Tutorial Virtual machine, you can download the example program and all
  97 the necessary dependencies to your local machine by installing the
  98 C<Task::Catalyst::Tutorial> distribution:
  99
 100      cpan Task::Catalyst::Tutorial
 101
 102 This will also test to make sure the dependencies are working.  If you
 103 have trouble installing these, please ask for help on the #catalyst
 104 IRC channel, or the Catalyst mailing list.
 105
 106 Subjects covered by the tutorial include:
 107
 108 =over 4
 109
 110 =item *
 111
 112 A simple application that lists and adds books.
 113
 114 =item *
 115
 116 The use of L<DBIx::Class> (DBIC) for the model (including
 117 some of the more advanced techniques you will probably want to use in
 118 your applications).
 119
 120 =item *
 121
 122 How to write CRUD (Create, Read, Update, and Delete) operations in
 123 Catalyst.
 124
 125 =item *
 126
 127 Authentication ("auth").
 128
 129 =item *
 130
 131 Role-based authorization ("authz").
 132
 133 =item *
 134
 135 Attempts to provide an example showing current (5.9) Catalyst
 136 practices.
 137
 138 =item *
 139
 140 The use of Template Toolkit (TT).
 141
 142 =item *
 143
 144 Useful techniques for troubleshooting and debugging Catalyst
 145 applications.
 146
 147 =item *
 148
 149 The use of SQLite as a database (with code also provided for MySQL and
 150 PostgreSQL).  (Note: Because we make use of the DBIx::Class Object
 151 Relational Mapping [ORM] layer, out our application will be database
 152 agnostic and can easily be used by any of the databases supported by
 153 DBIx::Class.)
 154
 155 =item *
 156
 157 The use of L<HTML::FormFu> or L<HTML::FormHandler>
 158 for automated form processing and validation.
 159
 160 =back
 161
 162 This tutorial makes the learning process its main priority.  For
 163 example, the level of comments in the code found here would likely be
 164 considered excessive in a "normal project."  Because of their contextual
 165 value, this tutorial will generally favor inline comments over a
 166 separate discussion in the text.  It also deliberately tries to
 167 demonstrate multiple approaches to various features (in general, you
 168 should try to be as consistent as possible with your own production
 169 code).
 170
 171 Furthermore, this tutorial tries to minimize the number of controllers,
 172 models, TT templates, and database tables.  Although this does result in
 173 things being a bit contrived at times, the concepts should be applicable
 174 to more complex environments.  More complete and complicated example
 175 applications can be found at
 176 L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
 177 in the C<examples> area of the Catalyst Subversion repository at
 178 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
 179 ***Todo: update link above?
 180
 181
 182
 183 =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
 184
 185 =over 4
 186
 187 =item 1
 188
 189 Download the C<debian-live-6.0.1-i386-rescue.iso> image from
 190 L<http://cdimage.debian.org/cdimage/release/current-live/i386/iso-hybrid/>.
 191
 192 =item 2
 193
 194 Uncompress the image:
 195
 196     tar zxvf CatalystTutorial.tgz
 197
 198 =item 3
 199
 200 Boot the virtual machine using a tool like VMWare Player
 201 L<http://www.vmware.com/products/player> or VirtualBox
 202 L<http://www.virtualbox.org/>.
 203
 204 =item 4
 205
 206 Once you get a login prompt, enter the username B<root> and a password
 207 for C<catalyst>.  You should now be at a prompt that looks like:
 208
 209     login: root
 210     password: catalyst
 211     root@catalyst:~#
 212
 213 =item 5
 214
 215 Type "C<ifconfig>" to get the IP address assigned to the virtual
 216 machine.  You should get output along the lines of:
 217
 218     eth0  Link encap:Ethernet  HWaddr 00:01:22:3b:45:69
 219           inet addr:192.168.245.128  Bcast:192.168.245.255  Mask:255.255.255.0
 220     ...
 221
 222 You want the IP address on the second line below the C<eth0> interface.
 223 The image it design to automatically use a DHCP-assigned address.
 224
 225 If DHCP is not working or is not available in your location, most
 226 virtual machine "host" environments let's you select between one of
 227 several different types of networking between the "guest" and the "host"
 228 machine.
 229
 230     1) Bridged
 231     2) NAT
 232     3) Local host only
 233
 234 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
 235 in the VM acting like another device on your network that will get a
 236 different DHCP IP address than the host machine.  The advantage of this
 237 approach, is that you can easily SSH and web browse to the guest virtual
 238 machine.
 239
 240 In some environments, you might have better luck with "NAT" (Network
 241 Address Translation) mode.  With this configuration, the guest VM shares
 242 the same IP address as the host machine.  The downside of the approach
 243 is that special configuration is required if you want to be able to SSH
 244 or web browse to the guest VM (some virtual machine host environments
 245 let you configure a "static NAT" or "port forwarding" to reach the guest
 246 OS).
 247
 248 "Local host only" mode let's the guest VM and the host machine talk on a
 249 "private subnet" that other devices in your network cannot reach.
 250
 251 Consult the documentation on your virtual machine host environment for
 252 help configuring the options above.
 253
 254 =item 6
 255
 256 B<From your main desktop machine>, open an SSH client and connect to
 257 the IP address found in the previous step.  You should get a login
 258 prompt (accept the SSH key).  Login with the same username and password:
 259 B<root> / B<catalyst>
 260
 261 =item 7
 262
 263 B<Using the SSH session>, change to the sample code directory for
 264 Chapter 3 included with the Tutorial Virtual Machine and start the
 265 Catalyst Development Server:
 266
 267     $ cd Final/Chapter03
 268     $ perl scripts/myapp_server -r
 269
 270 =item 8
 271
 272 B<From your main desktop machine>, open a web browser and go to
 273 B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP address to your
 274 virtual machine that you looked up in Step 5.  For example, if your
 275 virtual machine is using the IP address C<192.168.0.21>, you would put
 276 the following URL into your web browser:
 277
 278     http://192.168.0.21:3000/
 279
 280 Make sure you don't forget the B<:3000> to use port 3000 instead of the
 281 usual port 80 that is used by HTTP by default.
 282
 283 You should get a Catalyst Welcome Screen.  If you do, feel free to jump
 284 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
 285 of the tutorial.  If you don't go get the Catalyst Welcome Screen, go
 286 back and carefully check each of the steps above.
 287
 288 =item 9
 289
 290 B<Optional:> The VI/VIM editor is already installed on the Tutorial
 291 Virtual Machine.  In order to reduce the size of the download, Emacs is
 292 not pre-installed.  Since people obviously have very strong opinions
 293 about which editor is best, :-) Debian fortunately make it very easy to
 294 install Emacs:
 295
 296     $ aptitude install emacs
 297
 298 =back
 299
 300
 301 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
 302
 303 This tutorial was built using the following resources. Please note that
 304 you may need to make adjustments for different environments and versions
 305 (note that trailing zeros in version numbers are not significant and may
 306 get dropped with some techniques for viewing them; for example, Catalyst
 307 v5.80020 might show up as 5.8002):
 308
 309 =over 4
 310
 311 =item *
 312
 313 Debian 6 (Squeeze)
 314
 315 =item *
 316
 317 Catalyst v5.90002
 318
 319 =item *
 320
 321 Catalyst::Devel v1.34
 322
 323 =item *
 324
 325 DBIx::Class v0.08195
 326
 327 =item *
 328
 329 Catalyst::Model::DBIC::Schema v0.54
 330
 331 =item *
 332
 333 Template Toolkit v2.22
 334
 335
 336 =item *
 337
 338 HTML::FormFu -- v0.09004
 339
 340 =item *
 341
 342 B<NOTE:> You can check the versions you have installed with the
 343 following command (note the slash before the space):
 344
 345     perl -M<_mod_name_>\ 999
 346
 347 or:
 348
 349     perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
 350
 351 For example:
 352
 353     perl -MCatalyst::Devel\ 999
 354
 355 or:
 356
 357     perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
 358
 359 =item *
 360
 361 This tutorial will show URLs in the format of C<http://localhost:3000>,
 362 but if you are running your web browser from outside the Tutorial
 363 Virtual Machine, you will want to substitute the IP address of your VM
 364 for the C<localhost> in the URLs (again, you can get the IP address for
 365 eth0 from the C<ifconfig> command).  For example, if your VM has an
 366 IP address of 192.168.245.128, you will want to use a base URL of
 367 C<http://192.168.245.128:3000>.  Note that the development server
 368 defaults to port 3000 (you can change with with the "-p" option on the
 369 command line.
 370
 371 B<Please Note:> Depending on the web browser you are using, you might need
 372 to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
 373 testing your application at various points (see
 374 L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
 375 list of options for each browser).  Also, the C<-k> keepalive option to
 376 the development server can be necessary with some browsers (especially
 377 Internet Explorer).
 378
 379 =back
 380
 381
 382 =head1 DATABASES
 383
 384 This tutorial will primarily focus on SQLite because of its simplicity
 385 of installation and use; however, modifications in the script required
 386 to support MySQL and PostgreSQL will be presented in the Appendix.
 387
 388 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
 389 that applications become much more database independent.  As such, you
 390 will notice that only the C<.sql> files used to initialize the database
 391 change between database systems: most of the code generally remains the
 392 same.
 393
 394
 395 You can jump to the next chapter of the tutorial here:
 396 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
 397
 398
 399 =head1 AUTHOR
 400
 401 Kennedy Clark, C<hkclark@gmail.com>
 402
 403 Please report any errors, issues or suggestions to the author.  The
 404 most recent version of the Catalyst Tutorial can be found at
 405 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
 406
 407 Copyright 2006-2010, Kennedy Clark, under the
 408 Creative Commons Attribution Share-Alike License Version 3.0
 409 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).