models.md

Models

Models in Tungsten.js use the standard Backbone model API, along with support for related (nested) models and collections.

App Data

Each Tungsten.js app expects a single data store where the current state of the application is kept. This data store takes the form of an app model instance.

The root app model, like a standard Backbone model, contains the model's state in a hash of attributes. This is usually passed from the server, via either a boostrapped data object or an XHR request.

In addition to standard Backbone behavior, we also provide a nested model functionality based on Bret Little's backbone-nested-models. To define a particular attribute as a reference to a model or collection, set relations hash on the model constructor with the key being the attribute name and the value being the nested model/collection constructor:

BaseModel.extend({
  // [...]
  relations: {
    items: BaseCollection,
    foo: BaseModel
  }
});

Events

Events triggered in Tungsten (non-DOM events) "bubble up" through models and collections. Unless stopped, the event will proceed from whatever given nested model triggered it, all the way up to the base model. (This does not include when the event is from a component- there is a specific process for listening to events on a child component. See 'Components' for more information.) When an event has finished bubbling, a re-render is triggered.

This bubbling allows for an "events up, methods down" pattern of design. Events can bubble up from child models (containing bespoke data as necessary), and parents can listen for those events and, in response, call the appropriate methods on their children. This is how communication between parents and children in Tungsten should occur. Remember: Events Up, Methods Down!

Special Properties

Included with the Backbone adaptor are special model property types which were inspired by ampersand-state.

Derived Properties: Derived properties are properties which are computed based on the value of another property. They can be added with the derived hash in Backbone models, with the key being the property name and the value being an options object. The object should include an array at key deps of properties that the derived property relies on, as well as a function at key fn which should return the derived value. Derived properties will not be serialized with toJSON.

BaseModel.extend({
  // [...]
  derived: {
      incompletedItems: {
        deps: ['todoItems'],
        fn: function() {
          return this.get('todoItems').filter(function(item) {
            return !item.get('completed');
          });
        }
      }
  }
});

Computed Properties: Properties which are computed, but not reliant on any other properties, can be added simply by adding a method with the desired property name on the model. These will be read by templates during rendering, though they will not be accessible via model.get() or serialized with toJSON. Computed properties are now deprecated and will be removed in a future version of Tungsten.js. Use derived properties instead.

Session Properties: Transient properties that shouldn't be serialized when saving the model can be excluded from toJSON by adding a session property to the model:

BaseModel.extend({
  // [...]
  session: ['user', 'is_logged_in']
});