Class: kb.CollectionObservable

Defined in:

src/core/collection-observable.coffee

Overview

Base class for observing collections.

Examples:

How to create a ko.CollectionObservable using the ko.collectionObservable factory.

var collection = new Collection([{name: 'name1'}, {name: 'name2'}]);
var view_model = {
  todos: kb.collectionObservable(collection)
};

How to access and change the observed collection.

 var todos = new kb.CollectionObservable(new kb.Collection([{name: 'name1'}, {name: 'name2'}]);
 var current_collection = todos.collection(); // get
 todos.collection(new Backbone.Collection([{name: 'name3'}, {name: 'name4'}])); // set

Instance Method Summary

# (void) destroy() Required clean up function to break cycles, release view models, etc.
# (void) shareOptions() Get the options for a new collection that can be used for sharing view models.
# (void) filters(filters) Setter for the filters array for excluding models in the collection observable.
# (void) comparator(comparator) Setter for the sorted index function for auto-sorting the ViewModels or Models in a kb.CollectionObservable.
# (void) sortAttribute(sort_attribute) Setter for the sort attribute name for auto-sorting the ViewModels or Models in a kb.CollectionObservable.
# (void) viewModelByModel(model) Reverse lookup for a view model by model.
# (void) hasViewModels() Will return true unless created with models_only option.
# (void) compact() Compacts the Collection Observable to use the least amount of memory.

Constructor Details

# (ko.observableArray) constructor(collection, view_model, options)

Note: the constructor does not return 'this' but a ko.observableArray

Used to create a new kb.CollectionObservable.

When the observable is updated, the following Backbone.Events are triggered:

add: (view_model, collection_observable) or if batch: (collection_observable)
resort: (view_model, collection_observable, new_index) or if batch: (collection_observable)
remove: (view_model, collection_observable) or if batch: (collection_observable)

Parameters:

collection ( Collection ) — the collection to observe (can be null)
options ( Object ) — the create options

Options Hash: (options):

models_only ( Boolean ) — flag for skipping the creation of view models. The collection observable will be populated with (possibly sorted) models.
auto_compact ( Boolean ) — flag used to compact memory used by the collection observable when large changes occur, eg. resetting the collection.
view_model ( Constructor ) — the view model constructor used for models in the collection. Signature: constructor(model, options)
create ( Function ) — a function used to create a view model for models in the collection. Signature: create(model, options)
factories ( Object ) — a map of dot-deliminated paths; for example 'models.owner': kb.ViewModel to either constructors or create functions. Signature: 'some.path': function(object, options)
comparator ( Function ) — a function that is used to sort an object. Signature: function(model_a, model_b) returns negative value for ascending, 0 for equal, and positive for descending
sort_attribute ( String ) — the name of an attribute. Default: resort on all changes to a model.
filters ( Id|Function|Array ) — filters can be individual ids (observable or simple) or arrays of ids, functions, or arrays of functions.
path ( String ) — the path to the value (used to create related observables from the factory).
store ( kb.Store ) — a store used to cache and share view models.
factory ( kb.Factory ) — a factory used to create view models.
options ( Object ) — a set of options merge into these options. Useful for extending options when deriving classes rather than merging them by hand.

Returns:

( ko.observableArray ) — the constructor does not return 'this' but a ko.observableArray

Instance Method Details

# (void) destroy()

Required clean up function to break cycles, release view models, etc. Can be called directly, via kb.release(object) or as a consequence of ko.releaseNode(element).

# (void) shareOptions()

Get the options for a new collection that can be used for sharing view models.

Examples:

Sharing view models for an HTML select element.

var selected_collection = new Backbone.Collection();
var available_collection = new Backbone.Collection([{name: 'Bob'}, {name: 'Fred'}]);
var selected = kb.collectionObservable(available_collection);
var available = kb.collectionObservable(available_collection, available_collection.shareOptions()); // view models shared with selected collection observable

# (void) filters(filters)

Setter for the filters array for excluding models in the collection observable.

Examples:

 // exclude a single model by id
 collection_observable.filters(model.id);

Parameters:

filters ( Id|Function|Array ) — filters can be individual ids (observable or simple) or arrays of ids, functions, or arrays of functions.

# (void) comparator(comparator)

Setter for the sorted index function for auto-sorting the ViewModels or Models in a kb.CollectionObservable.

Examples:

 // change the sorting function
 collection_observable.comparator(
   function(view_models, vm){
     return _.comparator(view_models, vm, (test) -> kb.utils.wrappedModel(test).get('name'));
   }
 );

Parameters:

comparator ( Function ) — a function that returns an index where to insert the model. Signature: function(models, model)
comparator ( Function ) — a function that is used to sort an object. Signature: function(model_a, model_b) returns negative value for ascending, 0 for equal, and positive for descending

# (void) sortAttribute(sort_attribute)

Setter for the sort attribute name for auto-sorting the ViewModels or Models in a kb.CollectionObservable.

Examples:

 var todos = new kb.CollectionObservable(new Backbone.Collection([{name: 'Zanadu', name: 'Alex'}]));
 // in order of Zanadu then Alex
 todos.sortAttribute('name');
 // in order of Alex then Zanadu

Parameters:

sort_attribute ( String ) — the name of an attribute. Default: resort on all changes to a model.

# (void) viewModelByModel(model)

Reverse lookup for a view model by model. If created with models_only option, will return null.

# (void) hasViewModels()

Will return true unless created with models_only option.

Examples:

var todos1 = new kb.CollectionObservable(new Backbone.Collection(), {models_only: true});
todos1.hasViewModels();     // false
var todos2 = new kb.CollectionObservable(new Backbone.Collection());
todos2.hasViewModels();     // true

# (void) compact()

Compacts the Collection Observable to use the least amount of memory. Currently, this is brute force meaning it releases than regenerates all view models when called.