Falcon.js | Build Stellar Javascript Applications

initialize new Falcon.Collection( [models], [parent] )

Falcon.Collection This instance

The constructor method for a Falcon Collection. Creates a new instance of a Falcon Collection and should be overridden instead of overriding the internal constructor method.

models: An initial set of models to populate the collection with
parent: The owner of this collection, used for generating urls when making requests to the server.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({
 3 	model: Dog,
 4 
 5 	initialize: function() {
 6 		console.log("Collecting Dogs");
 7 	}
 8 });
 9 
10 new Dogs(); // Collecting Dogs

extend Falcon.Collection.extend( protoProps, [staticProps] )

Method used to create a new collection that inherits from the base Falcon Collection.

protoProps: Properties for the prototype of a class
staticProps: Static properties for a given object

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({
 3 	model: Dog,
 4 	bark: function()
 5 	{
 6 		console.log("All the dogs bark");
 7 	}
 8 },{
 9 	say: function() {
10 		console.log("Woof!");
11 	}
12 });
13 
14 var dogs = new Dogs();
15 
16 Dogs.say(); // Woof!
17 dogs.bark(); // "All the dogs bark";

model collection.model

The prototype of the model of each item in this collection. This is used to ensure that all models within this collection are the correct type. It is also used to determine the relative url for models in this collection when making sync requests to the server.

1 var Dog = Falcon.Model.extend();
2 var Dogs = Falcon.Collection.extend({model: Dog});

parent collection.parent

This represents the 'parent' object that holds these models. Generally this is used for determining the URL structure of rest objects in the makeURL() routine. This should also be a Model.

1 var Owner = Falcon.Model.extend();
2 var Dog = Falcon.Model.extend();
3 var Dogs = Falcon.Collection.extend({model: Dog});
4 
5 var owner = new Owner();
6 var dogs = new Dogs( owner ); // Owner becomes the 'parent' of dogs
7 
8 console.log( dogs.parent === owner ); // true

defaults collection.defaults

This is a hash map of non-observable defaults to create whenever an instance of this collection is initialized. If the value is a function, the function is called and the return value is assigned. Functions are called in context of this instance and with all the same arguments from the constructor method. Defaults are created before observables which means that any duplicate attributes between the observables (as in the 'observables' attribute on Falcon.Object) and default attributes will be overridden by those in the observables

 1 var Dogs = Falcon.Collection.extend({
 2 	defaults: {
 3 		"are_tame": true,
 4 		"name": function() {
 5 			return ( name || "Fido" );
 6 		}
 7 	}
 8 });
 9 
10 var dogs = new Dogs();
11 console.log( dogs.name ); // Fido
12 console.log( dogs.are_tame ); // true

observables collection.observables

This is a hash map of the default observables and values that will become properties of this collection when a new instance is created. If the value of a specific key is a function a computed observable is created. If the value is an object with the keys 'read' and/or 'write' a computed is created with those object keys as the definition for the computed observable. All computed observables are created with this objects's instance as their context.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({
 3 	model: Dog,
 4 
 5 	observables: {
 6 		"are_tame": true,
 7 		"has_dogs": function() {
 8 			return this.length() > 0;
 9 		}
10 	}
11 });
12 
13 var dogs = new Dogs();
14 
15 console.log( ko.isObservable( dogs.are_tame ) ); // true
16 console.log( ko.isComputed( dogs.has_dogs ) ); // true
17 
18 console.log( dogs.are_tame() ); // true
19 console.log( dogs.has_dogs() ); // false
20 
21 dog.push(new Dog());
22 
23 console.log( dogs.has_dogs() ); // true

all collection.all()

Array An array of all of the models in the collection

Used to retrieve a basic array of all of the models in this collection

1 var Dog = Falcon.Model.extend();
2 var Dogs = Falcon.Collection.extend({ model: Dog });
3 
4 var dogs = new Dogs([
5 	{"name": "Fido"},
6 	{"name": "Skip"}
7 ]);
8 
9 console.log( dogs.all() ); // [Fido, Skip]

any collection.any( iterator )

Boolean Does this collection match any of the itertor tests or models?

Method used to check if any of the models in the collection match the given iterator, id, or model. Returns true if at least of the models match the truth test.

iterator: Method used to test each model against.

id: The id to compare against each model in the collection.

model: A model to compare against each of the collection's models using an id-based comparison.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 var has_fido = dogs.any(function(dog) {
12 	return dog.get("name") === "Fido";
13 });
14 
15 var has_spot = dogs.any(function(dog) {
16 	return dog.get("name") === "Spot";
17 });
18 
19 console.log(has_fido); // true
20 console.log(has_spot); // false

append collection.append( items )

Falcon.Collection This instance

Append a single model or an array of models to the end of a collection. Append is simply a wrapper for the fill method with the option {'method': 'append'} pre-set.

item: A model to add to the end of the collection

