X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=blobdiff_plain;f=lib%2FCatalyst%2FManual%2FTutorial%2FIntro.pod;h=1a091a4b328e36cc731edc9b1fa462aeeeb8a84b;hp=b556adc800c12e66c5e49b0f94e3428f1c246900;hb=3b1fa91be1d89d2297aa9e8e83462344d9cd9820;hpb=3533daff0314522f79dff9c618da087568f1378c diff --git a/lib/Catalyst/Manual/Tutorial/Intro.pod b/lib/Catalyst/Manual/Tutorial/Intro.pod index b556adc..1a091a4 100644 --- a/lib/Catalyst/Manual/Tutorial/Intro.pod +++ b/lib/Catalyst/Manual/Tutorial/Intro.pod @@ -1,11 +1,11 @@ =head1 NAME -Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Part 1: Introduction +Catalyst::Manual::Tutorial::Intro - Catalyst Tutorial - Chapter 1: Introduction =head1 OVERVIEW -This is B for the Catalyst tutorial. +This is B for the Catalyst tutorial. L @@ -56,7 +56,7 @@ L =head1 DESCRIPTION -This tutorial provides a multipart introduction to the Catalyst web +This tutorial provides a multi-part 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. @@ -70,11 +70,10 @@ management). 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 + svn co http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/ 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. +This will download the most recent tarball for each chapter of the +tutorial into the CatalystTutorial directory on your machine. B -B It should make little or no difference to Catalyst's -operation, but this tutorial has been written using Ubuntu 8.04 -because that represents a quick and easy for most people to try out -Catalyst with virtually zero setup time and hassles. See the Catalyst -installation section below for more information. +operation, B because that represents a quick and easy for most people to +try out Catalyst with virtually zero setup time and hassles. Also, +the tutorial has been tested to work correctly with the versions of +Catalyst and all the supporting modules in Debian 5 (see "VERSIONS +AND CONVENTIONS USED IN THIS TUTORIAL" below for the specific versions +for some of the key modules), so B (for example, a module changed its +behavior in a newer version or a bug was introduced), B. See the "CATALYST INSTALLATION" +section below for more information. If you're reading this manual online, you can download the example program and all the necessary dependencies to your local machine by @@ -109,7 +115,9 @@ A simple application that lists and adds books. =item * -The use of L (DBIC) for the model. +The use of L (DBIC) for the model (including +some of the more advanced techniques you will probably want to use in +your applications). =item * @@ -130,14 +138,12 @@ 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 +with C, the use of C vs. C, etc. =item * -The use of Template Toolkit (TT) and the -L -view helper. +The use of Template Toolkit (TT). =item * @@ -173,10 +179,6 @@ 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 @@ -188,19 +190,19 @@ versions: =item * -Ubuntu 8.04 Hardy Heron +Debian 5 (Lenny) =item * -Catalyst v5.7011 +Catalyst v5.71000 =item * -Catalyst::Devel v1.03 +Catalyst::Devel v1.08 =item * -DBIx::Class v0.08008 +DBIx::Class v0.08012 =item * @@ -215,15 +217,7 @@ use. This tutorial has been tested against the following set of plugins: =item * -Catalyst::Plugin::Authentication -- v0.10002 - -=item * - -Catalyst::Plugin::Authentication::Store::DBIC -- v0.09 - -=item * - -Catalyst::Plugin::Authorization::ACL -- v0.08 +Catalyst::Plugin::Authentication -- v0.10006 =item * @@ -231,23 +225,23 @@ Catalyst::Plugin::Authorization::Roles -- v0.05 =item * -Catalyst::Plugin::ConfigLoader -- v0.17 +Catalyst::Plugin::ConfigLoader -- v0.20 =item * -Catalyst::Plugin::Session -- v0.18 +Catalyst::Plugin::Session -- v0.19 =item * -Catalyst::Plugin::Session::State::Cookie -- v0.08 +Catalyst::Plugin::Session::State::Cookie -- v0.09 =item * -Catalyst::Plugin::Session::Store::FastMmap -- v0.03 +Catalyst::Plugin::Session::Store::FastMmap -- v0.05 =item * -Catalyst::Plugin::StackTrace -- v0.06 +Catalyst::Plugin::StackTrace -- v0.08 =item * @@ -257,6 +251,14 @@ Catalyst::Plugin::Static::Simple -- v0.20 =item * +B You can check the versions you have installed with the +following command: + + perl -M<_mod_name_> -e '"print $<_mod_name_>::VERSION\n"' + +For example: + perl -MCatalyst::Plugin::StackTrace -e 'print "$Catalyst::Plugin::StackTrace::VERSION\n"' + 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 @@ -267,44 +269,214 @@ 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). +Depending on the web browser you are using, you might need to hit +C or C to pull a fresh page when testing +your application at various points (see +L for a comprehensive +list of options for each browser). Also, the C<-k> keepalive option +to the development server can be necessary with some browsers +(especially Internet Explorer). =back + =head1 CATALYST INSTALLATION -If approach in the wrong manner, it can be a daunting tasks to get -Catalyst initially installed. Although a compelling strength of -Catalyst is that it makes use of many of the modules in the -vast repository that is CPAN, this can complicate the installation -process. 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: +Although Catalyst installation has been a challenge in the past, the +good news is that there are a growing number of options to eliminate +(or at least dramatically simplify) this concern. Although a +compelling strength of Catalyst is that it makes use of many of the +modules in the vast repository that is CPAN, this can complicate the +installation process if you approach it in the wrong way. Consider +the following suggestions on the most common ways to get started with +a Catalyst development environment: + +=over 4 + +=item * + +Debian + +The Debian 5 live CD represents a great way for newcomers to +experiment with Catalyst. As a "live CD," you can simple boot from +the CD, run a few commands, and in a matter of minutes you should have +a fully function environment in which do this tutorial. B + +=over 4 + +=item * + +Download one of the ISO files from +L. +You can pick any one of the live CD variations will work, but +you may wish to consider the following points: + +=over 4 + +=item * + +"C" is probably the best all-around +option for most people because it includes many extra tools such as +the GCC compiler, therefore saving RAM (every package you need to +install when running from live CD consumes memory because RAM disk is +being used in lieu of real disk space). When initially booting under +this image, you may see some cryptic warning messages having to do +with various diagnostic tools it tries to load or enable, but you +should be able to safely ignore these. + +=item * + +"C" is a great option because of +its compact size, but you will probably need approximately 1 GB of RAM +in the computer where you will run the tutorial. Because the +"standard" live CD comes with with a minimal set of tools, we will +have to install extra packages (such as the GCC compiler), all of +which will require RAM when running from a live CD. + +=item * + +The other ISO images include different flavors of X-Windows desktop +managers. You can select one of these if you don't mind the larger +download size and prefer a graphical environment. Be aware that these +disks do not come with the extra tools found on the "rescue" image, so +you will need adequate RAM to be able to install them just as you +would under the "standard" image. B (If you are using one of the non- +graphical images discussed above, you can still use a graphical web +browser from another machine and point it to your Catalyst development +machine.) + +=back + +=item * + +Boot off the CD. + +=item * + +Select "C" from the initial boot menu. + +=item * + +Once the system has booted to a "C" prompt, enter the +following command to add the more current "unstable" package +repository: + + sudo vi /etc/apt/sources.list + +Add the following line to the bottom of this file: + + deb http://ftp.us.debian.org/debian/ unstable main + +If you are not familiar with VI, you can move to the bottom of this +file and press the "o" key to insert a new line and type the line +above. Then press the "Esc" key followed by a colon (":"), the +letters "wq" and then the "Enter" key. The rest of the tutorial will +assume that you know how to use some editor that is available from the +Linux command-line environment. + +=item * + +Install Catalyst: + + sudo aptitude update + sudo aptitude -y install sqlite3 libdbd-sqlite3-perl libcatalyst-perl \ + libcatalyst-modules-perl libconfig-general-perl libsql-translator-perl \ + libdatetime-perl libdatetime-format-mysql-perl libio-all-perl \ + libperl6-junction-perl + +Let it install (normally about a 30-second operaton) and you are +done. + +If you are using an image other than the "rescue" ISO, you will also need +to run the following command to install additional packages: + + sudo aptitude -y install gcc make libc6-dev + +If you are running from the Live CD, you probably also want to free up +some RAM disk space with the following: + + sudo aptitude clean + +NOTE: While the instructions above mention the Live CD because that +makes it easy for people new to Linux, you can obviously pick a +different Debian ISO image and install it to your hard drive. +Although there are many different ways to download and install Debian, +the "netinst" ISO image (such as "C" +represents a great option because it keeps your initial download small +(but still let's you install anything you want "over the network"). + +Here are some tips if you are running from a live CD and are running +out of disk space (which really means you are running out of RAM): =over 4 =item * +Always run "C" after you install new packages to +delete the original .deb files (the files installed B the .deb +package B remain available, just the .deb package itself is +deleted). + +=item * + +If you are installing modules from CPAN, you can free up some space +with "C". + +=item * + +If necessary, you can remove the cached package information with the +command "C". You can later pull this +information again via the command "C". + +=item * + +You can save a small amount of space by commenting out the lines in +C that reference "deb-src" and +"security.debian.org". If you have already done an "C" with these repositories enabled, you can use the tip in the +previous bullet to free the space up (and then do another "C"). + +=item * + +Although you can free up space by removing packages you installed +since you last booted (check out "C"), +don't bother trying to remove packages already available at the time +of boot. Instead of freeing up space, it will actual I some +space. (The live CD uses these "burn in" packages right from the CD +disk vs. first loading them on the virtual RAM disk. However, if you +remove them, the system has to update various files, something that +I consume some space on the virtual RAM disk.) + +=back + +=back + +=item * + Ubuntu -Given the popularity of Ubuntu and it's ease of use, Ubuntu can be -a great way for newcomers to experiment with Catalyst. Because it -is a "live CD," you can simply boot from the CD, run a few commands, -and you should have a fully functional environment in which to do -this tutorial in a matter of minutes. +Ubuntu is an extremely popular offshoot of Debian. It provides +cutting edge versions of many common tools, application and libraries +in an easy-to-run live CD configuration (and because a single download +option can be used for both live CD and install-to-disk usage, it +keeps your download options nice and simple). As with Debian 5, you +should be able to generate a fully function Catalyst environment in a +matter of minutes. Here are quick instructions on how to use Ubuntu +to prepare for the tutorial: =over 4 =item * -Download Ubuntu 8.04 (aka, Hardy Heron) Desktop edition and boot from -the CD and/or image file, select your language, and then "Try Ubuntu -without any changes to your computer." +Download the Ubuntu Desktop edition and boot from the CD and/or image +file, select your language, and then "Try Ubuntu without any changes +to your computer." =item * @@ -324,18 +496,19 @@ And remove the comments from the lines under the comments about the Install Catalyst: - sudo apt-get update - sudo apt-get install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl + sudo aptitude update + sudo aptitude install libdbd-sqlite3-perl libcatalyst-perl libcatalyst-modules-perl libconfig-general-perl -Accept all of the dependencies. Done. +Accept all of the dependencies. Done. -NOTE: If you are low on disk space after the above commands (use C -to tell), you can free up some space with -C (the Live CD uses memory for -disk space, so having a decent amount of memory will help). And, -while the instructions above mention the Live CD because that makes it -easy for people new to Linux, you can obviously also use one of the -options to install Ubuntu on your drive. +If you are running from the Live CD, you probably also want to free up +some disk space with the following: + + sudo aptitude clean + +NOTE: While the instructions above mention the live CD because that +makes it easy for people new to Linux, you can obviously also use one +of the options to install Ubuntu on your drive. =back @@ -343,28 +516,57 @@ options to install Ubuntu on your drive. 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. +Available at L, +C can be a fairly painless way to get Catalyst up and +running. Just download the script from the link above and type C. Depending on the speed of your Internet connection and +your computer, it will probably take 30 to 60 minutes to install because +it downloads, makes, compiles, and tests every module. But this is an +excellent way to automate the installation of all the latest modules +used by Catalyst from CPAN. + + +=item * + +Other Possibilities + +=over 4 + +=item * + +OpenBSD Packages + +The 2008 Advent Day 4 entry has more information on using OpenBSD +packages to quickly build a system: +L. + +=item * + +NetBSD Package Collection on Solaris + +The 2008 Advent Day 15 entry has more information on using C and +NetBSD packages on Solaris: +L. =item * -Chris Laco's CatInABox +CatInABox -Download the tarball from -L and unpack it -on your machine. Depending on your OS platform, either run C -or C. +You can get more information at +L +or L. =item * -Pre-Built VMWare Images +Frank Speiser's Amazon EC2 Catalyst SDK -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. +There are currently two flavors of publicly available Amazon Machine +Images (AMI) that include all the elements you'd need to begin +developing in a fully functional Catalyst environment within minutes. +See L +for more details. + +=back =back @@ -372,18 +574,12 @@ 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. +to support MySQL and PostgreSQL will be presented in Appendix. B One of the advantages of the MVC design patterns is that applications become much more database independent. As such, you will @@ -391,21 +587,47 @@ 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. +Each chapter of the tutorial has complete code available as a tarball in +the main Catalyst Subversion repository (see the note at the beginning +of each part for the appropriate svn command to use). -B You can run the test cases for the final code with the following -commands: +B You can run the test cases for the final code through Chapter 8 +with the following commands: - wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/Final_Tarball/MyApp.tgz - tar zxvf MyApp.tgz + sudo cpan Catalyst::Model::DBIC::Schema Time::Warp DBICx::TestDatabase \ + DBIx::Class::DynamicDefault DBIx::Class::TimeStamp DBIx::Class::EncodedColumn + wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8.tgz + tar zxvf MyApp_Chapter8.tgz cd MyApp - CATALYST_DEBUG=0 prove --lib lib t + CATALYST_DEBUG=0 prove --lib lib t + +If you wish to include the L section in +your tests, substitute C for +C in the URL above. However, you will also need to +run the following additional commands: + + sudo aptitude -y install libhtml-formfu-perl libmoose-perl \ + libregexp-assemble-perl libhtml-formfu-model-dbic-perl + sudo aptitude clean + sudo cpan Catalyst::Component::InstancePerContext Catalyst::Controller::HTML::FormFu + +You can also fire up the application under the development server that is conveniently +built in to Catalyst. Just issue this command from the C directory where you +ran the test suite above: + + script/myapp_server.pl + +And the application will start. You can try out the application by +pulling up C in your web browser (as mentioned +earlier, change C to a different IP address or DNS name if +you are running your web browser and your Catalyst development on +different boxes). We will obviously see more about how to use the +application as we go through the remaining chapters of the tutorial, but +for now you can log in using the username "test01" and a password of +"mypass". =head1 AUTHOR @@ -414,9 +636,7 @@ 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). - +L. +Copyright 2006-2008, Kennedy Clark, under Creative Commons License +(L).