An explanation of `wrapped.value` in Ractive adaptors

wrappedvalues.md

What is wrapper.value?

When using Ractive.js with adaptors, each 'wrappable' object (i.e. each object that passes the adaptor's filter() method) has a wrapper created:

ractive = new Ractive({
  el: 'body',
  template: '{{myModel.foo}}',
  data: {
    myModel: new Backbone.Model({ foo: 'bar' })
  },
  adaptors: [ 'Backbone' ]
});

In this case, the 'myModel' property will be wrapped - internally, this wrapper is referenced as ractive._wrapped.myModel. A wrapper has wrapper.get() and wrapper.teardown() methods (it can optionally also have wrapper.set() and wrapper.reset() methods - for the docs visit the wiki).

The wrapper.get() method returns a value which represents how Ractive should 'see' the object. In this case, we want {{myModel.foo}} to render as bar - so the Backbone adaptor's wrapper.get() method simply looks like this:

get: function () {
  return this.value.attributes;
}

Here, we're using this.value to refer to the original Backbone object, so that we can get its attributes. Every wrapper exposes its original object as the value property - Ractive enforces this - because in many situations we need to be able to retrieve that object.

If we do ractive.get('myModel.foo') we get 'bar'. But if we do ractive.get('myModel') we want to get the Backbone model itself - we don't really want to get the facade generated by wrapper.get(). This is possible because of wrapper.value.

ractive.get('myModel') === ractive._wrapped.myModel.value; // true