Sidecar API Reference Class: Data/BeanCollection

new Data/BeanCollection()

Base bean collection class. It extends Backbone.Collection.

A bean collection is a collection of beans. To instantiate a bean collection, you need to use Data/DataManager#createBeanCollection.

Example of usage:

The following snippet will create a collection of bean which belongs to the module 'Accounts':

const DataManager = require('data/data-manager');
let accounts = DataManager.createBeanCollection('Accounts');
accounts.add({name: 'account1', industry: 'Banking'});

Filtering and searching

The collection's Data/BeanCollection#fetch method supports filter and search options. For example, to search favorite accounts that have the string "Acme" in their name:

const DataManager = require('data/data-manager');
let accounts = DataManager.createBeanCollection('Accounts');
accounts.fetch({
    favorites: true,
    query: "Acme"
});

Members

<readonly> favorites :boolean

Flag indicating if a collection contains current user's favorite items.

Type:

boolean

fields :Array

Field names.

A list of fields that are populated on collection members. This property is used to build the fields URL parameter when fetching beans.

Type:

Array

filterDef :Array

Filter definition to filter the collection by.

Type:

Array

link

Link information.

{
    name: link name,
    bean: reference to the related bean
}

link :Object

Reference to a relationship.

Type:

Object

<readonly> model :Data/Bean

The default model of a bean collection is a Data/Bean.

Type:

Data/Bean

<readonly> module :string

The module name.

Type:

string

<readonly> myItems :boolean

Flag indicating if a collection contains items assigned to the current user.

Type:

boolean

<readonly> offset :number

Current collection offset for pagination.

Type:

number

<readonly> query :string

Search query.

Type:

string

<readonly> total :number

Readonly property for the total records in server.

Use Data/BeanCollection#fetchTotal to get the current total.

Type:

number

Methods

<protected> _decrementTotal()

Decrements the collection total.

abortFetchRequest()

Aborts the currently active fetch request.

add(models, options)

Keeps track of the added models.

Parameters:

Name	Type	Description
`models`	Object \| Array.<Object> \| Data/Bean \| Array.<Data/Bean>	The models to add.
`options`	Object	A hash of options.

Returns:

The added models.

Type: Data/Bean | Array.<Data/Bean>

clone()

Clones the collection including the Data/BeanCollection#link and all the persistent options.

Returns:

The new collection with an identical list of models as this one.

Type: Data/BeanCollection

constructor(models [, options])

Prepares related bean collections and attach collection plugins.

Parameters:

Name Type Argument Description

models

Array.<Object> | Array.<Data/Bean>

Initial array of models.

options

Object

A hash of options.

Properties

Name	Type	Argument	Description
`link`	Object	<optional>	A link specification.

dispose()

Disposes this collection.

fetch( [options])

Fetches beans. See Data/BeanCollection#paginate for details about pagination options.

Only one fetch request can be executed at a time - previous fetch requests will be aborted.

Parameters:

Name Type Argument Description

options

Object

Fetch options.

Properties

Name	Type	Argument	Description
`relate`	boolean	<optional>	`true` if relationships should be fetched. `false` otherwise.
`myItems`	boolean	<optional>	`true` if only records assigned to the current user should be fetched. `false` otherwise.
`favorites`	boolean	<optional>	`true` if favorited records should be fetched. `false` otherwise.
`add`	boolean	<optional>	`true` if new records should be appended to the collection. `false` otherwise.
`query`	string	<optional>	Search query string.
`success`	function	<optional>	The success callback to execute.
`error`	function	<optional>	The error callback to execute.

Returns:

The created fetch request.

Type: SUGAR.HttpRequest

fetchTotal( [options])

Fetches the total amount of records on the bean collection, and sets it on the Data/BeanCollection#total property.

Returns the total amount of filtered records if a filterDef property is set on the collection.

Parameters:

Name Type Argument Description

options

Object

Fetch total options.

Properties

Name	Type	Argument	Description
`success`	function	<optional>	Success callback.
`complete`	function	<optional>	Complete callback.
`error`	function	<optional>	Error callback.

Returns:

Result of SUGAR.Api#call, or undefined if Data/BeanCollection#total is not null.

Type: SUGAR.HttpRequest | undefined

getDelta()

Gets a hash of unsynced changes operated on the collection.

Adds the relationship fields for records to be linked.

Returns:

A hash representing the unsynced changes.

Type: Object

getFetchRequest()

Gets the currently active fetch request.

Returns:

The currently active http fetch request.

Type: SUGAR.HttpRequest

getModelIndex(model)

Returns the index of the model in this collection.

