From: Kennedy Clark Date: Wed, 28 Oct 2009 02:06:19 +0000 (+0000) Subject: Update tutorial for latest versions of Cat-related modules for Debian. X-Git-Tag: v5.8005~93 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=444d6b277933a652eb38bbeae072dbdfbe47c1c8 Update tutorial for latest versions of Cat-related modules for Debian. Misc cleanup/freshing up of tutorial. A few bug fixes from RT. Still need to wrap up Ch 7 - 10 before pushing to cpan. --- diff --git a/lib/Catalyst/Manual/Tutorial/01_Intro.pod b/lib/Catalyst/Manual/Tutorial/01_Intro.pod index 6da4708..4147f77 100644 --- a/lib/Catalyst/Manual/Tutorial/01_Intro.pod +++ b/lib/Catalyst/Manual/Tutorial/01_Intro.pod @@ -92,12 +92,14 @@ 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. +worth giving Debian 5 a try>. -If you're reading this manual online, you can download the example +If you plan to follow along with Debian 5, you can jump down to the +"Debian" section under L below and it will walk you +though the setup of a fully functional Catalyst environment. If you +would prefer to install directly from CPAN, you can download the example program and all the necessary dependencies to your local machine by -installing the C distribution from CPAN: +installing the C distribution: cpan Task::Catalyst::Tutorial @@ -153,7 +155,10 @@ applications. =item * The use of SQLite as a database (with code also provided for MySQL and -PostgreSQL). +PostgreSQL). (Note: Because we make use of the DBIx::Class Object +Relational Mapping [ORM] layer, out our application will be database +agnostic and can easily be used by any of the databases supported +by DBIx::Class.) =item * @@ -194,15 +199,15 @@ Debian 5 (Lenny) =item * -Catalyst v5.80004 +Catalyst v5.80013 =item * -Catalyst::Devel v1.10 +Catalyst::Devel v1.15 =item * -DBIx::Class v0.08102 +DBIx::Class v0.08108 =item * @@ -229,23 +234,23 @@ Catalyst::Plugin::Authorization::Roles -- v0.07 =item * -Catalyst::Plugin::ConfigLoader -- v0.22 +Catalyst::Plugin::ConfigLoader -- v0.23 =item * -Catalyst::Plugin::Session -- v0.20 +Catalyst::Plugin::Session -- v0.22 =item * -Catalyst::Plugin::Session::State::Cookie -- v0.10 +Catalyst::Plugin::Session::State::Cookie -- v0.11 =item * -Catalyst::Plugin::Session::Store::FastMmap -- v0.07 +Catalyst::Plugin::Session::Store::FastMmap -- v0.10 =item * -Catalyst::Plugin::StackTrace -- v0.09 +Catalyst::Plugin::StackTrace -- v0.10 =item * @@ -261,22 +266,28 @@ 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 -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. + perl -MCatalyst -e 'print "$Catalyst::VERSION\n";' + +or: + + perl -MCatalyst::Devel -e 'print "$Catalyst::Devel::VERSION\n";' =item * -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 +This tutorial will assume that the web browser is located on the same +system where the Catalyst development server is running, and +therefore use a URL of C (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. + +Please Note: 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). @@ -389,14 +400,13 @@ 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 libmoosex-emulate-class-accessor-fast-perl \ - libdbix-class-timestamp-perl - -Let it install (normally about a 30-second operaton) and you are done. -(Note the '\' above. Depending on your environment, you might be able -to cut and paste the text as shown or need to remove the '\' + libcatalyst-modules-perl libdbix-class-timestamp-perl \ + libdbix-class-encodedcolumn-perl libperl6-junction-perl \ + libdatetime-format-sqlite-perl + +Let it install (normally about a 30 to 90-second operaton) and you are +done. (Note the '\' above. Depending on your environment, you might +be able to cut and paste the text as shown or need to remove the '\' characters to that the command is all on a single line.) If you are using an image other than the "rescue" ISO, you will also need @@ -432,7 +442,9 @@ deleted). =item * If you are installing modules from CPAN, you can free up some space -with "C". +with "C" (change "/root/" in the previous +command to match your home directory or the location where CPAN +has been configured to perform build operations). =item * @@ -604,8 +616,6 @@ of each part for the appropriate svn command to use). B You can run the test cases for the final code through Chapter 8 with the following commands: - sudo cpan Catalyst::Model::DBIC::Schema Time::Warp DBICx::TestDatabase \ - DBIx::Class::DynamicDefault DBIx::Class::EncodedColumn wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter8.tgz tar zxvf MyApp_Chapter8.tgz cd MyApp @@ -613,13 +623,12 @@ with the following commands: 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: +C in the URL above. - 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 + wget http://dev.catalyst.perl.org/repos/Catalyst/trunk/examples/Tutorial/MyApp_Chapter9_FormFu.tgz + tar zxvf MyApp_Chapter8.tgz + cd MyApp + CATALYST_DEBUG=0 prove --lib lib t 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 diff --git a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod index 91c255b..27f1dcd 100644 --- a/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod +++ b/lib/Catalyst/Manual/Tutorial/02_CatalystBasics.pod @@ -103,7 +103,8 @@ them to the necessary model and view. The use of Object-Relational Mapping (ORM) technology for database access. Specifically, ORM provides an automated and standardized means -to persist and restore objects to/from a relational database. +to persist and restore objects to/from a relational database and will +automatically create our Catalyst model for use with a database. =back @@ -132,8 +133,13 @@ script to initialize the framework for an application called C: created "Hello/root" ... created "Hello/script/hello_create.pl" + Change to application directory and Run "perl Makefile.PL" to make sure your install is complete $ cd Hello +Note: If you are using Strawberry Perl on Win32, drop the ".pl" +from the end of the "catalyst.pl" command and simply use +"catalyst Hello". + The C helper script will display the names of the directories and files it creates: @@ -187,8 +193,8 @@ previous step): [debug] Statistics enabled [debug] Loaded plugins: .----------------------------------------------------------------------------. - | Catalyst::Plugin::ConfigLoader 0.20 | - | Catalyst::Plugin::Static::Simple 0.20 | + | Catalyst::Plugin::ConfigLoader 0.23 | + | Catalyst::Plugin::Static::Simple 0.21 | '----------------------------------------------------------------------------' [debug] Loaded dispatcher "Catalyst::Dispatcher" @@ -219,7 +225,7 @@ previous step): | / | /index | '-------------------------------------+--------------------------------------' - [info] Hello powered by Catalyst 5.80004 + [info] Hello powered by Catalyst 5.80013 You can connect to your server at http://debian:3000 Point your web browser to L (substituting a @@ -229,8 +235,8 @@ screen or an "Index" screen, you probably forgot to specify port 3000 in your URL). Information similar to the following should be appended to the logging output of the development server: - [info] *** Request 1 (0.005/s) [20712] [Sun Mar 8 15:49:09 2009] *** - [debug] "GET" request for "/" from "1.1.1.98" + [info] *** Request 1 (0.005/s) [20712] [Sun Oct 11 11:58:51 2009] *** + [debug] "GET" request for "/" from "172.0.0.1" [info] Request took 0.007342s (136.203/s) .----------------------------------------------------------------+-----------. | Action | Time | @@ -273,27 +279,26 @@ L), while C<$c-Ewelcome_message> is a special method that returns the welcome message that you saw in your browser. -The ":Path :Args(0)" after the method name are attributes which determine -which URLs will be dispatched to this method. (Depending on your version of -Catalyst, it used to say "Private" but using that with 'default' or 'index' -is currently deprecated.) +The ":Path :Args(0)" after the method name are attributes which +determine which URLs will be dispatched to this method. (You might see +":Private" if you are using an older version of Catalyst, but using +that with 'default' or 'index' is currently deprecated. If so, you +should also probably upgrade before continuing the tutorial.) Some MVC frameworks handle dispatching in a central place. Catalyst, by policy, prefers to handle URL dispatching with attributes on controller methods. There is a lot of flexibility in specifying which URLs to match. This particular method will match all URLs, because it doesn't specify the path (nothing comes after "Path"), but will only -accept a single args because of the ":Args(0)". - -The default is to map URLs to controller names, and because of -the way that Perl handles namespaces through package names, -it is simple to create hierarchical structures in -Catalyst. This means that you can create controllers with deeply -nested actions in a clean and logical way. +accept a URL without any args because of the ":Args(0)". -For example, the URL C maps -to the package C, and the C -method. +The default is to map URLs to controller names, and because of the way +that Perl handles namespaces through package names, it is simple to +create hierarchical structures in Catalyst. This means that you can +create controllers with deeply nested actions in a clean and logical +way. For example, the URL C +maps to the package C, and the +C method. Add the following subroutine to your C file: @@ -310,17 +315,18 @@ cutting and pasting example code from POD-based documents. Here you're sending your own string to the webpage. Save the file, start the server (stop and restart it if it's still -up), and go to L to -see "Hello, World!" +running), and go to L to +see "Hello, World!" Also notice that a new action is listed under +"Loaded Private actions" in the development server debug output. =head2 Hello, World! Using a View and a Template -In the Catalyst world a "View" is not a page of XHTML or a template -designed to present a page to a browser. It is the module that -determines the I of view -- HTML, pdf, XML, etc. For the -thing that generates the I of that view, (such as the -default Toolkit Template) the actual templates go under the +In the Catalyst world a "View" itself is not a page of XHTML or a +template designed to present a page to a browser. Rather, it is the +module that determines the I of view -- HTML, pdf, XML, etc. For +the thing that generates the I of that view (such as the a +Toolkit Template template file), the actual templates go under the "root" directory. To create a TT view, run: @@ -344,15 +350,16 @@ commonly used name for TT views. (You can name it anything you want, such as =item * -The final "TT" tells it that you are creating a Template Toolkit view. +The final "TT" tells Catalyst the I of the view, with "TT" +indicating that you want to a Template Toolkit view. =back -If you look at C you will find that it only contains a -config statement to set the TT extension to ".tt". +If you look at C you will find that it only +contains a config statement to set the TT extension to ".tt". Now that the TT.pm "View" exists, Catalyst will autodiscover it and be -able to use it to display the view templates, using the "process" +able to use it to display the view templates using the "process" method that it inherits from the C. Template Toolkit is a very full featured template facility, with @@ -383,14 +390,15 @@ following: $c->stash->{template} = 'hello.tt'; } -This time, instead of doing C<$c-Eresponse-Ebody()>, you are setting -the value of the "template" hash key in the Catalyst "stash", an area -for putting information to share with other parts of your application. -The "template" key determines which template will be displayed at the -end of the method. Catalyst controllers have a default "end" action -for all methods which causes the first (or default) view to be -rendered (unless there's a C<$c-Eresponse-Ebody()> statement). So your -template will be magically displayed at the end of your method. +This time, instead of doing C<$c-Eresponse-Ebody()>, you are +setting the value of the "template" hash key in the Catalyst "stash", +an area for putting information to share with other parts of your +application. The "template" key determines which template will be +displayed at the end of the request cycle. Catalyst controllers have a +default "end" action for all methods which causes the first (or +default) view to be rendered (unless there's a C<$c-Eresponse- +Ebody()> statement). So your template will be magically displayed +at the end of your method. After saving the file, restart the development server, and look at L again. You should @@ -405,8 +413,7 @@ Create a controller named "Site" by executing the create script: This will create a C file (and a test file). Bring Site.pm up in your editor, and you can see that there's -not much there. Most people probably don't bother to use the create -script to make controllers after they're used to using Catalyst. +not much there. In C, add the following method: @@ -418,8 +425,8 @@ In C, add the following method: } Notice the "Local" attribute on the C method. This will cause -the C action (now that we have assigned an action type to the -method it appears as a controller "action" to Catalyst) to be executed +the C action (now that we have assigned an "action type" to the +method it appears as a "controller action" to Catalyst) to be executed on the "controller/method" URL, or, in this case, "site/test". We will see additional information on controller actions throughout the rest of the tutorial, but if you are curious take a look at diff --git a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod index ffd01be..39db3e7 100644 --- a/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod +++ b/lib/Catalyst/Manual/Tutorial/03_MoreCatalystBasics.pod @@ -91,11 +91,13 @@ tutorial or in a directory that already has a "MyApp" subdirectory): created "MyApp/root" ... created "MyApp/script/myapp_create.pl" + Change to application directory and Run "perl Makefile.PL" to make sure your install is complete $ cd MyApp This creates a similar skeletal structure to what we saw in Chapter 2 of the tutorial, except with C and C substituted for -C and C. +C and C. (As noted in Chapter 2, omit the ".pl" from +the command if you are using Strawberry Perl.) =head1 EDIT THE LIST OF CATALYST PLUGINS @@ -119,15 +121,31 @@ Enables the Catalyst debug output you saw when we started the C