It’s time to build our Backbone.js app, “Comment on the Movies”.  This tutorial will, ideally, give you something interesting to build.  Take a look at the finished app (so far) on Heroku & feel free to pull it from GitHub.  In addition, I’ve updated the code to use Backbone.js 0.5.3, Underscore 1.2.2, Mustache 0.3 & jQuery 1.7.1.  Let’s do this!

*Before we get started, check out one more resource: Charlie Robbins (Co-Founder of Nodejitsu) wrote an awesome article about Scaling Isomorphic Javascript Code.  In the writeup, he describes popular methodologies in retrieving data and presenting it to the user.  It’s a great read.  The image below from that article:

Backbone.js interactions: Model-View-ViewModel

Prerequisites:  Rotten Tomatoes API Account, Ruby, Sinatra, & Haml

Rotten Tomatoes API Account

The app we’re writing is called “Comment On The Movies”.  The RottenTomatoes API is full of well formed data (which is more than I can say about the New York Times movie api calls).  Real data is always more interesting than building dummy datasets ourselves.

The Rotten Tomatoes API registration is free, quick & painless.  Get your api_key & come back to this tutorial.

We’ll also be using the R.T. assets.  R.T. makes their images available to developers to use in their apps and we’ll be taking advantage.

Ruby (Project Site)

Realistically, if you’re reading this webpage, you probably already have it installed (even if you don’t use it) .  I chose Ruby here because I 9-5 in Ruby and I really enjoy it.  You can use ANY server side scripting language here (PHP, Asp.NET, JSP), but you need to use something. You don’t want to simply expose your R.T. API App Key to the world.  By using a server side language, you can create a proxy page that protects your API App Key.  Here’s how this app will work:

1. Your Backbone app makes an AJAX call with R.T. API parameters to the proxy page
2. The proxy page appends your API_KEY & makes the call to a R.T. servers
3. The proxy page receives the response and returns it to your Backbone app
4. The Backbone app updates it’s UI.

Sinatra (Project Site)

Since we only need an index page and a proxy, Sinatra is a perfect option here.  A full Rails app would be WAY too much.

Haml (Project Site)

I enjoy haml.  It’s really easy to create markup with it.

The “Comment on the Movies” Spec

Here’s what the app needs to accomplish:
**Items in orange will be implemented in future tutorial posts**

• Users should be able to switch between the various lists of R.T. data:
• Box Office (default view on page load)
• In Theaters
• Opening
• Upcoming
• The “Movies Table” should display:
  • Title
  • Year
  • MPAA Rating (R, PG-13, etc)
  • Runtime
  • Release Date (default sort)
  • Critic’s Score
  • If it’s ‘certified fresh’ that should be indicated.
  • Number of comments
• Clicking on a table column title should sort the current set of movies in the table.
• Clicking on a movie’s row should take you to a “detailed” view of the film.  The “detailed” view should display:
  • Links [all links that lead us away from the site should open in a new window] to…
    • Showtimes
    • Awards (if any)
    • Trailers
    • Abridged Cast
    • IMDB records
• Comments
  • Add a new comment
  • Edit an existing comment
  • Delete a comment
  • Require that the review indicates if the comment is BEFORE or AFTER you’ve seen the movie
  • Comments should persists across browser restarts
• The app needs to be crawl-able by Google.
• It needs to be well tested

Make your Backbone App Google Crawl-able via hashbang URLs