items: An array of models to add to the end of the collection

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs();
 5 
 6 dogs.append({"name": "Fido"});
 7 console.log( dogs.pluck("name") ); // [Fido]
 8 
 9 dogs.append( new Dog({name: "Spot"}) ); 
10 console.log( dogs.pluck("name") ); // [Fido, Spot]
11 
12 dogs.append([
13 	{name: "Skip"},
14 	{name: "Bump"}
15 ]);
16 console.log( dogs.pluck("name") ); // [Fido, Spot, Skip, Bump]

at collection.at( index )

Falcon.Model The model at the specified index

Method used to retrieve a model from this collection at a specific, zero-based, index. If no model exists at the specified index, or the index is invalid, 'null' is returned.

index: zero-based index of the model to look up in the collection

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 console.log( dogs.at(1).get("name") ); // Skip
12 console.log( dogs.at(5) ); // null

chain collection.chain()

ChainedCollection A Chained collection object with the sort, filter, without, and slice methods overridden

Method used to create a chained version of this collection. A Chained Collection allows us to chain together mutliple filter methods. Typically, when calling 'sort', 'without', 'filter', or 'slice', a javascript array is returned and no other collection filter methods can be called on the resultant array. 'chain' fixes this and allows us to string together multiple filter methods.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"id": 1, "name": "Fido", "is_tame": true},
 6 	{"id": 2, "name": "Skip", "is_tame": true},
 7 	{"id": 3, "name": "Bump", "is_tame": true},
 8 	{"id": 4, "name": "Bucko", "is_tame": false},
 9 	{"id": 5, "name": "Spot", "is_tame": true},
10 	{"id": 6, "name": "Biscuit", "is_tame": true}
11 ]);
12 
13 var odd_dogs = dogs.chain().without(2).without(4).without(6);
14 
15 var tame_b_dogs = dogs.chain().filter(function(dog) {
16 	return dog.get("name").charAt(0) === "B";
17 }).filter(function(dog) {
18 	return dog.get("is_tame")
19 });
20 
21 var sorted_b_dogs = dogs.chain().filter(function(dog) {
22 	return dog.get("name").charAt(0) === "B";
23 }).sort(function(dog_a, dog_b) {
24 	var name_a = dog_a.get("name");
25 	var name_b = dog_b.get("name");
26 
27 	if( name_a < name_b ) { return -1; }
28 	if( name_a > name_b ) { return 1; }
29 	return 0;
30 });
31 
32 console.log( odd_dogs.pluck("name") ); // [Fido, Bump, Spot]
33 console.log( tame_b_dogs.pluck("name") ); // [Bump, Biscuit]
34 console.log( sorted_b_dogs.pluck("name") ); // [Biscuit, Bucko, Bump]

clone collection.clone( [attributes], [parent] )

Falcon.Collection A clone of this collection

Method used to create a deep clone of this collection and it's models. This method can only select certain attributes from each of the models in the collection. If a parent is given, then the resultant collection will have that parent rather than the original collection's parent. If 'null' is given for parent, then the resultant collection will have no parent set.

attributes: An object or an array of attributes to copy from each model in this collection. If this is not provided all attributes will be copied.
parent: An override of the parent to set in the resultant collection. If 'null' is explicitly given, then the resultant collection will be parent-free

 1 var Owner = Falcon.Model.extend();
 2 var Dog = Falcon.Model.extend();
 3 var Dogs = Falcon.Collection.extend({model: Dog});
 4 
 5 var owner = new Owner();
 6 var dogs = new Dogs([
 7 	{"name": "Fido"},
 8 	{"name": "Skip"},
 9 	{"name": "Bump"},
10 	{"name": "Bucko"}
11 ], owner);
12 
13 var dogs_clone = dogs.clone(null);
14 
15 console.log( dogs === dogs_clone ); // false
16 console.log( dogs.length() === dogs_clone.length() ); // true
17 console.log( dogs.at(2) === dogs_clone.at(2) ); // false
18 console.log( dogs.parent === owner); // true
19 console.log( dogs_clone.parent === null); // true

comparator collection.comparator

Method used to sort this collection when a new model(s) is added. By default, this is null and no sorting will occur. Note: If this is set then any model that is inserted into this collection will be sorted (regardless of append, prepend, etc.).

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({
 3 	model: Dog,
 4 
 5 	//Sort names ascending
 6 	comparator: function(dog_a, dog_b) {
 7 		name_a = dog_a.get("name");
 8 		name_b = dog_b.get("name");
 9 
10 		if(name_a < name_b) { return -1; }
11 		if(name_a > name_b) { return 1; }
12 		return 0;
13 	}
14 });
15 
16 var dogs = new Dogs([
17 	{"name": "Fido"},
18 	{"name": "Skip"},
19 	{"name": "Bump"},
20 	{"name": "Bucko"}
21 ]);
22 
23 console.log( dogs.at(0).get("name") ); // Bucko
24 console.log( dogs.at(1).get("name") ); // Bump
25 console.log( dogs.at(2).get("name") ); // Fido
26 console.log( dogs.at(3).get("name") ); // Skip

