1 //     Backbone.js 1.1.2

     2 

     3 //     (c) 2010-2014 Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors

     4 //     Backbone may be freely distributed under the MIT license.

     5 //     For all details and documentation:

     6 //     http://backbonejs.org

     7 

     8 (function(root, factory) {

     9 

    10   // Set up Backbone appropriately for the environment. Start with AMD.

    11   if (typeof define === 'function' && define.amd) {

    12     define(['underscore', 'jquery', 'exports'], function(_, $, exports) {

    13       // Export global even in AMD case in case this script is loaded with

    14       // others that may still expect a global Backbone.

    15       root.Backbone = factory(root, exports, _, $);

    16     });

    17 

    18   // Next for Node.js or CommonJS. jQuery may not be needed as a module.

    19   } else if (typeof exports !== 'undefined') {

    20     var _ = require('underscore');

    21     factory(root, exports, _);

    22 

    23   // Finally, as a browser global.

    24   } else {

    25     root.Backbone = factory(root, {}, root._, (root.jQuery || root.Zepto || root.ender || root.$));

    26   }

    27 

    28 }(this, function(root, Backbone, _, $) {

    29 

    30   // Initial Setup

    31   // -------------

    32 

    33   // Save the previous value of the `Backbone` variable, so that it can be

    34   // restored later on, if `noConflict` is used.

    35   var previousBackbone = root.Backbone;

    36 

    37   // Create local references to array methods we'll want to use later.

    38   var array = [];

    39   var push = array.push;

    40   var slice = array.slice;

    41   var splice = array.splice;

    42 

    43   // Current version of the library. Keep in sync with `package.json`.

    44   Backbone.VERSION = '1.1.2';

    45 

    46   // For Backbone's purposes, jQuery, Zepto, Ender, or My Library (kidding) owns

    47   // the `$` variable.

    48   Backbone.$ = $;

    49 

    50   // Runs Backbone.js in *noConflict* mode, returning the `Backbone` variable

    51   // to its previous owner. Returns a reference to this Backbone object.

    52   Backbone.noConflict = function() {

    53     root.Backbone = previousBackbone;

    54     return this;

    55   };

    56 

    57   // Turn on `emulateHTTP` to support legacy HTTP servers. Setting this option

    58   // will fake `"PATCH"`, `"PUT"` and `"DELETE"` requests via the `_method` parameter and

    59   // set a `X-Http-Method-Override` header.

    60   Backbone.emulateHTTP = false;

    61 

    62   // Turn on `emulateJSON` to support legacy servers that can't deal with direct

    63   // `application/json` requests ... will encode the body as

    64   // `application/x-www-form-urlencoded` instead and will send the model in a

    65   // form param named `model`.

    66   Backbone.emulateJSON = false;

    67 

    68   // Backbone.Events

    69   // ---------------

    70 

    71   // A module that can be mixed in to *any object* in order to provide it with

    72   // custom events. You may bind with `on` or remove with `off` callback

    73   // functions to an event; `trigger`-ing an event fires all callbacks in

    74   // succession.

    75   //

    76   //     var object = {};

    77   //     _.extend(object, Backbone.Events);

    78   //     object.on('expand', function(){ alert('expanded'); });

    79   //     object.trigger('expand');

    80   //

    81   var Events = Backbone.Events = {

    82 

    83     // Bind an event to a `callback` function. Passing `"all"` will bind

    84     // the callback to all events fired.

    85     on: function(name, callback, context) {

    86       if (!eventsApi(this, 'on', name, [callback, context]) || !callback) return this;

    87       this._events || (this._events = {});

    88       var events = this._events[name] || (this._events[name] = []);

    89       events.push({callback: callback, context: context, ctx: context || this});

    90       return this;

    91     },

    92 

    93     // Bind an event to only be triggered a single time. After the first time

    94     // the callback is invoked, it will be removed.

    95     once: function(name, callback, context) {

    96       if (!eventsApi(this, 'once', name, [callback, context]) || !callback) return this;

    97       var self = this;

    98       var once = _.once(function() {

    99         self.off(name, once);

   100         callback.apply(this, arguments);

   101       });

   102       once._callback = callback;

   103       return this.on(name, once, context);

   104     },

   105 

   106     // Remove one or many callbacks. If `context` is null, removes all

   107     // callbacks with that function. If `callback` is null, removes all

   108     // callbacks for the event. If `name` is null, removes all bound

   109     // callbacks for all events.

   110     off: function(name, callback, context) {

   111       var retain, ev, events, names, i, l, j, k;

   112       if (!this._events || !eventsApi(this, 'off', name, [callback, context])) return this;

   113       if (!name && !callback && !context) {

   114         this._events = void 0;

   115         return this;

   116       }

   117       names = name ? [name] : _.keys(this._events);

   118       for (i = 0, l = names.length; i < l; i++) {

   119         name = names[i];

   120         if (events = this._events[name]) {

   121           this._events[name] = retain = [];

   122           if (callback || context) {

   123             for (j = 0, k = events.length; j < k; j++) {

   124               ev = events[j];

   125               if ((callback && callback !== ev.callback && callback !== ev.callback._callback) ||

   126                   (context && context !== ev.context)) {

   127                 retain.push(ev);

   128               }

   129             }

   130           }

   131           if (!retain.length) delete this._events[name];

   132         }

   133       }

   134 

   135       return this;

   136     },

   137 

   138     // Trigger one or many events, firing all bound callbacks. Callbacks are

   139     // passed the same arguments as `trigger` is, apart from the event name

   140     // (unless you're listening on `"all"`, which will cause your callback to

   141     // receive the true name of the event as the first argument).

   142     trigger: function(name) {

   143       if (!this._events) return this;

   144       var args = slice.call(arguments, 1);

   145       if (!eventsApi(this, 'trigger', name, args)) return this;

   146       var events = this._events[name];

   147       var allEvents = this._events.all;

   148       if (events) triggerEvents(events, args);

   149       if (allEvents) triggerEvents(allEvents, arguments);

   150       return this;

   151     },

   152 

   153     // Tell this object to stop listening to either specific events ... or

   154     // to every object it's currently listening to.

   155     stopListening: function(obj, name, callback) {

   156       var listeningTo = this._listeningTo;

   157       if (!listeningTo) return this;

   158       var remove = !name && !callback;

   159       if (!callback && typeof name === 'object') callback = this;

   160       if (obj) (listeningTo = {})[obj._listenId] = obj;

   161       for (var id in listeningTo) {

   162         obj = listeningTo[id];

   163         obj.off(name, callback, this);

   164         if (remove || _.isEmpty(obj._events)) delete this._listeningTo[id];

   165       }

   166       return this;

   167     }

   168 

   169   };

   170 

   171   // Regular expression used to split event strings.

   172   var eventSplitter = /\s+/;

   173 

   174   // Implement fancy features of the Events API such as multiple event

   175   // names `"change blur"` and jQuery-style event maps `{change: action}`

   176   // in terms of the existing API.

   177   var eventsApi = function(obj, action, name, rest) {

   178     if (!name) return true;

   179 

   180     // Handle event maps.

   181     if (typeof name === 'object') {

   182       for (var key in name) {

   183         obj[action].apply(obj, [key, name[key]].concat(rest));

   184       }

   185       return false;

   186     }

   187 

   188     // Handle space separated event names.

   189     if (eventSplitter.test(name)) {

   190       var names = name.split(eventSplitter);

   191       for (var i = 0, l = names.length; i < l; i++) {

   192         obj[action].apply(obj, [names[i]].concat(rest));

   193       }

   194       return false;

   195     }

   196 

   197     return true;

   198   };

   199 

   200   // A difficult-to-believe, but optimized internal dispatch function for

   201   // triggering events. Tries to keep the usual cases speedy (most internal

   202   // Backbone events have 3 arguments).

   203   var triggerEvents = function(events, args) {

   204     var ev, i = -1, l = events.length, a1 = args[0], a2 = args[1], a3 = args[2];

   205     switch (args.length) {

   206       case 0: while (++i < l) (ev = events[i]).callback.call(ev.ctx); return;

   207       case 1: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1); return;

   208       case 2: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2); return;

   209       case 3: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2, a3); return;

   210       default: while (++i < l) (ev = events[i]).callback.apply(ev.ctx, args); return;

   211     }

   212   };

   213 

   214   var listenMethods = {listenTo: 'on', listenToOnce: 'once'};

   215 

   216   // Inversion-of-control versions of `on` and `once`. Tell *this* object to

   217   // listen to an event in another object ... keeping track of what it's

   218   // listening to.

   219   _.each(listenMethods, function(implementation, method) {

   220     Events[method] = function(obj, name, callback) {

   221       var listeningTo = this._listeningTo || (this._listeningTo = {});

   222       var id = obj._listenId || (obj._listenId = _.uniqueId('l'));

   223       listeningTo[id] = obj;

   224       if (!callback && typeof name === 'object') callback = this;

   225       obj[implementation](name, callback, this);

   226       return this;

   227     };

   228   });

   229 

   230   // Aliases for backwards compatibility.

   231   Events.bind   = Events.on;

   232   Events.unbind = Events.off;

   233 

   234   // Allow the `Backbone` object to serve as a global event bus, for folks who

   235   // want global "pubsub" in a convenient place.

   236   _.extend(Backbone, Events);

   237 

   238   // Backbone.Model

   239   // --------------

   240 

   241   // Backbone **Models** are the basic data object in the framework --

   242   // frequently representing a row in a table in a database on your server.

   243   // A discrete chunk of data and a bunch of useful, related methods for

   244   // performing computations and transformations on that data.

   245 

   246   // Create a new model with the specified attributes. A client id (`cid`)

   247   // is automatically generated and assigned for you.

   248   var Model = Backbone.Model = function(attributes, options) {

   249     var attrs = attributes || {};

   250     options || (options = {});

   251     this.cid = _.uniqueId('c');

   252     this.attributes = {};

   253     if (options.collection) this.collection = options.collection;

   254     if (options.parse) attrs = this.parse(attrs, options) || {};

   255     attrs = _.defaults({}, attrs, _.result(this, 'defaults'));

   256     this.set(attrs, options);

   257     this.changed = {};

   258     this.initialize.apply(this, arguments);

   259   };

   260 

   261   // Attach all inheritable methods to the Model prototype.

   262   _.extend(Model.prototype, Events, {

   263 

   264     // A hash of attributes whose current and previous value differ.

   265     changed: null,

   266 

   267     // The value returned during the last failed validation.

   268     validationError: null,

   269 

   270     // The default name for the JSON `id` attribute is `"id"`. MongoDB and

   271     // CouchDB users may want to set this to `"_id"`.

   272     idAttribute: 'id',

   273 

   274     // Initialize is an empty function by default. Override it with your own

   275     // initialization logic.

   276     initialize: function(){},

   277 

   278     // Return a copy of the model's `attributes` object.

   279     toJSON: function(options) {

   280       return _.clone(this.attributes);

   281     },

   282 

   283     // Proxy `Backbone.sync` by default -- but override this if you need

   284     // custom syncing semantics for *this* particular model.

   285     sync: function() {

   286       return Backbone.sync.apply(this, arguments);

   287     },

   288 

   289     // Get the value of an attribute.

   290     get: function(attr) {

   291       return this.attributes[attr];

   292     },

   293 

   294     // Get the HTML-escaped value of an attribute.

   295     escape: function(attr) {

   296       return _.escape(this.get(attr));

   297     },

   298 

   299     // Returns `true` if the attribute contains a value that is not null

   300     // or undefined.

   301     has: function(attr) {

   302       return this.get(attr) != null;

   303     },

   304 

   305     // Set a hash of model attributes on the object, firing `"change"`. This is

   306     // the core primitive operation of a model, updating the data and notifying

   307     // anyone who needs to know about the change in state. The heart of the beast.

   308     set: function(key, val, options) {

   309       var attr, attrs, unset, changes, silent, changing, prev, current;

   310       if (key == null) return this;

   311 

   312       // Handle both `"key", value` and `{key: value}` -style arguments.

   313       if (typeof key === 'object') {

   314         attrs = key;

   315         options = val;

   316       } else {

   317         (attrs = {})[key] = val;

   318       }

   319 

   320       options || (options = {});

   321 

   322       // Run validation.

   323       if (!this._validate(attrs, options)) return false;

   324 

   325       // Extract attributes and options.

   326       unset           = options.unset;

   327       silent          = options.silent;

   328       changes         = [];

   329       changing        = this._changing;

   330       this._changing  = true;

   331 

   332       if (!changing) {

   333         this._previousAttributes = _.clone(this.attributes);

   334         this.changed = {};

   335       }

   336       current = this.attributes, prev = this._previousAttributes;

   337 

   338       // Check for changes of `id`.

   339       if (this.idAttribute in attrs) this.id = attrs[this.idAttribute];

   340 

   341       // For each `set` attribute, update or delete the current value.

   342       for (attr in attrs) {

   343         val = attrs[attr];

   344         if (!_.isEqual(current[attr], val)) changes.push(attr);

   345         if (!_.isEqual(prev[attr], val)) {

   346           this.changed[attr] = val;

   347         } else {

   348           delete this.changed[attr];

   349         }

   350         unset ? delete current[attr] : current[attr] = val;

   351       }

   352 

   353       // Trigger all relevant attribute changes.

   354       if (!silent) {

   355         if (changes.length) this._pending = options;

   356         for (var i = 0, l = changes.length; i < l; i++) {

   357           this.trigger('change:' + changes[i], this, current[changes[i]], options);

   358         }

   359       }

   360 

   361       // You might be wondering why there's a `while` loop here. Changes can

   362       // be recursively nested within `"change"` events.

   363       if (changing) return this;

   364       if (!silent) {

   365         while (this._pending) {

   366           options = this._pending;

   367           this._pending = false;

   368           this.trigger('change', this, options);

   369         }

   370       }

   371       this._pending = false;

   372       this._changing = false;

   373       return this;

   374     },

   375 

   376     // Remove an attribute from the model, firing `"change"`. `unset` is a noop

   377     // if the attribute doesn't exist.

   378     unset: function(attr, options) {

   379       return this.set(attr, void 0, _.extend({}, options, {unset: true}));

   380     },

   381 

   382     // Clear all attributes on the model, firing `"change"`.

   383     clear: function(options) {

   384       var attrs = {};

   385       for (var key in this.attributes) attrs[key] = void 0;

   386       return this.set(attrs, _.extend({}, options, {unset: true}));

   387     },

   388 

   389     // Determine if the model has changed since the last `"change"` event.

   390     // If you specify an attribute name, determine if that attribute has changed.

   391     hasChanged: function(attr) {

   392       if (attr == null) return !_.isEmpty(this.changed);

   393       return _.has(this.changed, attr);

   394     },

   395 

   396     // Return an object containing all the attributes that have changed, or

   397     // false if there are no changed attributes. Useful for determining what

   398     // parts of a view need to be updated and/or what attributes need to be

   399     // persisted to the server. Unset attributes will be set to undefined.

   400     // You can also pass an attributes object to diff against the model,

   401     // determining if there *would be* a change.

   402     changedAttributes: function(diff) {

   403       if (!diff) return this.hasChanged() ? _.clone(this.changed) : false;

   404       var val, changed = false;

   405       var old = this._changing ? this._previousAttributes : this.attributes;

   406       for (var attr in diff) {

   407         if (_.isEqual(old[attr], (val = diff[attr]))) continue;

   408         (changed || (changed = {}))[attr] = val;

   409       }

   410       return changed;

   411     },

   412 

   413     // Get the previous value of an attribute, recorded at the time the last

   414     // `"change"` event was fired.

   415     previous: function(attr) {

   416       if (attr == null || !this._previousAttributes) return null;

   417       return this._previousAttributes[attr];

   418     },

   419 

   420     // Get all of the attributes of the model at the time of the previous

   421     // `"change"` event.

   422     previousAttributes: function() {

   423       return _.clone(this._previousAttributes);

   424     },

   425 

   426     // Fetch the model from the server. If the server's representation of the

   427     // model differs from its current attributes, they will be overridden,

   428     // triggering a `"change"` event.

   429     fetch: function(options) {

   430       options = options ? _.clone(options) : {};

   431       if (options.parse === void 0) options.parse = true;

   432       var model = this;

   433       var success = options.success;

   434       options.success = function(resp) {

   435         if (!model.set(model.parse(resp, options), options)) return false;

   436         if (success) success(model, resp, options);

   437         model.trigger('sync', model, resp, options);

   438       };

   439       wrapError(this, options);

   440       return this.sync('read', this, options);

   441     },

   442 

   443     // Set a hash of model attributes, and sync the model to the server.

   444     // If the server returns an attributes hash that differs, the model's

   445     // state will be `set` again.

   446     save: function(key, val, options) {

   447       var attrs, method, xhr, attributes = this.attributes;

   448 

   449       // Handle both `"key", value` and `{key: value}` -style arguments.

   450       if (key == null || typeof key === 'object') {

   451         attrs = key;

   452         options = val;

   453       } else {

   454         (attrs = {})[key] = val;

   455       }

   456 

   457       options = _.extend({validate: true}, options);

   458 

   459       // If we're not waiting and attributes exist, save acts as

   460       // `set(attr).save(null, opts)` with validation. Otherwise, check if

   461       // the model will be valid when the attributes, if any, are set.

   462       if (attrs && !options.wait) {

   463         if (!this.set(attrs, options)) return false;

   464       } else {

   465         if (!this._validate(attrs, options)) return false;

   466       }

   467 

   468       // Set temporary attributes if `{wait: true}`.

   469       if (attrs && options.wait) {

   470         this.attributes = _.extend({}, attributes, attrs);

   471       }

   472 

   473       // After a successful server-side save, the client is (optionally)

   474       // updated with the server-side state.

   475       if (options.parse === void 0) options.parse = true;

   476       var model = this;

   477       var success = options.success;

   478       options.success = function(resp) {

   479         // Ensure attributes are restored during synchronous saves.

   480         model.attributes = attributes;

   481         var serverAttrs = model.parse(resp, options);

   482         if (options.wait) serverAttrs = _.extend(attrs || {}, serverAttrs);

   483         if (_.isObject(serverAttrs) && !model.set(serverAttrs, options)) {

   484           return false;

   485         }

   486         if (success) success(model, resp, options);

   487         model.trigger('sync', model, resp, options);

   488       };

   489       wrapError(this, options);

   490 

   491       method = this.isNew() ? 'create' : (options.patch ? 'patch' : 'update');

   492       if (method === 'patch') options.attrs = attrs;

   493       xhr = this.sync(method, this, options);

   494 

   495       // Restore attributes.

   496       if (attrs && options.wait) this.attributes = attributes;

   497 

   498       return xhr;

   499     },

   500 

   501     // Destroy this model on the server if it was already persisted.

   502     // Optimistically removes the model from its collection, if it has one.

   503     // If `wait: true` is passed, waits for the server to respond before removal.

   504     destroy: function(options) {

   505       options = options ? _.clone(options) : {};

   506       var model = this;

   507       var success = options.success;

   508 

   509       var destroy = function() {

   510         model.trigger('destroy', model, model.collection, options);

   511       };

   512 

   513       options.success = function(resp) {

   514         if (options.wait || model.isNew()) destroy();

   515         if (success) success(model, resp, options);

   516         if (!model.isNew()) model.trigger('sync', model, resp, options);

   517       };

   518 

   519       if (this.isNew()) {

   520         options.success();

   521         return false;

   522       }

   523       wrapError(this, options);

   524 

   525       var xhr = this.sync('delete', this, options);

   526       if (!options.wait) destroy();

   527       return xhr;

   528     },

   529 

   530     // Default URL for the model's representation on the server -- if you're

   531     // using Backbone's restful methods, override this to change the endpoint

   532     // that will be called.

   533     url: function() {

   534       var base =

   535         _.result(this, 'urlRoot') ||

   536         _.result(this.collection, 'url') ||

   537         urlError();

   538       if (this.isNew()) return base;

   539       return base.replace(/([^\/])$/, '$1/') + encodeURIComponent(this.id);

   540     },

   541 

   542     // **parse** converts a response into the hash of attributes to be `set` on

   543     // the model. The default implementation is just to pass the response along.

   544     parse: function(resp, options) {

   545       return resp;

   546     },

   547 

   548     // Create a new model with identical attributes to this one.

   549     clone: function() {

   550       return new this.constructor(this.attributes);

   551     },

   552 

   553     // A model is new if it has never been saved to the server, and lacks an id.

   554     isNew: function() {

   555       return !this.has(this.idAttribute);

   556     },

   557 

   558     // Check if the model is currently in a valid state.

   559     isValid: function(options) {

   560       return this._validate({}, _.extend(options || {}, { validate: true }));

   561     },

   562 

   563     // Run validation against the next complete set of model attributes,

   564     // returning `true` if all is well. Otherwise, fire an `"invalid"` event.

   565     _validate: function(attrs, options) {

   566       if (!options.validate || !this.validate) return true;

   567       attrs = _.extend({}, this.attributes, attrs);

   568       var error = this.validationError = this.validate(attrs, options) || null;

   569       if (!error) return true;

   570       this.trigger('invalid', this, error, _.extend(options, {validationError: error}));

   571       return false;

   572     }

   573 

   574   });

   575 

   576   // Underscore methods that we want to implement on the Model.

   577   var modelMethods = ['keys', 'values', 'pairs', 'invert', 'pick', 'omit'];

   578 

   579   // Mix in each Underscore method as a proxy to `Model#attributes`.

   580   _.each(modelMethods, function(method) {

   581     Model.prototype[method] = function() {

   582       var args = slice.call(arguments);

   583       args.unshift(this.attributes);

   584       return _[method].apply(_, args);

   585     };

   586   });

   587 

   588   // Backbone.Collection

   589   // -------------------

   590 

   591   // If models tend to represent a single row of data, a Backbone Collection is

   592   // more analagous to a table full of data ... or a small slice or page of that

   593   // table, or a collection of rows that belong together for a particular reason

   594   // -- all of the messages in this particular folder, all of the documents

   595   // belonging to this particular author, and so on. Collections maintain

   596   // indexes of their models, both in order, and for lookup by `id`.

   597 

   598   // Create a new **Collection**, perhaps to contain a specific type of `model`.

   599   // If a `comparator` is specified, the Collection will maintain

   600   // its models in sort order, as they're added and removed.

   601   var Collection = Backbone.Collection = function(models, options) {

   602     options || (options = {});

   603     if (options.model) this.model = options.model;

   604     if (options.comparator !== void 0) this.comparator = options.comparator;

   605     this._reset();

   606     this.initialize.apply(this, arguments);

   607     if (models) this.reset(models, _.extend({silent: true}, options));

   608   };

   609 

   610   // Default options for `Collection#set`.

   611   var setOptions = {add: true, remove: true, merge: true};

   612   var addOptions = {add: true, remove: false};

   613 

   614   // Define the Collection's inheritable methods.

   615   _.extend(Collection.prototype, Events, {

   616 

   617     // The default model for a collection is just a **Backbone.Model**.

   618     // This should be overridden in most cases.

   619     model: Model,

   620 

   621     // Initialize is an empty function by default. Override it with your own

   622     // initialization logic.

   623     initialize: function(){},

   624 

   625     // The JSON representation of a Collection is an array of the

   626     // models' attributes.

   627     toJSON: function(options) {

   628       return this.map(function(model){ return model.toJSON(options); });

   629     },

   630 

   631     // Proxy `Backbone.sync` by default.

   632     sync: function() {

   633       return Backbone.sync.apply(this, arguments);

   634     },

   635 

   636     // Add a model, or list of models to the set.

   637     add: function(models, options) {

   638       return this.set(models, _.extend({merge: false}, options, addOptions));

   639     },

   640 

   641     // Remove a model, or a list of models from the set.

   642     remove: function(models, options) {

   643       var singular = !_.isArray(models);

   644       models = singular ? [models] : _.clone(models);

   645       options || (options = {});

   646       var i, l, index, model;

   647       for (i = 0, l = models.length; i < l; i++) {

   648         model = models[i] = this.get(models[i]);

   649         if (!model) continue;

   650         delete this._byId[model.id];

   651         delete this._byId[model.cid];

   652         index = this.indexOf(model);

   653         this.models.splice(index, 1);

   654         this.length--;

   655         if (!options.silent) {

   656           options.index = index;

   657           model.trigger('remove', model, this, options);

   658         }

   659         this._removeReference(model, options);

   660       }

   661       return singular ? models[0] : models;

   662     },

   663 

   664     // Update a collection by `set`-ing a new list of models, adding new ones,

   665     // removing models that are no longer present, and merging models that

   666     // already exist in the collection, as necessary. Similar to **Model#set**,

   667     // the core operation for updating the data contained by the collection.

   668     set: function(models, options) {

   669       options = _.defaults({}, options, setOptions);

   670       if (options.parse) models = this.parse(models, options);

   671       var singular = !_.isArray(models);

   672       models = singular ? (models ? [models] : []) : _.clone(models);

   673       var i, l, id, model, attrs, existing, sort;

   674       var at = options.at;

   675       var targetModel = this.model;

   676       var sortable = this.comparator && (at == null) && options.sort !== false;

   677       var sortAttr = _.isString(this.comparator) ? this.comparator : null;

   678       var toAdd = [], toRemove = [], modelMap = {};

   679       var add = options.add, merge = options.merge, remove = options.remove;

   680       var order = !sortable && add && remove ? [] : false;

   681 

   682       // Turn bare objects into model references, and prevent invalid models

   683       // from being added.

   684       for (i = 0, l = models.length; i < l; i++) {

   685         attrs = models[i] || {};

   686         if (attrs instanceof Model) {

   687           id = model = attrs;

   688         } else {

   689           id = attrs[targetModel.prototype.idAttribute || 'id'];

   690         }

   691 

   692         // If a duplicate is found, prevent it from being added and

   693         // optionally merge it into the existing model.

   694         if (existing = this.get(id)) {

   695           if (remove) modelMap[existing.cid] = true;

   696           if (merge) {

   697             attrs = attrs === model ? model.attributes : attrs;

   698             if (options.parse) attrs = existing.parse(attrs, options);

   699             existing.set(attrs, options);

   700             if (sortable && !sort && existing.hasChanged(sortAttr)) sort = true;

   701           }

   702           models[i] = existing;

   703 

   704         // If this is a new, valid model, push it to the `toAdd` list.

   705         } else if (add) {

   706           model = models[i] = this._prepareModel(attrs, options);

   707           if (!model) continue;

   708           toAdd.push(model);

   709           this._addReference(model, options);

   710         }

   711 

   712         // Do not add multiple models with the same `id`.

   713         model = existing || model;

   714         if (order && (model.isNew() || !modelMap[model.id])) order.push(model);

   715         modelMap[model.id] = true;

   716       }

   717 

   718       // Remove nonexistent models if appropriate.

   719       if (remove) {

   720         for (i = 0, l = this.length; i < l; ++i) {

   721           if (!modelMap[(model = this.models[i]).cid]) toRemove.push(model);

   722         }

   723         if (toRemove.length) this.remove(toRemove, options);

   724       }

   725 

   726       // See if sorting is needed, update `length` and splice in new models.

   727       if (toAdd.length || (order && order.length)) {

   728         if (sortable) sort = true;

   729         this.length += toAdd.length;

   730         if (at != null) {

   731           for (i = 0, l = toAdd.length; i < l; i++) {

   732             this.models.splice(at + i, 0, toAdd[i]);

   733           }

   734         } else {

   735           if (order) this.models.length = 0;

   736           var orderedModels = order || toAdd;

   737           for (i = 0, l = orderedModels.length; i < l; i++) {

   738             this.models.push(orderedModels[i]);

   739           }

   740         }

   741       }

   742 

   743       // Silently sort the collection if appropriate.

   744       if (sort) this.sort({silent: true});

   745 

   746       // Unless silenced, it's time to fire all appropriate add/sort events.

   747       if (!options.silent) {

   748         for (i = 0, l = toAdd.length; i < l; i++) {

   749           (model = toAdd[i]).trigger('add', model, this, options);

   750         }

   751         if (sort || (order && order.length)) this.trigger('sort', this, options);

   752       }

   753 

   754       // Return the added (or merged) model (or models).

   755       return singular ? models[0] : models;

   756     },

   757 

   758     // When you have more items than you want to add or remove individually,

   759     // you can reset the entire set with a new list of models, without firing

   760     // any granular `add` or `remove` events. Fires `reset` when finished.

   761     // Useful for bulk operations and optimizations.

   762     reset: function(models, options) {

   763       options || (options = {});

   764       for (var i = 0, l = this.models.length; i < l; i++) {

   765         this._removeReference(this.models[i], options);

   766       }

   767       options.previousModels = this.models;

   768       this._reset();

   769       models = this.add(models, _.extend({silent: true}, options));

   770       if (!options.silent) this.trigger('reset', this, options);

   771       return models;

   772     },

   773 

   774     // Add a model to the end of the collection.

   775     push: function(model, options) {

   776       return this.add(model, _.extend({at: this.length}, options));

   777     },

   778 

   779     // Remove a model from the end of the collection.

   780     pop: function(options) {

   781       var model = this.at(this.length - 1);

   782       this.remove(model, options);

   783       return model;

   784     },

   785 

   786     // Add a model to the beginning of the collection.

   787     unshift: function(model, options) {

   788       return this.add(model, _.extend({at: 0}, options));

   789     },

   790 

   791     // Remove a model from the beginning of the collection.

   792     shift: function(options) {

   793       var model = this.at(0);

   794       this.remove(model, options);

   795       return model;

   796     },

   797 

   798     // Slice out a sub-array of models from the collection.

   799     slice: function() {

   800       return slice.apply(this.models, arguments);

   801     },

   802 

   803     // Get a model from the set by id.

   804     get: function(obj) {

   805       if (obj == null) return void 0;

   806       return this._byId[obj] || this._byId[obj.id] || this._byId[obj.cid];

   807     },

   808 

   809     // Get the model at the given index.

   810     at: function(index) {

   811       return this.models[index];

   812     },

   813 

   814     // Return models with matching attributes. Useful for simple cases of

   815     // `filter`.

   816     where: function(attrs, first) {

   817       if (_.isEmpty(attrs)) return first ? void 0 : [];

   818       return this[first ? 'find' : 'filter'](function(model) {

   819         for (var key in attrs) {

   820           if (attrs[key] !== model.get(key)) return false;

   821         }

   822         return true;

   823       });

   824     },

   825 

   826     // Return the first model with matching attributes. Useful for simple cases

   827     // of `find`.

   828     findWhere: function(attrs) {

   829       return this.where(attrs, true);

   830     },

   831 

   832     // Force the collection to re-sort itself. You don't need to call this under

   833     // normal circumstances, as the set will maintain sort order as each item

   834     // is added.

   835     sort: function(options) {

   836       if (!this.comparator) throw new Error('Cannot sort a set without a comparator');

   837       options || (options = {});

   838 

   839       // Run sort based on type of `comparator`.

   840       if (_.isString(this.comparator) || this.comparator.length === 1) {

   841         this.models = this.sortBy(this.comparator, this);

   842       } else {

   843         this.models.sort(_.bind(this.comparator, this));

   844       }

   845 

   846       if (!options.silent) this.trigger('sort', this, options);

   847       return this;

   848     },

   849 

   850     // Pluck an attribute from each model in the collection.

   851     pluck: function(attr) {

   852       return _.invoke(this.models, 'get', attr);

   853     },

   854 

   855     // Fetch the default set of models for this collection, resetting the

   856     // collection when they arrive. If `reset: true` is passed, the response

   857     // data will be passed through the `reset` method instead of `set`.

   858     fetch: function(options) {

   859       options = options ? _.clone(options) : {};

   860       if (options.parse === void 0) options.parse = true;

   861       var success = options.success;

   862       var collection = this;

   863       options.success = function(resp) {

   864         var method = options.reset ? 'reset' : 'set';

   865         collection[method](resp, options);

   866         if (success) success(collection, resp, options);

   867         collection.trigger('sync', collection, resp, options);

   868       };

   869       wrapError(this, options);

   870       return this.sync('read', this, options);

   871     },

   872 

   873     // Create a new instance of a model in this collection. Add the model to the

   874     // collection immediately, unless `wait: true` is passed, in which case we

   875     // wait for the server to agree.

   876     create: function(model, options) {

   877       options = options ? _.clone(options) : {};

   878       if (!(model = this._prepareModel(model, options))) return false;

   879       if (!options.wait) this.add(model, options);

   880       var collection = this;

   881       var success = options.success;

   882       options.success = function(model, resp) {

   883         if (options.wait) collection.add(model, options);

   884         if (success) success(model, resp, options);

   885       };

   886       model.save(null, options);

   887       return model;

   888     },

   889 

   890     // **parse** converts a response into a list of models to be added to the

   891     // collection. The default implementation is just to pass it through.

   892     parse: function(resp, options) {

   893       return resp;

   894     },

   895 

   896     // Create a new collection with an identical list of models as this one.

   897     clone: function() {

   898       return new this.constructor(this.models);

   899     },

   900 

   901     // Private method to reset all internal state. Called when the collection

   902     // is first initialized or reset.

   903     _reset: function() {

   904       this.length = 0;

   905       this.models = [];

   906       this._byId  = {};

   907     },

   908 

   909     // Prepare a hash of attributes (or other model) to be added to this

   910     // collection.

   911     _prepareModel: function(attrs, options) {

   912       if (attrs instanceof Model) return attrs;

   913       options = options ? _.clone(options) : {};

   914       options.collection = this;

   915       var model = new this.model(attrs, options);

   916       if (!model.validationError) return model;

   917       this.trigger('invalid', this, model.validationError, options);

   918       return false;

   919     },

   920 

   921     // Internal method to create a model's ties to a collection.

   922     _addReference: function(model, options) {

   923       this._byId[model.cid] = model;

   924       if (model.id != null) this._byId[model.id] = model;

   925       if (!model.collection) model.collection = this;

   926       model.on('all', this._onModelEvent, this);

   927     },

   928 

   929     // Internal method to sever a model's ties to a collection.

   930     _removeReference: function(model, options) {

   931       if (this === model.collection) delete model.collection;

   932       model.off('all', this._onModelEvent, this);

   933     },

   934 

   935     // Internal method called every time a model in the set fires an event.

   936     // Sets need to update their indexes when models change ids. All other

   937     // events simply proxy through. "add" and "remove" events that originate

   938     // in other collections are ignored.

   939     _onModelEvent: function(event, model, collection, options) {

   940       if ((event === 'add' || event === 'remove') && collection !== this) return;

   941       if (event === 'destroy') this.remove(model, options);

   942       if (model && event === 'change:' + model.idAttribute) {

   943         delete this._byId[model.previous(model.idAttribute)];

   944         if (model.id != null) this._byId[model.id] = model;

   945       }

   946       this.trigger.apply(this, arguments);

   947     }

   948 

   949   });

   950 

   951   // Underscore methods that we want to implement on the Collection.

   952   // 90% of the core usefulness of Backbone Collections is actually implemented

   953   // right here:

   954   var methods = ['forEach', 'each', 'map', 'collect', 'reduce', 'foldl',

   955     'inject', 'reduceRight', 'foldr', 'find', 'detect', 'filter', 'select',

   956     'reject', 'every', 'all', 'some', 'any', 'include', 'contains', 'invoke',

   957     'max', 'min', 'toArray', 'size', 'first', 'head', 'take', 'initial', 'rest',

   958     'tail', 'drop', 'last', 'without', 'difference', 'indexOf', 'shuffle',

   959     'lastIndexOf', 'isEmpty', 'chain', 'sample'];

   960 

   961   // Mix in each Underscore method as a proxy to `Collection#models`.

   962   _.each(methods, function(method) {

   963     Collection.prototype[method] = function() {

   964       var args = slice.call(arguments);

   965       args.unshift(this.models);

   966       return _[method].apply(_, args);

   967     };

   968   });

   969 

   970   // Underscore methods that take a property name as an argument.

   971   var attributeMethods = ['groupBy', 'countBy', 'sortBy', 'indexBy'];

   972 

   973   // Use attributes instead of properties.

   974   _.each(attributeMethods, function(method) {

   975     Collection.prototype[method] = function(value, context) {

   976       var iterator = _.isFunction(value) ? value : function(model) {

   977         return model.get(value);

   978       };

   979       return _[method](this.models, iterator, context);

   980     };

   981   });

   982 

   983   // Backbone.View

   984   // -------------

   985 

   986   // Backbone Views are almost more convention than they are actual code. A View

   987   // is simply a JavaScript object that represents a logical chunk of UI in the

   988   // DOM. This might be a single item, an entire list, a sidebar or panel, or

   989   // even the surrounding frame which wraps your whole app. Defining a chunk of

   990   // UI as a **View** allows you to define your DOM events declaratively, without

   991   // having to worry about render order ... and makes it easy for the view to

   992   // react to specific changes in the state of your models.

   993 

   994   // Creating a Backbone.View creates its initial element outside of the DOM,

   995   // if an existing element is not provided...

   996   var View = Backbone.View = function(options) {

   997     this.cid = _.uniqueId('view');

   998     options || (options = {});

   999     _.extend(this, _.pick(options, viewOptions));

  1000     this._ensureElement();

  1001     this.initialize.apply(this, arguments);

  1002     this.delegateEvents();

  1003   };

  1004 

  1005   // Cached regex to split keys for `delegate`.

  1006   var delegateEventSplitter = /^(\S+)\s*(.*)$/;

  1007 

  1008   // List of view options to be merged as properties.

  1009   var viewOptions = ['model', 'collection', 'el', 'id', 'attributes', 'className', 'tagName', 'events'];

  1010 

  1011   // Set up all inheritable **Backbone.View** properties and methods.

  1012   _.extend(View.prototype, Events, {

  1013 

  1014     // The default `tagName` of a View's element is `"div"`.

  1015     tagName: 'div',

  1016 

  1017     // jQuery delegate for element lookup, scoped to DOM elements within the

  1018     // current view. This should be preferred to global lookups where possible.

  1019     $: function(selector) {

  1020       return this.$el.find(selector);

  1021     },

  1022 

  1023     // Initialize is an empty function by default. Override it with your own

  1024     // initialization logic.

  1025     initialize: function(){},

  1026 

  1027     // **render** is the core function that your view should override, in order

  1028     // to populate its element (`this.el`), with the appropriate HTML. The

  1029     // convention is for **render** to always return `this`.

  1030     render: function() {

  1031       return this;

  1032     },

  1033 

  1034     // Remove this view by taking the element out of the DOM, and removing any

  1035     // applicable Backbone.Events listeners.

  1036     remove: function() {

  1037       this.$el.remove();

  1038       this.stopListening();

  1039       return this;

  1040     },

  1041 

  1042     // Change the view's element (`this.el` property), including event

  1043     // re-delegation.

  1044     setElement: function(element, delegate) {

  1045       if (this.$el) this.undelegateEvents();

  1046       this.$el = element instanceof Backbone.$ ? element : Backbone.$(element);

  1047       this.el = this.$el[0];

  1048       if (delegate !== false) this.delegateEvents();

  1049       return this;

  1050     },

  1051 

  1052     // Set callbacks, where `this.events` is a hash of

  1053     //

  1054     // *{"event selector": "callback"}*

  1055     //

  1056     //     {

  1057     //       'mousedown .title':  'edit',

  1058     //       'click .button':     'save',

  1059     //       'click .open':       function(e) { ... }

  1060     //     }

  1061     //

  1062     // pairs. Callbacks will be bound to the view, with `this` set properly.

  1063     // Uses event delegation for efficiency.

  1064     // Omitting the selector binds the event to `this.el`.

  1065     // This only works for delegate-able events: not `focus`, `blur`, and

  1066     // not `change`, `submit`, and `reset` in Internet Explorer.

  1067     delegateEvents: function(events) {

  1068       if (!(events || (events = _.result(this, 'events')))) return this;

  1069       this.undelegateEvents();

  1070       for (var key in events) {

  1071         var method = events[key];

  1072         if (!_.isFunction(method)) method = this[events[key]];

  1073         if (!method) continue;

  1074 

  1075         var match = key.match(delegateEventSplitter);

  1076         var eventName = match[1], selector = match[2];

  1077         method = _.bind(method, this);

  1078         eventName += '.delegateEvents' + this.cid;

  1079         if (selector === '') {

  1080           this.$el.on(eventName, method);

  1081         } else {

  1082           this.$el.on(eventName, selector, method);

  1083         }

  1084       }

  1085       return this;

  1086     },

  1087 

  1088     // Clears all callbacks previously bound to the view with `delegateEvents`.

  1089     // You usually don't need to use this, but may wish to if you have multiple

  1090     // Backbone views attached to the same DOM element.

  1091     undelegateEvents: function() {

  1092       this.$el.off('.delegateEvents' + this.cid);

  1093       return this;

  1094     },

  1095 

  1096     // Ensure that the View has a DOM element to render into.

  1097     // If `this.el` is a string, pass it through `$()`, take the first

  1098     // matching element, and re-assign it to `el`. Otherwise, create

  1099     // an element from the `id`, `className` and `tagName` properties.

  1100     _ensureElement: function() {

  1101       if (!this.el) {

  1102         var attrs = _.extend({}, _.result(this, 'attributes'));

  1103         if (this.id) attrs.id = _.result(this, 'id');

  1104         if (this.className) attrs['class'] = _.result(this, 'className');

  1105         var $el = Backbone.$('<' + _.result(this, 'tagName') + '>').attr(attrs);

  1106         this.setElement($el, false);

  1107       } else {

  1108         this.setElement(_.result(this, 'el'), false);

  1109       }

  1110     }

  1111 

  1112   });

  1113 

  1114   // Backbone.sync

  1115   // -------------

  1116 

  1117   // Override this function to change the manner in which Backbone persists

  1118   // models to the server. You will be passed the type of request, and the

  1119   // model in question. By default, makes a RESTful Ajax request

  1120   // to the model's `url()`. Some possible customizations could be:

  1121   //

  1122   // * Use `setTimeout` to batch rapid-fire updates into a single request.

  1123   // * Send up the models as XML instead of JSON.

  1124   // * Persist models via WebSockets instead of Ajax.

  1125   //

  1126   // Turn on `Backbone.emulateHTTP` in order to send `PUT` and `DELETE` requests

  1127   // as `POST`, with a `_method` parameter containing the true HTTP method,

  1128   // as well as all requests with the body as `application/x-www-form-urlencoded`

  1129   // instead of `application/json` with the model in a param named `model`.

  1130   // Useful when interfacing with server-side languages like **PHP** that make

  1131   // it difficult to read the body of `PUT` requests.

  1132   Backbone.sync = function(method, model, options) {

  1133     var type = methodMap[method];

  1134 

  1135     // Default options, unless specified.