3 Catalyst::Manual::Tutorial::01_Intro - Catalyst Tutorial - Chapter 1: Introduction
8 This is B<Chapter 1 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::03_MoreCatalystBasics>
28 L<Basic CRUD|Catalyst::Manual::Tutorial::04_BasicCRUD>
32 L<Authentication|Catalyst::Manual::Tutorial::05_Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::06_Authorization>
40 L<Debugging|Catalyst::Manual::Tutorial::07_Debugging>
44 L<Testing|Catalyst::Manual::Tutorial::08_Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::09_AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::10_Appendices>
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.
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
70 The most recent code for the tutorial is included on the Tutorial Virtual
71 Machine you can download from:
73 L<http://cattut.shadowcat.co.uk/>
75 See L</STARTING WITH THE TUTORIAL VIRTUAL MACHINE> below for
76 instructions getting and using the VM.
78 Should you wish to download the code directly, you get pull it via the
79 following command (note: will probably be switching to git soon):
81 svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
83 This will download the most recent code for each chapter of the
84 tutorial into the CatalystTutorial directory on your machine.
86 These reference implementations are provided so that when you follow
87 the tutorial, you can use the code to ensure that your system is set up
88 correctly (which shouldn't be an issue if you use the Tutorial Virtual
89 Machine), :-) and that you have not inadvertently made any typographic
90 errors, or accidentally skipped part of the tutorial.
92 B<NOTE: You can use any Perl-supported OS and environment to run
93 Catalyst.> It should make little or no difference to Catalyst's
94 operation, B<but this tutorial has been written using the Debian-based
95 Tutorial Virtual Machine> that you can download and use to work through
96 the full tutorial step by step. B<WE STRONGLY RECOMMEND THAT YOU USE
97 THE VIRTUAL MACHINE IMAGE TO WORK THROUGH THE TUTORIAL> to avoid issues
98 that may crop up if you are working with a different configuration. We
99 have tested the Tutorial Virtual Machine to make sure all of the
100 examples work correctly, but it is hard to guarantee this on other
101 platforms and versions.
103 If you would prefer to install directly from CPAN and not use the
104 Tutorial Virtual machine, you can download the example program and all
105 the necessary dependencies to your local machine by installing the
106 C<Task::Catalyst::Tutorial> distribution:
108 cpan Task::Catalyst::Tutorial
110 This will also test to make sure the dependencies are working. If you
111 have trouble installing these, please ask for help on the #catalyst
112 IRC channel, or the Catalyst mailing list.
114 Subjects covered by the tutorial include:
120 A simple application that lists and adds books.
124 The use of L<DBIx::Class> (DBIC) for the model (including
125 some of the more advanced techniques you will probably want to use in
130 How to write CRUD (Create, Read, Update, and Delete) operations in
135 Authentication ("auth").
139 Role-based authorization ("authz").
143 Attempts to provide an example showing current (5.9) Catalyst
148 The use of Template Toolkit (TT).
152 Useful techniques for troubleshooting and debugging Catalyst
157 The use of SQLite as a database (with code also provided for MySQL and
158 PostgreSQL). (Note: Because we make use of the DBIx::Class Object
159 Relational Mapping [ORM] layer, out our application will be database
160 agnostic and can easily be used by any of the databases supported by
165 The use of L<HTML::FormFu> or L<HTML::FormHandler>
166 for automated form processing and validation.
170 This tutorial makes the learning process its main priority. For
171 example, the level of comments in the code found here would likely be
172 considered excessive in a "normal project." Because of their contextual
173 value, this tutorial will generally favor inline comments over a
174 separate discussion in the text. It also deliberately tries to
175 demonstrate multiple approaches to various features (in general, you
176 should try to be as consistent as possible with your own production
179 Furthermore, this tutorial tries to minimize the number of controllers,
180 models, TT templates, and database tables. Although this does result in
181 things being a bit contrived at times, the concepts should be applicable
182 to more complex environments. More complete and complicated example
183 applications can be found at
184 L<http://wiki.catalystframework.org/wiki/resources/catalystexamples> and
185 in the C<examples> area of the Catalyst Subversion repository at
186 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
189 =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
191 The steps below briefly outline how you can download the Tutorial
192 Virtual Machine. This document uses the term "host machine" to refer to
193 the physical machine where you will run the virtualization software and
194 boot up the VM. The terms "guest machine" or just "VM" refer to the
195 virtual machine itself -- the thing where you actually do the tutorial
196 (and that you boot up on the "host machine").
198 B<Note:> Throughout the tutorial, we will shows the UNIX shell prompt as
199 "C<$>". If you are using the Tutorial VM, the prompt will really be
200 "C<catalyst@catalyst:~$>" (where "C<~"> will change to show your
201 current directory), but we will keep it short and just use "C<$>".
208 Download a Tutorial Virtual Machine image from
209 L<http://cattut.shadowcat.co.uk/>
211 B<A big thanks to Shadowcat Systems for hosting the virtual machines>
212 B<(and everything else they do for the Perl community)!>
216 Uncompress the image on the "host machine":
218 MAINCOMPUTER:~$ tar zxvf CatalystTutorial.tgz
222 Boot the virtual machine using a tool like VMWare Player
223 L<http://www.vmware.com/products/player> or VirtualBox
224 L<http://www.virtualbox.org/>.
228 Once you get a login prompt, enter the username B<catalyst> and a
229 password for C<catalyst>. You should now be at a prompt that looks
232 catalyst login: catalyst
239 Type "C<ifconfig>" to get the IP address assigned to the virtual
240 machine. You should get output along the lines of:
242 eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
243 inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
246 You want the IP address on the second line below the C<eth0> interface.
247 The image it design to automatically use a DHCP-assigned address.
250 Try to ping this IP address from your "host machine" (main desktop):
253 MAINCOMPUTER:~$ ping 192.168.0.12
254 PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data.
255 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms
256 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms
260 B<Note:> The ping above is being originated B<from> your B<host machine>
261 (main desktop) and going B<to> your guest B<virtual machine>, not the
264 If you are not seeing a valid IP address or it's not responding to pings
265 (for example, you get error messages along the lines of "Request timed
266 out", "100% packet loss", or "Destination Host Unreachable"), there
267 could be a few network-related issues you might need to sort out. See
268 the section below L</Sorting Out Virtual Machine Network-Related Issues>
269 for additional information and troubleshooting advice.
271 B<Note:> Remember this IP address... you will be using it throughout the
277 B<From your main desktop machine>, open an SSH client and connect to the
278 IP address found in the previous step. You should get a login prompt
279 (accept the SSH key if you get a warning message about that). Login
280 with the same username and password as we used in Step 4: B<catalyst> /
283 catalyst login: catalyst
291 B<Using the SSH session>, change to the sample code directory for
292 Chapter 3 included with the Tutorial Virtual Machine and start the
293 Catalyst Development Server:
295 $ cd Final/Chapter03/MyApp
296 $ perl scripts/myapp_server
300 B<From your main desktop machine> (the "host machine"), open a web
301 browser and go to B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP
302 address to your virtual machine that you looked up in Step 5. For
303 example, if your virtual machine is using the IP address
304 C<192.168.0.12>, you would put the following URL into your web browser:
306 http://192.168.0.12:3000/
308 Make sure you don't forget the B<:3000> to use port 3000 instead of the
309 usual port 80 that is used by HTTP by default.
311 You should get a Catalyst Welcome Screen. If you do, feel free to jump
312 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
313 of the tutorial. If you don't go get the Catalyst Welcome Screen, go
314 back and carefully check each of the steps above.
318 B<Optional:> Also, to reduce download size, the Tutorial VM just
319 includes a minimal command-line environment. You are free to use
320 Debian's very capable C<apt> package manager to install other packages.
321 You will first want to pull the apt cache files with C<aptitude update>
322 (or C<apt-get update> if you prefer apt-get).
324 The VI/VIM editor is already installed on the Tutorial Virtual Machine.
325 In order to reduce the size of the download, Emacs is not pre-installed.
326 Since people obviously have very strong opinions about which editor is
327 best, :-) fortunately it's very easy to install Emacs:
329 $ sudo aptitude update
330 $ sudo aptitude install emacs
332 In general, it is expected that people will
333 boot up the Tutorial VM on their main desktop (the "host machine" using
334 the terminology above) and then use that main desktop machine to SSH and
335 web browse into the "guest VM" as they work through the tutorial. If
336 you wish to install X Windows (or any other packages), just use the
337 C<aptitude> (or C<apt-get>) Debian commands. For example, to install
338 X Windows with the Gnome desktop manager, you can do:
340 $ sudo aptitude update
341 $ sudo ptitude install gnome iceweasel
343 Or, if you prefer KDE:
345 $ sudo aptitude update
346 $ sudo aptitude install kde iceweasel
348 You can then start X Windows with:
356 You may note that the Tutorial Virtual Machine uses L<local::lib> so
357 that the Perl modules are run from ~/perl5 (in this case,
358 /home/catalyst/perl5) vs. the usual location of your "system Perl". We
359 recommend that you also consider using this very handy module. It can
360 greatly ease the process of maintaining and testing different
361 combinations or Perl modules across development, staging, and production
362 servers. (The "relocatable Perl" feature can also be used to to run
363 both the modules B<and> Perl itself from your home directory [or any
364 other directory you chose]).
366 B<Note>: Please provide feedback on how the Virtual Machine approach for
367 the tutorial works for you. If you have suggestions or comments, you
368 can reach the author through the email address at the bottom of this
369 page or via an RT ticket at
370 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
374 =head2 Sorting Out Virtual Machine Network-Related Issues
376 In general, using a virtual machine to work through the tutorial is
377 *much* easier than trying to do it in other environments, especially if
378 you are new to Catalyst (or Perl or CPAN or ...). However, it's
379 possible that you could run into a few network-related issues. The good
380 news is that there is lots of information about the issue available via
381 search engines on the Internet. Here is some background information to
384 In Step 5 of the prior section above, we assumed that a "Bridged Mode"
385 configuration and DHCP will work (it should for most people). If DHCP
386 is not working or is not available in your location, most virtual
387 machine "host" environments let you select between one of several
388 different types of networking between the "guest" and the "host"
395 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
396 in the VM acting like another device on your network that will get a
397 different DHCP IP address than the host machine. The advantage of this
398 approach, is that you can easily SSH and web browse to the guest virtual
399 machine. In general, this is the best option if you want to be able to
400 boot up the VM and then use your SSH client and web browser from your
401 main machine to connect into the virtual machine.
403 In some environments, you might have better luck with "NAT" (Network
404 Address Translation) mode. With this configuration, the guest VM shares
405 the same IP address as the host machine. The downside of this approach
406 is that special configuration is required if you want to be able to SSH
407 or web browse to the guest VM. The NAT option should automatically
408 allow the VM "outbound connection" (e.g., to the Internet if you want to
409 install additional Debian packages), but it requires special
410 configuration if you want to get "inbound connections" that go from some
411 other machine (including the "host machine") into the VM. Some virtual
412 machine host environments let you configure a "static NAT" or "port
413 forwarding" to reach the guest OS, but others omit this functionality.
415 "Local host only" mode let's the guest VM and the host machine talk on a
416 "private subnet" that other devices in your network cannot reach. This
417 can work as long as you don't need to go from the VM to the Internet
418 (for example, to install other Debian packages).
420 Consult the documentation on your virtual machine host environment for
421 help configuring the options above. Here are some links that might
428 L<http://vmfaq.com/entry/34/>
432 L<http://www.vmware.com/support/pubs/player_pubs.html>
436 L<http://www.virtualbox.org/manual/ch06.html>
443 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
445 This tutorial was built using the following resources. Please note that
446 you may need to make adjustments for different environments and versions
447 (note that trailing zeros in version numbers are not significant and may
448 get dropped with some techniques for viewing them; for example, Catalyst
449 v5.80020 might show up as 5.8002):
463 Catalyst::Devel v1.34
471 Catalyst::Model::DBIC::Schema v0.54
475 Template Toolkit v2.22
480 HTML::FormFu -- v0.09004
484 B<NOTE:> You can check the versions you have installed with the
485 following command (note the slash before the space):
487 perl -M<_mod_name_>\ 999
491 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
495 perl -MCatalyst::Devel\ 999
499 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
503 This tutorial will show URLs in the format of C<http://localhost:3000>,
504 but if you are running your web browser from outside the Tutorial
505 Virtual Machine, you will want to substitute the IP address of your VM
506 for the C<localhost> in the URLs (again, you can get the IP address for
507 eth0 from the C<ifconfig> command). For example, if your VM has an
508 IP address of 192.168.0.12, you will want to use a base URL of
509 C<http://192.168.0.12:3000>. Note that the development server
510 defaults to port 3000 (you can change with with the "-p" option on the
513 B<Please Note:> Depending on the web browser you are using, you might
514 need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
515 testing your application at various points (see
516 L<http://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache> for a
517 comprehensive list of options for each browser).
519 Also, the C<-k> B<keepalive option> to the development server can be
520 necessary with some browsers (B<especially Internet Explorer>).
527 This tutorial will primarily focus on SQLite because of its simplicity
528 of installation and use; however, modifications in the script required
529 to support MySQL and PostgreSQL will be presented in the Appendix.
531 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
532 that applications become much more database independent. As such, you
533 will notice that only the C<.sql> files used to initialize the database
534 change between database systems: most of the code generally remains the
538 You can jump to the next chapter of the tutorial here:
539 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
544 Kennedy Clark, C<hkclark@gmail.com>
546 Feel free to contact the author for any errors or suggestions, but the
547 best way to report issues is via the CPAN RT Bug system at
548 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
550 Copyright 2006-2011, Kennedy Clark, under the
551 Creative Commons Attribution Share-Alike License Version 3.0
552 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).