Skip to content

HubSpot/mixen

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

67 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Mixen

Mixen lets you combine classes on the fly. With it you can build smaller, easier to understand and more testable components, and more easily share code with others. It does not just merge the prototypes.

class MyModel extends Mixen(Throttle, APIBinding, Validate, Backbone.Model)
  # Inheritance Chain:
  #
  # MyModel -> Throttle -> APIBinding -> Validate -> Backbone.Model

class MyOtherModel extends Mixen(APIBinding, Backbone.Model)
  # Inheritance Chain:
  #
  # MyOtherModel -> APIBinding -> Backbone.Model

The 2kb library only exposes a single function, Mixen. This function allows you to combine classes together in such a way that the super keyword will dynamically call the appropriate method in the next mixin you're using.

Note:

These examples are in CoffeeScript. Skip down to the bottom for a short description of how this can be done with JavaScript.

Usage

Feel free to start playing with Mixen right now.

On the browser include mixen.min.js, and the Mixen function will be globally available. You can also use AMD.

On node:

npm install mixen
Mixen = require('mixen')

The Mixen function takes in any number of classes, and returns an object:

MyObject = Mixen(Object1, Object2, ...)

Skip down for a list of the publicly available mixins.

Example

A mixin is just a class:

class OnlyRenderWithModel
  render: ->
    return unless @model

    super

Any view who would like your method can now use Mixen to mix you in:

class MyView extends Mixen(OnlyRenderWithModel, Backbone.View)

You can now replace your BaseModels and BaseViews with modular components.

Multiple Mixins Which Share Methods

Mixen adds one very important capability to inheritance, the ability to have multiple mixins all implement the same method.

class CountSyncs
  sync: ->
    @syncs = (@syncs or 0) + 1

    super
class ThrottleSyncs
  sync: ->
    return if @syncing
    @syncing = true

    super.finally =>
      @syncing = false

Now, you can mix in both classes. When the first mixin calls super, it will dynamically find and call the second mixin's sync method.

class MyModel extends Mixen(ThrottleSyncs, CountSyncs, Backbone.Model)

MyModel will both throttle it's sync's and keep track of it's sync count.

Note that the count CountSyncs will change depending on if it is listed before or after ThrottleSyncs. All methods are resolved from left to right. In other words, when you call super, you are calling the mixin to the current mixins right.

The End of the Chain

When you're developing a mixin, you don't know if your mixin will be the last in a chain used to create a class or not. Therefore you must always call super (unless you want to break the chain), and you must always be ready for super to return undefined (as it will if there are no more classes mixed in which implement that method).

class UserInContext
  getContext: ->
    context = super ? {}
    context.user = 'bob smith'
    context

class AuthInContext
  getContext: ->
    context = super ? {}
    context.auth = 'logged-in'
    context

Each getContext method will be called, in the order they are defined in the Mixen call:

class MyView extends Mixen(AuthInContext, UserInContext, Backbone.View)
  getContext: ->
    context = super
    context.x = 2
    context

Mixening in Constructors

Mixins can have constructors. As long as the resultant class either does not have a constructor, or calls super in it's constructor, all of the mixins constructors will be called in the order they are defined. If you do not wish for the constructors to be called, simply don't call super in the constructor of the class extending the mixen.

class CallInitialize
  constructor: ->
    @initialize?()
# initialize will be called
class MyThing extends Mixen(CallInitialize)

# initialize will be called
class MyThing extends Mixen(CallInitialize)
  constructor: ->
    # Do whatever other stuff you want...

    super

# initialize WON'T be called
class MyThing extends Mixen(CallInitialize)
  constructor: ->
    # Never called super...

Note, that unlike the other methods, mixins should not call super in their constructors. This is necessary because, unlike with standard methods, all classes have a constructor, even if you never explicitly implemented one. This means that if we made you call super, you would have to explicitly call super in each constructor, even when you don't care to specify one. To keep things simple, we always call all the mixin's constructors in the order they are specified, provided the mixing class doesn't explicitly prevent it.

Aliases

Mixen doesn't create them for you, but you're more than welcome to create some helpful aliases as you need:

Mixen.View = (modules...) ->
  Mixen(modules..., Backbone.View)

You can do a similar thing to create a default list of mixins for your application:

ViewMixen = (modules...) ->
  Mixen(modules..., EventJanitor, Backbone.View)

Composition

You can safely mixin other mixens:

BaseView = Mixen(EventJanitor, Backbone.View)

class MyView extends Mixen(SuperSpecialModule, BaseView)

Diamond inheritance is not supported yet.

Not Using CoffeeScript?

If you're not using CoffeeScript, it is possible to write the necessary js manually. Replicating CoffeeScript's inheritance mechanism is fairly complicated however. It requires a robust extension mechanism, and replacing every super call used above with ModuleName.__super__.methodName.

var AuthInContext, MyView, UserInContext;

UserInContext = function (){}

UserInContext.prototype.getContext = function(){
  var context = UserInContext.__super__.getContext.apply(this, arguments) || {};
  context.user = 'bob smith';
  return context;
};

AuthInContext = function (){}

AuthInContext.prototype.getContext = function(){
  var context = AuthInContext.__super__.getContext.apply(this, arguments) || {};
  context.auth = 'logged-in';
  return context;
};

MyView = function (){
  return MyView.__super__.constructor.apply(this, arguments);
}

__extends(MyView, Mixen(AuthInContext, UserInContext, Backbone.View));

MyView.prototype.getContext = function(){
  var context = MyView.__super__.getContext.apply(this, arguments);
  context.x = 2;
  return context;
};

Where __extends is implemented as:

var __hasProp = {}.hasOwnProperty,
__extends = function(child, parent){
  for (var key in parent) {
    if (__hasProp.call(parent, key))
      child[key] = parent[key];
  }

  function ctor() {
    this.constructor = child;
  }

  ctor.prototype = parent.prototype;
  child.prototype = new ctor();
  child.__super__ = parent.prototype;

  return child;
};

Debugging

If it's not working the way you expect, it's usually because you forgot to call super in one of your methods.

Take a look at the tests for complete examples of how things should work.

You can always ask us for help in GitHub Issues.

Support

Mixen is tested in IE6+, Firefox 3+, Chrome 14+, Safari 4+, Opera 10+, Safari on iOS 3+, Android 2.2+ and Node 0.8+.

Contributing

We welcome pull requests and discussion using GitHub Issues.

To get setup for development, run this in the project directory:

npm install

Then, you can run grunt watch to have it watch the source files for changes. Run grunt test to ensure that the tests still pass. You can also open spec/vendor/jasmine-1.3.1/SpecRunner.html in your browser to check the tests (after doing a grunt build).

If you create a mixin which others might find useful, please name it mixen-<type>-<name>, where type identifies what sort of thing this mixin is designed to extend (leave type out of it's general-purpose).

Examples of good names:

mixen-view-eventjanitor mixen-model-throttle

Mixins

Backbone

View
Model

Please let us know of any interesting Mixen's you make!

Changelog

  • 0.5.0 - Initial public release
  • 0.5.1 - Fix bug with interoperability with Backbone.extend