Project Website Part 0: Introduction

Noel Rappin, Wednesday, July 2, 2008 @ 1:23 pm

One of the frustrations of trying to learn any programming tool is the lack of well-described real-world examples of how to use the tool in practice. Although open source tools make the underpinnings of successful software more explicit, documentation that combines a real example with a description and rationale of the choices made is still rare.

And so: Project Website. For various reason that aren't worth going into, I find my self rebuilding a small Web site in Rails, followed by the creation of version 2.0 of thee site with new features. I'm planning on blogging about the process on this site, with emphasis on the design and architecture decisions involved in taking the site forward. I can't mention the name of the client (at least I don't think I can), so some specific details will be fuzzed, but I'm going to make as much of the code and design rationale available as I can.

This first installment of the series will take stock of the current state of the application and the most critical needs for the new version.

Let's start with the client.

The client is a wholesale fulfillment company which manages inventory and shipping for customers who can't or won't manage individual drop shipments. Customers include dot-com online sites or companies managing some kind of giveaway or incentive program.

The website is currently intended to function as a catalog of products that the client currently handles. Users are potential and current customers as well as the internal client sales team. The long term goals are a little grander, but right now the site is basically a catalog search.

The existing Web site was written by, well, me, way back in 2002 and has been largely unchanged. It's a pretty decent MVC architecture using Jython running in a Tomcat server. If that seems idiosyncratic, it is, but at the time I had just finished writing Jython Essentials and was pretty excited about the Jython/Java Servlets structure I had come up with for the book... this was my first (and, as it turned out, pretty much only) chance to put that structure into practice.

Here's a quick audit of the MVC pieces of the current code, which I'll follow with a sense of the goals of the initial rewrite. This a pretty good glimpse of what I considered state of the art code back in 2002.

M is for Model

The data for this site currently is received via a CSV text file that contains a list of products and their attendant information. So, the Product table is nearly the only database table used in the current site (there are some metadata tables for category type info that are used). A quirk of the data set is that products belong to brands, but a brand may have products refer to it under multiple different names -- so products may refer to either Fred's Toys and FredCo, but both should be searched and displayed as FredCo.

The model layer is managed via a Python structure that, if you generously squint at it, you might consider a primordial ancestor of ActiveRecord. I wrote an SQL class that generated SQL from code like:

statement = sql.select("products", [[brand, "fredco"]])
products = self.database.selectInstances(statement, Product)

self.database was a connection object that included the JDBC driver and URL string, the select method generates an SQL statement, and the selectInstances method converts the result into a list of Python instance objects, with each column of the database turned into an attribute of the instance. There was a Product class for the actual data and a ProductSearch class that was responsible for converting form data into the SQL. A bit clunky compared to ActiveRecord, but a lot lower ceremony than the Java standard of the time, Castor, which involved an XML mapping file for the entire database.

The interaction with multiple brand names is handled pretty poorly in the code -- translations between database names and canonical names are done in a few different places, and adding new brands is, as a result, kind of awkward.

V is for View

The view was managed using the Velocity template tool for Java, a tool I liked then and still like now. I wrote some bridge code to ease the conversion between Jython data and Velocity, but basically the controller would populate a Velocity context object and invoke the template merger.

Two weird features. One is that the site was written with a frameset and some Flash-based navigation items that haven't really aged very well (even at the time, I didn't like framesets, but it was needed to make the Flash stuff work well). Also, the site has a layout/individual page structure, but it's a little inside/out. The overall layout was the actual Velocity template called for each page view -- the page specific template was invoked separately, saved as a string, and placed in the context for the global layout. In some sense this is not dissimilar to the Rails use of yield in a layout. In another sense, it's kind of twisted and backwards.

Also, since the data always came in from an external file, I never bothered writing admin functionality. This turned out to be a mistake, as I could have made my life a lot easier subsequently by making the data input process smoother.

C is for Controller

The controller layer is a series of Jython subclasses of java.lang.servlet. I think that a global servlet redirected requests ending in *.py to the servlet with the matching name (again, somewhat lower ceremony from the current Java solution, which was Struts). Each controller took the input params, built a Velocity context, and made a database call where appropriate. It's a fairly simple structure, and most of the code is in a common parent servlet.

Goals

In moving the site from Jython to Rails, I'm hoping to place the site on a firmer foundation to add new features. I'm also hoping that deployment and management will be more straightforward.

I'm not looking to change the design or functionality of the site much at the moment, but I would like to add the missing admin features. The Flash navigation can easily be replaced with JavaScript these days, so that's in the plan.

Often on a small-scale project such as this, I like to experiment with a tool that I haven't used much, and might evaluate for future use. In this case, I'm going to try jQuery for any JavaScript or Ajax needs.

Next time on Project Website

Data migration and administration. See you then.

agile ajax

Comments: 3 so far

• Leave a comment
• Comment feed for this post
• TrackBack URL

1. [...] Project Website Part 0: Introduction - Although open source tools make the underpinnings of successful software more explicit, documentation that combines a real example with a description and rationale of the choices made is still rare. And so: Project Website. … [...]

   Pingback by » Web Site Development Tool | XSitePro | Frontpage | Dreamweaver, Wednesday, July 2, 2008 @ 3:21 pm

2. 

   Oh hells yeah, im gonna love this. Keep the entries coming, I’d like to follow you along on this so I can get a better feel for real-life rails. This will go great along with my reading.

   Thanks!!

   Comment by Nick, Friday, July 11, 2008 @ 8:56 am

3. 

   Many thanks for this series — I’m developing my first Rails application right this moment, and it is very helpful to have company!

   Comment by DC Mom, Sunday, July 20, 2008 @ 3:53 pm

Leave a comment