Day 1 - Getting started with Catalyst and Subversion

Getting Started with Catalyst and Version Control

Getting Started

Catalyst ships with all the tools you need to get started with web
application programming. It uses the Model-View-Controller (MVC)
paradigm to separate the application logic, data storage, and display
logic from one another. This is a standard pattern, taken from the
Smalltalk programming language and popularised by the Gang of 4 book. MVC coding is an excellent antidote to
"spaghetti code". Catalyst's use of this approach, its powerful
dispatcher (controller logic), and its model and view agnosticism is
what accounts for its power.

For the first day of Catalyst Advent 2006, I'll keep it traditional:
we'll write a complete, if basic, sample application that shows several
aspects of Catalyst. Our application, called Cheer, will display the
number of days remaining until Christmas - how seasonally appropriate!
I'll also show the use of version control, which is not usually
demonstrated in such examples, but which is crucial in the development
process for any serious application.

As a result of the MVC architecture, a typical Catalyst application
has a well-defined structure, and contains quite a lot of files. This
makes using version control from the start very important. For this
example I'll use Subversion, a
powerful version-control system that grew out of CVS (which is in
extremely wide use, but has many limitations). Many Catalyst
developers use svk, itself based on Subversion.

The example application here is available from the Catalyst subversion
repository. Instructions for obtaining it are given at the end of
this article.

And we have a version-controlled skeleton application all ready for
use.

The purpose of the trunk tags and branches directories are beyond the
scope of this tutorial, however we are working exclusively out of the
trunk of the repository. The branches directory is for separate lines
of development, for example branches can be used for addition of
substantial new features, or significant refactoring. Once the branch
is complete it can be merged back to trunk. The tags directory should
contain project snapshots.

Modify the Root Controller to have More Sensible Default
Behavior

By default catalyst.pl makes the default action of the root
controller a "hello world" screen. We're going to change this so that
the index action provides the "hello world" screen and the default
action returns a 404 not found error code.

I'm going to do this to my local copy, then provide a svn diff which
you can use to patch your local copy. Back in a sec.

OK, that took me a couple of minutes. First I check that my code
actually compiles:

You can copy and paste the above code (from the line below "svn diff"
above to "=head2 end") into a file - cheer.patch - I'm going to put
it in /tmp/, but I need to undo my local modifications first. Again
I'm in the root dir for my application:

$ svn revert lib/Cheer/Controller/Root.pm

and patch the source from my patch at /tmp/cheer.patch. Make sure
that if you're following along at home that you get rid of all leading
spaces from the patch. The following Perl one-liner will do that
(followed by the invocation to patch):

Often, this is all you need to create the view. The only thing you
have to do to create your own view (from your own templating system,
for example) is to provide a process method in your application, as
documented in Catalyst::View (although a render method is also
rather useful). There are quite a lot of other views
available for catalyst, but the Template Toolkit is by far the most
popular. HTML::Mason the next most popular option.

I'm going to update the root controller to use the Template Toolkit
now. Here's the patch which includes changes to
the controller code and the addition of a couple of templates:

Because I added a couple of files to the application, this time I had
to add them to my working copy before creating the patch. This is
what I did (from the application root):

$ svn add root/*tt
$ svn diff > /tmp/tt.patch

This time it's up to you to figure out how to apply it - remember to
strip leading spaces first.

A (very) Simple Model.

As I said at the beginning, Catalyst is agnostic to the model and view
you use. This gives us an opportunity to show you a very simple
example. Most commonly the model will be used to talk to some kind of a
database, and Catalyst developers usually favor DBIx::Class as their
database mapping layer. However, here we're going to grab data from the
system clock instead.

First, create a new model called "Now" (from the application root), and
commit it to the Subversion repository.

I'm going to go and update the model to tell us the number of days to
Christmas in the index action in the root controller. Again I'll
provide this as a patch. We're going to use the Date::Calc module
from CPAN this time, so I'll also update the Makefile.PL so that
you're automatically told about dependencies from CPAN when you run
'perl Makefile.PL' from the application root. Some applications also
have actions defined for make installdeps so that if you run perl
Makefile.PL and then make installdeps cpan is started and all the
missing dependencies are installed. However, this is not done
automatically (yet?).

Wrap up.

So I've shown you how to use Catalyst with Subversion, touched briefly
on the View, and showed you how to use a custom model that uses a
non-catalyst CPAN module. If you don't know Catalyst, we recommend
that you go through the tutorials from Catalyst::Manual::Tutorial
which go into quite a lot more detail. For more details on
Subversion, and particularly the function of the tags, trunk, and
branches directory structure which we created, see the excellent free
Subversion Book.

You can obtain the code from this Advent Calendar entry from the
Catalyst Subversion repository by issuing the following command: