timeline_setter 0.2.0 → 0.3.0

data/public/javascripts/timeline-setter.js

@@ -1,9 +1,12 @@
-(function(){
+(function($, undefined){
 
   // Expose `TimelineSetter` globally, so we can call `Timeline.Timeline.boot()`
   // to kick off at any point.
   var TimelineSetter = window.TimelineSetter = (window.TimelineSetter || {});
 
+  // Current version of `TimelineSetter`
+  TimelineSetter.VERSION = "0.3.0";
+
   // Mixins
   // ------
   // Each mixin operates on an object's `prototype`.
@@ -12,18 +15,19 @@
   // object. Unlike other notification systems, when an event is triggered every
   // callback bound to the object is invoked.
   var observable = function(obj){
-
     // Registers a callback function for notification at a later time.
-    obj.bind = function(cb){
-      this._callbacks = this._callbacks || [];
-      this._callbacks.push(cb);
+    obj.bind = function(e, cb){
+      var callbacks = (this._callbacks = this._callbacks || {});
+      var list = (callbacks[e] = callbacks[e] || []);
+      list.push(cb);
     };
 
     // Invoke all callbacks registered to the object with `bind`.
-    obj.trigger = function(){
-      if (!this._callbacks) return;
-      for(var i = 0; callback = this._callbacks[i]; i++)
-        callback.apply(this, arguments);
+    obj.trigger = function(e){
+      if(!this._callbacks) return;
+      var list = this._callbacks[e];
+      if(!list) return;
+      for(var i = 0; i < list.length; i++) list[i].apply(this, arguments);
     };
   };
 
@@ -31,14 +35,9 @@
   // Each `transformable` contains two event listeners that handle moving associated
   // DOM elements around the page.
   var transformable = function(obj){
-
-    // Move the associated element a specified delta. Of note: because events
-    // aren't scoped by key, TimelineSetter uses plain old jQuery events for
-    // message passing. So each registered callback first checks to see if the
-    // event fired matches the event it is listening for.
-    obj.move = function(e){
-      if (!e.type === "move" || !e.deltaX) return;
-
+    // Move the associated element a specified delta.
+    obj.move = function(evtName, e){
+      if (!e.deltaX) return;
       if (_.isUndefined(this.currOffset)) this.currOffset = 0;
       this.currOffset += e.deltaX;
       this.el.css({"left" : this.currOffset});
@@ -47,12 +46,20 @@
     // The width for the `Bar` and `CardContainer` objects is set in percentages,
     // in order to zoom the Timeline all that's needed is to increase or decrease
     // the percentage width.
-    obj.zoom = function(e){
-      if (!e.type === "zoom") return;
+    obj.zoom = function(evtName, e){
+      if (!e.width) return;
       this.el.css({ "width": e.width });
     };
   };
 
+  // The `queryable` mixin scopes jQuery to
+  // a given container.
+  var queryable = function(obj, container) {
+    obj.$ = function(query) {
+      return window.$(query, container);
+    };
+  };
+
 
   // Plugins
   // -------
@@ -60,7 +67,7 @@
 
   // Check to see if we're on a mobile device.
   var touchInit = 'ontouchstart' in document;
-  if (touchInit) jQuery.event.props.push("touches");
+  if (touchInit) $.event.props.push("touches");
 
   // The `draggable` plugin tracks changes in X offsets due to mouse movement
   // or finger gestures and proxies associated events on a particular element.
@@ -182,41 +189,56 @@
     }
   };
 
-  // An object containing human translations for date indexes.
-  Intervals.HUMAN_DATES = {
-    months : ['Jan.', 'Feb.', 'March', 'April', 'May', 'June', 'July', 'Aug.', 'Sept.', 'Oct.', 'Nov.', 'Dec.']
+  // Format dates based for AP style.
+  // Pass an override function in the config object to override.
+  Intervals.dateFormats = function(timestamp) {
+    var d = new Date(timestamp);
+    var defaults = {};
+    var months   = ['Jan.', 'Feb.', 'March', 'April', 'May', 'June', 'July', 'Aug.', 'Sept.', 'Oct.', 'Nov.', 'Dec.'];
+    var bigHours = d.getHours() > 12;
+    var ampm     = " " + (d.getHours() >= 12 ? 'p.m.' : 'a.m.');
+
+
+    defaults.month = months[d.getMonth()];
+    defaults.year  = d.getFullYear();
+    defaults.date  = defaults.month + " " + d.getDate() + ', ' + defaults.year;
+
+    var hours;
+    if(bigHours) {
+      hours = d.getHours() - 12;
+    } else {
+      hours = d.getHours() > 0 ? d.getHours() : "12";
+    }
+
+    hours += ":" + padNumber(d.getMinutes());
+    defaults.hourWithMinutes = hours + ampm;
+    defaults.hourWithMinutesAndSeconds = hours + ":" + padNumber(d.getSeconds()) + ampm;
+    // If we have user overrides, set them to defaults.
+    return Intervals.formatter(d, defaults) || defaults;
   };
 
   // A utility function to format dates in AP Style.
   Intervals.dateStr = function(timestamp, interval) {
-    var d                 = new Date(timestamp);
-    var dYear             = d.getFullYear();
-    var dMonth            = Intervals.HUMAN_DATES.months[d.getMonth()];
-    var dDate             = dMonth + " " + d.getDate() + ', ' + dYear;
-    var bigHours          = d.getHours() > 12;
-    var isPM              = d.getHours() >= 12;
-    var dHourWithMinutes  = (bigHours ? d.getHours() - 12 : (d.getHours() > 0 ? d.getHours() : "12")) + ":" + padNumber(d.getMinutes()) + " " + (isPM ? 'p.m.' : 'a.m.');
-    var dHourMinuteSecond = dHourWithMinutes + ":" + padNumber(d.getSeconds());
-
+    var d = new Intervals.dateFormats(timestamp);
     switch (interval) {
       case "Decade":
-        return dYear;
+        return d.year;
       case "Lustrum":
-        return dYear;
+        return d.year;
       case "FullYear":
-        return dYear;
+        return d.year;
       case "Month":
-        return dMonth + ', ' + dYear;
+        return d.month + ', ' + d.year;
       case "Week":
-        return dDate;
+        return d.date;
       case "Date":
-        return dDate;
+        return d.date;
       case "Hours":
-        return dHourWithMinutes;
+        return d.hourWithMinutes;
       case "Minutes":
-        return dHourWithMinutes;
+        return d.hourWithMinutes;
       case "Seconds":
-        return dHourMinuteSecond;
+        return d.hourWithMinutesAndSeconds;
     }
   };
 
@@ -245,8 +267,9 @@
 
     // Find the maximum interval we should use based on the estimates in `INTERVALS`.
     computeMaxInterval : function() {
-      for (var i = 0; i < this.INTERVAL_ORDER.length; i++)
+      for (var i = 0; i < this.INTERVAL_ORDER.length; i++) {
         if (!this.isAtLeastA(this.INTERVAL_ORDER[i])) break;
+      }
       return i - 1;
     },
 
@@ -266,7 +289,7 @@
 
     // Returns the first year of the five year "lustrum" a Date belongs to
     // as an integer. A lustrum is a fancy Roman word for a "five-year period."
-    // You can read more about it [here](http://en.wikipedia.org/wiki/Lustrum). 
+    // You can read more about it [here](http://en.wikipedia.org/wiki/Lustrum).
     // This all means that if you pass in the year 2011 you'll get 2010 back.
     // And if you pass in the year 1997 you'll get 1995 back.
     getLustrum : function(date) {
@@ -297,7 +320,7 @@
 
       // Zero the special extensions, and adjust as idx necessary.
       switch(intvl){
-        case 'Decade':      
+        case 'Decade':
           date.setFullYear(this.getDecade(date));
           break;
         case 'Lustrum':
@@ -310,7 +333,7 @@
 
       // Zero out the rest
       while(idx--){
-        var intvl = this.INTERVAL_ORDER[idx];
+        intvl = this.INTERVAL_ORDER[idx];
         if(intvl !== 'Week') date["set" + intvl](intvl === "Date" ? 1 : 0);
       }
 
@@ -331,7 +354,7 @@
         case 'Week':
           date.setTime(this.getWeekCeil(date).getTime());
           break;
-        default: 
+        default:
           date["set" + intvl](date["get" + intvl]() + 1);
       }
       return date.getTime();
@@ -365,18 +388,10 @@
   var sync = function(origin, listener){
     var events = Array.prototype.slice.call(arguments, 2);
     _.each(events, function(ev){
-      origin.bind(function(e){
-        if (e.type === ev && listener[ev])
-          listener[ev](e);
-      });
+      origin.bind(ev, function(){ listener[ev].apply(listener, arguments); });
     });
   };
 
-  // Get a template from the DOM and return a compiled function.
-  var template = function(query) {
-    return _.template($(query).html());
-  };
-
   // Simple function to strip suffixes like `"px"` and return a clean integer for
   // use.
   var cleanNumber = function(str){
@@ -436,32 +451,80 @@
   // Models
   // ------
 
-  // The main kickoff point for rendering the timeline. The `Timeline` constructor
-  // takes a json array of card representations and then builds series, calculates
-  // intervals `sync`s the `Bar` and `CardContainer` objects and triggers the
-  // `render` event.
+  // Initialize a Timeline object in a container element specified
+  // in the config object.
   var Timeline = TimelineSetter.Timeline = function(data, config) {
-    data = data.sort(function(a, b){ return a.timestamp - b.timestamp; });
+    _.bindAll(this, 'render', 'setCurrentTimeline');
+    this.data = data.sort(function(a, b){ return a.timestamp - b.timestamp; });
     this.bySid    = {};
+    this.cards    = [];
     this.series   = [];
-    this.config   = (config || {});
-    this.bounds   = new Bounds();
-    this.bar      = new Bar(this);
-    this.cardCont = new CardScroller(this);
-    this.createSeries(data);
-    var range = new Intervals(this.bounds, config.interval);
-    this.intervals = range.getRanges();
-    this.bounds.extend(this.bounds.min - range.getMaxInterval() / 2);
-    this.bounds.extend(this.bounds.max + range.getMaxInterval() / 2);
-    this.bar.render();
-
-    sync(this.bar, this.cardCont, "move", "zoom");
-    var e = $.Event("render");
-    this.trigger(e);
+    this.config   = config;
+    this.config.container = this.config.container || "#timeline";
+
+    // Override default date formats
+    // by writing a `formatter` function that returns
+    // an object containing all the formats
+    // you'd like to override. Pass in `d`
+    // which is a date object, and `defaults`, which
+    // are the formatters we override.
+    //
+    //      formatter : function(d, defaults) {
+    //        defaults.months = ['enero', 'febrero', 'marzo', 
+    //                          'abril', 'mayo', 'junio', 'julio', 
+    //                          'agosto', 'septiembre', 'octubre', 
+    //                          'noviembre', 'diciembre'];
+    //        return defaults;
+    //      }
+    Intervals.formatter = this.config.formatter || function(d, defaults) { return defaults; };
   };
   observable(Timeline.prototype);
 
   Timeline.prototype = _.extend(Timeline.prototype, {
+    // The main kickoff point for rendering the timeline. The `Timeline` constructor
+    // takes a JSON array of card representations and then builds series, calculates
+    // intervals `sync`s the `Bar` and `CardContainer` objects.
+    render : function() {
+      var that = this;
+
+      // create `this.$` from queryable mixin.
+      queryable(this, this.config.container);
+
+      // Stick the barebones HTML structure in the dom,
+      // so we can play with it.
+      $(this.config.container).html(JST.timeline());
+
+      this.bounds   = new Bounds();
+      this.bar      = new Bar(this);
+      this.cardCont = new CardScroller(this);
+      this.createSeries(this.data);
+      var range = new Intervals(this.bounds, this.config.interval);
+      this.intervals = range.getRanges();
+      this.bounds.extend(this.bounds.min - range.getMaxInterval() / 2);
+      this.bounds.extend(this.bounds.max + range.getMaxInterval() / 2);
+      this.bar.render();
+      sync(this.bar, this.cardCont, "move", "zoom");
+      this.trigger('render');
+
+      new Zoom("in", this);
+      new Zoom("out", this);
+      this.chooseNext = new Chooser("next", this);
+      this.choosePrev = new Chooser("prev", this);
+      if (!this.$(".TS-card_active").is("*")) this.chooseNext.click();
+
+      // Bind a click handler to this timeline container
+      // that sets it as as the global current timeline
+      // for key presses.
+      $(this.config.container).bind('click', this.setCurrentTimeline);
+
+      this.trigger('load');
+    },
+
+    // Set a global with the current timeline, mostly for key presses.
+    setCurrentTimeline : function() {
+      TimelineSetter.currentTimeline = this;
+    },
+
     // Loop through the JSON and add each element to a series.
     createSeries : function(series){
       for(var i = 0; i < series.length; i++)
@@ -481,6 +544,8 @@
 
       this.bounds.extend(series.max());
       this.bounds.extend(series.min());
+
+      this.trigger('cardAdd', card);
     }
   });
 
@@ -494,18 +559,19 @@
   // scenes `Bar` handles the moving and zooming behaviours through the `draggable`
   // and `wheel` plugins.
   var Bar = function(timeline) {
-    this.el = $(".TS-notchbar");
-    this.el.css({ "left": 0 });
+    var that = this;
     this.timeline = timeline;
+
+    this.el = this.timeline.$(".TS-notchbar");
+    this.el.css({ "left": 0 });
     draggable(this);
     wheel(this);
     _.bindAll(this, "moving", "doZoom");
     this.el.bind("dragging scrolled", this.moving);
     this.el.bind("doZoom", this.doZoom);
-    this.template = template("#TS-year_notch_tmpl");
     this.el.bind("dblclick doubletap", function(e){
       e.preventDefault();
-      $(".TS-zoom_in").click();
+      that.timeline.$(".TS-zoom_in").click();
     });
   };
   observable(Bar.prototype);
@@ -527,9 +593,9 @@
       if (offset + e.deltaX > pOffset)
         e.deltaX = pOffset - offset;
 
-      e.type = "move";
-      this.trigger(e);
-      this.move(e);
+      this.trigger("move", e);
+      this.timeline.trigger("move", e); // for API
+      this.move("move", e);
     },
 
     // As the timeline zooms, the `Bar` tries to keep the current notch (i.e.
@@ -538,7 +604,7 @@
     // bar to correct for this behaviour, and in future versions we'll fix this.
     doZoom : function(e, width){
       var that = this;
-      var notch = $(".TS-notch_active");
+      var notch = this.timeline.$(".TS-notch_active");
       var getCur = function() {
         return notch.length > 0 ? notch.position().left : 0;
       };
@@ -553,7 +619,7 @@
           curr = getCur();
           e = $.Event("zoom");
           e.width = current + "%";
-          that.trigger(e);
+          that.trigger("zoom", e);
         }
       });
     },
@@ -565,7 +631,7 @@
       var bounds    = this.timeline.bounds;
 
       for (var i = 0; i < intervals.length; i++) {
-        var html = this.template({'timestamp' : intervals[i].timestamp, 'human' : intervals[i].human });
+        var html = JST.year_notch({'timestamp' : intervals[i].timestamp, 'human' : intervals[i].human });
         this.el.append($(html).css("left", bounds.project(intervals[i].timestamp, 100) + "%"));
       }
     }
@@ -575,7 +641,7 @@
   // The `CardScroller` mirrors the moving and zooming of the `Bar` and is the
   // canvas where individual cards are rendered.
   var CardScroller = function(timeline){
-    this.el = $("#TS-card_scroller_inner");
+    this.el = timeline.$(".TS-card_scroller_inner");
   };
   observable(CardScroller.prototype);
   transformable(CardScroller.prototype);
@@ -588,8 +654,7 @@
     this.color    = this.name.length > 0 ? color() : "default";
     this.cards    = [];
     _.bindAll(this, "render", "showNotches", "hideNotches");
-    this.template = template("#TS-series_legend_tmpl");
-    this.timeline.bind(this.render);
+    this.timeline.bind("render", this.render);
   };
   observable(Series.prototype);
 
@@ -609,23 +674,22 @@
     hideNotches : function(e){
       e.preventDefault();
       this.el.addClass("TS-series_legend_item_inactive");
-      this.trigger($.Event("hideNotch"));
+      this.trigger("hideNotch");
     },
 
     // Activate the legend item and trigger the `showNotch` event.
     showNotches : function(e){
       e.preventDefault();
       this.el.removeClass("TS-series_legend_item_inactive");
-      this.trigger($.Event("showNotch"));
+      this.trigger("showNotch");
     },
 
     // Create and append the label to `.TS-series_nav_container` and bind up
     // `hideNotches` and `showNotches`.
     render : function(e){
-      if (!e.type === "render") return;
       if (this.name.length === 0) return;
-      this.el = $(this.template(this));
-      $(".TS-series_nav_container").append(this.el);
+      this.el = $(JST.series_legend(this));
+      this.timeline.$(".TS-series_nav_container").append(this.el);
       this.el.toggle(this.hideNotches, this.showNotches);
     }
   });
@@ -642,43 +706,37 @@
   // and a `.TS-card_container` which is lazily rendered.
   var Card = function(card, series) {
     this.series = series;
-    var card = _.clone(card);
+    this.timeline = this.series.timeline;
+    card = _.clone(card);
     this.timestamp = card.timestamp;
     this.attributes = card;
     this.attributes.topcolor = series.color;
-
-    this.template = template("#TS-card_tmpl");
-    this.ntemplate = template("#TS-notch_tmpl");
     _.bindAll(this, "render", "activate", "flip", "setPermalink", "toggleNotch");
-    this.series.bind(this.toggleNotch);
-    this.series.timeline.bind(this.render);
-    this.series.timeline.bar.bind(this.flip);
+    this.series.bind("hideNotch", this.toggleNotch);
+    this.series.bind("showNotch", this.toggleNotch);
+    this.timeline.bind("render", this.render);
+    this.timeline.bar.bind("flip", this.flip);
     this.id = [
       this.get('timestamp'),
       this.get('description').split(/ /)[0].replace(/[^a-zA-Z\-]/g,"")
     ].join("-");
+    this.timeline.cards.push(this);
   };
 
-  Card.prototype = {
+  Card.prototype = _.extend(Card.prototype, {
     // Get a particular attribute by key.
     get : function(key){
       return this.attributes[key];
     },
 
-    // A version of `jQuery` scoped to the `Card`'s element.
-    $ : function(query){
-      return $(query, this.el);
-    },
-
     // When each `Card` is rendered via a render event, it appends a notch to the
     // `Bar` and binds a click handler so it can be activated. if the `Card`'s id
     // is currently selected via `window.location.hash` it's activated.
-    render : function(e){
-      if (!e.type === "render") return;
-      this.offset = this.series.timeline.bounds.project(this.timestamp, 100);
-      var html = this.ntemplate(this.attributes);
+    render : function(){
+      this.offset = this.timeline.bounds.project(this.timestamp, 100);
+      var html = JST.notch(this.attributes);
       this.notch = $(html).css({"left": this.offset + "%"});
-      $(".TS-notchbar").append(this.notch);
+      this.timeline.$(".TS-notchbar").append(this.notch);
       this.notch.click(this.activate);
       if (history.get() === this.id) this.activate();
     },
@@ -686,15 +744,15 @@
     // As the `Bar` moves the current card checks to see if it's outside the viewport,
     // if it is the card is flipped so as to be visible for the longest period
     // of time. The magic number here (7) is half the width of the css arrow.
-    flip : function(e) {
-      if (e.type !== "move" || !this.el || !this.el.is(":visible")) return;
+    flip : function() {
+      if (!this.el || !this.el.is(":visible")) return;
       var rightEdge   = this.$(".TS-item").offset().left + this.$(".TS-item").width();
-      var tRightEdge  = $("#timeline_setter").offset().left + $("#timeline_setter").width();
+      var tRightEdge  = this.timeline.$(".timeline_setter").offset().left + this.timeline.$(".timeline_setter").width();
       var margin      = this.el.css("margin-left") === this.originalMargin;
-      var flippable   = this.$(".TS-item").width() < $("#timeline_setter").width() / 2;
+      var flippable   = this.$(".TS-item").width() < this.timeline.$(".timeline_setter").width() / 2;
       var offTimeline = this.el.position().left - this.$(".TS-item").width() < 0;
 
-      // If the card's right edge is more than the timeline's right edge and 
+      // If the card's right edge is more than the timeline's right edge and
       // it's never been flipped before and it won't go off the timeline when
       // flipped. We'll flip it.
       if (tRightEdge - rightEdge < 0 && margin && !offTimeline) {
@@ -703,7 +761,7 @@
         // Otherwise, if the card is off the left side of the timeline and we have
         // flipped it before and the card's width is less than half of the width
         // of the whole timeline, we'll flip it to the default position.
-      } else if (this.el.offset().left - $("#timeline_setter").offset().left < 0 && !margin && flippable) {
+      } else if (this.el.offset().left - this.timeline.$(".timeline_setter").offset().left < 0 && !margin && flippable) {
         this.el.css({"margin-left": this.originalMargin});
         this.$(".TS-css_arrow").css({"left": 0});
       }
@@ -714,26 +772,33 @@
     // and moves the `Bar` if its element outside the visible portion of the
     // timeline.
     activate : function(e){
+      var that = this;
       this.hideActiveCard();
       if (!this.el) {
-        this.el = $(this.template({card: this}));
+        this.el = $(JST.card({card: this}));
+
+        // create a `this.$` scoped to its card.
+        queryable(this, this.el);
+
         this.el.css({"left": this.offset + "%"});
-        $("#TS-card_scroller_inner").append(this.el);
+        this.timeline.$(".TS-card_scroller_inner").append(this.el);
         this.originalMargin = this.el.css("margin-left");
         this.el.delegate(".TS-permalink", "click", this.setPermalink);
         // Reactivate if there are images in the html so we can recalculate
         // widths and position accordingly.
-        this.$("img").load(this.activate);
+        this.timeline.$("img").load(this.activate);
       }
+
       this.el.show().addClass(("TS-card_active"));
       this.notch.addClass("TS-notch_active");
       this.setWidth();
 
-      // In the case that the card is outside the bounds the wrong way when 
+      // In the case that the card is outside the bounds the wrong way when
       // it's flipped, we'll take care of it here before we move the actual
       // card.
-      this.flip($.Event("move"));
+      this.flip();
       this.move();
+      this.series.timeline.trigger("cardActivate", this.attributes);
     },
 
     // For Internet Explorer each card sets the width of` .TS-item_label` to
@@ -742,9 +807,10 @@
     // width. Which is a funny way of saying, if you'd like to set the width of
     // the card as a whole, fiddle with `.TS-item_year`s width.
     setWidth : function(){
-      var max = _.max(_.toArray(this.$(".TS-item_user_html").children()), function(el){ return $(el).width(); });
-      if ($(max).width() > this.$(".TS-item_year").width()) {
-        this.$(".TS-item_label").css("width", $(max).width());
+      var that = this;
+      var max = _.max(_.toArray(this.$(".TS-item_user_html").children()), function(el){ return that.$(el).width(); });
+      if (this.$(max).width() > this.$(".TS-item_year").width()) {
+        this.$(".TS-item_label").css("width", this.$(max).width());
       } else {
         this.$(".TS-item_label").css("width", this.$(".TS-item_year").width());
       }
@@ -754,13 +820,13 @@
     move : function() {
       var e = $.Event('moving');
       var offset  = this.$(".TS-item").offset();
-      var toffset = $("#timeline_setter").offset();
+      var toffset = this.timeline.$(".timeline_setter").offset();
       if (offset.left < toffset.left) {
         e.deltaX = toffset.left - offset.left + cleanNumber(this.$(".TS-item").css("padding-left"));
-        this.series.timeline.bar.moving(e);
-      } else if (offset.left + this.$(".TS-item").outerWidth() > toffset.left + $("#timeline_setter").width()) {
-        e.deltaX = toffset.left + $("#timeline_setter").width() - (offset.left + this.$(".TS-item").outerWidth());
-        this.series.timeline.bar.moving(e);
+        this.timeline.bar.moving(e);
+      } else if (offset.left + this.$(".TS-item").outerWidth() > toffset.left + this.timeline.$(".timeline_setter").width()) {
+        e.deltaX = toffset.left + this.timeline.$(".timeline_setter").width() - (offset.left + this.$(".TS-item").outerWidth());
+        this.timeline.bar.moving(e);
       }
     },
 
@@ -771,13 +837,13 @@
 
     // Globally hide any cards with `TS-card_active`.
     hideActiveCard : function() {
-      $(".TS-card_active").removeClass("TS-card_active").hide();
-      $(".TS-notch_active").removeClass("TS-notch_active");
+      this.timeline.$(".TS-card_active").removeClass("TS-card_active").hide();
+      this.timeline.$(".TS-notch_active").removeClass("TS-notch_active");
     },
 
-    // An event listener to toggle this notche on and off via `Series`.
+    // An event listener to toggle this notch on and off via `Series`.
     toggleNotch : function(e){
-      switch (e.type) {
+      switch (e) {
         case "hideNotch":
           this.notch.hide().removeClass("TS-notch_active").addClass("TS-series_inactive");
           if (this.el) this.el.hide();
@@ -787,7 +853,7 @@
       }
     }
 
-  };
+  });
 
 
   // Simple inheritance helper for `Controls`.
@@ -802,16 +868,17 @@
   // --------
 
   // Each control is basically a callback wrapper for a given DOM element.
-  var Control = function(direction){
+  var Control = function(direction, timeline){
+    this.timeline = timeline;
     this.direction = direction;
-    this.el = $(this.prefix + direction);
+    this.el = this.timeline.$(this.prefix + direction);
     var that = this;
     this.el.bind('click', function(e) { e.preventDefault(); that.click(e);});
   };
 
   // Each `Zoom` control adjusts the `curZoom` when clicked.
   var curZoom = 100;
-  var Zoom = function(direction) {
+  var Zoom = function(direction, timeline) {
     Control.apply(this, arguments);
   };
   inherits(Zoom, Control);
@@ -824,7 +891,7 @@
     click : function() {
       curZoom += (this.direction === "in" ? +100 : -100);
       if (curZoom >= 100) {
-        $(".TS-notchbar").trigger('doZoom', [curZoom]);
+        this.timeline.$(".TS-notchbar").trigger('doZoom', [curZoom]);
       } else {
         curZoom = 100;
       }
@@ -833,9 +900,9 @@
 
 
   // Each `Chooser` activates the next or previous notch.
-  var Chooser = function(direction) {
+  var Chooser = function(direction, timeline) {
     Control.apply(this, arguments);
-    this.notches = $(".TS-notch");
+    this.notches = this.timeline.$(".TS-notch");
   };
   inherits(Chooser, Control);
 
@@ -847,7 +914,7 @@
     click: function(e){
       var el;
       var notches    = this.notches.not(".TS-series_inactive");
-      var curCardIdx = notches.index($(".TS-notch_active"));
+      var curCardIdx = notches.index(this.timeline.$(".TS-notch_active"));
       var numOfCards = notches.length;
       if (this.direction === "next") {
         el = (curCardIdx < numOfCards ? notches.eq(curCardIdx + 1) : false);
@@ -859,37 +926,106 @@
     }
   });
 
+  // JS API
+  // ------
+
+  // The TimelineSetter JS API allows you to listen to certain
+  // timeline events, and activate cards programmatically.
+  // To take advantage of it, assign the timeline boot function to a variable 
+  // like so:
+  //
+  //     var currentTimeline = TimelineSetter.Timeline.boot(
+  //       [data], {config}
+  //     );
+  //
+  // then call methods on the `currentTimeline.api` object
+  //
+  //     currentTimeline.api.onLoad(function() { 
+  //       console.log("I'm ready");
+  //     });
+  //
+  TimelineSetter.Api = function(timeline) {
+    this.timeline = timeline;
+  };
+
+  TimelineSetter.Api.prototype = _.extend(TimelineSetter.Api.prototype, {
+    // Register a callback for when the timeline is loaded
+    onLoad : function(cb) {
+      this.timeline.bind('load', cb);
+    },
+
+    // Register a callback for when a card is added to the timeline
+    // Callback has access to the event name and the card object
+    onCardAdd : function(cb) {
+      this.timeline.bind('cardAdd', cb);
+    },
+
+    // Register a callback for when a card is activated.
+    // Callback has access to the event name and the card object
+    onCardActivate : function(cb) {
+      this.timeline.bind('cardActivate', cb);
+    },
+
+    // Register a callback for when the bar is moved or zoomed.
+    // Be careful with this one: Bar move events can be fast
+    // and furious, especially with scroll wheels in Safari.
+    onBarMove : function(cb) {
+      // Bind a 'move' event to the timeline, because
+      // at this point, `timeline.bar` isn't available yet.
+      // To get around this, we'll trigger the bar's
+      // timeline's move event when the bar is moved.
+      this.timeline.bind('move', cb);
+    },
+
+    // Show the card matching a given timestamp
+    // Right now, timelines only support one card per timestamp
+    activateCard : function(timestamp) {
+      _(this.timeline.cards).detect(function(card) { return card.timestamp === timestamp; }).activate();
+    }
+  });
+
+  // Global TS keydown function to bind key events to the
+  // current global currentTimeline.
+  TimelineSetter.bindKeydowns = function() {
+    $(document).bind('keydown', function(e) {
+      if (e.keyCode === 39) {
+         TimelineSetter.currentTimeline.chooseNext.click();
+      } else if (e.keyCode === 37) {
+        TimelineSetter.currentTimeline.choosePrev.click();
+      } else {
+        return;
+      }
+    });
+  };
+
 
   // Finally, let's create the whole timeline. Boot is exposed globally via
   // `TimelineSetter.Timeline.boot()` which takes the JSON generated by
-  // the timeline-setter binary as an argument. This is handy if you want
-  // to be able to generate timelines at arbitrary times (say, for example,
-  // in an ajax callback).
+  // the timeline-setter binary as its first argument, and a config hash as its second.
+  // The config hash looks for a container element, an interval for interval notches
+  // and a formatter function for dates. All of these are optional.
   //
-  // In the default install of TimelineSetter, Boot is called in the generated
-  // HTML. We'll kick everything off by creating a `Timeline`, some `Controls`
-  // and binding to `"keydown"`.
+  // We also initialize a new API object for each timeline, accessible via the
+  // timeline variable's `api` method (e.g. `currentTimeline.api`) and look for 
+  // how many timelines are globally on the page for keydown purposes. We'll only 
+  // bind keydowns globally if there's only one timeline on the page.
   Timeline.boot = function(data, config) {
-    $(function(){
-
-      TimelineSetter.timeline = new Timeline(data, config || {});
-      new Zoom("in");
-      new Zoom("out");
-      var chooseNext = new Chooser("next");
-      var choosePrev = new Chooser("prev");
-      if (!$(".TS-card_active").is("*")) chooseNext.click();
-
-      $(document).bind('keydown', function(e) {
-        if (e.keyCode === 39) {
-          chooseNext.click();
-        } else if (e.keyCode === 37) {
-          choosePrev.click();
-        } else {
-          return;
-        }
-      });
-    });
+    var timeline = TimelineSetter.timeline = new Timeline(data, config || {});
+    var api      = new TimelineSetter.Api(timeline);
 
+    if (!TimelineSetter.pageTimelines) {
+      TimelineSetter.currentTimeline = timeline;
+      TimelineSetter.bindKeydowns();
+    }
+
+    TimelineSetter.pageTimelines = TimelineSetter.pageTimelines ? TimelineSetter.pageTimelines += 1 : 1;
+
+    $(timeline.render);
+
+    return {
+      timeline : timeline,
+      api      : api
+    };
   };
 
-})();
+})(jQuery);