master
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.
1136 _.defaults(options || (options = {}), {
1137 emulateHTTP: Backbone.emulateHTTP,
1138 emulateJSON: Backbone.emulateJSON
1139 });
1140
1141 // Default JSON-request options.
1142 var params = {type: type, dataType: 'json'};
1143
1144 // Ensure that we have a URL.
1145 if (!options.url) {
1146 params.url = _.result(model, 'url') || urlError();
1147 }
1148
1149 // Ensure that we have the appropriate request data.
1150 if (options.data == null && model && (method === 'create' || method === 'update' || method === 'patch')) {
1151 params.contentType = 'application/json';
1152 params.data = JSON.stringify(options.attrs || model.toJSON(options));
1153 }
1154
1155 // For older servers, emulate JSON by encoding the request into an HTML-form.
1156 if (options.emulateJSON) {
1157 params.contentType = 'application/x-www-form-urlencoded';
1158 params.data = params.data ? {model: params.data} : {};
1159 }
1160
1161 // For older servers, emulate HTTP by mimicking the HTTP method with `_method`
1162 // And an `X-HTTP-Method-Override` header.
1163 if (options.emulateHTTP && (type === 'PUT' || type === 'DELETE' || type === 'PATCH')) {
1164 params.type = 'POST';
1165 if (options.emulateJSON) params.data._method = type;
1166 var beforeSend = options.beforeSend;
1167 options.beforeSend = function(xhr) {
1168 xhr.setRequestHeader('X-HTTP-Method-Override', type);
1169 if (beforeSend) return beforeSend.apply(this, arguments);
1170 };
1171 }
1172
1173 // Don't process data on a non-GET request.
1174 if (params.type !== 'GET' && !options.emulateJSON) {
1175 params.processData = false;
1176 }
1177
1178 // If we're sending a `PATCH` request, and we're in an old Internet Explorer
1179 // that still has ActiveX enabled by default, override jQuery to use that
1180 // for XHR instead. Remove this line when jQuery supports `PATCH` on IE8.
1181 if (params.type === 'PATCH' && noXhrPatch) {
1182 params.xhr = function() {
1183 return new ActiveXObject("Microsoft.XMLHTTP");
1184 };
1185 }
1186
1187 // Make the request, allowing the user to override any Ajax options.
1188 var xhr = options.xhr = Backbone.ajax(_.extend(params, options));
1189 model.trigger('request', model, xhr, options);
1190 return xhr;
1191 };
1192
1193 var noXhrPatch =
1194 typeof window !== 'undefined' && !!window.ActiveXObject &&
1195 !(window.XMLHttpRequest && (new XMLHttpRequest).dispatchEvent);
1196
1197 // Map from CRUD to HTTP for our default `Backbone.sync` implementation.
1198 var methodMap = {
1199 'create': 'POST',
1200 'update': 'PUT',
1201 'patch': 'PATCH',
1202 'delete': 'DELETE',
1203 'read': 'GET'
1204 };
1205
1206 // Set the default implementation of `Backbone.ajax` to proxy through to `$`.
1207 // Override this if you'd like to use a different library.
1208 Backbone.ajax = function() {
1209 return Backbone.$.ajax.apply(Backbone.$, arguments);
1210 };
1211
1212 // Backbone.Router
1213 // ---------------
1214
1215 // Routers map faux-URLs to actions, and fire events when routes are
1216 // matched. Creating a new one sets its `routes` hash, if not set statically.
1217 var Router = Backbone.Router = function(options) {
1218 options || (options = {});
1219 if (options.routes) this.routes = options.routes;
1220 this._bindRoutes();
1221 this.initialize.apply(this, arguments);
1222 };
1223
1224 // Cached regular expressions for matching named param parts and splatted
1225 // parts of route strings.
1226 var optionalParam = /\((.*?)\)/g;
1227 var namedParam = /(\(\?)?:\w+/g;
1228 var splatParam = /\*\w+/g;
1229 var escapeRegExp = /[\-{}\[\]+?.,\\\^$|#\s]/g;
1230
1231 // Set up all inheritable **Backbone.Router** properties and methods.
1232 _.extend(Router.prototype, Events, {
1233
1234 // Initialize is an empty function by default. Override it with your own
1235 // initialization logic.
1236 initialize: function(){},
1237
1238 // Manually bind a single named route to a callback. For example:
1239 //
1240 // this.route('search/:query/p:num', 'search', function(query, num) {
1241 // ...
1242 // });
1243 //
1244 route: function(route, name, callback) {
1245 if (!_.isRegExp(route)) route = this._routeToRegExp(route);
1246 if (_.isFunction(name)) {
1247 callback = name;
1248 name = '';
1249 }
1250 if (!callback) callback = this[name];
1251 var router = this;
1252 Backbone.history.route(route, function(fragment) {
1253 var args = router._extractParameters(route, fragment);
1254 router.execute(callback, args);
1255 router.trigger.apply(router, ['route:' + name].concat(args));
1256 router.trigger('route', name, args);
1257 Backbone.history.trigger('route', router, name, args);
1258 });
1259 return this;
1260 },
1261
1262 // Execute a route handler with the provided parameters. This is an
1263 // excellent place to do pre-route setup or post-route cleanup.
1264 execute: function(callback, args) {
1265 if (callback) callback.apply(this, args);
1266 },
1267
1268 // Simple proxy to `Backbone.history` to save a fragment into the history.
1269 navigate: function(fragment, options) {
1270 Backbone.history.navigate(fragment, options);
1271 return this;
1272 },
1273
1274 // Bind all defined routes to `Backbone.history`. We have to reverse the
1275 // order of the routes here to support behavior where the most general
1276 // routes can be defined at the bottom of the route map.
1277 _bindRoutes: function() {
1278 if (!this.routes) return;
1279 this.routes = _.result(this, 'routes');
1280 var route, routes = _.keys(this.routes);
1281 while ((route = routes.pop()) != null) {
1282 this.route(route, this.routes[route]);
1283 }
1284 },
1285
1286 // Convert a route string into a regular expression, suitable for matching
1287 // against the current location hash.
1288 _routeToRegExp: function(route) {
1289 route = route.replace(escapeRegExp, '\\$&')
1290 .replace(optionalParam, '(?:$1)?')
1291 .replace(namedParam, function(match, optional) {
1292 return optional ? match : '([^/?]+)';
1293 })
1294 .replace(splatParam, '([^?]*?)');
1295 return new RegExp('^' + route + '(?:\\?([\\s\\S]*))?$');
1296 },
1297
1298 // Given a route, and a URL fragment that it matches, return the array of
1299 // extracted decoded parameters. Empty or unmatched parameters will be
1300 // treated as `null` to normalize cross-browser behavior.
1301 _extractParameters: function(route, fragment) {
1302 var params = route.exec(fragment).slice(1);
1303 return _.map(params, function(param, i) {
1304 // Don't decode the search params.
1305 if (i === params.length - 1) return param || null;
1306 return param ? decodeURIComponent(param) : null;
1307 });
1308 }
1309
1310 });
1311
1312 // Backbone.History
1313 // ----------------
1314
1315 // Handles cross-browser history management, based on either
1316 // [pushState](http://diveintohtml5.info/history.html) and real URLs, or
1317 // [onhashchange](https://developer.mozilla.org/en-US/docs/DOM/window.onhashchange)
1318 // and URL fragments. If the browser supports neither (old IE, natch),
1319 // falls back to polling.
1320 var History = Backbone.History = function() {
1321 this.handlers = [];
1322 _.bindAll(this, 'checkUrl');
1323
1324 // Ensure that `History` can be used outside of the browser.
1325 if (typeof window !== 'undefined') {
1326 this.location = window.location;
1327 this.history = window.history;
1328 }
1329 };
1330
1331 // Cached regex for stripping a leading hash/slash and trailing space.
1332 var routeStripper = /^[#\/]|\s+$/g;
1333
1334 // Cached regex for stripping leading and trailing slashes.
1335 var rootStripper = /^\/+|\/+$/g;
1336
1337 // Cached regex for detecting MSIE.
1338 var isExplorer = /msie [\w.]+/;
1339
1340 // Cached regex for removing a trailing slash.
1341 var trailingSlash = /\/$/;
1342
1343 // Cached regex for stripping urls of hash.
1344 var pathStripper = /#.*$/;
1345
1346 // Has the history handling already been started?
1347 History.started = false;
1348
1349 // Set up all inheritable **Backbone.History** properties and methods.
1350 _.extend(History.prototype, Events, {
1351
1352 // The default interval to poll for hash changes, if necessary, is
1353 // twenty times a second.
1354 interval: 50,
1355
1356 // Are we at the app root?
1357 atRoot: function() {
1358 return this.location.pathname.replace(/[^\/]$/, '$&/') === this.root;
1359 },
1360
1361 // Gets the true hash value. Cannot use location.hash directly due to bug
1362 // in Firefox where location.hash will always be decoded.
1363 getHash: function(window) {
1364 var match = (window || this).location.href.match(/#(.*)$/);
1365 return match ? match[1] : '';
1366 },
1367
1368 // Get the cross-browser normalized URL fragment, either from the URL,
1369 // the hash, or the override.
1370 getFragment: function(fragment, forcePushState) {
1371 if (fragment == null) {
1372 if (this._hasPushState || !this._wantsHashChange || forcePushState) {
1373 fragment = decodeURI(this.location.pathname + this.location.search);
1374 var root = this.root.replace(trailingSlash, '');
1375 if (!fragment.indexOf(root)) fragment = fragment.slice(root.length);
1376 } else {
1377 fragment = this.getHash();
1378 }
1379 }
1380 return fragment.replace(routeStripper, '');
1381 },
1382
1383 // Start the hash change handling, returning `true` if the current URL matches
1384 // an existing route, and `false` otherwise.
1385 start: function(options) {
1386 if (History.started) throw new Error("Backbone.history has already been started");
1387 History.started = true;
1388
1389 // Figure out the initial configuration. Do we need an iframe?
1390 // Is pushState desired ... is it available?
1391 this.options = _.extend({root: '/'}, this.options, options);
1392 this.root = this.options.root;
1393 this._wantsHashChange = this.options.hashChange !== false;
1394 this._wantsPushState = !!this.options.pushState;
1395 this._hasPushState = !!(this.options.pushState && this.history && this.history.pushState);
1396 var fragment = this.getFragment();
1397 var docMode = document.documentMode;
1398 var oldIE = (isExplorer.exec(navigator.userAgent.toLowerCase()) && (!docMode || docMode <= 7));
1399
1400 // Normalize root to always include a leading and trailing slash.
1401 this.root = ('/' + this.root + '/').replace(rootStripper, '/');
1402
1403 if (oldIE && this._wantsHashChange) {
1404 var frame = Backbone.$('<iframe src="javascript:0" tabindex="-1">');
1405 this.iframe = frame.hide().appendTo('body')[0].contentWindow;
1406 this.navigate(fragment);
1407 }
1408
1409 // Depending on whether we're using pushState or hashes, and whether
1410 // 'onhashchange' is supported, determine how we check the URL state.
1411 if (this._hasPushState) {
1412 Backbone.$(window).on('popstate', this.checkUrl);
1413 } else if (this._wantsHashChange && ('onhashchange' in window) && !oldIE) {
1414 Backbone.$(window).on('hashchange', this.checkUrl);
1415 } else if (this._wantsHashChange) {
1416 this._checkUrlInterval = setInterval(this.checkUrl, this.interval);
1417 }
1418
1419 // Determine if we need to change the base url, for a pushState link
1420 // opened by a non-pushState browser.
1421 this.fragment = fragment;
1422 var loc = this.location;
1423
1424 // Transition from hashChange to pushState or vice versa if both are
1425 // requested.
1426 if (this._wantsHashChange && this._wantsPushState) {
1427
1428 // If we've started off with a route from a `pushState`-enabled
1429 // browser, but we're currently in a browser that doesn't support it...
1430 if (!this._hasPushState && !this.atRoot()) {
1431 this.fragment = this.getFragment(null, true);
1432 this.location.replace(this.root + '#' + this.fragment);
1433 // Return immediately as browser will do redirect to new url
1434 return true;
1435
1436 // Or if we've started out with a hash-based route, but we're currently
1437 // in a browser where it could be `pushState`-based instead...
1438 } else if (this._hasPushState && this.atRoot() && loc.hash) {
1439 this.fragment = this.getHash().replace(routeStripper, '');
1440 this.history.replaceState({}, document.title, this.root + this.fragment);
1441 }
1442
1443 }
1444
1445 if (!this.options.silent) return this.loadUrl();
1446 },
1447
1448 // Disable Backbone.history, perhaps temporarily. Not useful in a real app,
1449 // but possibly useful for unit testing Routers.
1450 stop: function() {
1451 Backbone.$(window).off('popstate', this.checkUrl).off('hashchange', this.checkUrl);
1452 if (this._checkUrlInterval) clearInterval(this._checkUrlInterval);
1453 History.started = false;
1454 },
1455
1456 // Add a route to be tested when the fragment changes. Routes added later
1457 // may override previous routes.
1458 route: function(route, callback) {
1459 this.handlers.unshift({route: route, callback: callback});
1460 },
1461
1462 // Checks the current URL to see if it has changed, and if it has,
1463 // calls `loadUrl`, normalizing across the hidden iframe.
1464 checkUrl: function(e) {
1465 var current = this.getFragment();
1466 if (current === this.fragment && this.iframe) {
1467 current = this.getFragment(this.getHash(this.iframe));
1468 }
1469 if (current === this.fragment) return false;
1470 if (this.iframe) this.navigate(current);
1471 this.loadUrl();
1472 },
1473
1474 // Attempt to load the current URL fragment. If a route succeeds with a
1475 // match, returns `true`. If no defined routes matches the fragment,
1476 // returns `false`.
1477 loadUrl: function(fragment) {
1478 fragment = this.fragment = this.getFragment(fragment);
1479 return _.any(this.handlers, function(handler) {
1480 if (handler.route.test(fragment)) {
1481 handler.callback(fragment);
1482 return true;
1483 }
1484 });
1485 },
1486
1487 // Save a fragment into the hash history, or replace the URL state if the
1488 // 'replace' option is passed. You are responsible for properly URL-encoding
1489 // the fragment in advance.
1490 //
1491 // The options object can contain `trigger: true` if you wish to have the
1492 // route callback be fired (not usually desirable), or `replace: true`, if
1493 // you wish to modify the current URL without adding an entry to the history.
1494 navigate: function(fragment, options) {
1495 if (!History.started) return false;
1496 if (!options || options === true) options = {trigger: !!options};
1497
1498 var url = this.root + (fragment = this.getFragment(fragment || ''));
1499
1500 // Strip the hash for matching.
1501 fragment = fragment.replace(pathStripper, '');
1502
1503 if (this.fragment === fragment) return;
1504 this.fragment = fragment;
1505
1506 // Don't include a trailing slash on the root.
1507 if (fragment === '' && url !== '/') url = url.slice(0, -1);
1508
1509 // If pushState is available, we use it to set the fragment as a real URL.
1510 if (this._hasPushState) {
1511 this.history[options.replace ? 'replaceState' : 'pushState']({}, document.title, url);
1512
1513 // If hash changes haven't been explicitly disabled, update the hash
1514 // fragment to store history.
1515 } else if (this._wantsHashChange) {
1516 this._updateHash(this.location, fragment, options.replace);
1517 if (this.iframe && (fragment !== this.getFragment(this.getHash(this.iframe)))) {
1518 // Opening and closing the iframe tricks IE7 and earlier to push a
1519 // history entry on hash-tag change. When replace is true, we don't
1520 // want this.
1521 if(!options.replace) this.iframe.document.open().close();
1522 this._updateHash(this.iframe.location, fragment, options.replace);
1523 }
1524
1525 // If you've told us that you explicitly don't want fallback hashchange-
1526 // based history, then `navigate` becomes a page refresh.
1527 } else {
1528 return this.location.assign(url);
1529 }
1530 if (options.trigger) return this.loadUrl(fragment);
1531 },
1532
1533 // Update the hash location, either replacing the current entry, or adding
1534 // a new one to the browser history.
1535 _updateHash: function(location, fragment, replace) {
1536 if (replace) {
1537 var href = location.href.replace(/(javascript:|#).*$/, '');
1538 location.replace(href + '#' + fragment);
1539 } else {
1540 // Some browsers require that `hash` contains a leading #.
1541 location.hash = '#' + fragment;
1542 }
1543 }
1544
1545 });
1546
1547 // Create the default Backbone.history.
1548 Backbone.history = new History;
1549
1550 // Helpers
1551 // -------
1552
1553 // Helper function to correctly set up the prototype chain, for subclasses.
1554 // Similar to `goog.inherits`, but uses a hash of prototype properties and
1555 // class properties to be extended.
1556 var extend = function(protoProps, staticProps) {
1557 var parent = this;
1558 var child;
1559
1560 // The constructor function for the new subclass is either defined by you
1561 // (the "constructor" property in your `extend` definition), or defaulted
1562 // by us to simply call the parent's constructor.
1563 if (protoProps && _.has(protoProps, 'constructor')) {
1564 child = protoProps.constructor;
1565 } else {
1566 child = function(){ return parent.apply(this, arguments); };
1567 }
1568
1569 // Add static properties to the constructor function, if supplied.
1570 _.extend(child, parent, staticProps);
1571
1572 // Set the prototype chain to inherit from `parent`, without calling
1573 // `parent`'s constructor function.
1574 var Surrogate = function(){ this.constructor = child; };
1575 Surrogate.prototype = parent.prototype;
1576 child.prototype = new Surrogate;
1577
1578 // Add prototype properties (instance properties) to the subclass,
1579 // if supplied.
1580 if (protoProps) _.extend(child.prototype, protoProps);
1581
1582 // Set a convenience property in case the parent's prototype is needed
1583 // later.
1584 child.__super__ = parent.prototype;
1585
1586 return child;
1587 };
1588
1589 // Set up inheritance for the model, collection, router, view and history.
1590 Model.extend = Collection.extend = Router.extend = View.extend = History.extend = extend;
1591
1592 // Throw an error when a URL is needed, and none is supplied.
1593 var urlError = function() {
1594 throw new Error('A "url" property or function must be specified');
1595 };
1596
1597 // Wrap an optional error callback with a fallback error event.
1598 var wrapError = function(model, options) {
1599 var error = options.error;
1600 options.error = function(resp) {
1601 if (error) error(model, resp, options);
1602 model.trigger('error', model, resp, options);
1603 };
1604 };
1605
1606 return Backbone;
1607
1608}));