/vendor-jsdoc/backbonejs/backbone-collection.js

 1/*
 2
 3@module Backbone
 4@class Backbone.Collection
 5
 6Collections are ordered sets of models. You can bind "change" events to be notified when any model in the collection has been modified, listen for "add" and "remove" events, fetch the collection from the server, and use a full suite of Underscore.js methods.
 7
 8Any event that is triggered on a model in a collection will also be triggered on the collection directly, for convenience. This allows you to listen for changes to specific attributes in any model in a collection, for example: documents.on("change:selected", ...)
 9
10
11
12@method extend
13To create a Collection class of your own, extend Backbone.Collection, providing instance properties, as well as optional classProperties to be attached directly to the collection's constructor function.
14
15@param {Object} properties
16@param {Object} classProperties Optional
17*/
18
19
20/* @method model 
21Override this property to specify the model class that the collection contains. If defined, you can pass raw attributes objects (and arrays) to add, create, and reset, and the attributes will be converted into a model of the proper type.
22
23	var Library = Backbone.Collection.extend({
24	  model: Book
25	});
26A collection can also contain polymorphic models by overriding this property with a constructor that returns a model.
27
28	var Library = Backbone.Collection.extend({
29
30	  model: function(attrs, options) {
31	    if (condition) {
32	      return new PublicDocument(attrs, options);
33	    } else {
34	      return new PrivateDocument(attrs, options);
35	    }
36	  }
37	});
38@param {Object}attrs
39@param {Object} options
40
41*/
42
43
44
45/*
46@constructor
47
48When creating a Collection, you may choose to pass in the initial array of models. The collection's comparator may be included as an option. Passing false as the comparator option will prevent sorting. If you define an initialize function, it will be invoked when the collection is created. There are a couple of options that, if provided, are attached to the collection directly: model and comparator.
49
50	var tabs = new TabSet([tab1, tab2, tab3]);
51	var spaces = new Backbone.Collection([], {
52	  model: Space
53	});
54
55@param {Array} models optional
56@param {Object} options optional
57
58*/
59
60
61/*
62@property {Array} models
63Raw access to the JavaScript array of models inside of the collection. Usually you'll want to use get, at, or the Underscore methods to access model objects, but occasionally a direct reference to the array is desired.
64*/
65
66
67/*@method toJSON
68Return an array containing the attributes hash of each model (via toJSON) in the collection. This can be used to serialize and persist the collection as a whole. The name of this method is a bit confusing, because it conforms to JavaScript's JSON API.
69
70	var collection = new Backbone.Collection([
71	  {name: "Tim", age: 5},
72	  {name: "Ida", age: 26},
73	  {name: "Rob", age: 55}
74	]);
75
76	alert(JSON.stringify(collection));
77
78@returns {Array}
79
80*/
81
82/*
83@method sync
84synccollection.sync(method, collection, [options]) 
85Uses Backbone.sync to persist the state of a collection to the server. Can be overridden for custom behavior.
86
87
88@param {String} method
89@param {Backbone.Collection} collection
90@param {Object} options optional
91
92*/