+-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-++-+
|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.
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
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.
: this.int_value = int_value; this.string_value = string_value; this.date_value = date_value; : -> return _type:'SomeClass' int_value:thisint_value string_value:thisstring_value date_value:JSONSserializethisdate_value : # note: this is a class method if json_type!='SomeClass' return null; return jsonint_valuejsonstring_valueJSONSdeserializejsondate_value;
Then if you put an instance in your model's attributes, it automatically gets serialized and deserialized for you:
instance = id: 'spiffy';instancesaveembedded_some_class: 1'two' instance2 = id: 'spiffy';instance2fetch : -> eq_isEqualinstanceget'embedded_some_class'toJSONinstance2get'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'