dw-backbone
Add security and clarity to your Backbone Models & Collections with easy to create custom serializers and de-serializers. Auto-instantiation of child models & collections. DotPath notation support.
Philosophy
Resilient patterns and practices are necessary for any long-lived codebase. Funky customization is necessary to meet the demands of many an API / UI. Embrace the funk, but don't let it dominate your work. Be kind to yourself and your successors.
dw-backbone was created with these problems in mind.
*This lib is provided uniminified, because that's either a part of your build process already, or you're like "source-map what?"
Exports Model, Collection, and convenience!
Model
extending .Model adds the following functionality
new Model() - instantiate a clean model from almost any garbage you throw at it. Case-convert, transform, black & white list.
//model = new Model({object}, [mode]) Model = DWBackboneModel;obj = 'some_junk':'and_stuff' 'a_bc':"['lazy','java','devs']"; model = obj 'underscored'; model; //{someJunk:'and_stuff', aBc:['lazy','java','devs']}model; //{some_junk:'and_stuff', a_bc:['lazy','java','devs']}
.toJSON() - a builtin jsonifier with transform, blacklist, whitelist. If no mode is specified a naked object version of the model. Supports nested Collections & Models.
//model.toJSON([mode]); model;
.logicallyIdentical() - takes either a raw {}, or a Model. Compares the attributes (and child attributes) of the Models for logical equivalence (not ===).
//model.logicallyIdentical([{} | Model])obj = a:b:'c';model = obj;model2 = a:b:'c'; model; //true model2; //true
._set.<attrName> - declare custom setters in a clean, brief structure. Appropriate setters run on calls to .set. Also runs after the transforms on new Model
Model = DWBackboneModel; model = x: a:'b' y:'hello world'; model //'Hello World' modelmodel //Apple Sauce child = model;child instanceof BackboneModel //truechild //'b' model; model instanceof BackboneModel //truemodel === child //false //Respects existing models with the same .constructor if you pass them inmodel;model === child //true //Listens for 'destroy' events and removes all listeners and removes the model //from .attributes. (un-binds on unset)child;model //undefined
._setCollections - declare child collections
Point = DWBackboneModel; Points = DWBackboneCollection; Model = DWBackboneModel; model = pointList:x:1y:2name:'Some name' x:3 y:4; model instanceof Points //truemodel //['None Specified','Some name']modellength //2model //[{name:'None Specified',x:1, y:2},{name:'Some name', x:3, y:4}] model //triggers resetmodellength //1model //[{name:'Another one',x:0, y:0}] points = x:1y:2name:'Some name' x:3 y:4model;model === points //false - model maintains its own Points collectionmodel === points //true - model retains the Point instances
.get() - accepts dotpath notation.
model = m: a:'b' c: d:'e' f: g:'h' i: j:'k' ; model == 'b' //truemodel //undefined - classic Backbone 'undefined' behavior for undefined attributesmodel //dotPath does not support raw objectsmodel == 'e' //true - Child Models must extend DWBackbone to support dotPathmodel == 'h' //true - Last attribute can be Backbone.Model
.set() - accepts dotpath notation.
Use it like .get, or set multiple attributes using an object with dotPathed property names. *All parts of the path (except the last) must already exist.
Collection
extending .Collection adds the following functionality
.get() - accepts dotpath notation.
collection = id:'x' name:'Foo' id:'y' name:'Bar' id:'z' name:'Nasty' collection === collection //true - collection == collection //true
.set('dotpath', val) - accepts dotpath notation if first argument is a string, default Backbone.Collection behavior otherwise
collection = id:'x' name:'Foo' id:'y' name:'Bar' id:'z' name:'Nasty' collectioncollection; //'Granny Smith' (you could also use a dotPath to get it, but this is less unambiguous. collectioncollection //'Not nasty' collectioncollection //'Are good'collection //'Are good'collection //'Are good'collection //['Are good'] - because Backbone.Collection.pluck returns unique values
.setOn() - accepts dotpath noted objects
collection = id:'x' name:'Foo' id:'y' name:'Bar' id:'z' name:'Nasty' //the following call does all of the .set calls in the previous examplecollection
.toJSON() - supports DWBackbone.Model.toJSON modes
Convenience
functions directly off DWBackbone
.isA(item, [type]) - used it like typeof, but also returns 'array', 'date', 'NaN', or true/false if type is passed in
DWBackbone //'array'DWBackbone //'NaN' DWBackbone //trueDWBackbone //falseDWBackbone //true
.logicallyIdentical({ object 1 },{ object 2 }, [{ ignoreTree }]) - are these two objects basically the same thing? Supports deep structures. Supports excluding specific attributes from the comparison.
.toUnderscored({ some object }) - converts a camelCased string to an underscored one. Pass in an object to convert all its keys without modifying the values.
.toCamel({ some object }) - converts an underscored string to a camelCased one. Pass in an object to convert all its keys without modifying the values.
.setLogger(function() ) - Pass in any logging function you like *as of 0.5 DWBackbone does not write directly to console.log
.getLogger() - because setLogger was lonely