Sidecar API Reference

Class: Data/Bean

Data/Bean

new Data/Bean()

Base bean class. Beans extend Backbone.Model.

Use Data.DataManager to create instances of beans.

CRUD

Use standard Backbone's fetch, save, and destroy methods to perform CRUD operations on beans. See the Data.DataManager class for details.

Validation

This class does not override Backbone.Model.validate. The validation is done in the save method. If the bean is invalid the save is rejected. Use Data/Bean#isValidAsync to check if the bean is valid in other situations. Failed validations trigger an app:error:validation:<field-name> event.

Members

_defaults :Object

The hash of field names and default values.

This hash should be used instead of the Backbone.Model#default property. Setting default values is done in Data/Bean#initialize only if the given model is new.

Type:
  • Object

<readonly> fields :Object

The list of fields and their vardefs.

Type:
  • Object

Relationship link information.

{
    name: link name,
    bean: reference to the related bean
    isNew: flag indicating that it is a new relationship
}

The link.isNew flag is used to distinguish between an existing relationship and a relationship that is about to be created. Please refer to REST API specification for details. In brief, REST API supports creating a new relationship for two existing records as well as updating an existing relationship (updating relationship fields). The link.isNew flag equals to true by default. The flag is set to false by data manager once a relationship is created and whenever relationships are fetched from the server.

Type:
  • Object

<readonly> module :string

The module name.

Type:
  • string

searchInfo :Object

FTS search results.

Example:

{
    highlighted: {
        account_name: {
            label: 'LBL_ACCOUNT_NAME',
            module: "Leads",
            text: 'Kings Royalty <span class="highlight">Trust</span>'
        }
    },
    score: 1
}
Type:
  • Object

Methods

<protected> _bindEvents()

Binds events on the model.

abortFetchRequest()

Aborts the currently active fetch request.

addValidationTask(taskName, validate)

Adds a validation task to the validation waterfall.

Parameters:
Name Type Description
taskName string

The name of the task.
validate function

The validation task.

canHaveAttachments()

Checks if this bean can have attachments.

Returns:

true if this bean's field definition has an attachment_list field.

Type
boolean

changedAttributes( [attrs])

Gets changed attributes.

Parameters:
Name Type Argument Description
attrs Object <optional>

A hash of attributes to compare the current bean attributes against.
Returns:

false if nothing has changed. An object containing the attributes passed in parameters that are different from the bean ones.

Type
Object | boolean

constructor( [attributes] [, options])

Extends Backbone.Model#constructor. Attaches model plugins to allow initialize() to be overridden.

Parameters:
Name Type Argument Description
attributes Object <optional>

Standard Backbone model attributes.
options Object <optional>

Standard Backbone model options.

copy(source [, fields] [, options])

Copies fields from a given bean into this bean.

This method does not copy the id field, link-type fields, or fields whose values are auto-incremented (metadata field definition has auto_increment === true).

Parameters:
Name Type Argument Description
source Data/Bean

The bean to copy the fields from.
fields Array <optional>

The fields to copy. All fields are copied if not specified.
options Object <optional>

Standard Backbone options that should be passed to the Backbone.Model#set method.

dispose()

Disposes this bean.

doValidate( [fields] [, callback])

Validates a bean asynchronously - firing events on start, complete, and failure.

This method is called before Data/Bean#save.

Parameters:
Name Type Argument Description
fields Array | Object <optional>

A hash of field definitions or array of field names to validate. If not specified, all fields will be validated. View-agnostic validation will be run. Keys are field names, values are field definitions (combination of viewdefs and vardefs).
callback function <optional>

Function called with isValid flag once the validation is complete.
Fires:
  • event:validation:success If validation passes.
  • event:error:validation If validation fails.
  • event:validation:complete When validation is finished.

favorite(flag [, options])

Favorites or unfavorites this bean.

Parameters:
Name Type Argument Description
flag boolean

