dtx-backbone-associations

<!DOCTYPE html> <html> <head> <title>backbone-associations.js</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <table cellpadding="0" cellspacing="0"> <thead> <tr> <th class="docs"> <h1> backbone-associations.js </h1> </th> <th class="code"> </th> </tr> </thead> <tbody> <tr id="section-1"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-1">¶</a> </div> Backbone-associations.js 0.6.2 (c) 2014 Dhruva Ray, Jaynti Kanani, Persistent Systems Ltd. Backbone-associations may be freely distributed under the MIT license. For all details and documentation: https://github.com/dhruvaray/backbone-associations/ </td> <td class="code"> <div class="highlight"><pre>(function(root, factory) {</pre></div> </td> </tr> <tr id="section-2"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-2">¶</a> </div> Set up Backbone-associations appropriately for the environment. Start with AMD. </td> <td class="code"> <div class="highlight"><pre> if (typeof define === 'function' && define.amd) { define(['underscore', 'backbone'], function(_, Backbone) {</pre></div> </td> </tr> <tr id="section-3"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-3">¶</a> </div> Export global even in AMD case in case this script is loaded with others that may still expect a global Backbone. </td> <td class="code"> <div class="highlight"><pre> return factory(root, Backbone, _); });</pre></div> </td> </tr> <tr id="section-4"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-4">¶</a> </div> Next for Node.js or CommonJS. </td> <td class="code"> <div class="highlight"><pre> } else if (typeof exports !== 'undefined') { var _ = require('underscore'), Backbone = require('backbone'); factory(root, Backbone, _); if (typeof module !== 'undefined' && module.exports) { module.exports = Backbone; } exports = Backbone;</pre></div> </td> </tr> <tr id="section-5"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-5">¶</a> </div> Finally, as a browser global. </td> <td class="code"> <div class="highlight"><pre> } else { factory(root, root.Backbone, root._); } }(this, function(root, Backbone, _) { "use strict";</pre></div> </td> </tr> <tr id="section-6"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-6">¶</a> </div> <h2>Initial Setup</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-7"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-7">¶</a> </div> The top-level namespace. All public Backbone classes and modules will be attached to this. Exported for the browser and CommonJS. </td> <td class="code"> <div class="highlight"><pre> var BackboneModel, BackboneCollection, ModelProto, BackboneEvent, CollectionProto, AssociatedModel, pathChecker, delimiters, pathSeparator, sourceModel, sourceKey, endPoints = {};</pre></div> </td> </tr> <tr id="section-8"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-8">¶</a> </div> Create local reference <code>Model</code> prototype. </td> <td class="code"> <div class="highlight"><pre> BackboneModel = Backbone.Model; BackboneCollection = Backbone.Collection; ModelProto = BackboneModel.prototype; CollectionProto = BackboneCollection.prototype; BackboneEvent = Backbone.Events; Backbone.Associations = { VERSION: "0.6.2" };</pre></div> </td> </tr> <tr id="section-9"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-9">¶</a> </div> Alternative scopes other than root </td> <td class="code"> <div class="highlight"><pre> Backbone.Associations.scopes = [];</pre></div> </td> </tr> <tr id="section-10"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-10">¶</a> </div> Define <code>getter</code> and <code>setter</code> for <code>separator</code> </td> <td class="code"> <div class="highlight"><pre> var getSeparator = function() { return pathSeparator; };</pre></div> </td> </tr> <tr id="section-11"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-11">¶</a> </div> Define <code>setSeperator</code> </td> <td class="code"> <div class="highlight"><pre> var setSeparator = function(value) { if (!_.isString(value) || _.size(value) < 1) { value = "."; }</pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">¶</a> </div> set private properties </td> <td class="code"> <div class="highlight"><pre> pathSeparator = value; pathChecker = new RegExp("[\\" + pathSeparator + "\\[\\]]+", "g"); delimiters = new RegExp("[^\\" + pathSeparator + "\\[\\]]+", "g"); }; try {</pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">¶</a> </div> Define <code>SEPERATOR</code> property to Backbone.Associations </td> <td class="code"> <div class="highlight"><pre> Object.defineProperty(Backbone.Associations, 'SEPARATOR', { enumerable: true, get: getSeparator, set: setSeparator }); } catch (e) {}</pre></div> </td> </tr> <tr id="section-14"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-14">¶</a> </div> <h2>Backbone.AssociatedModel</h2> </td> <td class="code"> <div class="highlight"><pre></pre></div> </td> </tr> <tr id="section-15"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-15">¶</a> </div> Add <code>Many</code> and <code>One</code> relations to Backbone Object. </td> <td class="code"> <div class="highlight"><pre> Backbone.Associations.Many = Backbone.Many = "Many"; Backbone.Associations.One = Backbone.One = "One"; Backbone.Associations.Self = Backbone.Self = "Self";</pre></div> </td> </tr> <tr id="section-16"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-16">¶</a> </div> Set default separator </td> <td class="code"> <div class="highlight"><pre> Backbone.Associations.SEPARATOR = "."; Backbone.Associations.getSeparator = getSeparator; Backbone.Associations.setSeparator = setSeparator; Backbone.Associations.EVENTS_BUBBLE = true; Backbone.Associations.EVENTS_WILDCARD = true; Backbone.Associations.EVENTS_NC = false; setSeparator();</pre></div> </td> </tr> <tr id="section-17"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-17">¶</a> </div> Define <code>AssociatedModel</code> (Extends Backbone.Model). </td> <td class="code"> <div class="highlight"><pre> AssociatedModel = Backbone.AssociatedModel = Backbone.Associations.AssociatedModel = BackboneModel.extend({</pre></div> </td> </tr> <tr id="section-18"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-18">¶</a> </div> Define relations with Associated Model. </td> <td class="code"> <div class="highlight"><pre> relations:undefined,</pre></div> </td> </tr> <tr id="section-19"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-19">¶</a> </div> Define <code>Model</code> property which can keep track of already fired <code>events</code>, and prevent redundant event to be triggered in case of cyclic model graphs. </td> <td class="code"> <div class="highlight"><pre> _proxyCalls:undefined,</pre></div> </td> </tr> <tr id="section-20"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-20">¶</a> </div> Override constructor to set parents </td> <td class="code"> <div class="highlight"><pre> constructor: function (attributes, options) {</pre></div> </td> </tr> <tr id="section-21"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-21">¶</a> </div> Set parent's opportunistically. </td> <td class="code"> <div class="highlight"><pre> options && options.__parents__ && (this.parents = [options.__parents__]); BackboneModel.apply(this, arguments); }, on: function (name, callback, context) { var result = BackboneEvent.on.apply(this, arguments);</pre></div> </td> </tr> <tr id="section-22"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-22">¶</a> </div> No optimization possible if nested-events is wanted by the application </td> <td class="code"> <div class="highlight"><pre> if (Backbone.Associations.EVENTS_NC) return result;</pre></div> </td> </tr> <tr id="section-23"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-23">¶</a> </div> Regular expression used to split event strings. </td> <td class="code"> <div class="highlight"><pre> var eventSplitter = /\s+/;</pre></div> </td> </tr> <tr id="section-24"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-24">¶</a> </div> Handle atomic event names only </td> <td class="code"> <div class="highlight"><pre> if (_.isString(name) && name && (!eventSplitter.test(name)) && callback) { var endPoint = getPathEndPoint(name); if (endPoint) {</pre></div> </td> </tr> <tr id="section-25"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-25">¶</a> </div> Increment end point counter. Represents # of nodes which listen to this end point </td> <td class="code"> <div class="highlight"><pre> endPoints[endPoint] = (typeof endPoints[endPoint] === 'undefined') ? 1 : (endPoints[endPoint] + 1); } } return result; }, off: function (name, callback, context) {</pre></div> </td> </tr> <tr id="section-26"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-26">¶</a> </div> No optimization possible if nested-events is wanted by the application </td> <td class="code"> <div class="highlight"><pre> if (Backbone.Associations.EVENTS_NC) return BackboneEvent.off.apply(this, arguments); var eventSplitter = /\s+/, events = this._events, listeners = {}, names = events ? _.keys(events) : [], all = (!name && !callback && !context), atomic_event = (_.isString(name) && (!eventSplitter.test(name))); if (all || atomic_event) { for (var i = 0, l = names.length; i < l; i++) {</pre></div> </td> </tr> <tr id="section-27"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-27">¶</a> </div> Store the # of callbacks listening to the event name prior to the <code>off</code> call </td> <td class="code"> <div class="highlight"><pre> listeners[names[i]] = events[names[i]] ? events[names[i]].length : 0; } }</pre></div> </td> </tr> <tr id="section-28"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-28">¶</a> </div> Call Backbone off implementation </td> <td class="code"> <div class="highlight"><pre> var result = BackboneEvent.off.apply(this, arguments); if (all || atomic_event) { for (i = 0, l = names.length; i < l; i++) { var endPoint = getPathEndPoint(names[i]); if (endPoint) { if (events[names[i]]) {</pre></div> </td> </tr> <tr id="section-29"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-29">¶</a> </div> Some listeners wiped out for this name for this object </td> <td class="code"> <div class="highlight"><pre> endPoints[endPoint] -= (listeners[names[i]] - events[names[i]].length); } else {</pre></div> </td> </tr> <tr id="section-30"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-30">¶</a> </div> All listeners wiped out for this name for this object </td> <td class="code"> <div class="highlight"><pre> endPoints[endPoint] -= listeners[names[i]]; } } } } return result; },</pre></div> </td> </tr> <tr id="section-31"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-31">¶</a> </div> Get the value of an attribute. </td> <td class="code"> <div class="highlight"><pre> get:function (attr) { var cache = this.__attributes__, val = ModelProto.get.call(this, attr), obj = cache ? (isValuePresent(val) ? val : cache[attr]) : val; return isValuePresent(obj) ? obj : this._getAttr.apply(this, arguments); },</pre></div> </td> </tr> <tr id="section-32"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-32">¶</a> </div> Set a hash of model attributes on the Backbone Model. </td> <td class="code"> <div class="highlight"><pre> set:function (key, value, options) { var attributes, result;</pre></div> </td> </tr> <tr id="section-33"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-33">¶</a> </div> Duplicate backbone's behavior to allow separate key/value parameters, instead of a single 'attributes' object. </td> <td class="code"> <div class="highlight"><pre> if (_.isObject(key) || key == null) { attributes = key; options = value; } else { attributes = {}; attributes[key] = value; } result = this._set(attributes, options);</pre></div> </td> </tr> <tr id="section-34"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-34">¶</a> </div> Trigger events which have been blocked until the entire object graph is updated. </td> <td class="code"> <div class="highlight"><pre> this._processPendingEvents(); return result; },</pre></div> </td> </tr> <tr id="section-35"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-35">¶</a> </div> Works with an attribute hash and options + fully qualified paths </td> <td class="code"> <div class="highlight"><pre> _set:function (attributes, options) { var attr, modelMap, modelId, obj, result = this; if (!attributes) return this;</pre></div> </td> </tr> <tr id="section-36"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-36">¶</a> </div> temp cache of attributes </td> <td class="code"> <div class="highlight"><pre> this.__attributes__ = attributes; for (attr in attributes) {</pre></div> </td> </tr> <tr id="section-37"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-37">¶</a> </div> Create a map for each unique object whose attributes we want to set </td> <td class="code"> <div class="highlight"><pre> modelMap || (modelMap = {}); if (attr.match(pathChecker)) { var pathTokens = getPathArray(attr), initials = _.initial(pathTokens), last = pathTokens[pathTokens.length - 1], parentModel = this.get(initials); if (parentModel instanceof BackboneModel) { obj = modelMap[parentModel.cid] || (modelMap[parentModel.cid] = {'model': parentModel, 'data': {}}); obj.data[last] = attributes[attr]; } } else { obj = modelMap[this.cid] || (modelMap[this.cid] = {'model':this, 'data':{}}); obj.data[attr] = attributes[attr]; } } if (modelMap) { for (modelId in modelMap) { obj = modelMap[modelId]; this._setAttr.call(obj.model, obj.data, options) || (result <span class="o