create collection.create( data, [options] )

mixed Whatever the response from the adapter's sync method is

Method used to both create and add a model on the server and to this collection. An optional options argument can be set to define options for the sync and fill methods.

data: The raw data that defines the model to be created based on the collection's 'model' attribute.
options: The options to pass to the sync and fill methods.

model: The model to create on the server and to add to this collection. This model's data will be unwrapped and a new model will be created in this collection if this argument is set.
options: See Above.

1 var Dog = Falcon.Model.extend({url: "dog.json"});
2 var Dogs = Falcon.Collection.extend({model: Dog});
3 
4 var dogs = new Dogs();
5 
6 // Sends a POST request to '/dog.json'. Upon success, appends
7 // the new dog model to the end of the dogs collection.
8 dogs.create({"name": "Fido"}); 
9 dogs.create(new Dog({"name": "Spot"}));

destroy collection.destroy( model, [options] )

mixed Whatever the response from the adapter's sync method is

Method used to both remove a model from this collection and delete it on the server. This method takes either an iterator, a model id, or a model to look up an existing model within this collection. If a model is given, it does not need to be the same instance of any model in this collection but rather an identical model based on its 'id'. If no models are found, then null is returned. If the delete method from the server fails, this method does not remove anything from the collection.

model: The model to delete from the server and, upon successful delete, remove from this collection.
options: An optional set of options to pass into the 'sync' method when deleting the model from the server

id: The id of the model to remove
options: An optional set of options to pass into the 'sync' method when deleting the model from the server

iterator: Iterator that can be used to find the first instance of a matching model in this collection.
options: An optional set of options to pass into the 'sync' method when deleting the model from the server

 1 var Dog = Falcon.Model.extend({url: "dog.json"});
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var fido = new Dog({"id": 1, "name": "Fido"});
 5 var spot = new Dog({"id": 2, "name": "Spot"});
 6 var skip = new Dog({"id": 3, "name": "Skip"});
 7 
 8 var dogs = new Dogs([ fido, spot, skip ]);
 9 
10 // Sends a DELETE request to '/dog/{dog_id}.json'. Upon success, removes
11 // the specific model from the collection.
12 
13 // deletes fido
14 dogs.destroy(fido); 
15 
16  // deletes spot
17 dogs.destroy(2);
18 
19  // deletes skip
20 dogs.destroy(function(dog) {
21 	return dog.get("name") === "Skip";
22 });

each collection.each( iterator, [context] )

Falcon.Collection This instance

Iterates over each model in this collection based on a given iterator. For each model that exists in this collection, the iterator method is called with the model passed into the first argument and that model's index in the collection passed into the second argument.

iterator([index], model): A function used to iterate over each model in this collection. The method will be called with each model passed in as the first argument and, optionally, the current index being as the second aguments.
context: Optionally, the context to apply to the iterator function.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 // Dog's name is Fido
12 // Dog's name is Skip
13 // Dog's name is Bump
14 // Dog's name is Bucko
15 dogs.each(function(dog) {
16 	console.log("Dog's name is " + dog.get("name") );
17 });

fetch collection.fetch( [options] )

mixed Whatever the response from the adapter's sync method is

Shorthand method for a GET sync request to get all of the models from the data source.

options: The options to pass to the 'sync' method

1 var Dog = Falcon.Model.extend({url: 'dog.json'});
2 var Dogs = Falcon.Collection.extend({model: Dog});
3 
4 var dogs = new Dogs();
5 
6 dogs.fetch() // 'GET' request to '/dog.json'

fill collection.fill( items, [options] )

Falcon.Collection This instance

Method used to add new models to the collection. By default, this method just replaces all of the existing models in the collection. Optionally, one may define how models are added to the collection by defining the 'method' attribute of the options argument. 'method' can be either 'replace', 'append', 'prepend', 'merge', or 'insert'. By default, 'replace' is chosen.

items

An array of models or model-like objects to add to the collection.

options

An object of options to use when filling this collection with the given models. The 'method' attribute of options can be used to dictate how the models are added to this collection. The possible options are:

{method: 'replace'} - Relays hte information onto the replace method
{method: 'append'} - Relays hte information onto the append method
{method: 'prepend'} - Relays hte information onto the prepend method
{method: 'merge'} - Relays the information onto the merge method.
{method: 'insert', ['index': 0], ['iterator': function(){}], ['model': Falcon.Model]} - Relays the information and options onto the insert method.

by default, the 'replace' method is chosen.

item: A model to add to the collection.
options: See Above

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{name: "Skip"},
 6 	{name: "Spot"}
 7 ]);
 8 
 9 console.log( dogs.pluck("name") ); // [Skip, Spot]
10 
11 dogs.fill([
12 	{'name': "Fido"},
13 	{'name': "Bump"}
14 ]);
15 
16 console.log( dogs.pluck("name") ); // [Fido, Bump]

