X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FTutorial%2FIntro.pod;fp=lib%2FCatalyst%2FManual%2FTutorial%2FTutorial%2FIntro.pod;h=524bcf22cca8c58befdb89cf0c1b9b3ec28ced15;hp=0000000000000000000000000000000000000000;hb=d442cc9fbdf45a28fe02f13552f44e3e2f7ec22e;hpb=4be096acef2b81af64442da618294f69630029a3 diff --git a/lib/Catalyst/Manual/Tutorial/Tutorial/Intro.pod b/lib/Catalyst/Manual/Tutorial/Tutorial/Intro.pod new file mode 100644 index 0000000..524bcf2 --- /dev/null +++ b/lib/Catalyst/Manual/Tutorial/Tutorial/Intro.pod @@ -0,0 +1,353 @@ +=head1 NAME + +Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction + + +=head1 OVERVIEW + +This is B of the Catalyst Tutorial. + +L + +=over 4 + +=item 1 + +B + +=item 2 + +L + +=item 3 + +L + +=item 4 + +L + +=item 5 + +L + +=item 6 + +L + +=item 7 + +L + +=item 8 + +L + +=item 9 + +L + +=back + +=head1 DESCRIPTION + +This tutorial provides a multipart introduction to the Catalyst web +framework. It seeks to provide a rapid overview of many of its most +commonly used features. The focus is on the real-world best practices +required in the construction of nearly all Catalyst applications. + +Although the primary target of the tutorial is users new to the Catalyst +framework, experienced users may wish to review specific sections (for +example, how to use DBIC for their model classes or how to add +authentication and authorization to an existing application). + +You can obtain the code for all the tutorial examples from the +catalyst subversion repository by issuing the command: + + svn co http://dev.catalyst.perl.org/repos/Catalyst/tags/examples/Tutorial/MyApp/5.7/ CatalystTutorial + +This will download the current code for each tutorial chapter in the +CatalystTutorial directory. Each example application directory has +the same name as the tutorial chapter. + +Additionally, if you're reading this manual online, you can download +the manual, the example program, and all the necessary dependencies to +your local machine by installing the C +distribution from CPAN: + + cpan Task::Catalyst::Tutorial + +This will also test to make sure the dependencies are working. If you +have trouble installing these, please ask for help on the #catalyst +IRC channel, or the Catalyst mailing list. + +Subjects covered include: + +=over 4 + +=item * + +A simple application that lists and adds books. + +=item * + +The use of L (DBIC) for the model. + +=item * + +How to write CRUD (Create, Read, Update, and Delete) operations in +Catalyst. + +=item * + +Authentication ("auth"). + +=item * + +Role-based authorization ("authz"). + +=item * + +Attempts to provide an example showing current (5.7XXX) Catalyst +practices. For example, the use of +L, +DBIC, L +with C, the use of C +vs. C, etc. + +=item * + +The use of Template Toolkit (TT) and the +L +view helper. + +=item * + +Useful techniques for troubleshooting and debugging Catalyst +applications. + +=item * + +The use of SQLite as a database (with code also provided for MySQL and +PostgreSQL). + +=item * + +The use of L for automated form processing +and validation. + +=back + +This tutorial makes the learning process its main priority. For +example, the level of comments in the code found here would likely be +considered excessive in a "normal project". Because of their contextual +value, this tutorial will generally favor inline comments over a +separate discussion in the text. It also deliberately tries to +demonstrate multiple approaches to various features (in general, you +should try to be as consistent as possible with your own production +code). + +Furthermore, this tutorial tries to minimize the number of controllers, +models, TT templates, and database tables. Although this does result in +things being a bit contrived at times, the concepts should be applicable +to more complex environments. More complete and complicated example +applications can be found in the C area of the Catalyst +Subversion repository at +L. + +B There are a variety of other introductory materials available +through the Catalyst web site and at +L and +L. + +=head1 VERSIONS AND CONVENTIONS USED IN THIS TUTORIAL + +This tutorial was built using the following resources. Please note that +you may need to make adjustments for different environments and +versions: + +=over 4 + +=item * + +OS = CentOS 4 Linux (RHEL 4) + +=item * + +Catalyst v5.6902 + +=item * + +DBIx::Class v0.06003 + +=item * + +Catalyst Plugins + +The plugins used in this tutorial all have sufficiently stable APIs that +you shouldn't need to worry about versions. However, there could be +cases where the tutorial is affected by what version of plugins you +use. This tutorial has been tested against the following set of plugins: + +=over 4 + +=item * + +Catalyst::Plugin::Authentication -- 0.09 + +=item * + +Catalyst::Plugin::Authentication::Store::DBIC -- 0.07 + +=item * + +Catalyst::Plugin::Authorization::ACL -- 0.08 + +=item * + +Catalyst::Plugin::Authorization::Roles -- 0.04 + +=item * + +Catalyst::Plugin::ConfigLoader -- 0.13 + +=item * + +Catalyst::Plugin::HTML::Widget -- 1.1 + +=item * + +Catalyst::Plugin::Session -- 0.12 + +=item * + +Catalyst::Plugin::Session::State::Cookie -- 0.05 + +=item * + +Catalyst::Plugin::Session::Store::FastMmap -- 0.02 + +=item * + +Catalyst::Plugin::StackTrace -- 0.06 + +=item * + +Catalyst::Plugin::Static::Simple -- 0.14 + +=back + +=item * + +Since the web browser is being used on the same box where Perl and the +Catalyst development server is running, the URL of +C will be used (the Catalyst development server +defaults to port 3000). If you are running Perl on a different box than +where your web browser is located (or using a different port number via +the C<-p> I option to the development server), then you +will need to update the URL you use accordingly. + +=item * + +Depending on the web browser you are using, you might need to hit +C to pull a fresh page when testing your application at +various points. Also, the C<-k> keepalive option to the development +server can be necessary with some browsers (especially Internet +Explorer). + +=back + +=head1 CATALYST INSTALLATION + +Unfortunately, one of the most daunting tasks faced by newcomers to +Catalyst is getting it installed. Although a compelling strength of +Catalyst is that it can easily make use of many of the modules in the +vast repository that is CPAN, this can result in initial installations +that are both time consuming and frustrating. However, there are a +growing number of methods that can dramatically ease this undertaking. +Of these, the following are likely to be applicable to the largest +number of potential new users: + +=over 4 + +=item * + +Matt Trout's C + +Available at L, +C can be a quick and painless way to get Catalyst up and +running. Just download the script from the link above and type C. + +=item * + +Chris Laco's CatInABox + +Download the tarball from +L and unpack it +on your machine. Depending on your OS platform, either run C +or C. + +=item * + +Pre-Built VMWare Images + +Under the VMWare community program, work is ongoing to develop a number +of VMWare images where an entire Catalyst development environment has +already been installed, complete with database engines and a full +complement of Catalyst plugins. + +=back + +For additional information and recommendations on Catalyst installation, +please refer to +L. + +B Step-by-step instructions to replicate the environment on +which this tutorial was developed can be found at +L. +Using these instructions, you should be able to build a complete CentOS +4.X server with Catalyst and all the plugins required to run this +tutorial. + +=head1 DATABASES + +This tutorial will primarily focus on SQLite because of its simplicity +of installation and use; however, modifications in the script required +to support MySQL and PostgreSQL will be presented in Appendix 2. + +B One of the advantages of the MVC design patterns is that +applications become much more database independent. As such, you will +notice that only the C<.sql> files used to initialize the database +change between database systems: the Catalyst code generally remains the +same. + +=head1 WHERE TO GET WORKING CODE + +Each part of the tutorial has complete code available in the main +Catalyst Subversion repository (see the note at the beginning of each +part for the appropriate svn command to use). Additionally, the final +code is available as a ready-to-run tarball at +L. + +B You can run the test cases for the final code with the following +commands: + + wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz + tar zxvf MyApp.tgz + cd MyApp + CATALYST_DEBUG=0 prove --lib lib t + + +=head1 AUTHOR + +Kennedy Clark, C + +Please report any errors, issues or suggestions to the author. The +most recent version of the Catalyst Tutorial can be found at +L. + +Copyright 2006, Kennedy Clark, under Creative Commons License +(L). + +