ampersand-io-model

Based on ampersand-model to be used with socket.io. ampersand-io-model is an extension built on ampersand-state to provide methods and properties that you'll often want when modeling data you get from an API, using a realtime based websocket app.

For further explanation see the learn ampersand-state guide and the ampersand-io documentation.

Installing

npm install ampersand-io-model

API Reference

The module exports just one item, the ampersand-io-model constructor. It has a method called extend that works as follows:

extend AmpersandIOModel.extend({ })

To create a Model class of your own, you extend AmpersandIOModel and provide instance properties and options for your class. Typically here you will pass any properties (props, session, and derived) of your model class, and any instance methods to be attached to instances of your class, including the override of any ampersand-io default properties.

extend correctly sets up the prototype chain, so that subclasses created with extend can be further extended as many times as you like.

As with AmpersandState, definitions like props, session, derived etc will be merged with superclass definitions.

var Person = AmpersandIOModel.extend({
  props: {
    firstName: 'string',
    lastName: 'string'
  },
  session: {
    signedIn: ['boolean', true, false],
  },
  derived: {
    fullName: {
      deps: ['firstName', 'lastName'],
      fn: function () {
        return this.firstName + ' ' + this.lastName;
      }
    }
  }
  events = {
    onFetch: 'my-fetch-response',
    create: 'my-model-create',
    update: 'my-model-update',
    fetch: 'my-model-fetch',
    remove: 'my-model-remove'
  }
});

Note: all the methods you're going to see here use ampersand-io emit method to persist the state of a model to the server. Usually you won't call this directly, you'd use save or destroy instead, but it can be overriden for custom behaviour.

constructor/initialize new ExtendedAmpersandIOModel([attrs], [options])

Uses the ampersand-state constructor and the ampsersand-io constructor to initalize you instance.

The options object is accordingly passed to each of the constructors. So if you set any prop like the socket prop it will be rightfully set using the ampersand-io constructor.

Also if you pass collection as part of options it'll be stored for reference.

As with AmpersandState, if you have defined an initialize function for your subclass of State, it will be invoked at creation time.

var me = new Person({
    firstName: 'Phil',
    lastName: 'Roberts'
});
 
me.firstName //=> Phil

Available options:

• [parse] {Boolean} - whether to call the class's parse function with the initial attributes. Defaults to false.
• [parent] {AmpersandState} - pass a reference to a model's parent to store on the model.
• [collection] {Collection} - pass a reference to the collection the model is in. Defaults to undefined.
• [socket] {Socket-io client/ string} - pass a reference to the socket-io client instance you're using or a string to be used as a namespace for a new socket.io-client instance.
• [events] {Events object} - pass an events object as defined to override the pre-defined events used by the model.

Other options are supported by the ampsersand-io constructor, although they don't seem the most suited to this use case, you may use them if you like.

events model.events

Overridable property containing a key-value reference to the events to be used by the socket conection. The model uses the default props:

var events = {
  onFetch: 'fetch-response',
  create: 'model-create',
  update: 'model-update',
  fetch: 'model-fetch',
  remove: 'model-remove'
};

You may override them on construction or extend the model by passing an events property on extend.

For more info on this property check ampersand-io events.

save model.save([attributes], [options])

Save a model to your database (or alternative persistence layer) by delegating to ampersand-io. Returns this model object if validation is successful and false otherwise. The attributes hash (as in set) should contain the attributes you'd like to change — keys that aren't mentioned won't be altered — but, a complete representation of the resource will be sent to the websocket server. As with set, you may pass individual keys and values instead of a hash. If the model has a validate method, and validation fails, the model will not be saved. If the model isNew, the save will be a "create" event. If the model already exists on the server, the save will be an "update" event.

Pass {wait: true} if you'd like to wait for the server callback ACK before setting the new attributes on the model.

var book = new Backbone.Model({
  title: "The Rough Riders",
  author: "Theodore Roosevelt"
});
 
book.save();
//=> triggers a `create` event via ampersand-io with { "title": "The Rough Riders", "author": "Theodore Roosevelt" }
 
book.save({author: "Teddy"});
//=> triggers a `update` via ampersand-io with { "title": "The Rough Riders", "author": "Teddy" }

save accepts a callback in the options hash, which will be passed the arguments (err, model, resp) If a server-side validation fails, return a JSON object as the first argument on the callback function describing the error.

fetch model.fetch([options])

Resets the model's state from the server by delegating a fetch event to ampersand-io. Returns this model. Useful if the model has yet to be populated with data, or you want to ensure you have the latest server state.

The fetch method is comprised of two parts. A first one where a fetch event is emitted (containing a data object with this model as a data prop and a options prop containing the options passed to the model) and a onFetch listener is set.

Then we have a second part where the server sends a onFetch event to which the model updates his model reference. The onFetch response object from the server should contain an err prop detailing any error ocurrences in the serverside and/or a data prop containing the object to update this model.

Accepts a callback in the options hash, which is passed (err, model, data) as arguments.

var me = new Person({id: 123});
me.fetch();

destroy model.destroy([options])

Destroys the model on the server by delegating a remove event to ampersand-io. Returns this model, or false if the model isNew. Accepts a callback in the options hash, which is passed (err, model, resp) as arguments.

Triggers:

• a "destroy" event on the model, which will bubble up through any collections which contain it.

Pass {wait: true} if you'd like to wait for the server to response before removing the model from the collection.

var task = new Task({id: 123});
task.destroy({
  callback: function (err, model, resp) {
    if(err){
      alert('An error ocurred');
    }
    alert('Task destroyed!');
  }
});

credits

Created by @JGAntunes, with the support of @SINFO and based on a series of Ampersand Modules.

License

MIT