backbone-support 0.0.1

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gem 'jasmine'
+gem 'headless'
+gem 'rake'

data/Gemfile.lock

@@ -0,0 +1,38 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    childprocess (0.2.0)
+      ffi (~> 1.0.6)
+    diff-lcs (1.1.2)
+    ffi (1.0.9)
+    headless (0.1.0)
+    jasmine (1.0.2.1)
+      json_pure (>= 1.4.3)
+      rack (>= 1.1)
+      rspec (>= 1.3.1)
+      selenium-webdriver (>= 0.1.3)
+    json_pure (1.5.3)
+    rack (1.3.2)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    rubyzip (0.9.4)
+    selenium-webdriver (2.3.2)
+      childprocess (>= 0.1.9)
+      ffi (>= 1.0.7)
+      json_pure
+      rubyzip
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  headless
+  jasmine
+  rake

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 thoughtbot
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+Helper and utility classes that fill out Backbone for serious development.
+
+Inspired by our projects and the Backbone.js on Rails book:
+http://workshops.thoughtbot.com/backbone-js-on-rails
+
+The book contains complete instructions and in-depth coverage of the internals
+of CompositeView and Swappingrouter, and an example application that shows
+their usage 
+
+### SwappingRouter
+
+A Router subclass the provides a standard way to swap one view for another.
+
+This introduces a convention that all views have a `leave()` function,
+responsible for unbinding and cleaning up the view. And the convention that
+all actions underneath the same `Router` share the same root element, and
+define it as `el` on the router.
+
+Now, a `SwappingRouter` can take advantage of the `leave()` function, and
+clean up any existing views before swapping to a new one.  It swaps into a new
+view by rendering that view into its own `el`:
+
+    swap: function(newView) {
+      if (this.currentView && this.currentView.leave) {
+        this.currentView.leave();
+      }
+  
+      this.currentView = newView;
+      this.currentView.render();
+      $(this.el).empty().append(this.currentView.el);
+    }
+
+An example SwappingRouter would look as follows:
+
+    Trajectory.Routers.Stories = Support.SwappingRouter.extend({
+      initialize: function(options) {
+        this.el = $("div.primary_content");
+      },
+      routes: {
+        "stories": "index",
+        "stories/new": "newStory"
+      }
+      index: function(story_id) {
+        var view = new Trajectory.Views.StoriesIndex();
+        this.swap(view);
+      },
+      newStory: function() {
+        var view = new Trajectory.Views.StoryNew({ model: new Story() });
+        this.swap(view);
+      }
+    }
+
+### CompositeView
+
+CompositeView provides a convention for a parent view that has one or more
+child views.
+
+This introduces a convention that all views have a `leave()` function,
+responsible for unbinding and cleaning up the view.
+
+`CompositeView` provides methods for adding and removing children from the
+parent view.
+
+`CompositeView` maintains an array of its immediate children as
+`this.children`.  With this reference in place, a parent view's `leave()`
+method can invoke `leave()` on its children, ensuring that an entire tree of
+composed views is cleaned up properly.
+
+For child views that can dismiss themselves, such as dialog boxes, children
+maintain a back-reference at `this.parent`. This is used to reach up and call
+`this.parent.removeChild(this)` for these self-dismissing views.
+
+## Dependencies
+
+You'll need these, but chances are you already have them in your app:
+
+* jQuery
+* Underscore
+* Backbone
+
+## Development
+
+First:
+
+    bundle
+
+While TDD'ing:
+
+    bundle exec rake jasmine
+
+To not open tests a browser window:
+
+    bundle exec rake jasmine:ci
+
+## Installation
+
+The recommended usage is with Rails 3.1.
+
+### With Rails 3.1
+
+Add the gem to your Gemfile
+
+    gem "backbone-support"
+
+And then `bundle install`
+
+In your application.js, or in whatever file your backbone.js assets are
+required in, add the following:
+
+    //= require backbone-support
+
+This should be _above_ any usage of SwappingController or SwappingRouter, but
+below the inclusion of Backbone.js, Underscore, and jQuery.
+
+If you do not wish to include all of backbone-support, you can include
+individual pieces.  First, require the main support file:
+
+    //= require backbone-support/support
+
+Then require the individual assets you wish to use:
+
+    //= require backbone-support/swapping_router
+    //= require backbone-support/composite_view
+
+### With Jammit
+
+First off:
+
+    rails plugin install git@github.com:thoughtbot/backbone-support.git
+
+In your `config/application.rb`:
+
+``` ruby
+config.middleware.use Rack::Static, 
+                      :urls => ['/vendor/plugins/backbone-support/lib/assets/javascripts']
+```
+
+And in your `config/assets.yml`:
+
+``` yaml
+javascripts:
+  common:
+    - public/javascripts/vendor/underscore.js
+    - public/javascripts/vendor/backbone.js
+    - vendor/plugins/backbone-support/lib/assets/**/*.js
+```
+
+If you have evergreen tests, you will need to change your `require` statements
+since these files live in `vendor/`. Change `config/evergreen.rb` to be this:
+
+``` ruby
+Evergreen.configure do |config|
+  config.public_dir = '.'
+end
+```
+
+Your individual specs will then need the full root path in `require`. For
+example:
+
+
+``` js
+requirePublic = function(path) {
+  require("/public/javascripts/" + path);
+};
+
+requirePublic("vendor/underscore.js");
+requirePublic("vendor/backbone.js");
+
+require("/vendor/plugins/backbone-support/lib/assets/javascripts/backbone-support.js");
+require("/vendor/plugins/backbone-support/lib/assets/javascripts/backbone-support/composite_view.js");
+require("/vendor/plugins/backbone-support/lib/assets/javascripts/backbone-support/swapping_router.js");
+```
+
+## License
+
+Copyright 2011 thoughtbot. Please check LICENSE for more details.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'jasmine'
+load 'jasmine/tasks/jasmine.rake'
+
+task :default => "jasmine:ci"

data/backbone-support.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "backbone-support/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'backbone-support'
+  s.version     = BackboneSupport::VERSION.dup
+  s.authors     = ['Chad Pytel', 'Joe Ferris', 'Jason Morrison', 'Nick Quaranto']
+  s.email       = ['support@thoughtbot.com']
+  s.homepage    = 'http://github.com/thoughtbot/backbone-support'
+  s.summary     = 'SwappingController and CompositeView for Backbone.js'
+  s.description = 'SwappingController and CompositeView for Backbone.js'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency('jasmine')
+end

data/lib/assets/javascripts/backbone-support.js

@@ -0,0 +1,2 @@
+//= require backbone-support/support
+//= require_tree ./backbone-support

data/lib/assets/javascripts/backbone-support/composite_view.js

@@ -0,0 +1,48 @@
+Support.CompositeView = function(options) {
+  this.children = _([]);
+  Backbone.View.apply(this, [options]);
+};
+
+_.extend(Support.CompositeView.prototype, Backbone.View.prototype, {
+  leave: function() {
+    this.unbind();
+    this.remove();
+    this._leaveChildren();
+    this._removeFromParent();
+  },
+
+  renderChild: function(view) {
+    view.render();
+    this.children.push(view);
+    view.parent = this;
+  },
+
+  appendChild: function(view) {
+    this.renderChild(view);
+    $(this.el).append(view.el);
+  },
+
+  renderChildInto: function(view, container) {
+    this.renderChild(view);
+    $(container).empty().append(view.el);
+  },
+
+  _leaveChildren: function() {
+    this.children.chain().clone().each(function(view) {
+      if (view.leave)
+        view.leave();
+    });
+  },
+
+  _removeFromParent: function() {
+    if (this.parent)
+      this.parent._removeChild(this);
+  },
+
+  _removeChild: function(view) {
+    var index = this.children.indexOf(view);
+    this.children.splice(index, 1);
+  }
+});
+
+Support.CompositeView.extend = Backbone.View.extend;

data/lib/assets/javascripts/backbone-support/support.js

@@ -0,0 +1,2 @@
+Support = {};
+Support.VERSION = "0.0.1";

data/lib/assets/javascripts/backbone-support/swapping_router.js

@@ -0,0 +1,17 @@
+Support.SwappingRouter = function(options) {
+  Backbone.Router.apply(this, [options]);
+};
+
+_.extend(Support.SwappingRouter.prototype, Backbone.Router.prototype, {
+  swap: function(newView) {
+    if (this.currentView && this.currentView.leave) {
+      this.currentView.leave();
+    }
+
+    this.currentView = newView;
+    this.currentView.render();
+    $(this.el).empty().append(this.currentView.el);
+  }
+});
+
+Support.SwappingRouter.extend = Backbone.Router.extend;

data/lib/backbone-support.rb

@@ -0,0 +1,7 @@
+module BackboneSupport
+  if defined?(Rails)
+    class Engine < ::Rails::Engine
+      require 'backbone-support/engine'
+    end
+  end
+end

data/lib/backbone-support/engine.rb

@@ -0,0 +1,5 @@
+module BackboneSupport
+  class Engine < Rails::Engine
+    # auto wire
+  end
+end

data/lib/backbone-support/version.rb

@@ -0,0 +1,3 @@
+module BackboneSupport
+  VERSION = '0.0.1'.freeze
+end

data/spec/javascripts/composite_view_spec.js

@@ -0,0 +1,133 @@
+describe("Support.CompositeView", function() {
+  var orangeView = Support.CompositeView.extend({
+    render: function() {
+      var text = this.make("span", {}, "Orange!");
+      $(this.el).append(text);
+    }
+  });
+
+  var blankView = Support.CompositeView.extend({
+    render: function() {
+    }
+  });
+
+  var normalView = Backbone.View.extend({
+    render: function() {
+      var text = this.make("span", {}, "Normal!");
+      $(this.el).append(text);
+    }
+  });
+
+  beforeEach(function() {
+    Helpers.setup();
+    Helpers.append("test1");
+    Helpers.append("test2");
+  });
+
+  afterEach(function() {
+    Helpers.teardown();
+  });
+
+  describe("#renderChild", function() {
+    it("renders children views", function() {
+      var view = new blankView();
+      view.renderChild(new orangeView({el: "#test1"}));
+      view.renderChild(new orangeView({el: "#test2"}));
+
+      expect($("#test1").text()).toEqual("Orange!");
+      expect($("#test2").text()).toEqual("Orange!");
+    });
+  });
+
+  describe("#appendChild", function() {
+    it("renders and appends children views", function() {
+      var view = new blankView({el: "#test"});
+      view.appendChild(new orangeView());
+      view.appendChild(new orangeView());
+
+      expect($("#test").text()).toEqual("Orange!Orange!");
+    });
+  });
+
+  describe("#renderChildInto", function() {
+    it("renders child into the given element and replaces content there", function() {
+      $("#test1").text("Replace this!");
+
+      var view = new blankView({el: "#test"});
+      view.renderChildInto(new orangeView(), "#test1");
+
+      expect($("#test").text()).toEqual("");
+      expect($("#test1").text()).toEqual("Orange!");
+    });
+  });
+
+  describe("#leave", function() {
+    it("removes elements and events when leave() is called", function() {
+      var view = new orangeView();
+      var spy = sinon.spy(view, "unbind");
+
+      runs(function() {
+        view.render();
+        $("#test").append(view.el);
+      });
+
+      Helpers.sleep();
+
+      runs(function() {
+        expect($("#test").text()).toEqual("Orange!");
+      });
+
+      Helpers.sleep();
+
+      runs(function() {
+        view.leave();
+      });
+
+      Helpers.sleep();
+
+      runs(function() {
+        expect($("#test").text()).toEqual("");
+        expect(spy.called).toBeTruthy();
+      });
+    });
+
+    it("removes children views on leave", function() {
+      var view = new blankView();
+      view.renderChild(new orangeView({el: "#test1"}));
+      view.renderChild(new orangeView({el: "#test2"}));
+
+      view.leave();
+
+      expect($("#test1").size()).toEqual(0);
+      expect($("#test2").size()).toEqual(0);
+    });
+
+    it("doesn't fail on normal backbone views that may be children", function() {
+      var view = new blankView();
+      view.renderChild(new orangeView({el: "#test1"}));
+      view.renderChild(new normalView({el: "#test2"}));
+
+      view.leave();
+
+      expect($("#test1").size()).toEqual(0);
+      expect($("#test2").size()).toEqual(1);
+    });
+
+    it("removes self from parent if invoked on a child view", function() {
+      var view = new blankView();
+      var childView = new orangeView({el: "#test1"});
+      view.renderChild(childView)
+      view.renderChild(new orangeView({el: "#test2"}));
+
+      expect($("#test1").size()).toEqual(1);
+      expect($("#test2").size()).toEqual(1);
+      expect(view.children.size()).toEqual(2);
+
+      childView.leave();
+
+      expect($("#test1").size()).toEqual(0);
+      expect($("#test2").size()).toEqual(1);
+      expect(view.children.size()).toEqual(1);
+    });
+  });
+});