ribcage-view

A simple base Backbone view class that adds subviews, rendering, and initialization.

• Install
• Usage
  • Simple example
  • Full example
• Methods
  • Override with caution
  • Override at will
  • Helpers
• Gotchas
• Contributing
  • Developing
  • Testing

Install

Installing via npm is easy:

npm install ribcage-view

Ribcage requires you to use browserify (or some other way to get require on the front-end).

Usage

Simple example

var View = require('ribcage-view')

/*
 * A view that doesn't do anything but render a template
 *
 * - a template is just a function that takes an object
 *   and returns a string to be rendered.
 *
 */
var templateView = new View({
  template: function(id){
    return '<div>' + id '</div>'
  }
})

Full example

// Extending a ribcage-view
var Base = require('ribcage-view')
  , _ = require('lodash')
  // it's not required, but using a state model is _highly_ recommended.
  , State = require('ampersand-state').extend({
    extraProperties: 'reject'
  })

var MyView = Base.extend({

  template: require('./template.html.hbs')

, className: 'myView'

, State: State.extend({
    props: {
      text: 'string'
    }
  })

, events: {
    'input input': 'onInputInput'
  }

// DOM Events
 , onInputInput: function onInputInput(e){
    this.state.text = e.target.value
   }

// Backbone Events
, bindEvents: function bindEvents(){
    // always stopListening so we don't reattach multiple listeners
    if (this.state) this.stopListening(this.state)

    // listen to state, model, etc… events
    this.listenTo(this.state, 'change:text', this.onStateChangeText)
  }

, onStateChangeText: function onStateChangeText(state, value){
    console.log(value)
  }

// Create Subviews
, createSubviewX: function createSubviewX(){
    return new SubviewX({})
  }

// Lifecycle Methods
, beforeInit: function beforeInit(options){
    this.state = new this.State(_.omit(options, ['model', 'collection']))
  }

// instantiate subviews
, afterInit: function afterInit() {
    this.subviewX = this.createSubviewX()
  }

, afterRender: function afterRender() {
    this.appendSubview(this.subviewX)
  }

, context: function context() {
    return this.state.toJSON()
  }

})

module.exports = MyView

Methods

Override with caution

These are methods that are reserved by Ribcage View. Overriding will break expected behavior.

initialize()

Sets up the view and calls the render method.

render()

Attaches the template to the DOM with all DOM and backbone events attached. Returns the view.

close([<Object> options, [<Function> callback]])

Closes out a view completely by removing it and all subviews from the DOM, destroying all listeners, and the view's DOM node.

options currently only accepts one key: keepDom which is a boolean. When set to true, it will preserve the view's DOM node. This is really only useful if removing many subviews at once that all share a parent node. Instead of removing each node, we can just remove the parent when we're done closing all the subviews.

The close happens in a requestAnimationFrame and the callback will be called when the close is complete.

// kill the subview. This removes it from the DOM, kills all event listeners, closes all subviews, and is the memory-leak free way to kill a view.
// `keepDom` is false by default. If you want to close, but leave this in the DOM (probably a bad idea), you can set to `true`
// The `keepDom` option exists for closing many views that share a parent element. You can then remove just the parent element.
this.myView.close({keepDom: false}, function myViewClosed(){
  console.log('myView has been closed')
})

closeSubviews([<Object> options, [<Function> callback]])

Closes all subviews. Takes the same options as close().

eachSubview(<Function> iterator[, <Object> context])

Iterate over each subview, performing the iterator function. context defaults to the view you're calling from.

// go through all the subviews
this.eachSubview(function eachSubview(subview) {
  // `this` is the parent view
  this.doSomething(subview.property)
})

Override at will

These methods provide defaults, but you should feel free to replace them with your own.

context()

Return an object for the template to use for its data. Defaults to the options.

beforeInit(<Object> options)

Called before anything else happens. Is passed the options from the constructor. This is a good place to instantiate a state model.

