3 Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction
8 This is B<Part 2 of 10> for the Catalyst tutorial.
10 L<Tutorial Overview|Catalyst::Manual::Tutorial>
20 L<Catalyst Basics|Catalyst::Manual::Tutorial::CatalystBasics>
24 L<More Catalyst Basics|Catalyst::Manual::Tutorial::MoreCatalystBasics>
28 L<Basic CRUD|Catalyst::Manual::Tutorial::BasicCRUD>
32 L<Authentication|Catalyst::Manual::Tutorial::Authentication>
36 L<Authorization|Catalyst::Manual::Tutorial::Authorization>
40 L<Debugging|Catalyst::Manual::Tutorial::Debugging>
44 L<Testing|Catalyst::Manual::Tutorial::Testing>
48 L<Advanced CRUD|Catalyst::Manual::Tutorial::AdvancedCRUD>
52 L<Appendices|Catalyst::Manual::Tutorial::Appendices>
59 This tutorial provides a multipart 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, or form
70 You can obtain the code for all the tutorial examples from the
71 catalyst subversion repository by issuing the command:
73 svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/ CatalystTutorial
75 This will download the current code for each tutorial chapter in the
76 CatalystTutorial directory. Each example application directory has
77 the same name as the tutorial chapter.
79 B<These reference implementations are provided so that when you follow
80 the tutorial, you can use the code from the subversion repository to
81 ensure that your system is set up correctly, and that you have not
82 inadvertently made any typographic errors, or accidentally skipped
83 part of the tutorial.>
85 Additionally, if you're reading this manual online, you can download
86 the example program and all the necessary dependencies to
87 your local machine by installing the C<Task::Catalyst::Tutorial>
88 distribution from CPAN:
90 cpan Task::Catalyst::Tutorial
92 This will also test to make sure the dependencies are working. If you
93 have trouble installing these, please ask for help on the #catalyst
94 IRC channel, or the Catalyst mailing list.
96 Subjects covered include:
102 A simple application that lists and adds books.
106 The use of L<DBIx::Class|DBIx::Class> (DBIC) for the model.
110 How to write CRUD (Create, Read, Update, and Delete) operations in
115 Authentication ("auth").
119 Role-based authorization ("authz").
123 Attempts to provide an example showing current (5.7XXX) Catalyst
124 practices. For example, the use of
125 L<Catalyst::Action::RenderView|Catalyst::Action::RenderView>,
126 DBIC, L<Catalyst::Plugin::ConfigLoader|Catalyst::Plugin::ConfigLoader>
127 with C<myapp.yml>, the use of C<lib/MyApp/Controller/Root.pm>
128 vs. C<lib/MyApp.pm>, etc.
132 The use of Template Toolkit (TT) and the
133 L<Catalyst::Helper::View::TTSite|Catalyst::Helper::View::TTSite>
138 Useful techniques for troubleshooting and debugging Catalyst
143 The use of SQLite as a database (with code also provided for MySQL and
148 The use of L<HTML::FormFu|HTML::FormFu> for automated form processing
153 This tutorial makes the learning process its main priority. For
154 example, the level of comments in the code found here would likely be
155 considered excessive in a "normal project." Because of their contextual
156 value, this tutorial will generally favor inline comments over a
157 separate discussion in the text. It also deliberately tries to
158 demonstrate multiple approaches to various features (in general, you
159 should try to be as consistent as possible with your own production
162 Furthermore, this tutorial tries to minimize the number of controllers,
163 models, TT templates, and database tables. Although this does result in
164 things being a bit contrived at times, the concepts should be applicable
165 to more complex environments. More complete and complicated example
166 applications can be found in the C<examples> area of the Catalyst
167 Subversion repository at
168 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/>.
170 B<Note:> There are a variety of other introductory materials available
171 through the Catalyst web site and at
172 L<http://dev.catalyst.perl.org/wiki/UserIntroductions> and
173 L<http://dev.catalyst.perl.org/>.
175 =head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL
177 This tutorial was built using the following resources. Please note that
178 you may need to make adjustments for different environments and
185 Ubuntu 8.04 Hardy Heron
193 Catalyst::Devel v1.03
203 The plugins used in this tutorial all have sufficiently stable APIs that
204 you shouldn't need to worry about versions. However, there could be
205 cases where the tutorial is affected by what version of plugins you
206 use. This tutorial has been tested against the following set of plugins:
212 Catalyst::Plugin::Authentication -- v0.10002
216 Catalyst::Plugin::Authentication::Store::DBIC -- v0.09
220 Catalyst::Plugin::Authorization::ACL -- v0.08
224 Catalyst::Plugin::Authorization::Roles -- v0.05
228 Catalyst::Plugin::ConfigLoader -- v0.17
232 Catalyst::Plugin::Session -- v0.18
236 Catalyst::Plugin::Session::State::Cookie -- v0.08
240 Catalyst::Plugin::Session::Store::FastMmap -- v0.03
244 Catalyst::Plugin::StackTrace -- v0.06
248 Catalyst::Plugin::Static::Simple -- v0.20
254 Since the web browser is being used on the same box where Perl and the
255 Catalyst development server is running, the URL of
256 C<http://localhost:3000> will be used (the Catalyst development server
257 defaults to port 3000). If you are running Perl on a different box than
258 where your web browser is located (or using a different port number via
259 the C<-p> I<port_number> option to the development server), then you
260 will need to update the URL you use accordingly.
264 Depending on the web browser you are using, you might need to hit
265 C<Shift+Reload> to pull a fresh page when testing your application at
266 various points. Also, the C<-k> keepalive option to the development
267 server can be necessary with some browsers (especially Internet
272 =head1 CATALYST INSTALLATION
274 If approach in the wrong manner, it can be a daunting tasks to get
275 Catalyst initally installed. Although a compelling strength of
276 Catalyst is that it makes use of many of the modules in the
277 vast repository that is CPAN, this can complicate the installation
278 process. However, there are a growing number of methods
279 that can dramatically ease this undertaking. Of these, the following
280 are likely to be applicable to the largest number of potential new
289 Given the popularity of Ubuntu and it's ease of use, Ubuntu can be
290 a great way for newcomers to experiment with Catalyst. Because it
291 is a "live CD," you can simply boot from the CD, run a few commands,
292 and you should have a fully functional environment in which to do
293 this tutorial in a matter of minutes.
299 Download Ubuntu 8.04 (aka, Hardy Heron) and boot from the CD and/or
300 image file, select your language, and then "Try Ubuntu without any
301 changes to your computer."
305 Open a terminal session.
309 Add the 'universe' repositories:
311 sudo vi /etc/apt/sources.list
313 And remove the comments from the lines under the comments about the
314 'universe' repositories.
322 sudo apt-get install sqlite3 libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl
324 Accept all of the dependencies. Done.
330 Matt Trout's C<cat-install>
332 Available at L<http://www.shadowcatsystems.co.uk/static/cat-install>,
333 C<cat-install> can be a quick and painless way to get Catalyst up and
334 running. Just download the script from the link above and type C<perl
339 Chris Laco's CatInABox
341 Download the tarball from
342 L<http://handelframework.com/downloads/CatInABox.tar.gz> and unpack it
343 on your machine. Depending on your OS platform, either run C<start.bat>
348 Pre-Built VMWare Images
350 Under the VMWare community program, work is ongoing to develop a number
351 of VMWare images where an entire Catalyst development environment has
352 already been installed, complete with database engines and a full
353 complement of Catalyst plugins.
357 For additional information and recommendations on Catalyst installation,
359 L<Catalyst::Manual::Installation|Catalyst::Manual::Installation>.
361 B<NOTE:> Step-by-step instructions to replicate the environment on
362 which this tutorial was developed can be found at
363 L<Catalyst::Manual::Installation::CentOS4|Catalyst::Manual::Installation::CentOS4>.
364 Using these instructions, you should be able to build a complete CentOS
365 4.X server with Catalyst and all the plugins required to run this
370 This tutorial will primarily focus on SQLite because of its simplicity
371 of installation and use; however, modifications in the script required
372 to support MySQL and PostgreSQL will be presented in Appendix 2.
374 B<Note:> One of the advantages of the MVC design patterns is that
375 applications become much more database independent. As such, you will
376 notice that only the C<.sql> files used to initialize the database
377 change between database systems: the Catalyst code generally remains the
380 =head1 WHERE TO GET WORKING CODE
382 Each part of the tutorial has complete code available in the main
383 Catalyst Subversion repository (see the note at the beginning of each
384 part for the appropriate svn command to use). Additionally, the final
385 code is available as a ready-to-run tarball at
386 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz>.
388 B<NOTE:> You can run the test cases for the final code with the following
391 wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz
394 CATALYST_DEBUG=0 prove --lib lib t
399 Kennedy Clark, C<hkclark@gmail.com>
401 Please report any errors, issues or suggestions to the author. The
402 most recent version of the Catalyst Tutorial can be found at
403 L<http://dev.catalyst.perl.org/repos/Catalyst/trunk/Catalyst-Manual/lib/Catalyst/Manual/Tutorial/>.
405 Copyright 2006, Kennedy Clark, under Creative Commons License
406 (L<http://creativecommons.org/licenses/by-nc-sa/2.5/>).