Tuesday, January 10th 2012, 12:00:00 am
The flatiron library is no more. So, other than reading stuff, there just isn't all that much relevant stuff, here.

The makers of flatiron.js bill it as “an unobtrusive framework initiative for node.js.” It consists of five major components that the creators want to behave “isomorphically,” that is, similarly in the browser and on the server.

director : A URL router for the framework.

union : A hybrid buffered / streaming middleware kernel backwards compatible with connect middleware.

plates : A simple, unobtrusive templating solution that keeps the trash/placeholders out of your html.

resourceful : A storage agnostic resource-oriented ODM for building prototypical models with validation and sanitization.

broadway : A simple plug-in API which allows you to extend the top-level application object easily.

Installation

Because flatiron promises an unobtrusive framework, it only relies on broadway and director from that list. You get to choose whether or not you want to use the other three components. So, if you want middleware, templating, or object-document mapping, you’ll need to install the other components separately.

1
2
3
mkdir todo
cd todo
npm install flatiron union plates resourceful

(Warning: If you want to use flatiron for responding to HTTP requests, it requires union.)

Using flatiron on the server

When you require the flatiron library in your server code, it exposes an app property that allows plugins through the use of broadway. flatiron comes with a plugin to provide HTTP router function through director. You configure it like this.

1
2
3
4
var flatiron = require('flatiron'),
    app = flatiron.app; // Singleton instance of an App.

app.use(flatiron.plugins.http);

After you execute that code, the plugin mixes four new attributes into the app instance.

app.http: object : An object with before and after arrays to run callbacks before and after each successful HTTP request. It also has a map named headers that allows you to specify a set of headers that director should add to each HTTP request.

app.listen: function(port, host, callback) : A method that creates an middleware server using union and calls its listen method with the specified port, host, and callback.

app.router: object : An instance of the director HTTP router.

app.start: function(port, host, callback) : A method that initializes the underlying broadway subsystem and, then, calls listen.

We use the app.router attribute to configure the URLs to which our application will respond. Then, we can use app.start to get it running.

The to-do list design

Let’s figure out the user stories.

  1. When a user first issues a GET to /, then it creates a new session.
  2. When a user first issues a GET to /, it serves an HTML page that shows an entry text box for a to-do list item and a button to POST the item to /.
  3. When a user POSTs a form to /, it creates a new ToDo item, adds it to the session, and redirects to /.
  4. When a user issues a GET to / after session creation, the HTML page continues to show the input and button while showing the task list beneath it.
  5. Each item in the task list will have a “Delete” link next to it so the user can remove the to-do item from the list.

That seems pretty reasonable for a primitive, functional to-do list. Let’s make it happen.

Building the to-do list application, story-by-story, without unit tests

Yes, without unit tests. Sorry. I want to do a blog post on vows, an asynchronous BDD framework for node.js. However, I haven’t had enough time to play with it, so I will just cowboy my way through the stories.

Story 0: Getting started

Create some directory in which you want to write the code that I write. I ran the following commands from the command line. Then, I opened the directory in my currently favored text editor, Sublime Text 2.

1
2
3
4
mkdir -p ~/dev/todo
cd ~/dev/todo
touch package.json server.js
subl .

I like to let npm handle my dependencies. So, in package.json, put the following contents. If you don’t know what this means, run npm help json at the command line.

1
2
3
4
5
6
7
8
9
10
11
{
  "name": "todo-list",
  "version": "0.1.0",
  "dependencies": {
    "flatiron": "*",
    "union": "*",
    "plates": "*",
    "resourceful": "*",
    "connect": "*"
  }
}

The asterisks in the dependencies dictionary just means load the latest version available from npm.

Now, run npm install in that directory to get those dependencies installed.