Example of default fill method

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{name: "Skip"},
 6 	{name: "Spot"}
 7 ]);
 8 
 9 console.log( dogs.pluck("name") ); // [Skip, Spot]
10 
11 dogs.fill([
12 	{'name': "Fido"},
13 	{'name': "Bump"}
14 ], {method: 'append'});
15 
16 console.log( dogs.pluck("name") ); // [Skip, Spot, Fido, Bump]

Example of append fill method

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{name: "Skip"},
 6 	{name: "Spot"}
 7 ]);
 8 
 9 console.log( dogs.pluck("name") ); // [Skip, Spot]
10 
11 dogs.fill([
12 	{'name': "Fido"},
13 	{'name': "Bump"}
14 ], {method: 'prepend'});
15 
16 console.log( dogs.pluck("name") ); // [Fido, Bump, Skip, Spot]

Example of prepend fill method

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{id: 1, name: "Skip"},
 6 	{id: 2, name: "Spot"}
 7 ]);
 8 
 9 console.log( dogs.pluck("name") ); // [Skip, Spot]
10 
11 dogs.fill([
12 	{id: 2, 'name': "Fido"},
13 	{id: 3, 'name': "Bump"}
14 ], {method: 'merge'});
15 
16 console.log( dogs.pluck("name") ); // [Skip, Fido, Bump]

Example of merge fill method

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{name: "Skip"},
 6 	{name: "Spot"}
 7 ]);
 8 
 9 console.log( dogs.pluck("name") ); // [Skip, Spot]
10 
11 dogs.fill([
12 	{'name': "Fido"},
13 	{'name': "Bump"}
14 ], {
15 	method: 'insert',
16 	index: 1
17 });
18 
19 console.log( dogs.pluck("name") ); // [Skip, Fido, Bump, Spot]

Example of insert fill method

filter collection.filter( [iterator] )

Array An array of the matched models

Filter method used to get an array of all the models that match the given truth-test iterator.

iterator: An iterator to truth-test each model in the collection.

id: The id of models to match against in the collection

model: A model to look up in the collection

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var my_dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 var dogs_with_b_names = my_dogs.filter(function(dog) {
12 	return dog.get("name").charAt(0) === "B";
13 });
14 
15 console.log( dogs_with_b_names ); // [Bump, Bucko]

first collection.first( [iterator] )

Falcon.Model The first model in this collection or the first model that passes the iterator's truth test. If no model was found, then 'null' is returned.

Method used to obtain the first model in the collection. If an iterator is given, then each model starting from the beginning and moving towards the end of the collection, is tested. The first model to pass the truth test is returned. If no model could be found, then 'null' is returned.

iterator: A function to check each model in this collection against. If the iterator returns true then that model is selected.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{id: 1, "name": "Fido"},
 6 	{id: 2, "name": "Skip"},
 7 	{id: 3, "name": "Bump"},
 8 	{id: 4, "name": "Bucko"}
 9 ]);
10 
11 var first_dog = dogs.first();
12 var first_b_dog = dogs.first(function(dog) {
13 	return dog.get("name").charAt(0) === "B";
14 });
15 
16 console.log( first_dog.get("name") ); // Fido
17 console.log( first_b_dog.get("name") ); // Bump

indexOf collection.indexOf( model )

Number The index of the matched model, -1 if none found

Find the index for the specified model or where the iterator first returns true. -1 is returned if nothing matches.

model: The model to look up.

id: The id of the model to look up.

iterator: Truth test iterator function to test each model with.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var fido = new Dog({id: 1, "name": "Fido"});
 5 var skip = new Dog({id: 2, "name": "Skip"});
 6 var bump = new Dog({id: 3, "name": "Bump"});
 7 var bucko = new Dog({id: 4, "name": "Bucko"});
 8 
 9 var dogs = new Dogs([fido, skip, bump, bucko]);
10 
11 var index_bump = dogs.indexOf(bump);
12 var index_id = dogs.indexOf(2);
13 var index_iterator = dogs.indexOf(function(dog) {
14 	return dog.get("name") === "Bucko";
15 });
16 
17 console.log( index_bump );  // 2
18 console.log( index_id );  // 1
19 console.log( index_iterator );  // 3

insert collection.insert( insert_model, model )

Falcon.Collection This instance

Method used to insert a model before another within the collection. If no model is found in the collection, the model is added to the end of the collection. Alternatively, an iterator can be given and the model will be inserted before the first model to pass the truth test

insert_model: The model to insert
model: The model to insert before.

insert_model: The model to insert
id: The model id to insert before.

insert_model.: The model to insert
iterator: The iterator to truth test each model against

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var fido = new Dog({id: 1, "name": "Fido"});
 5 var skip = new Dog({id: 2, "name": "Skip"});
 6 var bump = new Dog({id: 3, "name": "Bump"});
 7 var bucko = new Dog({id: 4, "name": "Bucko"});
 8 var spot = new Dog({id: 5, "name": "Spot"});
 9 
