Notes from first project using Backbone Marionette

I really enjoy using Backbone.Marionette.

I was recently tasked with a pretty exciting opportunity at work: build a cross platform mobile web app. This project has been (still is) incredibly challenging for me because I’ve never built anything like this before. It’s probably the most complex JavaScript I’ve ever written and I was able to build a reasonably decent app from the ground up thanks to a few technologies and frameworks that made my life infinitely easier:

  • Backbone.js framework
  • Backbone.Marionette framework
  • Jade javascript templates
  • (Iced) CoffeeScript
  • Stylus CSS
  • jQuery Mobile
  • jQuery + underscore (prereqs anyway)
  • Mobile Boiler Plate
  • Modernizr
  • cdnjs (This has almost all of the above libraries on a CDN! Free! Magnificent.)
  • a handful of utilities (makefiles, etc.) that our build engineer created in-house to package things up real nicely.

Figuring out how to use Backbone and Marionette took a long time for me to grasp but now that I’m comfortable using them I feel like I have the tools and skills necessary to build some cool stuff in the future. Maybe not GMail in complexity nor 8-bit Nintendo Emulator coolness but give me an API and some time, I’ll be able to whip up something that could be pretty neat.


Important Resources that helped me understand Marionette

These tutorials and code samples helped me the most when trying to pick up a new framework. I don’t watch a lot of screencasts because they tend to be really slow and I can’t copy-paste the code samples.

Tutorial: a full Backbone.Marionette application – is the first tutorial that I found that actually helped me wrap my head around Marionette. The code is easy to read and well explained. Downside — the structure and style are slightly different from the patterns that Derrick Bailey, creator of Marionette,  uses in his examples. The tutorial is slightly old and does not take advantage of newer features that have been added to Marionette (for instance, AMD-style loading). Nevertheless, this tutorial is what got me used to the basic elements of Marionette. Mr. Bailey’s blogs regarding Marionette are well written but they only started to make sense after 1-2 days of staring at this tutorial first.

Addy Osmani’s TodoMVC implemented in Marionette – A useful example of how to use Marionette but I find the JavaScript AMD code extremely hard to follow because all the code is spread around in different files. The order in which the various modules get included on the page matter.

Stack Overflow questions answered by Derrick Bailey – Back to Mr. Bailey… he is active/proactive in Stack Overflow and he often provides insightful answers and comments to many of the questions about backbone.marionette. It will benefit you to look beyond the big green check “Accepted Answer” blocks to seek out Mr. Bailey’s comments in any S.O. thread.

Backbone Marionette Docs in Github – the documentation is extensive and well written. The problem is that there are so many modules available to use it’s hard to know where to get started. In my first non-trivial Marionette app I only used half of the modules in my code (some of the modules are base classes but I didn’t specifically call them). The Marionette components that I used:

  • Marionette.ItemView
  • Marionette.CompositeView
  • Marionette.Layout
  • Marionette.Region
  • Marionette.AppRouter
  • Marionette.Application.Module
  • Marionette.Application — just 1 instance but it provides the foundation for everything else.
  • Backbone.View — I was easily able to adapt a View I had written before to work fine with Marionette. It would be possible to break my View into ItemView + CompositeView but not worth the time.
  • Backbone.Model — a building block
  • Backbone.Collection — a building block

I chose the jQuery Mobile (jQM) framework to help me organize my HTML and take advantage of its transitions and animation libraries. With a little bit of planning jQuery Mobile has turned out to compliment Marionette, I did however have to throw out a lot of jQM’s default JavaScript behavior.

My app architecture in a nutshell:

  • Marionette.Application is the starting point, basically a singleton to get things started.
  • My Marionette.Application provides a single point of contact for application-level event handling and tying together all of the component pieces of my various Backbone/Marionette Views and Controllers.

In the jQM paradigm Pages are a fundamental component. Each Page is demarcated by a <div data-role="page">. I have 3 basic jQM Pages. Each layout had a unique layout and imagine the wireframe looks something like below:

  • a start page (id=start)
  • a search page (id=search)
  • and a google map page (id=gmap)
Rough layout

Rough layout

Since I had these 3 pages, it made sense to define each as a Region in Marionette. Although a Region has all kinds of bells and whistles I can get a way with using these top-level Page Regions to only hide/show an individual page.

  • Each jQuery Mobile HTML block corresponds to its own Application.Module to maintain separation for the logic of my various views.
  • jQuery Mobile Page. Each Layout has multiple Region areas within. Notice how I have nested Regions by having Region > Layout > Region(s)
  • I get whatever content I need (in this case AJAX data from an API) whereby Backbone.Collection (i.e. a SQL table) contains many Backbone.Models (i.e. individual table rows)
  • ItemView is a View for individual Backbone.Model objects
  • In this case I use a CompositeView for my Backbone.Collection.
  • As a Collection contains multiple Models, so too does a CompositeView contain multiple ItemViews
  • A “show” call to will automatically cause the entire collection to render whereby the CompositeView wraps all of the individually rendered ItemView HTML. (think UL>LI*5, or TABLE>TR*5). The rendered aggregate HTML block will then be rendered into the region, replacing anything that was there before (may be override available)