Permalink
Browse files

update for sprockets, rails 3.1

  • Loading branch information...
1 parent ef6ebcf commit 18689dcf923724768339f6e2868da74d376b5200 Chad Pytel committed Nov 29, 2011
View
121 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.
View
@@ -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
@@ -0,0 +1,2 @@
+//= require backbone-support/support
+//= require_tree ./backbone-support
View
@@ -0,0 +1,7 @@
+module BackboneSupport
+ if defined?(Rails)
+ class Engine < ::Rails::Engine
+ require 'backbone-support/engine'
+ end
+ end
+end
@@ -0,0 +1,5 @@
+module BackboneSupport
+ class Engine < Rails::Engine
+ # auto wire
+ end
+end
@@ -0,0 +1,3 @@
+module BackboneSupport
+ VERSION = '0.0.1'.freeze
+end

0 comments on commit 18689dc

Please sign in to comment.