Class: Collection

Oracle® Fusion Middleware Oracle JavaScript Extension Toolkit (JET)
12c (12.1.4)

E54107-01

QuickNav

oj. Collection

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
options Object <optional>
Passed through to the user's initialize routine, if any, upon construction
Source:

Mixes In

Fields

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

If set, sort the collection using the given attribute of a model (if string); function(Model) returning a string attribute by which the sort should take place; function(Model1, Model2) if a user-defined function comparing Model1 and Model2 (see the JavaScript array.sort() for details)
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/paging is not being used or is not available, and all records will be fetched. and 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, beyond the latest fetch.
Source:

lastFetchCount :number

The number of records actually fetched the last time the collection went to the server. This may or may not match fetchSize or limit
Source:

lastFetchSize :number

The number of records brought back on the last fetch.
Source:

length :number

Total number of models in the collection (note that when the collection is virtual, not all may be available or currently fetched)
Source:

model :Object

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

modelLimit :number

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.
Note that this property should not be used directly when a collection is paging (virtual).
Automatic fetches will not be triggered for undefined elements in the model. Use at() instead.
Source:

offset :number

The actual starting record number of the last fetch from the server.
Source:

sortDirection :number

Sort direction for string-based field comparators. A value of 1 (the default), indicates ascending sorts, -1 indicates descending
Source:

sortSupported :boolean

Set to true if sort is supported. This will only be false if the collection is connected to a paging REST service that does not support sorting
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 URL on the server.
Source:

Methods

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

Create a new, specific type of Collection object to represent a collection of records from a JSON data set.
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

model: the specific type of Model object to use for each member of the Collection

url: the URL to use to get the record collection from the data service

initialize: a user callback function to be called when this collection is created

comparator: a user callback used on sort calls. May also be set to false to prevent sorting.

fetchSize: the number of records to be fetched on each round trip to the server. If not set, none of the paging/virtualization API will be invoked

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.

Source:
Returns:
new Collection object
Type
function(new:Object, ...)

['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 Object the Collection to be read
options Object <optional>
to control sync success: called if sync succeeds error: called if sync fails others are passed to jQuery
Source:
Returns:
xhr response
Type
Object

add(m, options) → {Object}

Add an instance of this collection's model(s) to the end of the collection. 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.
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 an add event

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.

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 when the set has completed
Type
Object

any(iterator, context) → {boolean}

Parameters:
Name Type Argument Description
iterator function(Object) function to determine if a model 'passes'
context Object <optional>
context with which to make the calls on iterator
Source:
Throws:
when called on a virtual/paging Collection
Type
Error
Returns:
true if any of the models cause the iterator function to return true
Type
boolean

at(index, options) → {Object}

Return the model object found at the given index of the collection, or a promise object that will return the model to a function in the done() call.
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 return value will be determined by whether or not the collection is virtual

Source:
Returns:
Model object located at index. If index is out of range, returns null. If this is a paging/virtual collection or if deferred is specified and true, at will return a jQuery promise object which will call its done function, passing the value at(index)
Type
Object

clone() → {Object}

Source:
Returns:
copy of the Collection
Type
Object

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

Creates a new model, saves it to the data service, and adds it on to the collection.
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 oj.Model.save). 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 calls with the new model
Type
Object | boolean

customPagingOptions(response) → {function(Object):(Object|null)|null}

A callback allowing users to extract their own paging/virtualization return values from their response The callback is made with the raw data response to the collection fetch
Parameters:
Name Type Description
response Object the raw data response coming back from the fetch
Source:
Returns:
customPagingOptions callbacks should return either null, in which case the Collection will look for the simple default properties, or an object containing the 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 returned in this object):

totalResults: the total number of records available on the server side, not just in the current result. Default is "totalResults"

limit: the actual fetchSize used by the server in generating the result. This may not be the client's fetchSize or the number of records in the current result. Default is "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"

offset: the actual starting record number of the current result. Default is "offset"

hasMore: boolean indicating whether or not there are more records available beyond the current result. Default is "hasMore"

Type
function(Object):(Object | null) | null

customURL(operation, collection, options) → {(function(string,Object,Object):(string|Object|null))|null}

A callback to allow users to completely customize the data service URLs
Parameters:
Name Type Description
operation String one of create, read, update, patch, or delete indicating the type of operation for which to return the URL

collection Object the oj.Collection object requesting the URL

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

