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:> The VI/VIM editor is already installed on the Tutorial
317 Virtual Machine. In order to reduce the size of the download, Emacs is
318 not pre-installed. Since people obviously have very strong opinions
319 about which editor is best, :-) Debian fortunately make it very easy to
322 $ aptitude install emacs
327 You may note that the Tutorial Virtual Machine uses L<local::lib> so
328 that the Perl modules are run from ~/perl5 (in this case, /root/perl5)
329 vs. the usual location of your "system Perl". We recommend that you
330 also consider using this very handy module. It can greatly ease the
331 process of maintaining and testing different combinations or Perl
332 modules across development, staging, and production servers. (The
333 "relocatable Perl" feature can also be used to to run both the modules
334 B<and> Perl itself from your home directory [or any other directory you
337 B<Note>: Please provide feedback on how the Virtual Machine approach for
338 the tutorial works for you. If you have suggestions or comments, you
339 can reach the author through the email address at the bottom of this
340 page or via an RT ticket at
341 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
345 =head2 Sorting Out Virtual Machine Network-Related Issues
347 In general, using a virtual machine to work through the tutorial is
348 *much* easier than trying to do it in other environments, especially if
349 you are new to Catalyst (or Perl or CPAN or ...). However, it's
350 possible that you could run into a few network-related issues. The good
351 news is that there is lots of information about the issue available via
352 search engines on the Internet. Here is some background information to
355 In Step 5 of the prior section above, we assumed that a "Bridged Mode"
356 configuration and DHCP will work (it should for most people). If DHCP
357 is not working or is not available in your location, most virtual
358 machine "host" environments let you select between one of several
359 different types of networking between the "guest" and the "host"
366 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
367 in the VM acting like another device on your network that will get a
368 different DHCP IP address than the host machine. The advantage of this
369 approach, is that you can easily SSH and web browse to the guest virtual
370 machine. In general, this is the best option if you want to be able to
371 boot up the VM and then use your SSH client and web browser from your
372 main machine to connect into the virtual machine.
374 In some environments, you might have better luck with "NAT" (Network
375 Address Translation) mode. With this configuration, the guest VM shares
376 the same IP address as the host machine. The downside of this approach
377 is that special configuration is required if you want to be able to SSH
378 or web browse to the guest VM. The NAT option should automatically
379 allow the VM "outbound connection" (e.g., to the Internet if you want to
380 install additional Debian packages), but it requires special
381 configuration if you want to get "inbound connections" that go from some
382 other machine (including the "host machine") into the VM. Some virtual
383 machine host environments let you configure a "static NAT" or "port
384 forwarding" to reach the guest OS, but others omit this functionality.
386 "Local host only" mode let's the guest VM and the host machine talk on a
387 "private subnet" that other devices in your network cannot reach. This
388 can work as long as you don't need to go from the VM to the Internet
389 (for example, to install other Debian packages).
391 Consult the documentation on your virtual machine host environment for
392 help configuring the options above. Here are some links that might
399 L<http://vmfaq.com/entry/34/>
403 L<http://www.vmware.com/support/pubs/player_pubs.html>
407 L<http://www.virtualbox.org/manual/ch06.html>
414 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
416 This tutorial was built using the following resources. Please note that
417 you may need to make adjustments for different environments and versions
418 (note that trailing zeros in version numbers are not significant and may
419 get dropped with some techniques for viewing them; for example, Catalyst
420 v5.80020 might show up as 5.8002):
434 Catalyst::Devel v1.34
442 Catalyst::Model::DBIC::Schema v0.54
446 Template Toolkit v2.22
451 HTML::FormFu -- v0.09004
455 B<NOTE:> You can check the versions you have installed with the
456 following command (note the slash before the space):
458 perl -M<_mod_name_>\ 999
462 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
466 perl -MCatalyst::Devel\ 999
470 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
474 This tutorial will show URLs in the format of C<http://localhost:3000>,
475 but if you are running your web browser from outside the Tutorial
476 Virtual Machine, you will want to substitute the IP address of your VM
477 for the C<localhost> in the URLs (again, you can get the IP address for
478 eth0 from the C<ifconfig> command). For example, if your VM has an
479 IP address of 192.168.0.12, you will want to use a base URL of
480 C<http://192.168.0.12:3000>. Note that the development server
481 defaults to port 3000 (you can change with with the "-p" option on the
484 B<Please Note:> Depending on the web browser you are using, you might
485 need to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
486 testing your application at various points (see
487 L<http://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache> for a
488 comprehensive list of options for each browser).
490 Also, the C<-k> B<keepalive option> to the development server can be
491 necessary with some browsers (B<especially Internet Explorer>).
498 This tutorial will primarily focus on SQLite because of its simplicity
499 of installation and use; however, modifications in the script required
500 to support MySQL and PostgreSQL will be presented in the Appendix.
502 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
503 that applications become much more database independent. As such, you
504 will notice that only the C<.sql> files used to initialize the database
505 change between database systems: most of the code generally remains the
509 You can jump to the next chapter of the tutorial here:
510 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
515 Kennedy Clark, C<hkclark@gmail.com>
517 Feel free to contact the author for any errors or suggestions, but the
518 best way to report issues is via the CPAN RT Bug system at
519 L<https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Manual>.
521 Copyright 2006-2011, Kennedy Clark, under the
522 Creative Commons Attribution Share-Alike License Version 3.0
523 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).