Final Class: Collection

Oracle® JavaScript Extension Toolkit (JET)
15.1.0
F83698-01

Since:
  • 1.0
Module:
  • ojmodel

QuickNav

Fields

Methods

Type Definitions

Description

Collection of Model objects


Usage

Signature:

final class Collection

Typescript Import Format
//To import this class, use the format below.
import {Collection} from "ojs/ojmodel";

For additional information visit:


Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.


Constructor

new Collection(models, options)

Parameters:
Name Type Argument Description
models Array.<Model> <optional>
 Set of model objects to put into collection at construction time. If models contain actual Model objects, then any custom parse callback set on the collection must be able to handle Model objects as a possible argument
options Object <optional>
 Passed through to the user's initialize routine, if any, upon construction

Mixes In

Fields

EventType :string

Properties:
Name Type Default Description
ADD string add Triggered when a model is added to a collection

The event passes these arguments to the handler:

    model: the model being added to the collection
    collection: the collection to which the model has been added
    options: any options passed in to the add call that triggered the event

ALL string all Triggered for any of the above events

The event passes the name of the actual event and then any arguments normally passed to that event following the name

ALLADDED string alladded Triggered by a collection during an add call once all models passed in have been added

The event passes these arguments to the handler:

    collection: the collection to which the models have been added
    models: the array of models that have been added
    options: any options passed in to the add call

ALLREMOVED string allremoved Triggered by a collection during a remove call once all models passed in have been removed and destroyed

The event passes these arguments to the handler:

    collection: the collection from which the models have been removed
    models: the array of models that have been removed
    options: any options passed in to the remove call

CHANGE string change Triggered when a model's attributes are changed. This can be the result of a clear call on a model; a property set call on a model; an unset call on a model; or the changing of properties due to the merging of models (in an add, for example)

The event passes these arguments to the handler:

    model: the model on which the change occurred
    value: for property-specific change events, the new value of the property being changed
    options: any options passed in to the call that triggered the change event. This is the second argument passed for overall change events, and the third parameter (after value) for property-specific change events.

DESTROY string destroy Triggered when a model is deleted from the data service (and thus from its Collection), due to a model destroy call

The event passes these arguments to the handler:

    model: the model being deleted
    collection: the deleted model's collection, if any

ERROR string error Triggered when a model has failed to update on the data service

The event passes these arguments to the handler:
collection or model: the collection or model that made the call that resulted in the error
xhr: the xhr argument for the failing request, if any
options: any options passed in to the call that triggered the failing request, plus the status and error as textStatus and errorThrown

INVALID string invalid Triggered on an error with data source interactions

The event passes these arguments to the handler:

    model: the model (or collection) on which the error operation happened
    xhr: the xhr involved, if relevant
    options: any options passed in to the call that triggered the invalid event

READY string ready Triggered when all pending promises from Collection API calls have been resolved

The event passes these arguments to the handler:

    collection: the collection on which the promises have been resolved

REFRESH string refresh Triggered when a collection is refreshed (see Collection.refresh)

The event passes these arguments to the handler:

    collection: the collection being refreshed
    options: any options passed in to the refresh call

REMOVE string remove Triggered when a model is removed from a collection

The event passes these arguments to the handler:

    model: the model being removed from the collection
    collection: the collection from which the model was removed
    options: index: the index of the model being removed

REQUEST string request Triggered when a model or collection has sent a request to the data service

The event passes these arguments to the handler:

    collection or model: the collection or model triggering the request
    xhr: the xhr argument for the request
    options: any options passed as part of the request

RESET string reset Triggered when a collection is reset (see Collection.reset)

The event passes these arguments to the handler:

    collection: the collection being reset
    options: any options passed in to the reset call

SORT string sort Triggered when a collection is sorted. If the second argument to the callback is set (options) and 'add' is true, it means this sort event was triggered as a result of an add

The event passes these arguments to the handler:

    collection: the collection being sorted
    options: add: true if this sort event was triggered as the result of an add call, undefined or false if not

SYNC string sync Triggered when a model or collection has been updated from the data service

The event passes these arguments to the handler:

    collection or model: the collection or model that triggered the update
    response: the response object from the data service
    options: any options passed in to the call that triggered the update

changes :Array.<number>

Changes that have occured due to adds/removes since the last fetch. This is a list of indicies that have changed (location at which a model was added, deleted, or set). They do not shift with subsequent operations
Since:
  • 1.0.0

comparator :(null|string|function(Model, Model=): number)

If set to a string, sort the collection using the given attribute of a model.

If set to a function(Model), the function should return a string giving the model attribute by which the sort should take place.

If set to a function(Model1, Model2), then this function is called comparing Model1 and Model2 (see the JavaScript array.sort() for details)

In the virtual case, comparator must be a string-based field comparator, which will be passed to the server.

Users should call sort() after making any changes to the comparator to ensure that the models are correctly sorted, or that there are no leftover models sorted incorrectly in the virtual case.

Since:
  • 1.0.0

customPagingOptions :((response: object)=> Collection.CustomPagingOptionsReturn|null)|null

A callback function allowing users to extract their own paging/virtualization return values from the server's response.

It should accept these parameters:

response: the Object data response coming back from the fetch call

