New feature: Jsonify

[nachocodoner]

Hi again!

As I stated early this week (https://github.com/pathable/supermodel/pull/66), I want to share with you some modifications to Supermodel library which I miss on working in my day to day.

This time I bring you Jsonify options which will be very useful when serializing models to persist or use in templates.

PD: This branch includes some corrections and test fixing I made for newer versions of Backbone.js. I made a pull request formerly. (https://github.com/pathable/supermodel/pull/65)

Jsonify

We sometimes need that relationships defined among models are also parsed when running "toJSON" function. Thus, I have brought to you the possibility to configure which relationships you want to be serialized. Further, you are also enabled to configure which attributes or associations to include or exclude in the "toJSON" method output.

Global configuration

You may set up a default behaviour to the "toJSON" function.

defaultInJson

Boolean. Set to true to serialize all associations by default when jsonify.

cidInJson

Boolean. A value of true includes cid attribute in json output.

Example

_.extend(Supermodel.configure, {
  defaultInJson: true, // A true value serializes all associations when jsonify
  cidInJson: false // whether or not include cid in object response
});

Local configuration

You may have the neccesity to configure serialization specifically. To do so, you are enable to do it by function parameter, model and association level. If a local configuration does not include some association, the default value defined in the global configuration will be used.

Configuration by parameter

"toJSON" function has been altered to accept options to control output and relationship serialization. This configuration method could be very useful to distingish serialization for persisting or templating processes.

The options that are able to be passed to model.toJSON([options]) are described below:

includeInJson

String or String[]. Returns the object which represents the model but only picks the provided attribute/s and relation/s.

excludeInJson

String or String[]. Returns the object which represents the model but omits the provided attribute/s and association/s.

assocInJson

Object representing:

{associationName : configuration}

Configuration may accept a boolean, a string or an array referencing a model's attribute/s or association/s, or an object.

• Boolean. Set to true to serialize the related model/s and the full set of attributes and associations. In case of false, the relationship is not be serialized.
• String. Represents a single attribute or association. Serializes the related model/s and returns an object which includes such attribute or association.
• String[]. Represents a set of attributes and associations. Serializes the related model/s and returns an object which includes such set of attributes or associations.
• Object. Serializes the related model/s and represents options to include or exclude attributes and associations.
  • includeInJson. String or String[]. Returns an object which includes the provided attribute/s and association/s.
  • excludeInJson. String or String[]. Returns an object which omits the provided attribute/s and association/s.

    Example

// User has one Settings
var user = User.create({
  id: 1,
  name: "Peter"
});
var settings = Settings.create({
  id: 1,
  notifications: true
});

user.settings(settings);

user.toJSON({
  excludeInJson: "id",
  assocInJson: {
    settings: true
  }
}); // outputs {name: "Peter", settings_id: 1, settings: {notifications: true}}

Configuration by model

When you are defining models, you may set up the serialize configuration as well.

Example

var User = Supermodel.Model.extend({
  assocInJson: {
    settings: false // Set configuration at model level
  }
});
var Settings = Supermodel.Model.extend();

User.has().one('settings', {
  model: Settings,
  inverse: 'user'
});

var settings = Settings.create({id: 1});

var user = User.create({
  id: 1,
  name: "Peter",
  settings_id: 1
});

user.toJSON(); // outputs {id: 1, name: "Peter", settings_id: 1}

Configuration by association

You may set up the serialize configuration when you are defining associations.

Example

User.has().one('settings', {
  model: Settings,
  inverse: 'user',
  assocInJson: true // Set configuration at association level
});

user.toJSON(); // outputs {id: 1, name: "Peter", settings_id: 1, settings: {id: 1}}

[flippyhead]

Thank you! Sorry for the delay, will be reviewing this shortly.

[nachocodoner]

I have just noticed that this feature is an extended version of (https://github.com/pathable/supermodel/pull/61) recently pull request accepted.