Class: Collection

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Fields

oj. Collection

Version:
  • 3.2.0
Collection of Model objects

Constructor

new Collection(models, options)

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

Mixes In

Fields

changes :Array

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
Source:

comparator :String|function(Object)|function(Object,Object)

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.

Source:

customPagingOptions :function(Object):(Object|null)|null

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

It should accept these parameters:

response: the 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"

Source:

customURL :function(string,Object,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 oj.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

Source:

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.
The number of records actually fetched comes back as count
Source:

hasMore :boolean

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

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
Source:

lastFetchSize :number

The server's fetch size. This may not match fetchSize.
Source:

length :number

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

model :Object

Property specifying the model class object used by the collection
Source:

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
Source:

models :Array

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.
Source:

offset :number

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

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.
Source:

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.
Source:

url :String

The data service's server URL.
Source:

Methods

<static> extend(properties, classProperties) → {function(new:Object, ...)}

Create a new, specific type of Collection object to represent a collection of records from a JSON data set.
This:
  • {oj.Collection}
Parameters:
Name Type Argument Description
properties Object <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 oj.Models or collection.set is used with actual oj.Models, the parse callback must expect that the argument passed to it may contain raw JSON data *or* oj.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 with collection, 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 [fetchSize]{oj.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
Source:
Returns:
new Collection object
Type
function(new:Object, ...)

abort() → {Promise}

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
Source:
Returns:
a promise that when resolved, indicates that all the open xhr objects generated by this collection have aborted
Type
Promise

add(m, options) → {Promise|Array}

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 Object | Array Model object (or array of models) to add. These can be already-created instance of the oj.Model object, or sets of attribute/values, which will be wrapped by add() using the collection's model.
options Object <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
Source:
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

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
Source:
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) → {Object|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 Object <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
Source:
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
Object | null

clone() → {Object}

Return a copy of the Collection
Source:
Returns:
copy of the Collection
Type
Object

contains(model, options) → {boolean|Promise}

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>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
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

create(attributes, options) → {Object|boolean|Promise}

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 Object <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

Source:
Returns:
new model or false if validation failed. If virtual, returns a promise that resolves with the new model
Type
Object | boolean | Promise

difference(var_args) → {Array}

Return an array of models in the collection but not passed in the array arguments
Parameters:
Name Type Description
var_args Array models arrays of models to check against the collection
Source:
Throws:
when called on a virtual Collection
Type
Error
Returns:
array of models from the collection not passed in as arguments
Type
Array

each(iterator, context)

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

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 Object <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 object, xhr, and options arguments.
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

Source:
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}

Return an array of models that cause passed-in iterator to return true
Parameters:
Name Type Argument Description
iterator function(Object) 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
Source:
Throws:
when called on a virtual Collection
Type
Error
Returns:
array of models that caused iterator to return true
Type
Array

findWhere(attrs, options) → {Object|Promise}

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 attribute/value pairs to find. See where for more details and examples.
options Object <optional>
deferred: if true, return a promise as though this collection were virtual whether it is or not

Source:
Returns:
first model found with the attribute/value pairs. If virtual or deferred, a promise that resolves with the returned array from the server
Type
Object | Promise

first(n, options) → {Array|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>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
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 | null | Promise

get(id, options) → {Object|null|Promise}

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>

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 promise as though this collection were virtual whether it is or not

Source:
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
Object | null | Promise

getByCid(clientId) → {Object|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.
Source:
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
Object | 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(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
Source:
Throws:
when called on a virtual collection
Type
Error
Returns:
models grouped into sets
Type
Object

include()

An alias for contains
Source:

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(Object) 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
Source:
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}

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 Object Model object (or Model id) to locate
options Object <optional>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
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

initial(n) → {Array}

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
Source:
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

isEmpty() → {boolean}

Determine if the collection has any models
Source:
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
Source:
Returns:
true if all elements are local, false otherwise
Type
boolean

last(n, options) → {Promise|Object|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>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
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 | Object | 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 Object Model object to locate
fromIndex number <optional>
optionally start search at the given index
Source:
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

map(iterator, context) → {Array}

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(Object) function to determine the mapped value for each model
context Object <optional>
context with which to make the calls on iterator
Source:
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

max(iterator, context) → {Object}

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(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
Source:
Throws:
when called on a virtual collection
Type
Error
Returns:
"Maximum" model in the collection
Type
Object

min(iterator, context) → {Object}

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(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
Source:
Throws:
when called on a virtual Collection
Type
Error
Returns:
"Minimum" model in the collection
Type
Object

modelId()

Function specifying how to construct the id for models in this collection. Override to change the construction of the id.
Source:

next(n, options) → {Object}

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 property value
options Object <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.

Source:
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

pluck(attr) → {Array}

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

pop(options) → {Object|Promise}

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 Object <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

Source:
Returns:
the model that was removed, or a promise that will resolve with the model that was removed when complete
Type
Object | Promise

previous(n, options) → {Object}

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 Object <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.

Source:
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}

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 Object model to add to the end of the Collection
options Object <optional>
same options as add
Source:
Returns:
if deferred or virtual, a promise that will be resolved when the function is done. Otherwise undefined
Type
Promise

refresh(options) → {Promise}

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 Object <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}oj.Collection#setRangeLocal

Source:
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

remove(m, options) → {Array|Object}

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 Object | Array model object or array of models to remove.
options Object <optional>
silent: if set, do not fire events
Source:
Returns:
an array of models or single model removed
Type
Array | Object

reset(data, options) → {Object|Array}

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 Object <optional>
user options, passed to event, unless silent
silent: if set, do not fire events

Source:
Returns:
The model or models added to the collection, if passed in
Type
Object | Array

rest(n, options) → {Array|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>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
Returns:
array of models from the collection. If this is a virtual collection, or if deferred is passed as true, return a promise which resovles passing the array of models.
Type
Array | 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 oj.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 oj.Model.
options Object <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
Source:
Returns:
if deferred or virtual, return a promise that resolves when the set has completed
Type
Promise | null

setFetchSize(n)

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
Source:

setModelLimit(n)

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
Source:

setRangeLocal(start, count) → {Promise}

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 Description
start number starting index to make local
count number number of elements to make local
Source:
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

shift(options) → {Promise}

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, plus:
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
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
Promise

size() → {number}

Return the length of the collection
Source:
Returns:
length of the collection
Type
number

slice(start, end, options) → {Array|Promise}

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>
deferred: if true, return a promise as though this collection were virtual whether it is or not
Source:
Returns:
array of model objects from start to end, or a promise that resolves specifying the returned array when done
Type
Array | Promise

sort(options) → {Promise|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}oj.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 Object <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}oj.Collection#setRangeLocal

Source:
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 | null

sortBy(iterator, context) → {Object}

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(Object) method called or property used to get the attribute to sort by.
context Object <optional>
context with which to make the calls on iterator
Source:
Throws:
when called on a virtual collection
Type
Error
Returns:
models sorted using iterator
Type
Object

sortedIndex(model, comparator) → {number}

Return the index at which the given model would be inserted, using the collection comparator See [sort}oj.Collection#sort. Not supported for virtual collections.
Parameters:
Name Type Argument Description
model Object model for which to determine the insert point
comparator String | Object <optional>
optional comparator to override the default
Source:
Throws:
when called on a virtual collection
Type
Error
Returns:
index at which model would be inserted. -1 if no comparator
Type
number

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

Parameters:
Name Type Argument Description
method string "read"
collection Object the collection to be read (fetched)
options Object <optional>
to control sync
success: called if sync succeeds. Called with the array of JSON data being fetched
error: called if sync fails. Called with xhr, status, and error info, per jQuery Ajax (all if available)
Source:
Returns:
xhr response from ajax by default
Type
Object

toJSON() → {Array|Promise}

Return a copy of the Collection's list of current attribute/value pairs.
Source:
Returns:
an array containing all the Collection's current sets of attribute/value pairs. If virtual, a promise that will resolve with that array
Type
Array | Promise

unshift(m, options) → {Promise}

Add the given model to the front of the collection
For events that may be fired, see add.
Parameters:
Name Type Argument Description
m Object model to add to the beginning of the collection
options Object <optional>
See add
Source:
Returns:
If this is a virtual collection, this will return a promise that will be resolved when the operation is done. Otherwise undefined
Type
Promise

whenReady() → {Promise}

Return a promise, the resolution of which indicates that all promise-returning API in process have completed.
Source:
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) → {Array|Promise}

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 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>
deferred: if true, return a promise as though this collection were virtual whether it is or not

Source:
Returns:
array of models. If virtual or deferred, a promise that resolves with the returned array from the server
Type
Array | Promise

whereToCollection() → {Object|Promise}

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
Source:
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
Object | Promise

without(var_args) → {Array}

Return an array of models minus those passed in as arguments
Parameters:
Name Type Description
var_args Object models models to remove from the returned array
Source:
Throws:
when called on a virtual Collection
Type
Error
Returns:
array of models from the collection minus those passed in to models
Type
Array