The callback should return either null, in which case the collection will look for the default properties, or an object containing one or more of the following attribute/value pairs (note that the Collection will look back to the response for default paging return properties if not found in the returned object):

    totalResults: the total number of records available on the server side, not just in the current result. By default the collection looks in the response for "totalResults"
    limit: the actual fetchSize from the server. This may not be the client's fetchSize or the number of records in the current result. By default the collection looks in the response for "limit". This becomes the collection's "lastFetchSize" property
    count: the actual number of records returned by the server in the last result. This becomes the collection's "lastFetchCount". By default the collection looks in the response for "count".
    offset: the actual starting record number of the current result. By default the collection looks in the response for "offset"
    hasMore: boolean indicating whether or not there are more records available beyond the current result. By default the collection looks in the response for "hasMore"

Since:
  • 1.0.0

customURL :(function(string, Collection, Object): (string|Object|null)|null)

A callback to allow users to customize the data service URLs. The callback should accept these parameters:

operation: one of "create", "read", "update", "patch", or "delete", indicating the type of operation for which to return the URL

collection: the Collection object requesting the URL

options: any of the following properties:

    recordID: id of the record involved, if relevant
    fetchSize: how many records to return. If not set, return all.
    startIndex: Starting record number of the set to return.
    startID: Retrieve records starting with the record with the given unique ID.
    since: Retrieve records with timestamps after the given timestamp.
    until: Retrieve records with timestamps up to the given timestamp. Default is "until"
    sort: field(s) by which to sort, if set
    sortDir: sort ascending or descending (asc/dsc)
    query: a set of attributes indicating filtering that should be done on the server. See where for complete documentation of query values
    all: true (along with 'query', above) indicates that this is a findWhere or where type call that is expecting all models meeting the query condition to be returned

customURL callbacks should return either: null, in which case the default will be used; a url string, which will be used with the standard HTTP method for the type of operation, or an Object with any other attributes that should be passed to the ajax call.
This object must at minimum include the URL, and other attributes as follows:

    url: the custom URL string
    type: (optional) a string indicating the type of HTTP method to use (GET, POST, DELETE, etc.)
    (other): (optional) any other attributes to pass in the ajax call

Since:
  • 1.0.0

fetchSize :number

The number of records to be fetched from the server in any one round trip. The server's fetch size comes back as the "limit" property. The default value of -1 indicates that virtualization is not being used or is not available, and all records will be fetched.

hasMore :boolean

Indicates whether or not there are more records available on the server, at indices beyond the last fetch.
Since:
  • 1.0.0

lastFetchCount :number

The number of records actually fetched the last time the collection fetched from the server. This may or may not match fetchSize or lastFetchSize

lastFetchSize :number

The server's fetch size. This may not match fetchSize.
Since:
  • 1.0.0

length :number

Total number of models in the collection. When the collection is virtual, not all of the models may be locally available.
Since:
  • 1.0.0

model :Model

Property specifying the model class object used by the collection

modelLimit :number

For virtual collections, the number of records to be kept in memory at any one time. The default of -1 indicates that no records are thrown out

models :Array.<Model>

Direct access to the collection's list of models objects
Note that this property should not be used directly when a collection is virtual, as automatic fetches will not be triggered for undefined elements in the model. Use at() instead.
Since:
  • 1.0.0

offset :number

The actual starting index number at which models from the last server fetch were inserted into the collection.

omitLanguageHeader :boolean

If true, do not insert the JET locale-based Accept-Language header. If false, let the Ajax system set the header.
Since:
  • 5.0.0

parse :function(Object):Object

Optional callback to parse responses from the server. It is called with the server's response and should return a response (possibly modified) for processing
Since:
  • 1.0.0

sortDirection :number

Sort direction for string-based sort comparators (model attribute names). A value of 1 indicates ascending sorts, -1 indicates descending. The default is 1 (ascending).
Users should call sort() after changing sort direction to ensure that models in the collection are sorted correctly, or, for virtual collections, that there are no left over models in an incorrect order.

totalResults :number

The total number of records available for this collection regardless of whether they have been fetched or not. For non-virtual collections this will equal the length.

url :(null|string|function(): string)

The data service's server URL.
Since:
  • 1.0.0

Methods

(static) extend(properties, classProperties) : {any}

Create a new, specific type of Collection object to represent a collection of records from a JSON data set.
This:
Parameters:
Name Type Argument Description
properties {parse?: (data: any)=> any, model?: Model, url?: string, initialize?: (models: Array<Model>, options: object)=> void, comparator?: null | string | ((model1: Model, model2?: Model)=> number), fetchSize?: number, modelLimit?: number, [propName: string]: any} <optional>
 Properties for the new Collection class.