afterInit(<Object> options)

Called after all the initialization has completed. This is a good place to create subviews.

loadData(<Function> done)

If defined, will block rendering until done is called. Useful if you need to async load data from the server before anything happens.

beforeRender()

Called after loadData but before anything else in the render flow.

afterRender()

Called after the render has happened. This is a good place to put subviews into the DOM.

…
, afterRender: function afterRender(){
  this.appendSubview(this.mySubview)
}
…

bindEvents()

Called on every render. This is the place to attach backbone events to subviews. Be sure you call stopListening before listenTo so that you don't create multiple listeners for the same event.

…
, bindEvents: function bindEvents(){
  // always stopListening so we don't reattach multiple listeners
  if (this.model) this.stopListening(this.model)

  this.listenTo(this.model, 'change', this.render)
}
…

Helpers

These are methods that assist with common tasks.

proxy(<String> name, <Backbone.View> view)

Listen to an event from another view (probably a subview), and trigger the same event. This is useful if you want to pass an event up the chain of subviews.

appendSubview(<Backbone.View> view[, <jQuery el> el])

Appends the view to the view's DOM. Optionally, you can pass a specific DOM node to append to.

prependSubview(<Backbone.View> view[, <jQuery el> el])

Just like appendSubview, only it prepends.

appendSubviews(<Array of Backbone.View> views[, <jQuery el> el[, <Function> callback]])

Append an array of views. You can optionally pass in the el to append into.

This is an async function that is has better performance than calling appendSubview many times because it creates a documentFragment before appending to the DOM, and uses requestAnimationFrame.

The third argument is an optional callback that is called when the views are in the DOM.

// append many subviews at once
// e.g. if you want to append a sub view for all models in a collection
var collectionSubviews = this.collection.map(function(model){
  return new MyView({model: model})
})
// only the first argument is required
this.appendSubviews(collectionSubviews, this.$('.collection'), function(views){
  // views are rendered after a requestAnimationFrame
  console.log(assert.deepEqual(views, collectionSubviews))
})

batchAppendSubviews(<Array of Backbone.View> views[, <jQuery el> el], <Int> batchCount[, <Function> batchCallback, [<Function> callback]])

This is like appendSubviews, but it requires the third argument be a Number. It allows you to append a set amount of views per animationFrame which might be necessary for performance reasons.

batchAppendSubview takes two callbacks. The first is called on every batch append, the second is called when all views have been appended.

// if your subviews take time to render and slow down the DOM
// will render 2 subviews at a time.
this.batchAppendSubviews(collectionSubviews
  , this.$('#place')
  , 2
  , function onPortionAppended(){
    console.log('2 more subviews appended')
  }
  , function onBatchAppended(){
    console.log('all subviews appended')
  }
)

detachSubview(<Backbone.View> view)

Remove a view from the DOM, but keep it's node around in memory. This is useful if you want to move it to a different node.

closeSubviewsByModel(<Backbone.Model> model)

Finds all subviews that have the model set as their model and closes them.

this.listenTo(this.collection, 'remove', this.closeSubviewsByModel)

detachSubviewByModel(<Backbone.Model> model)

Like closeSubviewsByModel, but only detaches.

Gotchas

1. Remember to call View.prototype.initialize.apply(this, arguments) if you are override initialize. This fixes the loadData is not defined error. Alternatively, override afterInit and beforeInit instead.
2. Subviews are closed when their parent is rendered, and will lose their events unless you call .delegateEvents() on them in the parent's afterRender. See #5.

Contributing

Developing

Run this command to run tests at http://localhost:9999.

grunt dev

Testing

Tests can be run on Saucelabs.

# Run once to set up login info
$ export SAUCE_USERNAME=YOUR-SAUCE-USERNAME
$ export SAUCE_ACCESS_KEY=YOUR-SAUCE-API-KEY

# Run to test on sauce
$ grunt test