#
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.
#
(readonly) fields :Object
The list of fields and their vardefs.
#
link :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.
#
(readonly) module :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
}
Methods
#
(protected) _bindEvents()
#
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() → {boolean}
Checks if this bean can have attachments.
Returns:
true
if this bean's field definition has
an attachment_list
field.
-
Type
-
boolean
#
changedAttributes(attrsopt) → {Object|boolean}
Parameters:
Name |
Type |
Attributes |
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(attributesopt, optionsopt)
Extends Backbone.Model#constructor
. Attaches model plugins to allow
initialize()
to be overridden.
Parameters:
Name |
Type |
Attributes |
Description |
attributes |
Object
|
<optional>
|
Standard Backbone model attributes. |
options |
Object
|
<optional>
|
Standard Backbone model options. |
#
copy(source, fieldsopt, optionsopt)
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 |
Attributes |
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()
#
doValidate(fieldsopt, callbackopt)
Validates a bean asynchronously - firing events on start, complete,
and failure.
This method is called before Data/Bean#save.
Parameters:
Name |
Type |
Attributes |
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, optionsopt) → {SUGAR.Api.HttpRequest}
Favorites or unfavorites this bean.
Parameters:
Name |
Type |
Attributes |
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(optionsopt) → {SUGAR.Api.HttpRequest}
Extends Backbone.Model#fetch
.
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 |
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) → {Array}
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, optionsopt) → {Object}
Subscribes or unsubscribes to record changes.
Parameters:
Name |
Type |
Attributes |
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) → {string}
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) → {Object}
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(attrsopt) → {Object}
Gets a hash of collection fields attributes.
Parameters:
Name |
Type |
Attributes |
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(keyopt) → {*}
Gets the default value of an attribute.
Parameters:
Name |
Type |
Attributes |
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() → {SUGAR.Api.HttpRequest}
Retrieves the currently active fetch request.
Returns:
The active fetch request.
-
Type
-
SUGAR.Api.HttpRequest
#
getFiles(callbacks, optionsopt) → {Object}
Fetches a list of files (attachments).
Parameters:
Name |
Type |
Attributes |
Description |
callbacks |
Object
|
|
Hash of callbacks.
Properties
Name |
Type |
Attributes |
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. |
#
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. If
unspecified, retrieves all options. |
Returns:
A specific option, or the list of options.
-
Type
-
*
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(keyopt) → {*}
Gets the value of the synced attribute for the given key. If no key
is passed, all synced attributes are returned.
Parameters:
Name |
Type |
Attributes |
Description |
key |
string
|
<optional>
|
The attribute name. |
Returns:
The synced attribute's value.
-
Type
-
*
#
hasChanged(attropt) → {boolean}
Checks if this bean has changed.
Parameters:
Name |
Type |
Attributes |
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(attributesopt)
Initializes this bean. Extends Backbone.Model#initialize
.
Parameters:
Name |
Type |
Attributes |
Description |
attributes |
Object
|
<optional>
|
Standard Backbone model attributes. |
#
isCopy() → {boolean}
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() → {boolean}
Checks if this bean is favorited.
Returns:
true
if this bean is favorited, false
otherwise.
-
Type
-
boolean
#
isValidAsync(fieldsopt, callbackopt)
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 |
Attributes |
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, moduleopt) → {Object}
Merges changes into a bean's attributes.
The default implementation overrides attributes with changes.
Parameters:
Name |
Type |
Attributes |
Description |
attributes |
Object
|
|
Bean attributes. |
changes |
Object
|
|
Object hash with changed attributes. |
module |
string
|
<optional>
|
Module name. |
#
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 |
Attributes |
Default |
Description |
silent |
boolean
|
<optional>
|
false
|
If true , do not trigger
attributes:revert . |
|
Fires:
- attributes:revert If `options.event:silent` is falsy.
#
save(attributesopt, optionsopt) → {SUGAR.Api.HttpRequest}
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 |
Attributes |
Description |
attributes |
Object
|
<optional>
|
The model attributes. |
options |
Object
|
<optional>
|
Standard Backbone save options.
Properties
Name |
Type |
Attributes |
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) → {Data/Bean}
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. |
#
setDefault(key, valopt) → {Data/Bean}
Sets the default values (one or many) on the model, and fill in
undefined attributes with the default values.
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. |
#
setOption(key, valopt) → {Data/Bean}
Sets the default fetch options (one or many) on the model.
Parameters:
Name |
Type |
Attributes |
Description |
key |
string
|
Object
|
|
The name of the option, or an hash of
options. |
val |
*
|
<optional>
|
The value for the key option. |
#
setSyncedAttributes(attributes)
Sets internal synced attribute hash that's used in revertAttributes
.
Parameters:
Name |
Type |
Description |
attributes |
Object
|
Attributes of model to setup. |
#
toJSON(optionsopt) → {Object}
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 |
Attributes |
Description |
options |
Object
|
<optional>
|
Serialization options.
Properties
Name |
Type |
Attributes |
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() → {string}
Returns a string representation useful for debugging, in the form
bean:[module-name]/[id]
.
Returns:
A string representation of this bean.
-
Type
-
string
#
unsetOption(keyopt) → {Data/Bean}
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. |
#
uploadFile(fieldName, $files, callbacksopt, optionsopt) → {Object}
Parameters:
Name |
Type |
Attributes |
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. |