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").
197 B<Note:> Throughout the tutorial, we will shows the UNIX shell prompt
198 as "C<$>". If you are using Tutorial VM, the prompt will really be
199 "C<catalyst@catalyst:~#>", but we will keep it short (and also use "C<$>" in
200 lieu of "C<#>", since "C<#>" looks too much like a Perl comment).
207 Download a Tutorial Virtual Machine image from
208 L<http://cattut.shadowcat.co.uk/>
210 B<A big thanks to Shadowcat Systems for hosting the virtual machines>
211 B<(and everything else they do for the Perl community)!>
215 Uncompress the image on the "host machine":
217 MAINCOMPUTER:~$ tar zxvf CatalystTutorial.tgz
221 Boot the virtual machine using a tool like VMWare Player
222 L<http://www.vmware.com/products/player> or VirtualBox
223 L<http://www.virtualbox.org/>.
227 Once you get a login prompt, enter the username B<catalyst> and a
228 password for C<catalyst>. You should now be at a prompt that looks
231 catalyst login: catalyst
238 Type "C<ifconfig>" to get the IP address assigned to the virtual
239 machine. You should get output along the lines of:
241 eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
242 inet addr:192.168.0.12 Bcast:192.168.0.255 Mask:255.255.255.0
245 You want the IP address on the second line below the C<eth0> interface.
246 The image it design to automatically use a DHCP-assigned address.
249 Try to ping this IP address from your "host machine" (main desktop):
252 MAINCOMPUTER:~$ ping 192.168.0.12
253 PING 192.168.0.12 (192.168.0.12) 56(84) bytes of data.
254 64 bytes from 192.168.0.12: icmp_req=1 ttl=255 time=4.97 ms
255 64 bytes from 192.168.0.12: icmp_req=2 ttl=255 time=3.43 ms
259 B<Note:> The ping above is being originated B<from> your B<host machine>
260 (main desktop) and going B<to> your guest B<virtual machine>, not the
263 If you are not seeing a valid IP address or it's not responding to pings
264 (for example, you get error messages along the lines of "Request timed
265 out", "100% packet loss", or "Destination Host Unreachable"), there
266 could be a few network-related issues you might need to sort out. See
267 the section below L</Sorting Out Virtual Machine Network-Related Issues>
268 for additional information and troubleshooting advice.
270 B<Note:> Remember this IP address... you will be using it throughout the
276 B<From your main desktop machine>, open an SSH client and connect to the
277 IP address found in the previous step. You should get a login prompt
278 (accept the SSH key if you get a warning message about that). Login
279 with the same username and password as we used in Step 4: B<catalyst> /
282 catalyst login: catalyst
290 B<Using the SSH session>, change to the sample code directory for
291 Chapter 3 included with the Tutorial Virtual Machine and start the
292 Catalyst Development Server:
294 $ cd Final/Chapter03/MyApp
295 $ perl scripts/myapp_server
299 B<From your main desktop machine> (the "host machine"), open a web
300 browser and go to B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP
301 address to your virtual machine that you looked up in Step 5. For
302 example, if your virtual machine is using the IP address
303 C<192.168.0.12>, you would put the following URL into your web browser:
305 http://192.168.0.12:3000/
307 Make sure you don't forget the B<:3000> to use port 3000 instead of the
308 usual port 80 that is used by HTTP by default.
310 You should get a Catalyst Welcome Screen. If you do, feel free to jump
311 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
312 of the tutorial. If you don't go get the Catalyst Welcome Screen, go
313 back and carefully check each of the steps above.
317 B<Optional:> Also, to reduce download size, the Tutorial VM just
318 includes a minimal command-line environment. You are free to use
319 Debian's very capable C<apt> package manager to install other packages.
320 You will first want to pull the apt cache files with C<aptitude update>
321 (or C<apt-get update> if you prefer apt-get).
323 The VI/VIM editor is already installed on the Tutorial Virtual Machine.
324 In order to reduce the size of the download, Emacs is not pre-installed.
325 Since people obviously have very strong opinions about which editor is
326 best, :-) fortunately it's very easy to install Emacs:
329 $ aptitude install emacs
331 In general, it is expected that people will
332 boot up the Tutorial VM on their main desktop (the "host machine" using
333 the terminology above) and then use that main desktop machine to SSH and
334 web browse into the "guest VM" as they work through the tutorial. If
335 you wish to install X Windows (or any other packages), just use the
336 C<aptitude> (or C<apt-get>) Debian commands. For example, to install
337 X Windows with the Gnome desktop manager, you can do:
340 $ aptitude install gnome iceweasel
342 Or, if you prefer KDE:
345 $ aptitude install kde iceweasel
347 You can then start X Windows with:
355 You may note that the Tutorial Virtual Machine uses L<local::lib> so
356 that the Perl modules are run from ~/perl5 (in this case,
357 /home/catalyst/perl5) vs. the usual location of your "system Perl". We
358 recommend that you also consider using this very handy module. It can
359 greatly ease the process of maintaining and testing different
360 combinations or Perl modules across development, staging, and production
361 servers. (The "relocatable Perl" feature can also be used to to run
362 both the modules B<and> Perl itself from your home directory [or any
363 other directory you chose]).
365 B<Note>: Please provide feedback on how the Virtual Machine approach for
366 the tutorial works for you. If you have suggestions or comments, you
367 can reach the author through the email address at the bottom of this
368 page or via an RT ticket at
369 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
373 =head2 Sorting Out Virtual Machine Network-Related Issues
375 In general, using a virtual machine to work through the tutorial is
376 *much* easier than trying to do it in other environments, especially if
377 you are new to Catalyst (or Perl or CPAN or ...). However, it's
378 possible that you could run into a few network-related issues. The good
379 news is that there is lots of information about the issue available via
380 search engines on the Internet. Here is some background information to
383 In Step 5 of the prior section above, we assumed that a "Bridged Mode"
384 configuration and DHCP will work (it should for most people). If DHCP
385 is not working or is not available in your location, most virtual
386 machine "host" environments let you select between one of several
387 different types of networking between the "guest" and the "host"
394 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
395 in the VM acting like another device on your network that will get a
396 different DHCP IP address than the host machine. The advantage of this
397 approach, is that you can easily SSH and web browse to the guest virtual
398 machine. In general, this is the best option if you want to be able to
399 boot up the VM and then use your SSH client and web browser from your
400 main machine to connect into the virtual machine.
402 In some environments, you might have better luck with "NAT" (Network
403 Address Translation) mode. With this configuration, the guest VM shares
404 the same IP address as the host machine. The downside of this approach
405 is that special configuration is required if you want to be able to SSH
406 or web browse to the guest VM. The NAT option should automatically
407 allow the VM "outbound connection" (e.g., to the Internet if you want to
408 install additional Debian packages), but it requires special
409 configuration if you want to get "inbound connections" that go from some
410 other machine (including the "host machine") into the VM. Some virtual
411 machine host environments let you configure a "static NAT" or "port
412 forwarding" to reach the guest OS, but others omit this functionality.
414 "Local host only" mode let's the guest VM and the host machine talk on a
415 "private subnet" that other devices in your network cannot reach. This
416 can work as long as you don't need to go from the VM to the Internet
417 (for example, to install other Debian packages).
419 Consult the documentation on your virtual machine host environment for
420 help configuring the options above. Here are some links that might
427 L<http://vmfaq.com/entry/34/>
431 L<http://www.vmware.com/support/pubs/player_pubs.html>
435 L<http://www.virtualbox.org/manual/ch06.html>
442 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
444 This tutorial was built using the following resources. Please note that
445 you may need to make adjustments for different environments and versions
446 (note that trailing zeros in version numbers are not significant and may
447 get dropped with some techniques for viewing them; for example, Catalyst
448 v5.80020 might show up as 5.8002):
462 Catalyst::Devel v1.34
470 Catalyst::Model::DBIC::Schema v0.54
474 Template Toolkit v2.22
479 HTML::FormFu -- v0.09004
483 B<NOTE:> You can check the versions you have installed with the
484 following command (note the slash before the space):
486 perl -M<_mod_name_>\ 999
490 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
494 perl -MCatalyst::Devel\ 999
498 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
502 This tutorial will show URLs in the format of C<http://localhost:3000>,
503 but if you are running your web browser from outside the Tutorial
504 Virtual Machine, you will want to substitute the IP address of your VM
505 for the C<localhost> in the URLs (again, you can get the IP address for
506 eth0 from the C<ifconfig> command). For example, if your VM has an
507 IP address of 192.168.0.12, you will want to use a base URL of
508 C<http://192.168.0.12:3000>. Note that the development server
509 defaults to port 3000 (you can change with with the "-p" option on the
512 B<Please Note:> Depending on the web browser you are using, you might
513 need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
514 testing your application at various points (see
515 L<http://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache> for a
516 comprehensive list of options for each browser).
518 Also, the C<-k> B<keepalive option> to the development server can be
519 necessary with some browsers (B<especially Internet Explorer>).
526 This tutorial will primarily focus on SQLite because of its simplicity
527 of installation and use; however, modifications in the script required
528 to support MySQL and PostgreSQL will be presented in the Appendix.
530 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
531 that applications become much more database independent. As such, you
532 will notice that only the C<.sql> files used to initialize the database
533 change between database systems: most of the code generally remains the
537 You can jump to the next chapter of the tutorial here:
538 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
543 Kennedy Clark, C<hkclark@gmail.com>
545 Feel free to contact the author for any errors or suggestions, but the
546 best way to report issues is via the CPAN RT Bug system at
547 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
549 Copyright 2006-2011, Kennedy Clark, under the
550 Creative Commons Attribution Share-Alike License Version 3.0
551 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).