Parameters:

Name	Type	Description
`model`	Object	Current model.

Returns:

The index of the passed model in this array.

Type: number

getNext(current, callback)

Returns the next model in a collection, paginating if needed.

Parameters:

Name	Type	Description
`current`	Object	Current model or id of a model.
`callback`	Object	Callback for success call.

getOption( [key])

Gets one or all persistent fetch options.

Parameters:

Name	Type	Argument	Description
`key`	string \| Object	<optional>	The name of the option to retrieve, or nothing to retrieve all options.

Returns:

A specific option, or the list of options.

Type: *

getPageNumber( [options])

Gets the current page of collection being displayed depending on the offset.

Parameters:

Name Type Argument Description

options

Object

Fetch options used when paginating.

Properties

Name	Type	Argument	Default	Description
`limit`	number	<optional>	App.config.maxQueryResult	The size of each page.

Returns:

The current page number.

Type: number

getPrev(current, callback)

Finds the previous model in a collection and calls a function on it.

Parameters:

Name	Type	Description
`current`	Object	Current model or id of a model.
`callback`	function	Callback for success call.

hasAtLeast(amount [, options])

A convenience method that checks to see if there are at least the amount of records passed in amount. Also passes to a provided success callback the length of records up to amount, and if there are more records to be fetched (hasMore).

Fetches the partial amount of filtered records if a filterDef property is set on the collection.

Parameters:

Name Type Argument Description

amount

number

The number of records to check if there are a minimum of.

options

Object

Fetch partial total options.

Properties

Name	Type	Argument	Description
`filterDef`	Object	<optional>	Filter definition to be applied.
`success`	function	<optional>	Success callback.
`complete`	function	<optional>	Complete callback.
`error`	function	<optional>	Error callback.

Returns:

Result of SUGAR.Api#call.

Type: SUGAR.HttpRequest

hasDelta()

Checks if there is anything in the deltas.

Returns:

true if some records are to be created, linked or unlinked to the bean.

Type: boolean

hasNextModel(current)

Checks whether is there next model in collection.

Parameters:

Name	Type	Description
`current`	Object	Current model or id of a model.

Returns:

true if has next model, false otherwise.

Type: boolean

hasPreviousModel(current)

Checks whether is there previous model in this collection.

Parameters:

Name	Type	Description
`current`	Object	Current model or id of a model.

Returns:

true if has previous model, false otherwise.

Type: boolean

initialize(models, options)

Sets the given options persistently on the bean collection. They will be used by Data/BeanCollection#fetch.

Parameters:

Name	Type	Description
`models`	Array.<Object> \| Array.<Data/Bean>	Initial array of models.
`options`	Object	Backbone collection options.

paginate( [options])

Paginates a collection. This methods calls Data/BeanCollection#fetch, hence it supports the same options as well as the one described below.

Parameters:

Name Type Argument Description

options

Object

Fetch options.

Properties

Name	Type	Argument	Default	Description
`page`	number	<optional>	1	Page index from the current page to paginate to.

remove(models, options)

Keeps track of the removed models.

Parameters:

Name	Type	Description
`models`	Object \| Array.<Object> \| Data/Bean \| Array.<Data/Bean>	The models to remove.
`options`	Object	A hash of options.

Returns:

The removed models.

Type: Data/Bean | Array.<Data/Bean>

reset(models, options)

Keeps track of the unsynced changes on this collection.

Parameters:

Name	Type	Description
`models`	Object \| Array.<Object> \| Data/Bean \| Array.<Data/Bean>	The models to reset the collection with.
`options`	Object	A hash of options.

Returns:

The model(s) you have reset the collection with.

Type: Data/Bean | Array.<Data/Bean>

resetDelta()

Resets the delta object representing the unsaved collection changes.

resetPagination()

Resets pagination properties on this collection to initial values.

setOption(key [, val])

Sets the default fetch options (one or many) on the model.

Parameters:

Name	Type	Argument	Description
`key`	string \| Object		The name of the attribute, or a hash of attributes.
`val`	*	<optional>	The default value for the `key` argument.

Returns:

This instance.

Type: Data/BeanCollection

toString()

Returns string representation useful for debugging.

Format: coll:[module-name]-[length] or coll:[related-module-name]/[id]/[module-name]-[length] if it's a collection of related beans.

Returns:

The string representation of this collection.

Type: string

unsetOption( [key])

Unsets a default fetch option (or all).

Parameters:

Name	Type	Argument	Description
`key`	string \| Object	<optional>	The name of the option to unset, or nothing to unset all options.

Returns:

This instance.

Type: Data/BeanCollection