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 svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ CatalystTutorial
75 This will download the most recent code for each chapter of the
76 tutorial into the CatalystTutorial directory on your machine.
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.>
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.
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:
100 cpan Task::Catalyst::Tutorial
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.
106 Subjects covered by the tutorial include:
112 A simple application that lists and adds books.
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
122 How to write CRUD (Create, Read, Update, and Delete) operations in
127 Authentication ("auth").
131 Role-based authorization ("authz").
135 Attempts to provide an example showing current (5.9) Catalyst
140 The use of Template Toolkit (TT).
144 Useful techniques for troubleshooting and debugging Catalyst
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
157 The use of L<HTML::FormFu> or L<HTML::FormHandler>
158 for automated form processing and validation.
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
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?
183 =head1 STARTING WITH THE TUTORIAL VIRTUAL MACHINE
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/>.
194 Uncompress the image:
196 tar zxvf CatalystTutorial.tgz
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/>.
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:
216 Type "C<ifconfig>" to get the IP address assigned to the virtual
217 machine. You should get output along the lines of:
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
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.
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"
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
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
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.
252 Consult the documentation on your virtual machine host environment for
253 help configuring the options above.
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>
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:
269 $ perl scripts/myapp_server -r
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:
279 http://192.168.0.21:3000/
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.
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.
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
297 $ aptitude install emacs
302 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
304 This tutorial was built using the following resources. Please note that
305 you may need to make adjustments for different environments and versions
306 (note that trailing zeros in version numbers are not significant and may
307 get dropped with some techniques for viewing them; for example, Catalyst
308 v5.80020 might show up as 5.8002):
322 Catalyst::Devel v1.34
330 Catalyst::Model::DBIC::Schema v0.54
334 Template Toolkit v2.22
339 HTML::FormFu -- v0.09004
343 B<NOTE:> You can check the versions you have installed with the
344 following command (note the slash before the space):
346 perl -M<_mod_name_>\ 999
350 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
354 perl -MCatalyst::Devel\ 999
358 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
362 This tutorial will show URLs in the format of C<http://localhost:3000>,
363 but if you are running your web browser from outside the Tutorial
364 Virtual Machine, you will want to substitute the IP address of your VM
365 for the C<localhost> in the URLs (again, you can get the IP address for
366 eth0 from the C<ifconfig> command). For example, if your VM has an
367 IP address of 192.168.245.128, you will want to use a base URL of
368 C<http://192.168.245.128:3000>. Note that the development server
369 defaults to port 3000 (you can change with with the "-p" option on the
372 B<Please Note:> Depending on the web browser you are using, you might need
373 to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
374 testing your application at various points (see
375 L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
376 list of options for each browser). Also, the C<-k> keepalive option to
377 the development server can be necessary with some browsers (especially
385 This tutorial will primarily focus on SQLite because of its simplicity
386 of installation and use; however, modifications in the script required
387 to support MySQL and PostgreSQL will be presented in the Appendix.
389 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
390 that applications become much more database independent. As such, you
391 will notice that only the C<.sql> files used to initialize the database
392 change between database systems: most of the code generally remains the
396 You can jump to the next chapter of the tutorial here:
397 L<Catalyst Basics|Catalyst::Manual::Tutorial::02_CatalystBasics>
402 Kennedy Clark, C<hkclark@gmail.com>
404 Please report any errors, issues or suggestions to the author. The
405 most recent version of the Catalyst Tutorial can be found at
406 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
408 Copyright 2006-2010, Kennedy Clark, under the
409 Creative Commons Attribution Share-Alike License Version 3.0
410 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).