Hashbanging (/#!) your URLs let’s the Google crawling bot know that there’s AJAXed content on this page.  Fortunately, it’s really easy in Backbone.js as you can see in the live demo

In The Next Post…

I’ll explain how I implemented the app thus far.  That’ll include the filling the index view & the hashbang technique mentioned above.

It’s been a while since our last post.  Gabe’s been hard at work in Australia, hacking on a number of things.  Rebecca & Brad have large, awesome projects in the works.  Meanwhile  I’ve switched jobs a couple of times .  All the while, we’ve been coding like mad and learning a ton of interesting things.  While I can’t promise that we’ll “turn the posting faucet back on”, I can say that we’ll try to reduce the big draughts.  Now then, on to the show!

Backbone.js Philosophy (as I see it)

I’ve been getting pretty friendly with Backbone.js lately.  This 2-part post will teach you some backbone basics & show you how to create your own backbone.js app with multiple routes.

Before we begin, take a look at some of these other tutorials to get a sense of what we’re about to do.  I learned a LOT from them:

• Document Cloud’s backbone.js framework documentation
• Jérôme Gravel-Nique’s ”Todo list” example
• The Meta Cloud’s backbone tutorial
• Liquid Media’s backbone tutorial (3 parts)
• Elf Sternberg’s backbone tutorial
• James Yu’s tutorial
• David Richard’s thoughts on backbone.js

The most important thing to understand about a Backbone.js app is the separations of concerns.  Each of the parts below can do even more than what I’m describing, but here’s the minimum of what you need to know about them.

Models and Collections (an array of models)

• knows how to speak to the data source (both restful resources and api calls).
• can parse data before handed responses off to a view.

Views

• knows how to display your models and collections.  You define the markup rules in the render method
• handles events (clicks, changes to markup, changes to models) and changes the markup appropriately.
• can initialize your js plugins that should be attached to markup.

Gabe had this to say about views:

“I see two ways to use backbone views:

1. A view can be bound directly to a model or collection.  Whenever that model/collection changes, the view would re-call it’s render method and redraw itself. In essence, the view’s job is to represent a model’s state in the DOM now.  Also keep in mind that the model doesn’t have to be something bound to your db.

2. A view can be more of a stateful widget that remembers some of its own state.  In this widget style, the view would keep track of some state and maybe decide what parts of itself it should show/hide depending on its state.

In conclusion, the two view philosophies are very similar:

- one is more modular
- one is more monolithic

The view can be an island OR it can be obsessed with something.“

Thanks Gabe!

Controllers/Router

• handle all of your ‘#’ routes.
• the app is started by creating a new instance of this class.
• your app only needs 1 controller/router

[5/7/2011 : Amendment]  A quick word about markup

In a Backbone app you’ll have markup that lives on your page (index.html) & markup that you’ll need to generate as new elements are added (This will become clearer when you see our tutorial app in action in the next post).  While Backbone gives you view.make() to create markup, you’ll want to use a templating library to help you out with more complicated stuff.  A fellow KAL member recently how I draw the line between what markup lives on the page and what markup lives in a template.

My Rule: If the markup has an ID, then it should live on the page.  By maintaing this idea, you can create your page layout in it’s empty state.  The Views that you create will attach to ID’ed elements to dynamically fill/update them as events occur.  Also, with Backbone, you don’t need to have markup that contain the object’s ID (“foo_1″, “foo_2″, “foo_3″, etc).  The object is bound to the markup (if you do it correctly) which removes the need to parse it out of the ID in the markup (or other well known chicanery that we’ve all done at one point or another ).  It’s often better to have your template markup use the ‘class’ attribute declaration since they’re best used when you’re representing models in a collection.  This also fits with the W3C’s HTML spec which says that an ID/Name “must be unique in a document“.

Consider my rule when constructing a table (the tutorial app will do this):  The table’s markup lives on the page with an ID (id=”MoviesTable”) without any rows.  We’ll generate/update the rows (class=”movie”) of the table on the fly via a template fueled by my View’s Collection.  The Collection is filled by the response from our movie API.

That’s a lot to digest

Stay tuned for Part 2 where we’ll build our app, “Comment on the Movies”.

To play along at home, you’ll need your own Google Maps key or you can just aim your mobile browser to my example code at http://kickasslabs.com/examples/gmap_events.html. (Note that this will not work in a regular desktop browser.) Besides a <script> tag importing the GMaps JavaScript, you should not need any other libraries or tools besides Mobile Safari to view and use the example page. If the page is zoomed way out when you start, just double-tap the map tile in the upper-left corner – it should zoom to fill your viewport.

What you should see is a map tile with a line painted on it. If you touch the screen, you should see one end of the line follow your finger.

It looks simple but I had a bit of trouble getting it to work, because touch events are not like mouse events (curious as to why?), and GMaps doesn’t respond to touch events by default.

Step by Step

First, you need 2 divs:

    <!-- This div holds our map -->
    <div id="map" style="width: 320; height: 320px"></div>
 
    <!-- This div lies on top of the map and acts as an event proxy -->
    <div id="mapoverlay" style="height:320px; width: 320px; position: absolute;"></div>

And you need to position one div over the other:

    mapDiv = document.getElementById('map');
    mapOverlayDiv = document.getElementById('mapoverlay');
    mapOverlayDiv.style.top = (mapDiv.offsetTop + 0) + 'px';
    mapOverlayDiv.style.left = (mapDiv.offsetLeft + 0) + 'px';

You set up the map div like you would for any other GMaps-enabled page:

    // the map
    _map = new GMap2(document.getElementById("map"));
 
    // coordinates for home base
    _lat = 37;
    _lng = -95;
    mapCenter = new GLatLng(_lat, _lng);
    _map.setCenter(mapCenter, 15);

Set up the overlay div to respond to touch events by firing a custom event for your map, e.g.:

    mapOverlayDiv.ontouchstart = function(e) {
      GEvent.trigger(_map, 'customTouchStart',
        (e.touches[0].pageX - mapDiv.offsetLeft),
        (e.touches[0].pageY - mapDiv.offsetTop));
    }

Now have your map respond to that event:

    GEvent.addListener(_map, 'customTouchStart', mapTouchStart);

…where mapTouchStart is a callback function that does something useful in response to a touch:

    function mapTouchStart(xPixel, yPixel) {
      redrawLine(xPixel, yPixel);
    }

And… well, then you’re done. My example also responds to the touchMove event and has a little code for drawing lines, but you’ve seen all you need to know to get event proxying up and running for your app.

Got a question? Got working code for an easier way? Drop me a line in the comments!

The solution was quick & dirty (as most solutions are during Rails Rumble), but the results worked, and allowed us to qualify for judging and reach a respectable 28th place finish in the “Completeness” category.

Check out the details after the fold.

Design Constraints

Great Minds is a word game played by 2 or more players. The game is played in a virtual chat Room, containing one or more Players. Players can take various actions, such as submitting a word to the game, chatting, or changing their handle/username. The results of these actions must be transmitted to other players in the room.

Other constraints on the design included:

• No New Technologies: There are tools like Juggernaut that make messaging pretty easy, but we had no hands-on experience with them, and learning a new tool on a 48-hour schedule was deemed a risk to completing the project & qualifying for Rumble judging.
• Broadcast: We needed something more than a simple message queue like Beanstalk; the consumer of a message couldn’t remove it from the queue, as there might be other consumers needing the same message.
• Room State Reconstruction: Someone coming to the room for the first time (or leaving and returning) should be able to see the current room state, including all participants, recently played words, and recent chat.
• Replay: Though we didn’t get around to implementing it, we wanted to offer the ability to review a particularly funny game.

The first two constraints affected our design and technology choices; the second two demanded that the messages be persisted. (Alternatively, we could have saved the room state in some other way, but as long as we had the messages anyway, it seemed simpler to just keep them and reconstruct the state.)

Client Implementation

In the absence of a viable push solution like Juggernaut, we opted for a polling solution: Clients would periodically send a signal that:

• let the server know they’re still alive and connected,
• sent any new messages to the server, and
• requested any pending messages from the server.

On the client side, this meant that every message got packaged as JSON, stuck in a queue, and periodically collected and sent to the server as the optional payload of a keep-alive signal. With some help from Prototype, this was as simple as:

  function SyncMessages() {
          var data = Object.toJSON(MESSAGES_QUEUE);
          var url = '/room/sync_messages';
          var params = {
                  authenticity_token: AUTH_TOKEN,
                  messages: '[]',
                  //messages: Object.toJSON(MESSAGES_QUEUE),
                  last_message_id: LAST_MESSAGE_ID };

          new Ajax.Request(url, {
            method: 'post',
                  parameters: params,
            onSuccess: HandleMessages });
  }

  SyncMessages(); //start first on load
  var message_syncer = new PeriodicalExecuter(SyncMessages, 3);

HandleMessages() updates the DOM based on messages coming back.

The other feature to note is the LAST_MESSAGE_ID token above. Each client is responsible for keeping track of the last message ID it got. On the server side, message IDs are assigned sequentially, so all new messages are guaranteed to have a higher ID.

We could have kept track of each client’s last message on the server side, but this would have been much more complex – we would have needed to store data either in the session (which already held a fair amount of stuff) or in another table in order to keep track of who had received what.

Server Implementation

On the server side, messages were persisted in a table. This table would have relatively frequent inserts, somewhat more frequent reads, and no updates or deletions. For this reason, we went with the default MyISAM table architecture. (We had considered a design that would have updated the table with delivery status information and would have required InnoDB’s row-level locking, but in the end we opted for the simpler design.) The table looks like:

  class CreateMessages < ActiveRecord::Migration
    def self.up
      create_table :messages do |t|
        t.integer :message_type_id, :room_id, :game_id, :user_id
        t.string  :data, :user_handle
        t.timestamps
      end
    end

    def self.down
      drop_table :messages
    end
  end

It also has an index:

  class AddRoomIndexToMessages < ActiveRecord::Migration
    def self.up
      add_index :messages, [:room_id, :id]
    end

    def self.down
      remove_index :messages, [:room_id, :id]
    end
  end

Recall that the client keeps track of the last message it got, and periodically requests all messages since. This index speeds that request - which is just msgs = Message.find :all, :conditions => ['room_id = ? AND id > ?', session['room_id'], last_message_id], rder => 'id'. (Yes, I know that should be a named scope. I hadn't gotten around to learning those yet at the time of the Rumble.)

When the a keep-alive signal hits the server:

• any new messages attached to the signal are added to the messages table,
• any game mechanics related to those messages are executed (which may result in more messages being added to the table), and
• all messages for the caller's room with an ID greater than the caller's LAST_MESSAGE_ID are packaged as JSON and sent back down in the HTTP response.

A note: If you're in a room and you enter (for example) a chat message, there's actually a server round-trip involved (pushing the message to the server and getting the same message back as a response) before that chat message is shown in your browser. We worried about this, but not for long - the interactivity delay turned out to be minimal, and it was much simpler to keep it this way (every message is treated the same for all clients) than to create an exception (you update your DOM with your chat messages immediately, but your own chat messages are somehow filtered from your message stream).

What's Missing?

Obviously, this was a quick & dirty solution, tailored to the immediate needs of a Rails Rumble project. Here's what I'd do differently (and indeed, will do differently, as we have plans for the future of Great Minds - stay tuned):

• Security: We do use the Rails session authenticity_token, but there's still no protection from a server flood from someone who has a token, either by cranking down the polling interval or by fiddling with the LAST_MESSAGE_ID.
• Server Push: Polling is wasteful - requests are made whether or not there are any messages to send or receive. We plan to move to Juggernaut soon.
• Decoupling from Game Mechanics: In the first iteration, message receipt and delivery were too intimately tied to game mechanics, with Message objects being explictly constructed and followed by Message.save! calls. I've already started the process of teasing them apart in preparation for the move to Juggernaut, factoring this into a deliver_message() method.

Questions? Thoughts? Add a comment! I promise to get back to you.