A mixin is simply a collection of properties and methods that you can add to a class or object when you create them. You can use mixins to add features to your classes or objects without having to directly inherit from another class, reducing the amount of code in your application and improving consistency. Additionally, SproutCore comes bundled with many mixins that you can use yourself to build classes that conform to certain key interfaces.

This page will show you how to define and use mixins in your classes and describe some important details behind how mixins are actually implemented. Read this page if you are new to SproutCore or want to learn the dirty details of how mixins work.

Creating a Mixin

Creating a mixin is easy, you just define a hash of properties like so:

MyApp.NameProperties = {
  firstName: "John",
  lastName: "Doe",
  
  fullName: function() {
   return this.getEach('firstName', 'lastName').join(' ');
  }.property('firstName', 'lastName').cacheable()
};

To use a mixin, simply include it in the list of properties you want added to a class or object when you create it. For example, this is how you would create a new class with your mixin applied. All instances of this class will include your mixin properties:

MyApp.MyClass = SC.Object.extend(MyApp.NameProperties, {
  // other properties go here
});

You can do the same thing with object instances. When creating an object, just pass any mixins you want applied to that instance only:

MyApp.myObject = SC.Object.Create(MyApp.NameProperties, {
  // other properties go here
});

Including Observers, Bindings, and Computed Properties

You can define observers, bindings and computed properties on a mixin just like you would on a class or object. These special properties will be copied onto the class or object you apply the mixin to and initialized just like any other property you might define. In the example below, every instance of ClassA and ClassB will create a titleBinding:

MyApp.DemoMixin = {
  titleBinding: "MyApp.myController.title"
};

ClassA = SC.Object.extend(MyApp.DemoMixin, {
  // added properties
});

ClassB = SC.Object.extend(MyApp.DemoMixin, {
  // added properties 
});

Initializing and Destroying Your Mixin

When writing an class or object, you can define init() and destroy() methods to perform setup and teardown on your object. Since you could have many mixins applied to a class though, you can’t simply define these same methods for a mixin or else it would overwrite versions found in your class.

Instead, SproutCore allows you to define an initMixin() method and a destroyMixin() method. These methods will be saved separately for every mixin you apply and called in order when your object is created or destroyed. Note that if you try to get these properties on an object once it is created, you will not get back just your initMixin() method, but instead an array of all the initMixin() and destroyMixin() methods defined on the object.

The following example defines an initMixin method that is called when an object the mixin is applied to is created:

MyApp.MyMixin = {
  initMixin: function() {
   console.log("mixin inited!");  // just for demo
  }
};

MyApp.myController = SC.Object.create(MyApp.MyMixin, {
  // other properties
});
=> "mixin inited!"

Note that unlike init() or destroy(), you do not needs to call sc_super() in your initMixin() and destroyMixin() methods. The return value of these methods is also ignored.

Implementation Details and Common Gotchas

The most important thing to understand about mixins is that a mixin is simply a hash of properties that are copied onto your class or object when you create it. In fact, when you pass a hash or properties to extend() or create(), you are effectively creating a one-time-use mixin that is applied to the new class or object you are creating. Here is the process that SproutCore uses to apply a mixin:

1. Any properties in your mixin are copied onto the new object or class you are creating.
2. If you have defined an initMixin() method or a destroyMixin() method, these methods will be added to the initMixin or destroyMixin array on the object or class.
3. Repeat for the next mixin in the list passed to extend() or create()

Because mixins are copied on to your target object or class, you cannot later change a mixin’s properties and expect those changes to be reflected in classes or objects that already have the mixin applied.

Additionally, if you apply two mixins with the same property name, the last mixin will overwrite the value set by the earlier mixins. Because of this, if you want to write a method that is truly private to your mixin and you want to make sure no other mixin inadvertently overwrites it, you should typically prefix your methods with “nameOfMixin”, like so:

MyApp.MyMixin = {
  _myMixin_myPrivateMethod: function() {
  },

  _myMixin_myPrivateProperty: "value"
};