by onsi

onsi /cocktail

Cocktail: DRY up your backbone code with mixins

412 Stars 48 Forks Last release: over 5 years ago (0.5.10) 97 Commits 21 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Cocktail npm npm

Break out your shared Backbone.js model/collection/view behaviors into separate modules and mix them into your classes with Cocktail - an implementation of Backbone mixins.

  • bower install cocktail
  • npm install backbone.cocktail

Concocting Mixins

Mixins are simply bare-bones JavaScript objects that provide additional functionality to your Backbone objects. Think of them as bags of methods that will get added to all instances of your objects.

Here's an example mixin that implements selectability on a view based on a model's selection state:

window.MyMixins = {};

MyMixins.SelectMixin = { initialize: function() { this.model.on('change:selected', this.refreshSelect, this); },

events: { click: 'toggleSelect' },

render: function() { this.refreshSelect(); },

refreshSelect: function() { this.$el.toggleClass('selected', this.model.get('selected')); },

toggleSelect: function() { this.model.set('selected', !this.model.get('selected')); } }

As you can see: nothing special, just a bag of functions.

Obviously, the bit about

is just a suggested pattern for organizing your mixins!

And, yes, having models know about view state like selection is often an anti-pattern... but it makes for a simple intelligible example!

Mixing Mixins In

Once you have your mixins defined including them in your Backbone object definitions is a one-liner:

var MyView = Backbone.View.extend({
  events: {
    'click .myChild': 'myCustomHandler'

initialize: function() { ... },

render: function() { ... },

etc... });

Cocktail.mixin(MyView, MyMixins.SelectMixin, MyMixins.SomeOtherMixin);

Now all instances of

will have the selection behavior defined in the
var view = new MyView(...);
view.toggleSelect(); //works!

Alternatively, you can lazily mix into your views/models like so:

var MyView = Backbone.View.extend({
  events: {
    'click .myChild': 'myCustomHandler'

initialize: function() { Cocktail.mixin(this, MyMixins.SelectMixin, MyMixins.SomeOtherMixin); },

render: function() { ... },

etc... });

This looks a bit cleaner if you can't monkeypatch (described below). In addition, this syntax gives you the flexibility to mix in certain methods in particular states of your application. For example, maybe you have an interface that you'd like an object to assume on login/logout or in the presence of another object (like a Flash embed).

If you don't mind monkeypatching

By default, as of 0.2.0 Cocktail no longer messes with Backbone's built-in extend method. However, if you don't mind some monkey patching then running:


before you define any classes will allow you to mixin code like this:

var MyView = Backbone.View.extend({
  mixins: [MyMixins.SelectMixin, MyMixins.SomeOtherMixin],

etc... });

or like this for CoffeeScript users:

class MyView extends Backbone.View
  @mixin MyMixins.SelectMixin

with the monkey-patch installed, mixins are just a convenient bit of configuration at the top of your class definitions. Note that the patch should only be applied once.

Named mixins

Whether or not you're monkey patching Backbone, you can also use named mixins by registering them with Cocktail:

Cocktail.mixins = {
  select: MyMixins.SelectMixin,
  other: MyMixins.SomeOtherMixin

// Without monkey patching Cocktail.mixin(MyView, 'select', 'other', MyMixins.yetAnotherMixin);

// With monkey patching var MyView = Backbone.View.extend({ mixins: ['select', 'other', MyMixins.yetAnotherMixin],

etc... });

But What About Collisions?

In the example above, both

both defined
, and
. What happens with these colliding methods?

Cocktail automatically ensures that methods defined in your mixins do not obliterate the corresponding methods in your classes. This is accomplished by wrapping all colliding methods into a new method that is then assigned to the final composite object.

Note: Cocktail will ensure that if you accidentally try to mix in the same method, it will not result in a collision and will do nothing.

How are colliding functions called?

Let's take a concrete example. Class X implements

and mixes in mixins A, B, and C (in that order). Of these only A and C implement


is called on instances of X the implementation of
in X is called first, followed by the implementation in A and then C. In this way the original implementation is always called first, followed by the mixins.

What are the return values from colliding functions?

The return value of the composite function is the last non-

return value from the chain of colliding functions.

To be clear: let's say X mixes in A and B. Say X implements a method

that returns
, A implements
but returns nothing (i.e.
is implicitly returned) and B returns
. Then instances of X will return
-- the last non-
return value from
's XAB collision chain.

And how about hashes?

When both a mixin and the class define a hash, Cocktail will merge the hashes together. In the case of a key collision, keys and values defined in the hash on the class take precedence followed the hash on the first mixin, then the second mixin, etc...

Note that this includes the events hash. As a result, mixins are allowed to add new event listeners.

And what about subclasses?

Subclass hierarchies with mixins should work just fine. If a super class mixes in a mixin, then all subclasses will inherit that mixin. If those subclasses mixin additional mixins, those mixins will be folded in to the subclasses and collisions will be handled correctly, even collisions with methods further up the class hierarchy.

However, if a subclass redefines a method that is provided by a mixin of the super class, the mixin's implementation will not be called. This shouldn't be surprising: the subclass's method is further up in the prototype chain and is the method that gets evaluated. In this circumstance, you must remember to call

to ensure that the mixin's method gets called.

Testing Mixins

The example directory includes an example mixin and its usage, and the accompanying Jasmine test. It also includes a readme that walks through the testing pattern employed for testing mixins with Jasmine.

Dependencies, Installation, and Contributing

Cocktail requires:

Running Tests:

Open up

in your favorite browser.


You can contribute a new build by issuing the terminal command

within the root folder.

Future changes to backbone could break Cocktail or obviate its need. If the latter happens - great! If the former: let me know and I'll try to ensure compatibility going forward.

If you like Cocktail...

...check out Coccyx. Coccyx helps you plug up backbone leaks with two things: named constructors and tear-downable view hierarchies.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.