If true, marks this bean as a favorite.
options Object <optional>

Standard Backbone options for Backbone.Model#save operation.
Returns:

The request to update this bean.

Type
SUGAR.Api.HttpRequest

fetch( [options])

Extends Backbone.Model#fetch.

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

The success callback to execute.
error function <optional>

The error callback to execute.
Returns:

The active fetch request.

Type
SUGAR.Api.HttpRequest

fieldsOfType(type)

Gets all fields of a given type.

Parameters:
Name Type Description
type string

The type of the field to search for.
Returns:

List of fields filtered by the given type.

Type
Array

follow(flag [, options])

Subscribes or unsubscribes to record changes.

Parameters:
Name Type Argument Default Description
flag boolean

If true, subscribes to record changes. If false, unsubscribes from record changes.
options Object <optional>
 {}

Options for Backbone.Model#save.
Returns:

jqXHR object or false if error occurs.

Type
Object

get(attr)

Extends Backbone.Model#get to create a mixed bean collection for collection fields if there is none yet.

Parameters:
Name Type Description
attr string

The attribute name.
Returns:

The value of the requested attribute.

Type
string

getChangeDiff(original, exclude)

Calculates the difference between backup and changed model for restoring model.

Parameters:
Name Type Description
original Object

Hash of original (backed up) values.
exclude Array

List of fields to exclude from comparison.
Returns:

Difference between original and the current model attributes.

Type
Object

getCollectionFields( [attrs])

Gets a hash of collection fields attributes.

Parameters:
Name Type Argument Default Description
attrs Object <optional>
 this.attributes

The hash of attributes to get the collection fields from.
Returns:

A hash of collection fields attributes.

Type
Object

getDefault( [key])

Gets the default value of an attribute.

Parameters:
Name Type Argument Description
key string <optional>

The name of the attribute. If unspecified, the default values of all attributes are returned.
Returns:

The default value if you passed a key, or the hash of default values.

Type
*

getFetchRequest()

Retrieves the currently active fetch request.

Returns:

The active fetch request.

Type
SUGAR.Api.HttpRequest

getFiles(callbacks [, options])

Fetches a list of files (attachments).

Parameters:
Name Type Argument Description
callbacks Object

Hash of callbacks.

Properties
Name Type Argument Description
success function <optional>

Called on success.
error function <optional>

Called on error.
complete function <optional>

Called on completion.
options Object <optional>

Request options. See SUGAR.Api#file for details.
Returns:

XHR object.

Type
Object

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. If unspecified, retrieves all options.
Returns:

A specific option, or the list of options.

Type
*

getRelatedCollection(link)

Gets a collection of related beans.

This method returns a cached in memory instance of the collection. If the collection doesn't exist in the cache, it will be created using the Data.DataManager#createRelatedCollection method. Use the Data.DataManager#createRelatedCollection method to get a new instance of a related collection.

Example of usage:

var contacts = opportunity.getRelatedCollection('contacts');
contacts.fetch({ relate: true });
Parameters:
Name Type Description
link string

Relationship link name.
Returns:

Previously created collection or a new collection of related beans.

Type
Data/BeanCollection

getSynced( [key])

Gets the value of the synced attribute for the given key. If no key is passed, all synced attributes are returned.

Parameters:
Name Type Argument Description
key string <optional>

The attribute name.
Returns:

The synced attribute's value.

Type
*

hasChanged( [attr])

Checks if this bean has changed.

Parameters:
Name Type Argument Description
attr string <optional>

The attribute to check. If not specified, checks all attributes.
Returns:

true if at least one attribute has changed.

Type
boolean

initialize( [attributes])

Initializes this bean. Extends Backbone.Model#initialize.

Parameters:
Name Type Argument Description
attributes Object <optional>

Standard Backbone model attributes.

isCopy()

Checks whether this bean was populated as a result of a copy.

Returns:

true if this bean was populated as a result of a copy; false otherwise.