10 var dogs = new Dogs([ fido, skip ]);
11 
12 dogs.insert( bump, skip ); // insert bump before skip
13 console.log( dogs.pluck("name") ); // [Fido, Bump, Skip]
14 
15 dogs.insert( bucko, 2 ); // insert bucko before skip
16 console.log( dogs.pluck("name") ); // [Fido, Bump, Bucko, Skip]
17 
18 dogs.insert( spot, function(dog) {
19 	return dog.get("name") === "Bump";
20 });
21 console.log( dogs.pluck("name") ); // [Fido, Spot, Bump, Bucko, Skip]

last collection.last( [iterator] )

Falcon.Model The last model in this collection or the last model that passed the iterator's truth test. If no model was found, then 'null' is returned.

Method used to obtain the last model in the collection. If an iterator is given, then each model starting from the end and moving towards the beginning of the collection, is tested. The first model to pass the truth test is returned. If no model could be found, then 'null' is returned.

iterator: A function to check each model in this collection against. If the iterator returns true then that model is selected.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Bump"},
 7 	{"name": "Bucko"},
 8 	{"name": "Skip"}
 9 ]);
10 
11 var last_dog = dogs.last();
12 var last_b_dog = dogs.last(function(dog) {
13 	return dog.get("name").charAt(0) === "B";
14 });
15 
16 console.log(last_dog.get("name")); // Skip
17 console.log(last_b_dog.get("name")); // Bucko

lastIndexOf collection.lastIndexOf( model )

Number The index of the last matched model, -1 if none found

Find the last index for the specified model or where the iterator first returns true. -1 is returned if nothing matches.

model: The model to look up.

id: The id of the model to look up.

iterator: Truth test iterator function to test each model with.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var fido = new Dog({id: 1, "name": "Fido"});
 5 var skip = new Dog({id: 2, "name": "Skip"});
 6 var bump = new Dog({id: 3, "name": "Bump"});
 7 var bucko = new Dog({id: 4, "name": "Bucko"});
 8 
 9 var dogs = new Dogs([fido, skip, bump, bucko, bump, skip, fido]);
10 
11 var index_bump = dogs.lastIndexOf(bump);
12 var index_id = dogs.lastIndexOf(2);
13 var index_iterator = dogs.lastIndexOf(function(dog) {
14 	return dog.get("name") === "Bucko";
15 });
16 
17 console.log( index_bump );  // 4
18 console.log( index_id );  // 5
19 console.log( index_iterator );  // 3

length collection.length()

The total number of models in this collection. This is an observable so anything that is bound against this will also be updated when any models are added or removed from the collection.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Bump"}
 7 ]);
 8 
 9 console.log( dogs.length() ); // 2
10 
11 dogs.append([
12 	{"name": "Bucko"},
13 	{"name": "Skip"}
14 ]);
15 
16 console.log( dogs.length() ); // 4

makeUrl collection.makeUrl( type, [parent] )

String The generated url