parse: a user callback function to allow parsing of the JSON collection after it's returned from the data service. If a collection is initialized with actual Models or collection.set is used with actual Models, the parse callback must expect that the argument passed to it may contain raw JSON data *or* Model objects
model: the specific type of model object to use for each member of the collection
url: the URL string to use to get records from the data service
initialize: a user callback function to be called when this collection is created. Called in the context of the collection and passed: models, options.
comparator: a user callback used on sort calls. May also be set to false to prevent sorting. See comparator
fetchSize: the number of records to be fetched on each round trip to the server. Overrides {Collection#fetchSize}. If not set, the collection will not consider itself virtual
modelLimit: the number of records to be held in memory at any one time, if virtualization is in force. The default is all records. This uses an LRU algorithm to determine which to roll off as more records are added.
classProperties Object <optional>
 optional properties that get attached to the constructor of the extended Collection
Since:
  • 1.0.0
Returns:

new Collection object

Type
any

abort : {Promise.<null>}

Cancel all xhr requests known to this collection as still pending. Return a promise that is resolved when all of the requests abort, and all the promises tied to those requests resolve with an error
Since:
  • 2.1.0
Returns:

a promise that when resolved, indicates that all the open xhr objects generated by this collection have aborted

Type
Promise.<null>

add(m, options) : {(Promise.<Array.<Model>>|Array.<Model>)}

Add a model or models to the end of the collection.
Events:

    add: fired for each model added, passing the collection, model added, and options
    alladded: fired after all models have been added, passing the collection, array of models added, and options

Note that for virtual collections, if a new model is added after being saved up to the server, no add event will be fired as the collection will already "see" the model as existing. Note that a warning will be logged if this add is not a force, not merging, and duplicate IDs are found.

Parameters:
Name Type Argument Description
m Model | Object | Array.<Object> | Array.<Model> Model object (or array of models) to add. These can be already-created instance of the Model object, or sets of attribute/values, which will be wrapped by add() using the collection's model.
options {silent?: boolean, at?: number, merge?: boolean, sort?: boolean, force?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 silent: if set, do not fire events
at: splice the new model into the collection at the value given (at:index)
merge: if set, and if the given model already exists in the collection (matched by id), then merge the attribute/value sets, firing change events
sort: if set, do not re-sort the collection even if the comparator is set.
force: if set to true, do an add to the collection no matter whether the item is found or not
deferred: if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

The model or models added to the collection (or found/merged if appropriate). If deferred or virtual, return the model or models added in a promise when the set has completed

Type
(Promise.<Array.<Model>>|Array.<Model>)

any(iterator, context) : {boolean}

Return true if any of the models in the collection pass the test made by calling the iterator function parameter
Parameters:
Name Type Argument Description
iterator function(Object) function called with each model to determine if it "passes". The function should return true or false.
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

true if any of the models cause the iterator function to return true

Type
boolean

at(index, options) : {Model|Promise.<Model>|null}

Return the model object found at the given index of the collection, or a promise object that will pass the model as an argument when it resolves.

For events that may be fired if the collection is virtual, see fetch.

Parameters:
Name Type Argument Description
index number Index for which to return the model object.
options {fetchSize?: number, deferred?: boolean, [propName: string]: any} <optional>
 fetchSize: fetch size to use if the call needs to fetch more records from the server, if virtualized. Overrides the overall fetchSize setting
deferred: if true, return a deferred/promise object as described below. If not specified, the type of return value will be determined by whether or not the collection is virtual
Since:
  • 1.0.0
Returns:

Model model located at index. If index is out of range, returns null. If this is a virtual collection, or if deferred is specified and true, at will return a Promise object which will resolve passing the model at the given index (or null if out of range)

Type
Model | Promise.<Model> | null

clone : {Collection}

Return a copy of the Collection
Returns:

copy of the Collection

Type
Collection

contains(model, options) : {boolean|Promise.<boolean>}

Determine if the given model object is present in the collection.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
model Object Model object (or Model id) to locate
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

true if the model is contained in the collection, false if not. If deferred, a promise that will resolve with true or false when complete.

Type
boolean | Promise.<boolean>

create(attributes, options) : {Model|boolean|Promise.<Model>}

Creates a new model, saves it to the data service, and adds it on to the collection.

Events:

    add: fired when the model is added, passing the collection, model added, and options, if not silent
    alladded: fired after all models have been added, passing the collection, array of models added, and options
    request:: fired when the request to save is going to the server
    sync:: fired when the model is saved to the data service, passing the model and the raw response

Parameters:
Name Type Argument Description
attributes Object <optional>
 Set of attribute/value pairs with which to initialize the new model object, or a new Model object
options {silent?: boolean, at?: number, merge?: boolean, sort?: boolean, force?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 Options to control save (see save), or add (see add). Plus:

deferred: if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

new model or false if validation failed. If virtual, returns a promise that resolves with the new model

Type
Model | boolean | Promise.<Model>

difference(var_args) : {Array.<Model>}

Return an array of models in the collection but not passed in the array arguments
Parameters:
Name Type Description
var_args Model[][] models arrays of models to check against the collection
Since:
  • 1.0.0
Throws:
when called on a virtual Collection
Type
Error
Returns:

array of models from the collection not passed in as arguments

Type
Array.<Model>

each(iterator, context) : {undefined}

Iterates over the models in the collection and calls the given iterator function
Parameters:
Name Type Argument Description
iterator function(Model) function to call for each model
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:
Type
undefined

fetch(options) : {Object}

Loads the Collection object from the data service URL. Performs a data "read."

Events:

    request: fired when the request to fetch is going to the server, passing the collection, xhr object, and options
    sync: fired when the collection is fetched from the data service, passing the collection and the raw response
    error: fired if there is an error during the fetch, passing the collection, xhr object, options

Parameters:
Name Type Argument Description
options {success?: (collection: Collection, response: any, options: object)=> void, error?: (collection: Collection, error:any, options: object, xhr?: any, status?: any)=> void, add?: boolean, set?: boolean, startIndex?: number, startID?: any, since?: any, until?: any, fetchSize?: number, [propName: string]: any} <optional>
 Options to control fetch

success: a user callback called when the fetch has completed successfully. This makes the fetch an asynchronous process. The callback is called passing the Collection object, raw response, and the fetch options argument.
error: a user callback function called if the fetch fails. The callback is called passing the Collection, error, fetch options, xhr (if any) and status arguments (if any).
add: if set, new records retrieved from the data service will be added to those models already in the collection. If not set, the records retrieved will be passed to the reset() method, effectively replacing the previous contents of the collection with the new data. Not supported for virtual/paging cases.
set: if true, fetch will try to use the set function to try and merge the fetched models with those already in the collection, on the client. The default behavior is to reset the collection before adding back in the fetched models. This default is the reverse of Backbone's current default.
startIndex: numeric index with which to start fetching Models from the server. The page setting controls the number of Models to be fetched. startID takes precedence over startIndex if both are specified. If both are specified and startID isn't supported then startIndex will be used instead.
startID: unique ID of the Model to start fetching from the server. The page setting controls the number of Models to be fetched. Note if this is not supported by the server then startID will be ignored.
since: fetch records having a timestamp since the given UTC time
until: fetch records having a timestamp up to the given UTC time
fetchSize: use specified page size instead of collection's setting
Since:
  • 1.0.0
Returns:

xhr ajax object, by default. If sync has been replaced, this would be the value returned by the custom implementation.

Type
Object

filter(iterator, context) : {Array.<Model>}

Return an array of models that cause passed-in iterator to return true
Parameters:
Name Type Argument Description
iterator function(Model) function to determine if a model should be included or not. Should return true or false
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual Collection
Type
Error
Returns:

array of models that caused iterator to return true

Type
Array.<Model>

findWhere(attrs, options) : {Model|Promise.<Model>}

A version of where that only returns the first element found
Events: for events, if virtual, see fetch
Parameters:
Name Type Argument Description
attrs Object | Array.<Object> attribute/value pairs to find. See where for more details and examples.
options {deferred?: boolean, [propName: string]: any} <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

first model found with the attribute/value pairs. If virtual or deferred, a promise that resolves with the returned model from the server

Type
Model | Promise.<Model>

first(n, options) : {Array.<Model>|null|Promise}

Return the first model object in the collection, or an array of the first n model objects from the collection.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
n number <optional>
 Number of model objects to include in the array, starting with the first.
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

An array of n model objects found in the collection, starting with the first. If n is not included, returns all of the collection's models as an array. If deferred or virtual, returns a promise that resolves with the array or model

Type
Array.<Model> | null | Promise

get(id, options) : {Model|null|Promise.<Model>}

Return the first model object from the collection whose model id value is the given id or cid, or the id or cid from a passed in model Note this method will not function as expected if the id or cid is not set
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
id Object | string ID, cid, or Model (see Model id or cid) for which to return the model object, if found.
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
fetchSize number <optional>
 fetch size to use if the call needs to fetch more records from the server, if virtualized. Overrides the overall fetchSize setting
Since:
  • 1.0.0
Returns:

First model object in the collection where model.id = id or model.cid = id. If none are found, returns null. If deferred or virtual, return a promise passing the model when done

Type
Model | null | Promise.<Model>

getByCid(clientId) : {Model|null}

Return the first model object from the collection whose client ID is the given model cid
Parameters:
Name Type Description
clientId string Client ID (see Model cid) for which to return the model object, if found.
Since:
  • 1.0.0
Throws:
when called on a virtual Collection if the item isn't found in memory
Type
Error
Returns:

First model object in the collection where model.cid = clientId. If none are found, returns null.

Type
Model | null

groupBy(iterator, context) : {Object}

Return the collection with models grouped into sets determined by the iterator function (or property, if a string value)
Parameters:
Name Type Argument Description
iterator string | function(Model):Object method called or property (if a string) used to get the group key
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

models grouped into sets

Type
Object

include(model, options) : {boolean|Promise.<boolean>}

An alias for contains
Parameters:
Name Type Argument Description
model Object Model object (or Model id) to locate
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

true if the model is contained in the collection, false if not. If deferred, a promise that will resolve with true or false when complete.

Type
boolean | Promise.<boolean>

indexBy(iterator, context) : {Object}

Return an object with models as values for their properties determined by the iterator function or property string
Parameters:
Name Type Argument Description
iterator string | function(Model) method called or property (if a string) used to get the index attribute
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

models listed as property values where the properties are the values returned by iterator or the attribute value given by the iterator string

Type
Object

indexOf(model, options) : {number|Promise.<number>}

Return the array index location of the given model object.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
model Model | string Model object (or Model id) to locate
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

The index of the given model object, or a promise that will resolve with the index when complete. If the object is not found, returns -1.

Type
number | Promise.<number>

initial(n) : {Array.<Model>}

Return an array of models found in the Collection, excepting the last n.
Parameters:
Name Type Argument Description
n number <optional>
 number of models to leave off the returned array; defaults to 1
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

array of models from 0 to the length of the collection - n - 1

Type
Array.<Model>

isEmpty : {boolean}

Determine if the collection has any models
Since:
  • 1.0.0
Returns:

true if collection is empty

Type
boolean

isRangeLocal(start, count) : {boolean}

Determine if every element of the given range is filled in locally
Parameters:
Name Type Description
start number starting index to check
count number number of elements to check
Since:
  • 1.0.0
Returns:

true if all elements are local, false otherwise

Type
boolean

last(n, options) : {Promise.<Model>|Array.<Model>|null}

Return the last model in the collection. If n is passed in, then the last n models are returned as an array Note that if the collection is virtual, and totalResults is not returned by the server, the results returned by last can be difficult to predict. They depend on the fetch sizes, last known offset of a fetch, etc. If code is using a server that does not return totalResults the use of last is not recommended.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
n number <optional>
 number of models to return. Defaults to 1
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

array of n models from the end of the Collection. If this is a virtual collection, this will return a promise which will resolve passing the array or single model

Type
Promise.<Model> | Array.<Model> | null

lastIndexOf(model, fromIndex) : {number}

Returns the index of the last location of the given model. Not supported in virtual cases.
Parameters:
Name Type Argument Description
model Model Model object to locate
fromIndex number <optional>
 optionally start search at the given index
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

The last index of the given model object. If the object is not found, returns -1.

Type
number

listenTo(otherObj, eventType, callback) : {undefined}

Add an event handler for an event type to a second model or collection object ("otherObj"), but track it on the called object.
Parameters:
Name Type Description
otherObj Model | Collection Model or collection object on which to add this event handler.
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
Since:
  • 1.0.0
Returns:
Type
undefined

listenToOnce(otherObj, eventType, callback) : {undefined}

Add an event handler for an event type to a second model or collection object ("otherObj"), but track it on the called object. Only fire once.
Parameters:
Name Type Description
otherObj Model | Collection Model or collection object on which to add this event handler.
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
Since:
  • 1.0.0
Returns:
Type
undefined

map(iterator, context) : {Array.<Object>}

Return an array whose entries are determined by the results of calling the passed iterator function. The iterator will be called for each model in the collection
Parameters:
Name Type Argument Description
iterator function(Model):Object function to determine the mapped value for each model
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual Collection
Type
Error
Returns:

array of values determined by the return value of calls made to iterator for each model

Type
Array.<Object>

max(iterator, context) : {Model}

Return the "maximum" model in the collection, as determined by calls to iterator. The return value of iterator (called with a model passed in) will be compared against the current maximum
Parameters:
Name Type Argument Description
iterator function(Model):Object function to determine a model's value for checking for the maximum
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

"Maximum" model in the collection

Type
Model

min(iterator, context) : {Model}

Return the "minimum" model in the collection, as determined by calls to iterator. The return value of iterator (called with a model passed in) will be compared against the current minimum
Parameters:
Name Type Argument Description
iterator function(Model):Object function to determine a model's value for checking for the minimum
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual Collection
Type
Error
Returns:

"Minimum" model in the collection

Type
Model

modelId(attrs) : {null|string}

Function specifying how to construct the id for models in this collection. Override to change the construction of the id.
Parameters:
Name Type Description
attrs Object attributes of a model
Since:
  • 1.0.0
Returns:
Type
null | string

next(n, options) : {Object|null}

Fetch the next set of models from the server.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
n number number of models to fetch. If undefined or null, the collection will attempt to use the overall [fetchSize]fetchSize property value
options {success?: (collection: Collection, response: any, options: object)=> void, error?: (collection: Collection, xhr: any, options: object)=> void, [propName: string]: any} <optional>
 Options to control next

success: a user callback called when the fetch has completed successfully. This makes the fetch an asynchronous process. The callback is called passing the Collection object, raw response, and the options argument.
error: a user callback function called if the fetch fails. The callback is called passing the collection object, xhr, and options arguments.
Since:
  • 1.0.0
Returns:

xhr ajax object, by default. null if nothing to fetch (the success callback will still be called). Note if sync has been replaced, this would be the value returned by the custom implementation.

Type
Object | null

off(eventType, callback, context) : {undefined}

Remove an event handler for an event type from the model or collection object.
Parameters:
Name Type Argument Description
eventType string | Object <optional>
 Types of event handlers to remove (may be a single event type, a space-delimited set of event types, or a map of events to callbacks). If omitted, remove all event handlers.
callback (context: object, data?: any, data2?: any)=> void <optional>
 If provided, remove handlers only for eventType events with the given callback function.
context Object <optional>
 If provided, remove handlers only for eventType events with the given callback function and context object.
Since:
  • 1.0.0
Returns:
Type
undefined

on(eventType, callback, context) : {undefined}

Add an event handler for an event type to the model or collection object.
Parameters:
Name Type Argument Description
eventType string | Object Types of event handlers to add (may be a single event type, a space-delimited set of event types, or an object mapping events to callbacks).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
context Object <optional>
 A context for the event
Since:
  • 1.0.0
Returns:
Type
undefined

once(eventType, callback, context) : {undefined}

Add an event handler for an event type to the model or collection object, but only fire it once, then remove it from the list of handlers.
Parameters:
Name Type Argument Description
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
context Object <optional>
 A context for the event
Since:
  • 1.0.0
Returns:
Type
undefined

pluck(attr) : {Array.<Object>}

Return a list of all the values of attr found in the collection
Parameters:
Name Type Description
attr string attribute to return
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

array of values of attr

Type
Array.<Object>

pop(options) : {Model|Promise.<Model>}

Remove the last model from the collection and return it
For events that may be fired if the collection is virtual, see remove.
Parameters:
Name Type Argument Description
options {silent?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 Options for the method:

silent: if set, do not fire a remove event
deferred: if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

the model that was removed, or a promise that will resolve with the model that was removed when complete

Type
Model | Promise.<Model>

previous(n, options) : {Object}

Fetch the previous set of models from the server.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
n number number of models to fetch. If undefined or null, the collection will attempt to use the overall fetchSize property value
options {success?: (collection: Collection, response: any, options: object)=> void, error?: (collection: Collection, xhr: any, options: object)=> void, [propName: string]: any} <optional>
 Options to control previous

success: a user callback called when the fetch has completed successfully. This makes the fetch an asynchronous process. The callback is called passing the Collection object, raw response, and the options argument.

error: a user callback function called if the fetch fails. The callback is called passing the collection object, xhr, and options arguments.
Since:
  • 1.0.0
Returns:

xhr ajax object, by default. null if there is nothing earlier to fetch (no fetch has happened or the last fetch started at 0). The success callback will still be called. Note if sync has been replaced, this would be the value returned by the custom implementation.

Type
Object

push(m, options) : {(Promise.<Array.<Model>>|undefined)}

Add the given model to the end of the Collection
For events that may be fired if the collection is virtual, see add.
Parameters:
Name Type Argument Description
m Model | Object model to add to the end of the Collection (or a set of attribute value pairs)
options {silent?: boolean, at?: number, merge?: boolean, sort?: boolean, force?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 same options as add
Since:
  • 1.0.0
Returns:

if deferred or virtual, a promise that will be resolved when the function is done. Otherwise undefined

Type
(Promise.<Array.<Model>>|undefined)

refresh(options) : {Promise.<(Collection.SetRangeLocalPromise|undefined)>}

Clear all data from the collection and refetch (if non-virtual). If virtual, clear all data. If fetch() cannot be called (e.g., there is no URL) then the caller must reload the collection wtih data. The existing data is still cleared. Events (if silent is not set):

    refresh: fired passing the collection and options
    For more events that may be fired if the collection is not virtual, see fetch.

Parameters:
Name Type Argument Description
options {silent?: boolean, startIndex?: number, [propName: string]: any} <optional>
 user options

silent: if set, do not fire a refresh event

startIndex: if provided, and if collection is virtual, do a fetch of startIndex+fetchSize immediately after the refresh and return a promise. See [comparator}Collection#setRangeLocal
Since:
  • 1.0.0
Returns:

promise object resolved when complete (in case there is a fetch for non-virtual mode). If startIndex is provided as an option, the returned promise resolution is the same as setRangeLocal.

Type
Promise.<(Collection.SetRangeLocalPromise|undefined)>

remove(m, options) : {Array.<Model>|Model}

Remove a model from the collection, if found.
Events:

    remove: fired for each model removed, passing the model removed, collection, and options
    allremoved: fired after all models have been removed, passing the collection, array of models removed, and options

Parameters:
Name Type Argument Description
m Model | Array.<Model> model object or array of models to remove.
options Object <optional>
Properties:
Name Type Argument Description
silent boolean <optional>
 if set, do not fire events
Since:
  • 1.0.0
Returns:

an array of models or single model removed

Type
Array.<Model> | Model

reset(data, options) : {Model|Array.<Model>}

Remove and replace the collection's entire list of models with a new set of models, if provided. Otherwise, empty the collection. totalResults is reset when no new data is passed in, set to the new length in the non-virtual case if data is passed in, and left as was in the virtual case if data is passed in.
Events (if silent is not set):

    reset: fired passing the collection and options. The new length of the collection should be in effect when the event is fired
    For events that may be fired if data is passed in, see add.

Parameters:
Name Type Argument Description
data Object <optional>
 Array of model objects or attribute/value pair objects with which to replace the collection's data.
options {silent?: boolean, [propName: string]: any} <optional>
 user options, passed to event, unless silent
silent: if set, do not fire events
Since:
  • 1.0.0
Returns:

The model or models added to the collection, if passed in

Type
Model | Array.<Model>

rest(n, options) : {Array.<Model>|Promise}

Return the array of models found in the Collection starting with index n.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
n number <optional>
 index at which to start the returned array of models. Defaults to 1.
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

array of models from the collection. If this is a virtual collection, or if deferred is passed as true, return a promise which resolves passing the array of models.

Type
Array.<Model> | Promise

set(models, options) : {Promise|null}

Update the collection with a model or models. Depending on the options, new models will be added, existing models will be merged, and unspecified models will be removed. The model cid is used to determine whether a given model exists or not.
May fire events as specified by add or remove, depending on the options.
Parameters:
Name Type Argument Description
models Object an array of or single model with which to update the collection. If models contains actual Model objects, then any custom 'parse' function set on the collection needs to take that into account and be prepared to handle an array of Model.
options {add?: boolean, remove?: boolean, merge?: boolean, silent?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 add:false stops the addition of new models
remove: false stops the removal of missing models
merge: false prevents the merging of existing models
silent: true prevents notifications on adds, removes, etc.
deferred: if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

if deferred or virtual, return a promise that resolves when the set has completed

Type
Promise | null

setFetchSize(n) : {undefined}

Set or change the number of models to fetch with each server request
Parameters:
Name Type Description
n number number of models to fetch with each request
Since:
  • 1.0.0
Returns:
Type
undefined

setModelLimit(n) : {undefined}

Set or change the number of models held at any one time
Parameters:
Name Type Description
n number maximum number of models to keep at a time
Since:
  • 1.0.0
Returns:
Type
undefined

setRangeLocal(start, count, options) : {Promise.<Collection.SetRangeLocalPromise>}

Tell the collection to try and ensure that the given range is available locally. Note that if the collection is virtual, setRangeLocal may make repeated fetch calls to the server to satisfy the request, stopping only when the range has been made local or the end of the records on the server is reached.
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
start number starting index to make local
count number number of elements to make local
options {silent?: boolean} <optional>
 Options to control whether events are fired by this call (silent: true)
Since:
  • 1.0.0
Returns:

a promise Object that resolves upon completion. The promise will be passed an Object containing start and count properties that represent the *actual* starting position (start), count (count), and array (models) of the Models fetched, which may be fewer than what was requested. The promise will be rejected on an error and will pass the ajax status, xhr object, error, and collection, if relevant.

Type
Promise.<Collection.SetRangeLocalPromise>

shift(options) : {Model|Promise.<Model>|null}

Remove the first model from the collection and return it.
For events that may be fired, see remove.
Parameters:
Name Type Argument Description
options Object <optional>
 same as remove
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
silent boolean <optional>
 if set, do not fire events
Since:
  • 1.0.0
Returns:

model that was removed. If this is a virtual collection, this will return a promise which will resolve passing the model value that was removed

Type
Model | Promise.<Model> | null

size : {number}

Return the length of the collection
Since:
  • 1.0.0
Returns:

length of the collection

Type
number

slice(start, end, options) : {(Promise.<Array.<Model>>|Array.<Model>)}

Return a shallow copy of the models from start to end (if specified), in an array
For events that may be fired if the collection is virtual, see fetch.
Parameters:
Name Type Argument Description
start number model to start the return array with
end number <optional>
 model to end the return array with, if specified (not inclusive). If not, returns to the end of the collection
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

array of model objects from start to end, or a promise that resolves specifying the returned array when done

Type
(Promise.<Array.<Model>>|Array.<Model>)

sort(options) : {(Promise.<Collection.SetRangeLocalPromise>|null)}

Sort the models in the collection. For virtual collections, any locally stored models are cleaned out in preparation for new fetches sending server-sorted models down to the client. No fetch is automatically performed.

For non-virtual collections, the models are sorted based on the comparator property.

See [comparator}Collection#comparator

For virtual collections, all sorting must be handled by the server. If the string (attribute) comparator and sortDirection are set, then this information will be passed back via URL parameters, or passed to the customURL callback for application-construction of the appropriate URL. Function-based custom comparators are ignored in virtual collections. Events:

Fires a sort event, passing the collection and options

Parameters:
Name Type Argument Description
options {silent?: boolean, startIndex?: number, [propName: string]: any} <optional>
 silent: if true, do not fire the sort event
startIndex: if provided, and if collection is virtual, do a fetch of startIndex+fetchSize immediately after the sort and return a promise. See [comparator}Collection#setRangeLocal
Since:
  • 1.0.0
Returns:

if virtual and if startIndex is provided in options, a promise Object that resolves upon completion. The promise will be passed an Object containing start and count properties that represent the *actual* starting position (start), count (count), and array (models) of the Models fetched, which may be fewer than what was requested. The promise will be rejected on an error and will pass the ajax status, xhr object, error, and collection, if relevant.

Type
(Promise.<Collection.SetRangeLocalPromise>|null)

sortBy(iterator, context) : {Array.<Model>}

Return the models sorted determined by the iterator function (or property, if a string value). If a function, the function should return the attribute by which to sort.
Parameters:
Name Type Argument Description
iterator string | function(Model):string method called or property used to get the attribute to sort by.
context Object <optional>
 context with which to make the calls on iterator
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

models sorted using iterator

Type
Array.<Model>

sortedIndex(comparator) : {number}

Return the index at which the given model would be inserted, using the collection comparator See [sort}Collection#sort. Not supported for virtual collections.
Parameters:
Name Type Description
comparator string | function(Model,Model=):Object optional comparator to override the default
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

index at which model would be inserted. -1 if no comparator

Type
number

stopListening(otherObj, eventType, callback) : {undefined}

Remove event handlers from a model or collection object. If the arguments are omitted, removes all event handlers from the model or collection.
Parameters:
Name Type Argument Description
otherObj Model | Collection If specified, remove event handlers that target otherObj from this model or collection.
eventType string <optional>
 If specified, remove the event handlers for the given event types from this model or collection
callback (context: Object, data?: any, data2?: any)=> void <optional>
 If specified, remove event handlers that call the given user callback function from this model or collection
Since:
  • 1.0.0
Returns:
Type
undefined

sync(method, collection, options) : {Object}

Called to perfrom server interactions, such as reading the collection. Designed to be overridden by users.
Parameters:
Name Type Argument Description
method string "read"
collection Collection the collection to be read (fetched)
options {success?: (response?: any)=> void, error?: (xhr: any, status: any, error: any)=> void, [propName: string]: any} <optional>
 to control sync
success: called if sync succeeds. Called with the data being fetched
error: called if sync fails. Called with xhr, status, and error info, per jQuery Ajax (all if available)
Since:
  • 1.0.0
Returns:

xhr response from ajax by default

Type
Object

toJSON : {Array.<Object>}

Return a copy of the Collection's list of current attribute/value pairs.
Since:
  • 1.0.0
Throws:
when called on a virtual collection
Type
Error
Returns:

an array containing all the Collection's current sets of attribute/value pairs.

Type
Array.<Object>

trigger(eventType) : {undefined}

Fire the given event type(s) for all registered handlers.
Parameters:
Name Type Description
eventType string Types of event handlers to fire (may be a single event type or a space-delimited set of event types).
Since:
  • 1.0.0
Returns:
Type
undefined

unshift(m, options) : {(Promise.<Array.<Model>>|Array.<Model>)}

Add the given model to the front of the collection
For events that may be fired, see add.
Parameters:
Name Type Argument Description
m Model | Object model (or set of attribute/value pairs) to add to the beginning of the collection
options {silent?: boolean, at?: number, merge?: boolean, sort?: boolean, force?: boolean, deferred?: boolean, [propName: string]: any} <optional>
 See add
Since:
  • 1.0.0
Returns:

The model or models added to the collection. If deferred or virtual, return the model or models added in a promise when the set has completed

Type
(Promise.<Array.<Model>>|Array.<Model>)

whenReady : {Promise}

Return a promise, the resolution of which indicates that all promise-returning API in process have completed.
Since:
  • 1.0.0
Returns:

a promise that when resolved, indicates that all unresolved promise-returning API calls made at the moment of the whenReady have completed

Type
Promise

where(attrs, options) : {(Promise.<Array.<Model>>|Array.<Model>)}

Return an array of models that contain the given attribute/value pairs. Note that this function, along with findWhere, expects server-resolved filtering to return *all* models that meet the criteria, even in virtual cases. The fetchSize will be set to the value of totalResults for this call to indicate that all should be returned.
Events: for events, if virtual, see fetch
Parameters:
Name Type Argument Description
attrs Object | Array.<Object> attribute/value pairs to find. The attribute/value pairs are ANDed together. If attrs is an array of attribute/value pairs, then these are ORed together If the value is an object (or an array of objects, in which case the single attribute must meet all of the value/comparator conditions), then if it has both 'value' and 'comparator' parameters these will be interpreted as expressions needing custom commparisons. The comparator value may either be a string or a comparator callback function. Strings are only valid where the filtering is sent back to the data service (virtual collections). In the case of a comparator function, the function always takes the signature function(model, attr, value), and for non-virtual collections, is called for each Model in the collection with the associated attribute and value. The function should return true if the model meets the attribute/value condition, and false if not. For cases where the filtering is to be done on the server, the function will be called once per attr/value pair with a null model, and the function should return the string to pass as the comparison in the expression for the filtering parameter in the URL sent back to the server. Note that the array of value object case is really only meaningful for server-evaluated filters where a complex construction on a single attribute might be needed (e.g., x>v1 && x <=v2) for example:

{Dept:53,Name:'Smith'}
will return an array of models that have a Dept=53 and a Name=Smith, or, for server-filtered collections, a ?q=Dept=53+Name=Smith parameter will be sent with the URL.

[{Dept:53},{Dept:90}]
will return all models that have a Dept of 53 or 90. Or, ?q=Dept=53,Dept=90 will be sent to the server.

{Dept:{value:53,comparator:function(model, attr, value) { return model.get(attr) !== value;}}}
will return all models that do not have a Dept of 53.

{Dept:{value:53,comparator:'<>'}}
For server-evaluated filters, a parameter ?q=Dept<>53 will be sent with the URL. This form is an error on locally-evaluated colleection filters

{Dept:{value:53,comparator:function(model, attr, value) { return "<>";}}}
expresses the same thing for server-evaluated filters

{Dept:[{value:53,comparator:'<'},{value:90,comparator:'<'}]}
For server-evaluated filters, a parameter ?q=Dept>53+Dept<93 will be sent to the server
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

array of models. If virtual or deferred, a promise that resolves with the returned array from the server

Type
(Promise.<Array.<Model>>|Array.<Model>)

whereToCollection(attrs, options) : {Collection|Promise.<Collection>}

Return a collection of models that contain the given attribute/value pairs. Note that this returns a non-virtual collection with all the models returned by the server, even if the original collection is virtual. Virtual collections doing filtering on the server should return all models that meet the critera. See where See where for complete documentation of events and parameters
Parameters:
Name Type Argument Description
attrs Object | Array.<Object> attribute/value pairs to find. The attribute/value pairs are ANDed together. If
options Object <optional>
Properties:
Name Type Argument Description
deferred boolean <optional>
 if true, return a promise as though this collection were virtual whether it is or not
Since:
  • 1.0.0
Returns:

A collection containing models with given attribute/value pairs. If virtual or deferred, a promise that resolves with the collection returned by the server

Type
Collection | Promise.<Collection>

without(var_args) : {Array.<Model>}

Return an array of models minus those passed in as arguments
Parameters:
Name Type Description
var_args Model models models to remove from the returned array
Since:
  • 1.0.0
Throws:
when called on a virtual Collection
Type
Error
Returns:

array of models from the collection minus those passed in to models

Type
Array.<Model>

Type Definitions

CustomPagingOptionsReturn

Properties:
Name Type Argument
count number <optional>
hasMore boolean <optional>
limit number <optional>
offset number <optional>
totalResults number <optional>

CustomURLCallbackOptions

Properties:
Name Type Argument Description
all boolean <optional>
 true (along with 'query', above) indicates that this is a findWhere or where type call that is expecting all models meeting the query condition to be returned
fetchSize number <optional>
 how many records to return. If not set, return all
query Object <optional>
 a set of attributes indicating filtering that should be done on the server. See where for complete documentation of query values
recordID string <optional>
 id of the record involved, if relevant
since string <optional>
 Retrieve records with timestamps after the given timestamp
sort string <optional>
 field(s) by which to sort, if set
sortDir string <optional>
 sort ascending or descending (asc/dsc)
startID string <optional>
 Retrieve records starting with the record with the given unique ID
startIndex number <optional>
 Starting record number of the set to return
until string <optional>
 Retrieve records with timestamps up to the given timestamp. Default is "until"

SetRangeLocalPromise

Properties:
Name Type Description
count number number of models fetched
models Model[] array of models fetched
start number starting index of fetched models