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     catalyst login: root
 210     Password: catalyst
 211     ...
 212     root@catalyst:~#
 213
 214 =item 5
 215
 216 Type "C<ifconfig>" to get the IP address assigned to the virtual
 217 machine.  You should get output along the lines of:
 218
 219     eth0  Link encap:Ethernet  HWaddr 00:01:22:3b:45:69
 220           inet addr:192.168.245.128  Bcast:192.168.245.255  Mask:255.255.255.0
 221     ...
 222
 223 You want the IP address on the second line below the C<eth0> interface.
 224 The image it design to automatically use a DHCP-assigned address.
 225
 226 If DHCP is not working or is not available in your location, most
 227 virtual machine "host" environments let's you select between one of
 228 several different types of networking between the "guest" and the "host"
 229 machine.
 230
 231     1) Bridged
 232     2) NAT
 233     3) Local host only
 234
 235 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
 236 in the VM acting like another device on your network that will get a
 237 different DHCP IP address than the host machine.  The advantage of this
 238 approach, is that you can easily SSH and web browse to the guest virtual
 239 machine.
 240
 241 In some environments, you might have better luck with "NAT" (Network
 242 Address Translation) mode.  With this configuration, the guest VM shares
 243 the same IP address as the host machine.  The downside of the approach
 244 is that special configuration is required if you want to be able to SSH
 245 or web browse to the guest VM (some virtual machine host environments
 246 let you configure a "static NAT" or "port forwarding" to reach the guest
 247 OS).
 248
 249 "Local host only" mode let's the guest VM and the host machine talk on a
 250 "private subnet" that other devices in your network cannot reach.
 251
 252 Consult the documentation on your virtual machine host environment for
 253 help configuring the options above.
 254
 255 =item 6
 256
 257 B<From your main desktop machine>, open an SSH client and connect to
 258 the IP address found in the previous step.  You should get a login
 259 prompt (accept the SSH key).  Login with the same username and password:
 260 B<root> / B<catalyst>
 261
 262 =item 7
 263
 264 B<Using the SSH session>, change to the sample code directory for
 265 Chapter 3 included with the Tutorial Virtual Machine and start the
 266 Catalyst Development Server:
 267
 268     $ cd Final/Chapter03
 269     $ perl scripts/myapp_server -r
 270
 271 =item 8
 272
 273 B<From your main desktop machine>, open a web browser and go to
 274 B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP address to your
 275 virtual machine that you looked up in Step 5.  For example, if your
 276 virtual machine is using the IP address C<192.168.0.21>, you would put
 277 the following URL into your web browser:
 278
 279     http://192.168.0.21:3000/
 280
 281 Make sure you don't forget the B<:3000> to use port 3000 instead of the
 282 usual port 80 that is used by HTTP by default.
 283
 284 You should get a Catalyst Welcome Screen.  If you do, feel free to jump
 285 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
 286 of the tutorial.  If you don't go get the Catalyst Welcome Screen, go
 287 back and carefully check each of the steps above.
 288
 289 =item 9
 290
 291 B<Optional:> The VI/VIM editor is already installed on the Tutorial
 292 Virtual Machine.  In order to reduce the size of the download, Emacs is
 293 not pre-installed.  Since people obviously have very strong opinions
 294 about which editor is best, :-) Debian fortunately make it very easy to
 295 install Emacs:
 296
 297     $ aptitude install emacs
 298
 299 =back
 300
 301
 302 You will note that the Tutorial Virtual Machine uses L<local::lib> so
 303 that the Perl modules are run from ~/perl5 (in this case, /root/perl5)
 304 vs. the usual location of your "system Perl".  We recommend that you
 305 also consider using this very handy module.  It can greatly ease the
 306 process of maintaining and testing different combinations or Perl
 307 modules across development, staging, and production servers.  (The
 308 "relocatable Perl" feature can also be used to to run both the modules
 309 B<and> Perl itself from your home directory [or any other directory you
 310 chose]).
 311
 312
 313 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
 314
 315 This tutorial was built using the following resources. Please note that
 316 you may need to make adjustments for different environments and versions
 317 (note that trailing zeros in version numbers are not significant and may
 318 get dropped with some techniques for viewing them; for example, Catalyst
 319 v5.80020 might show up as 5.8002):
 320
 321 =over 4
 322
 323 =item *
 324
 325 Debian 6 (Squeeze)
 326
 327 =item *
 328
 329 Catalyst v5.90002
 330
 331 =item *
 332
 333 Catalyst::Devel v1.34
 334
 335 =item *
 336
 337 DBIx::Class v0.08195
 338
 339 =item *
 340
 341 Catalyst::Model::DBIC::Schema v0.54
 342
 343 =item *
 344
 345 Template Toolkit v2.22
 346
 347
 348 =item *
 349
 350 HTML::FormFu -- v0.09004
 351
 352 =item *
 353
 354 B<NOTE:> You can check the versions you have installed with the
 355 following command (note the slash before the space):
 356
 357     perl -M<_mod_name_>\ 999
 358
 359 or:
 360
 361     perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
 362
 363 For example:
 364
 365     perl -MCatalyst::Devel\ 999
 366
 367 or:
 368
 369     perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
 370
 371 =item *
 372
 373 This tutorial will show URLs in the format of C<http://localhost:3000>,
 374 but if you are running your web browser from outside the Tutorial
 375 Virtual Machine, you will want to substitute the IP address of your VM
 376 for the C<localhost> in the URLs (again, you can get the IP address for
 377 eth0 from the C<ifconfig> command).  For example, if your VM has an
 378 IP address of 192.168.245.128, you will want to use a base URL of
 379 C<http://192.168.245.128:3000>.  Note that the development server
 380 defaults to port 3000 (you can change with with the "-p" option on the
 381 command line.
 382
 383 B<Please Note:> Depending on the web browser you are using, you might need
 384 to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
 385 testing your application at various points (see
 386 L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
 387 list of options for each browser).  Also, the C<-k> keepalive option to
 388 the development server can be necessary with some browsers (especially
 389 Internet Explorer).
 390
 391 =back
 392
 393
 394 =head1 DATABASES
 395
 396 This tutorial will primarily focus on SQLite because of its simplicity
 397 of installation and use; however, modifications in the script required
 398 to support MySQL and PostgreSQL will be presented in the Appendix.
 399
 400 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
 401 that applications become much more database independent.  As such, you
 402 will notice that only the C<.sql> files used to initialize the database
 403 change between database systems: most of the code generally remains the
 404 same.
 405
 406
 407 You can jump to the next chapter of the tutorial here:
 408 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
 409
 410
 411 =head1 AUTHOR
 412
 413 Kennedy Clark, C<hkclark@gmail.com>
 414
 415 Please report any errors, issues or suggestions to the author.  The
 416 most recent version of the Catalyst Tutorial can be found at
 417 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
 418
 419 Copyright 2006-2010, Kennedy Clark, under the
 420 Creative Commons Attribution Share-Alike License Version 3.0
 421 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).