Attempts to generate url for a specific type of request being made. Url's are generated based on this collection's relative url (extracted from the collection's model prototype), the parent model for this collection, and the Falcon.baseApiUrl setting.

An optional override to the 'parent' attribute can be passed into the second argument of this method. If the parent argument is set, then that will be used instead of the instance parent attribute. Alternatively, if 'null' is explicitly set for the parent attribute, then this collection's url will be used as the base url for the full url generation.

type: The type of request that is trying to be executed. Type can be either "GET", "POST", "PUT", "DELETE".
parent: An override to the parent model of this collection. If 'null' is explicitly stated, then no parent will be used meaning this collection's model prototype will be used to find the the base relative url for this request.

 1 	Falcon.baseApiUrl = "http://www.falconjs.com/"
 2 var Owner = Falcon.Model.extend({"url": "owner.json"});
 3 var Dog = Falcon.Model.extend({"url": "dog.json"});
 4 var Dogs = Falcon.Collection.extend({ model: Dog });
 5 
 6 var owner = new Owner({'id': 1});
 7 var dogs = new Dogs( owner ); // Owner is the parent
 8 
 9 console.log( dogs.makeUrl("GET") ); // http://www.falconjs.com/owner/1/dog.json
10 console.log( dogs.makeUrl("GET", null) ); // http://www.falconjs.com/dog.json

merge collection.merge( items )

Falcon.Collection This instance

Attempts to merge the current collection with the given items. A collection is merged by attempting to find a model in the existing collection that matches the id each model or model-like object and filled with its data if found. If no model is found in the colleciton, then the input model is appended on to the collection.

item: A model to merge into the collection.

items: A list of models or model-like objects to merge into the collection

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dog_one = new Dog({"id": 1, "name": "Fido"});
 5 var dog_two = new Dog({"id": 2, "name": "Skip"});
 6 var dogs = new Dogs([dog_one, dog_two]);
 7 
 8 // Updates Fido -> Bump
 9 dogs.merge(new Dog({"id": 1, "name": "Bump"}))
10 console.log( dogs.pluck("name") ); // [Bump, Skip]
11 console.log( dogs.at(0) === dog_one ); // true
12 console.log( dogs.at(1) === dog_two ); // true
13 
14 // Can be merged based on objects without losing reference
15 // to the original object
16 dogs.merge([
17 	{"id": 1, "name": "Lassie"},
18 	{"id": 2, "name": "Howard"},
19 	{"id": 3, "name": "Bucko"}
20 ]);
21 console.log( dogs.pluck("name") ); // [Lassie, Howard, Bucko]
22 console.log( dogs.at(0) === dog_one ); // true
23 console.log( dogs.at(1) === dog_two ); // true

mixin collection.mixin( mapping )

Falcon.Collection This instance

Adds attributes and functions to all of the current and future models in the collection. This is especially useful for adding one-off functions or observables where needed on each item in the collection that isn't really necessary for every time this specific collection is created. A good example of this would be adding a 'deleting' flag to each current and future model in the collection to signify if the model is currently being deleted (hence allowing us to show a loader and ignore any additional delete requests).

mapping: The mapping to apply to each of the current models and any future models that are added to the collection. This should be an object of values, observables, and functions to add to this collection's models.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"}
 6 ]);
 7 
 8 dogs.mixin({
 9 	"color": "Black",
10 	"is_tame": ko.observable( true ),
11 	"bark": function() {
12 		console.log(this.get("name") + " says woof!");
13 	}
14 });
15 
16 dogs.append({"name": "Spot"});
17 
18 var fido = dogs.at( 0 );
19 var spot = dogs.at( 1 );
20 
21 console.log( fido.get("name") ); // Fido
22 console.log( fido.get("color") ); // Black
23 console.log( ko.isObservable( fido.is_tame ) ); // true
24 console.log( fido.get("is_tame") ); // true
25 fido.bark(); // Fido says woof!
26 
27 console.log( spot.get("name") ); // Spot
28 console.log( spot.get("color") ); // Black
29 console.log( ko.isObservable( spot.is_tame ) ); // true
30 console.log( spot.get("is_tame") ); // true
31 spot.bark(); // Spot says woof!

models collection.models()

The internal observable array that contains all of the models added to this collection.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 console.log( ko.isObservable( dogs.models ) ); // true 
12 console.log( dogs.models() );  // [Dog, Dog, Dog, Dog]

parse collection.parse( data, options, xhr )

Array The formatted response to fill the collection with.

The parse method is called after any successful request is completed but before any of the data is actually filled into the collection. It's purpose is to allow you to intercept and parse through the raw server data in order to format it correctly to how this collection expects to see it. This method must return an array of objects in order for the collection to be filled correctly.

data: The raw data returned from the server
options: The options that were passed into the sync function
xhr: The XmlHttpRequest that was created when making this request

1 {
2 	"data": [
3 		{"id": 1, "name": "Fido"},
4 		{"id": 2, "name": "Spot"},
5 		{"id": 3, "name": "Skip"}
6 	],
7 	"created_at": "01/01/1970",
8 	"updated_at": "01/01/1970"
9 }

Response JSON

 1 var Dog = Falcon.Model.extend({'url': "dog.json"});
 2 var Dogs = Falcon.Collection.extend({
 3 	model: Dog,
 4 
 5 	// Example parse method, the array that is returned from 
 6 	// this will be passed into the collection's fill() method.
 7 	parse: function( response ) {
 8 		return response["data"];
 9 	}
10 });
11 
12 var dogs = new Dogs();
13 
14 // Get's the server data and runs the parse method
15 // Callback is called on complete
16 dogs.fetch(function(dogs) {
17 	console.log( dogs.length() ); // 3
18 	console.log( dogs.at(0).get("id") ); // 1
19 	console.log( dogs.at(0).get("name") ); // Fido
20 });

Application Javascript

pluck collection.pluck( attribute, [unwrap] )

Array An array of the values from each model corresponding to the given attribute.

This method extracts a specific attribute from each model in the collection and returns it in an array. If the unwrap flag is set to true (which it is by default), each attribute is removed from its observable container if it exists wihin one. If the attribute given isn't found in a model, 'undefined' is returned in the resultant array.

attribute: The attribute to pluck from each model in the collecton
unwrap: Flag that states if we should unwrap the values that are observables. This is true by default.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 console.log(dogs.pluck("name")); // [Fido, Skip, Bump, Bucko]

pop collection.pop()

Falcon.Model The last model in this collection. 'null' is returned if the collection is empty.

Removes and returns the last model from this collection. If this collection is empty, 'null' is returned instead.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 var last_dog = dogs.pop();
12 
13 console.log( dogs.length() ); // 3
14 console.log( last_dog.get("name") ); // Bucko

