update for sprockets, rails 3.1

README.md

@@ -1,16 +1,84 @@
-# backbone-support
-
 Helper and utility classes that fill out Backbone for serious development.
 
-## dependencies
+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
+## Development
 
 First:
 
@@ -24,10 +92,37 @@ To not open tests a browser window:
 
     bundle exec rake jasmine:ci
 
-## integrating
+## 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
 
-This hasn't been tried with Sprockets yet, but hopefully it's Rails 3.1 ready.
-Meanwhile, for Jammit...
+### With Jammit
 
 First off:
 
@@ -36,7 +131,8 @@ First off:
 In your `config/application.rb`:
 
 ``` ruby
-config.middleware.use Rack::Static, :urls => ['/vendor/plugins/backbone-support/lib/assets']
+config.middleware.use Rack::Static, 
+                      :urls => ['/vendor/plugins/backbone-support/lib/assets']
 ```
 
 And in your `config/assets.yml`:
@@ -49,16 +145,17 @@ javascripts:
     - 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:
+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:
+Your individual specs will then need the full root path in `require`. For
+example:
 
 
 ``` js
@@ -74,6 +171,6 @@ require("/vendor/plugins/backbone-support/lib/assets/backbone-support/composite_
 require("/vendor/plugins/backbone-support/lib/assets/backbone-support/swapping_router.js");
 ```
 
-## license
+## License
 
 Copyright 2011 thoughtbot. Please check LICENSE for more details.

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

lib/assets/javascripts/backbone-support.js

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

lib/backbone-support.rb

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

lib/backbone-support/engine.rb

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

lib/backbone-support/version.rb

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