Type
boolean

isFavorite()

Checks if this bean is favorited.

Returns:

true if this bean is favorited, false otherwise.

Type
boolean

isValidAsync( [fields] [, callback])

Validates a bean asynchronously.

This method simply runs validation on the bean and calls the callback with the result - it does not fire any events or display any alerts. If you need events and alerts, use Data/Bean#doValidate.

Validation is view-agnostic.

Note: This method is different from Backbone.Model#isValid which does not support the asynchronous validation we require.

Parameters:
Name Type Argument Default Description
fields Array.<string> | Object <optional>
 this.fields

A hash of field definitions or array of field names to validate. If not specified, all fields will be validated. Keys are field names, values are field definitions (combination of viewdefs and vardefs).
callback function <optional>

Function called with isValid flag and any errors once the validation is complete.

merge(attributes, changes [, module])

Merges changes into a bean's attributes.

The default implementation overrides attributes with changes.

Parameters:
Name Type Argument Description
attributes Object

Bean attributes.
changes Object

Object hash with changed attributes.
module string <optional>

Module name.
Returns:

Merged attributes.

Type
Object

removeValidationTask(taskName)

Removes a specified validation task from the bean.

Parameters:
Name Type Description
taskName string

The name of the task.

revertAttributes(options)

Reverts model attributes to the last values from last sync or values on creation.

Parameters:
Name Type Description
options Object

Options are passed onto set.

Properties
Name Type Argument Default Description
silent boolean <optional>
 false

If true, do not trigger attributes:revert.
Fires:
  • attributes:revert If `options.event:silent` is falsy.

save( [attributes] [, options])

Overrides Backbone.Model#save so we can run asynchronous validation outside of the standard validation loop.

This method checks if this bean is valid only if options hash contains fieldsToValidate parameter.

Parameters:
Name Type Argument Description
attributes Object <optional>

The model attributes.
options Object <optional>

Standard Backbone save options.

Properties
Name Type Argument Description
fieldsToValidate Array <optional>

List of field names to validate.
Returns:

Returns an HTTP request if there are no fields to validate or undefined if validation needs to happen first.

Type
SUGAR.Api.HttpRequest

set(key, val, options)

Overrides Backbone.Model#set to add specific logic for collection fields.

Parameters:
Name Type Description
key string | Object

The key. Can also be an object with the key/value pair.
val string

The value to set.
options Object

A hash of options.
Returns:

This bean instance.

Type
Data/Bean

setDefault(key [, val])

Sets the default values (one or many) on the model, and fill in undefined attributes with the default values.

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 bean instance.

Type
Data/Bean

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 option, or an hash of options.
val * <optional>

The value for the key option.
Returns:

This bean instance.

Type
Data/Bean

setSyncedAttributes(attributes)

Sets internal synced attribute hash that's used in revertAttributes.

Parameters:
Name Type Description
attributes Object

Attributes of model to setup.

toJSON( [options])

Returns an object of attributes, containing what needs to be sent to the server when saving the bean . This method is called when JSON.stringify() is called on this bean.

Parameters:
Name Type Argument Description
options Object <optional>

Serialization options.

Properties
Name Type Argument Description
fields Object <optional>

List of field names to be included in the object of attributes. It retrieves all fields by default.
Returns:

A hashmap of attribute names to attribute values.

Type
Object

toString()

Returns a string representation useful for debugging, in the form bean:[module-name]/[id].

Returns:

A string representation of this bean.

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 bean instance.

Type
Data/Bean

uploadFile(fieldName, $files [, callbacks] [, options])

Uploads a file.

Parameters:
Name Type Argument Default Description
fieldName string

Name of the file field.
$files Array

List of DOM elements that contain file inputs.
callbacks Object <optional>
 {}

Callback hash.
options Object <optional>
 {}

Upload options. See the SUGAR.Api#file method for details.
Returns:

XHR object.

Type
Object