prepend collection.prepend( items )

Falcon.Collection This instance

Adds a model or an array of models to the beginning of this collection.

item: A model to prepend to the beginning of this collection.

items: An array of models to prepend to the beginning of this collection.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs();
 5 
 6 dogs.prepend({"name": "Fido"});
 7 console.log( dogs.pluck("name") ); // [Fido]
 8 
 9 dogs.prepend( new Dog({name: "Spot"}) ); 
10 console.log( dogs.pluck("name") ); // [Spot, Fido]
11 
12 dogs.prepend([
13 	{name: "Skip"},
14 	{name: "Bump"}
15 ]);
16 console.log( dogs.pluck("name") ); // [Skip, Bump, Spot, Fido]

push collection.push( items )

Falcon.Collection This instance

Push an element on to the end of this collection. This method is an alias of append.

item: A model to add to the collection

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs();
 5 
 6 dogs.push({"name": "Fido"});
 7 console.log( dogs.pluck("name") ); // [Fido]
 8 
 9 dogs.push( new Dog({name: "Spot"}) ); 
10 console.log( dogs.pluck("name") ); // [Fido, Spot]
11 
12 dogs.push([
13 	{name: "Skip"},
14 	{name: "Bump"}
15 ]);
16 console.log( dogs.pluck("name") ); // [Fido, Spot, Skip, Bump]

remove collection.remove( models )

Falcon.Collection This instance

Used to remove elements from this collection. This method does not make any API delete requests and will simply remove an instance of a model from this collection.

models: An array of models to remove from this collection.

model: A model to remove from this collection.

iterator: An iterator function to truth test each of this collection's models with. If the iterator is true, then the model is removed.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var fido = new Dog({"name": "Fido"});
 5 var skip = new Dog({"name": "Skip"});
 6 var bump = new Dog({"name": "Bump"});
 7 var bucko = new Dog({"name": "Bucko"});
 8 var spot = new Dog({"name": "Spot"});
 9 var zeus = new Dog({"name": "Zeus"});
10 
11 var dogs = new Dogs([fido, skip, bump, bucko, spot, zeus]);
12 
13 dogs.remove( skip );
14 console.log( dogs.length() ); // 5
15 console.log( dogs.any(skip) ); // false
16 
17 dogs.remove( [fido, spot] );
18 console.log( dogs.length() ); // 3
19 console.log( dogs.any(fido) ); // false
20 console.log( dogs.any(spot) ); // false
21 
22 dogs.remove(function(dog) {
23 	return dog.get("name").charAt(0) === "B";
24 });
25 console.log( dogs.length() ); // 1
26 console.log( dogs.any(bump) ); // false
27 console.log( dogs.any(bucko) ); // false
28 
29 console.log( dogs.any(zeus) ); // true

replace collection.replace( items )

Falcon.Collection This instance

Replaces all of the models in the collection with the input array

item: A model to replace all of the models in the current collection with.

items: An array of models to replace the current list of models in the collection.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"}
 7 ]);
 8 console.log( dogs.pluck("name") ); // [Fido, Skip]
 9 
10 dogs.replace({"name": "Lassie"});
11 console.log( dogs.pluck("name") ); // [Lassie]
12 
13 dogs.replace([{"name": "Bucko"}, ["name": "Spot"]]);
14 console.log( dogs.pluck("name") ); // [Bucko, Spot]

reset collection.reset()

Falcon.Collection This instance

'resets' the internal observable array of this collection. This will make sure the model list is an observable array, has no elements, and the length of the collection is restored to zero.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 console.log( dogs.length() ); // 4
12 
13 dogs.reset();
14 
15 console.log( dogs.length() ); // 0

serialize collection.serialize( [attributes] )

Array The serialized collection

attributes: The attributes that should be included in the serialization of each model in this collection. If none given, all attributes unique to each model is included.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{id: 1, "name": "Fido"},
 6 	{id: 2, "name": "Skip"},
 7 	{id: 3, "name": "Bump"}
 8 ]);
 9 
10 // [{id: 1, name: "Fido"}, {id: 2, name: "Skip"}, {id: 3, name: "Bump"}]
11 console.log( dogs.serialize() ); 
12 
13 // [{name: "Fido"}, {name: "Skip"}, {name: "Bump"}]
14 console.log( dogs.serialize(["name"]) );

set collection.set( key, value )

Falcon.Collection This instance

Sets a specific property of all of the models in the collection to a certain value.

key: The property to update.

value: The value to set on each model at the given key.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"}
 7 ]);
 8 console.log( dogs.pluck("name") ); // [Fido, Skip]
 9 
10 dogs.set("name", "Super Dog");
11 console.log( dogs.pluck("name") ); // [Super Dog, Super Dog]

shift collection.shift()

Falcon.Model The first model in this collection

Removes the first element from the collection and returns it.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 var first_dog = dogs.shift();
12 
13 console.log( dogs.length() ); // 3
14 console.log( first_dog.get("name") ); // Fido

