backbone-computed-properties v0.3.0

Backbone Computed Properties

Ember-style computed properties for Backbone models. This is very much a work in progress. Pull requests are welcome!

Install

Grab backbone-computed.min.js from the dist directory and include it on your page.

<script src="backbone-computed.min.js"></script>

Or install through Bower

bower install backbone-computed-properties

Or install through NPM

npm install backbone-computed-properties

You can also use this with Browserify.

var Computed = require('backbone-computed-properties');

Once you do that, you can either use Computed or Backbone.computed.

Why Computed Properties?

Computed properties let you declare functions as properties. It's super handy for taking one or more normal properties and transforming or manipulating their data to create a new value.

You can achieve computed properties now in Backbone with observers in your model's initialize() method.

Backbone.Model.extend({
	initialize: function() {
  		this.computeHasDiscount();
		this.on('change:price change:discountprice', this.computeHasDiscount, this);

		// could have more here ...
	},

	computeHasDiscount: function() { /* implementation */ }
});

In the example above, I have only set up 1 computed property using the base Backbone features. If I had more than 1, the initialize method could get really long and quite messy. Instead of using this approach, I decided to create a computed property library for Backbone with an API like that of Ember's computed properties.

Basic Example

var Person = Backbone.Model.extend({
  fullName: Backbone.computed('first', 'last', function() {
    return this.get('first') + ' ' + this.get('last');
  })
});

var david = new Person({
  first: 'David',
  last: 'Tang'
});

david.toJSON(); // { first: 'David', last: 'Tang', fullName: 'David Tang' }
david.get('fullName'); // David Tang
david.set({ last: 'Doe' });
david.get('fullName'); // David Doe
david.set({ first: 'David', last: 'Tang' });
david.get('fullName'); // David Tang

You can also set up computed properties that rely on model events using the prefix event:. For example:

Person = Backbone.Model.extend({
  syncCount: Backbone.computed('event:sync', function() {
    return this.get('syncCount') + 1;
  })
});

Chaining Computed Properties

You can use computed properties as values to create new computed properties. Let's add a username computed property to the previous example, and use the existing fullName computed property:

var Person = Backbone.Model.extend({
  fullName: Backbone.computed('first', 'last', function() {
    return this.get('first') + ' ' + this.get('last');
  }),

  username: Backbone.computed('fullName', function() {
    return this.get('fullName').replace(/\s/g, '').toLowerCase();
  })
});

var david = new Person({
  first: 'David',
  last: 'Tang'
});

david.get('username'); // davidtang
david.set({ last: 'Doe' });
david.get('username')); // daviddoe

Macros

alias(dependentKey)

Creates a new property that is an alias for another property on an object.

var Person = Backbone.Model.extend({
	age: Backbone.computed.alias('theage')
});

var person = new Person({
	theage: 66
});

person.get('age'); //66

equal(dependentKey, value)

A computed property that returns true if the provided dependent property is equal to the given value.

var Person = Backbone.Model.extend({
	napTime: Backbone.computed.equal('state', 'sleepy')
});

var person = new Person({
	state: 'sleepy'
});

person.get('napTime'); // true
person.set('state', 'hungry');
person.get('napTime'); // false

Unit Tests

Unit tests are written using Mocha, Chai, and Sinon. Install karma and bower and then start karma.

npm install -g bower
npm install -g karma
npm install -g browserify

bower install
npm install
karma start

Build

The build process will create a minified version and place it in the dist directory.

gulp