Class: Data/BeanCollection

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

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

Reference to a relationship.

Type:
  • Object

<readonly> model :Data/Bean

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

Type:

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

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

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

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

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

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

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