slice collection.slice( start, [end] )

Array A subset of the collection's array

Slices the collection the same way slice works on an array. Returns an array of the models within the range.

start: An integer that specifies where to start the selection (The first element has an index of 0). Use negative numbers to select from the end of an array.
end: An integer that specifies where to end the selection. If omitted, all elements from the start position and to the end of the array will be selected. Use negative numbers to select from the end of an array

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 console.log( dogs.slice( 1 ) ); // [Skip, Bump, Bucko]
12 console.log( dogs.slice( 1, 3 ) );  // [Skip, Bump]

sort collection.sort( comparator )

Array The sorted array

Sorts the collection by a given comparator function.

comparator(a, b): A comparator function to sort the collection with.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var dogs = new Dogs([
 5 	{"name": "Fido"},
 6 	{"name": "Skip"},
 7 	{"name": "Bump"},
 8 	{"name": "Bucko"}
 9 ]);
10 
11 // Sort names from A->Z
12 dogs.sort(function(dog_a, dog_b) {
13 	name_a = dog_a.get("name");
14 	name_b = dog_b.get("name");
15 
16 	if(name_a < name_b) { return -1; }
17 	if(name_a > name_b) { return 1; }
18 	return 0;
19 });
20 
21 console.log( dogs.pluck("name") ); // [Bucko, Bump, Fido, Skip]

sync collection.sync( type, [options], [context] )

mixed Whatever the response from the adapter's sync method is

Method used to interact with the backend API and this collection. Internally this method just calls the Falcon.adapter.sync method.

type: The HTTP Method to call to the backend with. Valid options options include "GET", "POST", "PUT", "DELETE".
options: Optional object of settings to use on this call. Please refer to Falcon.Adapter#standardizeOptions
context: An optional context value to execute the callback methods on

 1 var Dog = Falcon.Model.extend({"url": "dog.json"});
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs();
 5 var parent_dogs = new Dogs();
 6 
 7 // Creates a GET request that will be sent to '/dog.json'
 8 // each callback method has the same arguments:
 9 //
10 //   dogs: This collection
11 //   data: The raw response data prior to being passed into the parse() method
12 //   options: The standardized request options
13 //   other_args: An object of adapter implementation specific arguments
14 //
15 // All of the callback methods will be called with parent_dogs as 'this'
16 dogs.sync("GET", {
17 	complete: function(dogs, data, options, other_args) {
18 		console.log("Completed trying to find the Dogs.");
19 	},
20 
21 	success: function(dogs, data, options, other_args) {
22 		console.log("Successfully found the Dogs!");
23 	},
24 
25 	error: function(dogs, data, options, other_args) {
26 		console.log("Couldn't find the dogs :(");
27 	}
28 }, parent_dogs);

unshift collection.unshift( items )

Falcon.Collection This instance

Prepend a model or a list of models to the front of this collection. This is an alias of prepend.

item: A model to prepend to the beginning of this collection.

items: An array of models to prepend to the beginning of this collection.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({model: Dog});
 3 
 4 var dogs = new Dogs();
 5 
 6 dogs.unshift({"name": "Fido"});
 7 console.log( dogs.pluck("name") ); // [Fido]
 8 
 9 dogs.unshift( new Dog({name: "Spot"}) ); 
10 console.log( dogs.pluck("name") ); // [Spot, Fido]
11 
12 dogs.unshift([
13 	{name: "Skip"},
14 	{name: "Bump"}
15 ]);
16 console.log( dogs.pluck("name") ); // [Skip, Bump, Spot, Fido]

without collection.without( iterator )

Array The list of models after being filtered by the iterator

Used to generate an array of models from this collection without the matching models included.

model: The model to remove from the list.

id: The id of the model to remove from the list.

iterator: A truth test iterator to check each model against.

 1 var Dog = Falcon.Model.extend();
 2 var Dogs = Falcon.Collection.extend({ model: Dog });
 3 
 4 var fido = new Dog({"id": 1, "name": "Fido"});
 5 var skip = new Dog({"id": 2, "name": "Skip"});
 6 var bump = new Dog({"id": 3, "name": "Bump"});
 7 var bucko = new Dog({"id": 4, "name": "Bucko"});
 8 
 9 var dogs = new Dogs([ fido, skip, bump, bucko ]);
10 
11 var without_skip = dogs.without( skip );
12 var without_bump = dogs.without( 3 );
13 var without_b_dogs = dogs.without(function(dog) {
14 	return dog.get("name").charAt(0) === "B";
15 });
16 
17 console.log( without_skip ); // [Fido, Bump, Bucko]
18 console.log( without_bump ); // [Fido, Skip, Bucko]
19 console.log( without_b_dogs ); // [Fido, Skip]

Falcon.Collection extends Falcon.Object

Collections represent an array of models. They provide numerous filtering, insertion, and sync methods.