fromID: 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 (@link 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

Source:
Returns:
customURL callbacks should return either: null, in which case the default will be used; a string, which will be used with the standard HTTP method for the type of operation, or an Object with any ajax attributes. This must at minimum include the URL:

url: giving the custom URL string

type: (optional) a string indicating the type of HTTP method to use (GET, POST, DELETE, etc.)

(other): (optional) any other ajax attributes to pass in the ajax call

Type
(function(string,Object,Object):(string | Object | null)) | null

each(iterator, context)

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/paging Collection
Type
Error

fetch(options) → {Object}

Loads the Collection object from the data service URL. Performs a data "read."
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.

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

filter(iterator, context) → {Array}

Parameters:
Name Type Argument Description
iterator function(Object) function to determine if a model should be included or not
context Object <optional>
context with which to make the calls on iterator
Source:
Throws:
when called on a virtual/paging Collection
Type
Error
Returns:
array of models that cause iterator to return true
Type
Array

findWhere(attrs, options) → {Object}

Parameters:
Name Type Argument Description
attrs Object | Array attribute/value pairs to find.
options Object <optional>
deferred: if true, return a promise as though this collection were virtual whether it is or not

Source:
See:
  • (@link where) for more details and examples.
Returns:
first model found with the attribute/value pairs. If virtual or deferred, a promise that calls with the returned array from the server
Type
Object

first(n, options) → {Array|null}

Return the first model object in the collection, or an array of the first n model objects from the collection.
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. Returns a promise that returns the array or model if deferred or virtual
Type
Array | null

get(id, options) → {Object}

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

getByCid(clientId) → {Object}

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/paging 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

groupBy(iterator, context) → {Object}

Parameters:
Name Type Argument Description
iterator String | function(Object) method called or property 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/paging Collection
Type
Error
Returns:
models grouped into sets
Type
Object

indexOf(model, options) → {number}

Return the array index location of the given model object.
Parameters:
Name Type Argument Description
model Object Model object 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 call with the index when complete. If the object is not found, returns -1.
Type
number

initial(n) → {Object}

Parameters:
Name Type Argument Description
n number <optional>
number of models to leave off the returned array; defaults to 1
Source:
Returns:
array of models from 0 to the length of the collection - n - 1
Type
Object

isEmpty() → {boolean}

Source:
Returns:
true if collection is empty
Type
boolean

isRangeLocal(start, count) → {boolean}

Parameters:
Name Type Description
start number starting index to make local
count number number of elements to make local
Source:
Returns:
true if all elements are local, false otherwise
Type
boolean

last(n, options) → {Object|Array|null}

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 paging/virtual collection, this will return a jQuery promise which will call its done function, passing the array or single model
Type
Object | Array | null

lastIndexOf(model, fromIndex) → {number}

Parameters:
Name Type Argument Description
model Object Model object to locate
fromIndex number <optional>
optionally start search at the given index
Source:
Returns:
The last index of the given model object. If the object is not found, returns -1.
Type
number

map(iterator, context) → {Array}

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/paging Collection
Type
Error
Returns:
array of values determined by calls to iterator for each model
Type
Array

max(iterator, context) → {Object}

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/paging Collection
Type
Error
Returns:
"Maximum" model in the collection
Type
Object

min(iterator, context) → {Object}

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/paging Collection
Type
Error
Returns:
"Minimum" model in the collection
Type
Object

next(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 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 object; null if nothing to fetch (the success callback will still be called)
Type
Object

pluck(attr) → {Object}

Parameters:
Name Type Description
attr string attribute to return
Source:
Throws:
when called on a virtual/paging Collection
Type
Error
Returns:
array of values of attr
Type
Object

pop(options) → {Object}

Parameters:
Name Type Argument Description
options Object <optional>
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 call with the model that was removed when complete
Type
Object

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 object, or 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
Type
Object

push(m, options) → {Object}

Parameters:
Name Type Argument Description
m Object model to add to the end of the Collection
options Object <optional>
same options as add

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

Source:
Returns:
if deferred or virtual, a promise that will be called when the function is done. Otherwise undefined
Type
Object

refresh(options) → {Object}

Clear all data from the collection and refetch (if non-virtual). If virtual, clear all data. In both cases, fire a refresh event if silent is not set
Parameters:
Name Type Argument Description
options Object <optional>
user options

silent: if set, do not fire a refresh event

Source:
Returns:
promise object triggering done when complete (in case there is a fetch for non-virtual mode)
Type
Object

remove(m, options)

Remove a model from the collection, if found.
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 a remove event
Source:

reset(data, options)

Remove and replace the collection's entire list of models with a new set of models, if provided. Otherwise, empty the collection.
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 an add event

Source:

rest(n, options) → {Object}

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

set(models, options) → {Object|null}

Parameters:
Name Type Argument Description
models Object an array of or single model with which to update the Collection
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 when the set has completed
Type
Object | 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)

Parameters:
Name Type Description
n number maximum number of models to keep at a time
Source:

setRangeLocal(start, count) → {Object}

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 calls done upon completion
Type
Object

shift(options) → {Object}

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 paging/virtual collection, this will return a jQuery promise which will call its done function, passing the model value that was removed
Type
Object

size() → {number}

Source:
Returns:
length of the collection
Type
number

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

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 calls specifying the returned array when done
Type
Array

sort(options)

Parameters:
Name Type Argument Description
options Object <optional>
silent: if true, do not fire the sort event
Source:

sortBy(iterator, context) → {Object}

Parameters:
Name Type Argument Description
iterator String | function(Object) method called or property used to get the sorting value
context Object <optional>
context with which to make the calls on iterator
Source:
Returns:
models sorted using iterator
Type
Object

sortedIndex(model) → {number}

Parameters:
Name Type Description
model Object model for which to determine the insert point
Source:
Returns:
index at which model would be inserted. -1 if no comparator
Type
number

toJSON() → {Object}

Return a copy of the Collection's list of current attribute/value pairs.
Source:
Throws:
when called on a virtual/paging Collection
Type
Error
Returns:
a copy of all the Collection's current sets of attribute/value pairs.
Type
Object

unshift(m, options) → {Object}

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 paging/virtual collection, this will return a jQuery promise that will be called when the operation is done. Otherwise undefined
Type
Object

where(attrs, options) → {Object}

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 calls with the returned array from the server
Type
Object

whereToCollection() → {Object}

Source:
See:
  • (@link where) for complete documentation of the parameters
Returns:
A collection, or if virtual or deferred, a promise that calls with the Collection
Type
Object

without(var_args) → {Array}

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