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:
215 Type "C<ifconfig>" to get the IP address assigned to the virtual
216 machine. You should get output along the lines of:
218 eth0 Link encap:Ethernet HWaddr 00:01:22:3b:45:69
219 inet addr:192.168.245.128 Bcast:192.168.245.255 Mask:255.255.255.0
222 You want the IP address on the second line below the C<eth0> interface.
223 The image it design to automatically use a DHCP-assigned address.
225 If DHCP is not working or is not available in your location, most
226 virtual machine "host" environments let's you select between one of
227 several different types of networking between the "guest" and the "host"
234 The Tutorial Virtual Machine defaults to "Bridged" -- this should result
235 in the VM acting like another device on your network that will get a
236 different DHCP IP address than the host machine. The advantage of this
237 approach, is that you can easily SSH and web browse to the guest virtual
240 In some environments, you might have better luck with "NAT" (Network
241 Address Translation) mode. With this configuration, the guest VM shares
242 the same IP address as the host machine. The downside of the approach
243 is that special configuration is required if you want to be able to SSH
244 or web browse to the guest VM (some virtual machine host environments
245 let you configure a "static NAT" or "port forwarding" to reach the guest
248 "Local host only" mode let's the guest VM and the host machine talk on a
249 "private subnet" that other devices in your network cannot reach.
251 Consult the documentation on your virtual machine host environment for
252 help configuring the options above.
256 B<From your main desktop machine>, open an SSH client and connect to
257 the IP address found in the previous step. You should get a login
258 prompt (accept the SSH key). Login with the same username and password:
259 B<root> / B<catalyst>
263 B<Using the SSH session>, change to the sample code directory for
264 Chapter 3 included with the Tutorial Virtual Machine and start the
265 Catalyst Development Server:
268 $ perl scripts/myapp_server -r
272 B<From your main desktop machine>, open a web browser and go to
273 B<http://A.B.C.D:3000/>, where C<A.B.C.D> is the IP address to your
274 virtual machine that you looked up in Step 5. For example, if your
275 virtual machine is using the IP address C<192.168.0.21>, you would put
276 the following URL into your web browser:
278 http://192.168.0.21:3000/
280 Make sure you don't forget the B<:3000> to use port 3000 instead of the
281 usual port 80 that is used by HTTP by default.
283 You should get a Catalyst Welcome Screen. If you do, feel free to jump
284 right in to L<Chapter 2|Catalyst::Manual::Tutorial::02_CatalystBasics>
285 of the tutorial. If you don't go get the Catalyst Welcome Screen, go
286 back and carefully check each of the steps above.
290 B<Optional:> The VI/VIM editor is already installed on the Tutorial
291 Virtual Machine. In order to reduce the size of the download, Emacs is
292 not pre-installed. Since people obviously have very strong opinions
293 about which editor is best, :-) Debian fortunately make it very easy to
296 $ aptitude install emacs
301 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
303 This tutorial was built using the following resources. Please note that
304 you may need to make adjustments for different environments and versions
305 (note that trailing zeros in version numbers are not significant and may
306 get dropped with some techniques for viewing them; for example, Catalyst
307 v5.80020 might show up as 5.8002):
321 Catalyst::Devel v1.34
329 Catalyst::Model::DBIC::Schema v0.54
333 Template Toolkit v2.22
338 HTML::FormFu -- v0.09004
342 B<NOTE:> You can check the versions you have installed with the
343 following command (note the slash before the space):
345 perl -M<_mod_name_>\ 999
349 perl -M<_mod_name_> -e 'print "$<_mod_name_>::VERSION\n"'
353 perl -MCatalyst::Devel\ 999
357 perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";'
361 This tutorial will show URLs in the format of C<http://localhost:3000>,
362 but if you are running your web browser from outside the Tutorial
363 Virtual Machine, you will want to substitute the IP address of your VM
364 for the C<localhost> in the URLs (again, you can get the IP address for
365 eth0 from the C<ifconfig> command). For example, if your VM has an
366 IP address of 192.168.245.128, you will want to use a base URL of
367 C<http://192.168.245.128:3000>. Note that the development server
368 defaults to port 3000 (you can change with with the "-p" option on the
371 B<Please Note:> Depending on the web browser you are using, you might need
372 to hit C<Shift+Reload> or C<Ctrl+Reload> to pull a fresh page when
373 testing your application at various points (see
374 L<http://en.wikipedia.org/wiki/Bypass_your_cache> for a comprehensive
375 list of options for each browser). Also, the C<-k> keepalive option to
376 the development server can be necessary with some browsers (especially
384 This tutorial will primarily focus on SQLite because of its simplicity
385 of installation and use; however, modifications in the script required
386 to support MySQL and PostgreSQL will be presented in the Appendix.
388 B<Note:> One of the advantages of using tools like Catalyst and DBIC is
389 that applications become much more database independent. As such, you
390 will notice that only the C<.sql> files used to initialize the database
391 change between database systems: most of the code generally remains the
397 Kennedy Clark, C<hkclark@gmail.com>
399 Please report any errors, issues or suggestions to the author. The
400 most recent version of the Catalyst Tutorial can be found at
401 L<http://dev.catalyst.perl.org/repos/Catalyst/Catalyst-Manual/5.80/trunk/lib/Catalyst/Manual/Tutorial/>.
403 Copyright 2006-2010, Kennedy Clark, under the
404 Creative Commons Attribution Share-Alike License Version 3.0
405 (L<http://creativecommons.org/licenses/by-sa/3.0/us/>).