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