backbone-articulation

+-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-+
|B||a||c||k||b||o||n||e||-||A||r||t||i||c||u||l||a||t||i||o||n||.||j||s|
+-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-+

Backbone-Articulation.js enhances Backbone.js model attributes with object serialization and deserialization.

#Download Latest (0.3.4):

Please see the release notes for upgrade pointers.

• Development version
• Production version

###Module Loading

Backbone-Articulation.js is compatible with RequireJS, CommonJS, Brunch and AMD module loading. Module names:

• 'backbone-articulation' - backbone-articulation.js.
• 'backbone-articulation-backbone-relational' - backbone-articulation-backbone-relational.js.

Dependencies

• Backbone.js
• Underscore.js
• Lifecycle.js
• JSON-Serialize.js

Due to monkey patching, you must include the dependencies in this order:

• Backbone
• Backbone.Relational (if you use it)
• Backbone.Articulation

Examples

• Creating custom serialization for one of your classes.

class SomeClass
  constructor: (int_value, string_value, date_value) ->
    this.int_value = int_value;
    this.string_value = string_value;
    this.date_value = date_value;

  toJSON: ->
    return {
      _type:'SomeClass',
      int_value:this.int_value,
      string_value:this.string_value,
      date_value:JSONS.serialize(this.date_value)
    }

  @fromJSON: (json) ->    # note: this is a class method
    if (json._type!='SomeClass') return null;
    return new SomeClass(json.int_value, json.string_value, JSONS.deserialize(json.date_value));

Then if you put an instance in your model's attributes, it automatically gets serialized and deserialized for you:

instance = new Backbone.Model({id: 'spiffy'});
instance.save({embedded_some_class: new SomeClass(1, 'two', new Date())})

instance2 = new Backbone.Model({id: 'spiffy'});
instance2.fetch({
  success: -> eq(_.isEqual(instance.get('embedded_some_class').toJSON(), instance2.get('embedded_some_class').toJSON()), "automatically serialized and deserialized a class!")
})

The way it works

• Choose and implement the lifecycle you want for specific attributes. Choices: a) clone() and destroy() b) retain() and release() c) new() only and using Javascript's garbage collection d) plain old JSON (with no custom serialization)

Note: You can use heterogenous lifecycles paradigms in the same model's attributes and even embed Backbone models in your attributes (by adding type attribute)!

• see Lifecycle.js for more details.

• Choose a serialization/deserialization strategy a) using toJSON() instance method and fromJSON class or factory method b) plain old JSON (with no custom serialization)

• see JSON-Serialize.js for more details and library options.

If you choose 2a) - take a look at the examples below and:

• implement a toJSON() serialization method which returns plain old JSON. Include a _type attribute in the JSON which is used to find the corresponding fromJSON() class or factory method.
• implement a fromJSON() class or factory method that is used to articulation your attributes as objects. Note: your fromJSON method should be in the Javscript global namespace, but Backbone-Articulation.js will traverse nested namespaces as needed to find it (see example 2).

To use it

• Just put it after Backbone.js in your Javascript script dependencies (it replaces some build in methods).
• If you are already including Lifecycle.js or JSON-Serialize.js, use backbone-articulation_core.js as it does not bundle those libraries with it.

Settings

• Backbone.Articulation.TYPE_UNDERSCORE_SINGULARIZE - if you are using a convention of a lower cased and underscored type field (like CouchDB), set Backbone.Articulation.TYPE_UNDERSCORE_SINGULARIZE to true and include implementations for String.prototype.underscore and String.prototype.singularize (for example, from inflection.js)

• Note: this is not guaranteed to work unless Class.constructor.name exists

Backbone.Articulation.TYPE_UNDERSCORE_SINGULARIZE = true;

That's it! Go crazy!

A big thank you to Jeremy Ashkenas and DocumentCloud for making all of this Backbone awesomeness possible.

Building, Running and Testing the library

###Installing:

• install node.js: http://nodejs.org
• install node packages: 'npm install'

###Commands:

Look at: https://github.com/kmalakoff/easy-bake