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"
});
Source:

Members

# (readonly) favorites :boolean

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

Type:
  • boolean
Source:

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

# filterDef :Array

Filter definition to filter the collection by.

Type:
  • Array
Source:

Reference to a relationship.

Type:
  • Object
Source:

Link information.

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

# (readonly) model :Data/Bean

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

Type:
Source:

# (readonly) module :string

The module name.

Type:
  • string
Source:

# (readonly) myItems :boolean

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

Type:
  • boolean
Source:

# (readonly) offset :number

Current collection offset for pagination.

Type:
  • number
Source:

# (readonly) query :string

Search query.

Type:
  • string
Source:

# (readonly) total :number

Readonly property for the total records in server.

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

Type:
  • number
Source:

Methods

# (protected) _decrementTotal()

Decrements the collection total.

Source:

# abortFetchRequest()

Aborts the currently active fetch request.

Source:

# add(models, options) → {Data/Bean|Array.<Data/Bean>}

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

The added models.

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

# clone() → {Data/BeanCollection}

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

Source:
Returns:

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

Type
Data/BeanCollection

# constructor(models, optionsopt)

Prepares related bean collections and attach collection plugins.

Parameters:
Name Type Attributes Description
models Array.<Object> | Array.<Data/Bean>

Initial array of models.
options Object <optional>

A hash of options.

Properties
Name Type Attributes Description
link Object <optional>

A link specification.
Source:

# dispose()

Disposes this collection.

Source:

# fetch(optionsopt) → {SUGAR.HttpRequest}

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 Attributes Description
options Object <optional>

Fetch options.

Properties
Name Type Attributes 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.
Source:
Returns:

The created fetch request.

Type
SUGAR.HttpRequest

# fetchTotal(optionsopt) → {SUGAR.HttpRequest|undefined}

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 Attributes Description
options Object <optional>

Fetch total options.

Properties
Name Type Attributes Description
success function <optional>

Success callback.
complete function <optional>

Complete callback.
error function <optional>

Error callback.
Source:
Returns:

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

Type
SUGAR.HttpRequest | undefined

# getDelta() → {Object}

Gets a hash of unsynced changes operated on the collection.

Adds the relationship fields for records to be linked.

Source:
Returns:

A hash representing the unsynced changes.

Type
Object

# getFetchRequest() → {SUGAR.HttpRequest}

Gets the currently active fetch request.

Source:
Returns:

The currently active http fetch request.

Type
SUGAR.HttpRequest

# getModelIndex(model) → {number}

Returns the index of the model in this collection.

Parameters:
Name Type Description
model Object

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

# getOption(keyopt) → {*}

Gets one or all persistent fetch options.

Parameters:
Name Type Attributes Description
key string | Object <optional>

The name of the option to retrieve, or nothing to retrieve all options.
Source:
Returns:

A specific option, or the list of options.

Type
*

# getPageNumber(optionsopt) → {number}

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

Parameters:
Name Type Attributes Description
options Object <optional>

Fetch options used when paginating.

Properties
Name Type Attributes Default Description
limit number <optional>
 App.config.maxQueryResult

The size of each page.
Source:
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.
Source:

# hasAtLeast(amount, optionsopt) → {SUGAR.HttpRequest}

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 Attributes 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 Attributes Description
filterDef Object <optional>

Filter definition to be applied.
success function <optional>

Success callback.
complete function <optional>

Complete callback.
error function <optional>

Error callback.
Source:
Returns:

Result of SUGAR.Api#call.

Type
SUGAR.HttpRequest

# hasDelta() → {boolean}

Checks if there is anything in the deltas.

Source:
Returns:

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

Type
boolean

# hasNextModel(current) → {boolean}

Checks whether is there next model in collection.

Parameters:
Name Type Description
current Object

Current model or id of a model.
Source:
Returns:

true if has next model, false otherwise.

Type
boolean

# hasPreviousModel(current) → {boolean}

Checks whether is there previous model in this collection.

Parameters:
Name Type Description
current Object

Current model or id of a model.
Source:
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.
Source:

# paginate(optionsopt)

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 Attributes Description
options Object <optional>

Fetch options.

Properties
Name Type Attributes Default Description
page number <optional>
 1

Page index from the current page to paginate to.
Source:

# remove(models, options) → {Data/Bean|Array.<Data/Bean>}

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

The removed models.

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

# reset(models, options) → {Data/Bean|Array.<Data/Bean>}

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

Source:

# resetPagination()

Resets pagination properties on this collection to initial values.

Source:

# setOption(key, valopt) → {Data/BeanCollection}

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

Parameters:
Name Type Attributes Description
key string | Object

The name of the attribute, or a hash of attributes.
val * <optional>

The default value for the key argument.
Source:
Returns:

This instance.

Type
Data/BeanCollection

# toString() → {string}

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.

Source:
Returns:

The string representation of this collection.

Type
string

# unsetOption(keyopt) → {Data/BeanCollection}

Unsets a default fetch option (or all).

Parameters:
Name Type Attributes Description
key string | Object <optional>

The name of the option to unset, or nothing to unset all options.
Source:
Returns:

This instance.

Type
Data/BeanCollection