skuid.model.Model

All models on a Skuid page are constructed by Skuid as skuid.model.Model objects and will have the properties listed below.

To see these properties in action, use the skuid.model.getModelsByName() function at runtime.

Properties

skuid.model.Model.canRetrieveMoreRows

boolean

Indicates whether there are more rows in the dataset beyond the limit requested by the user.

skuid.model.Model.changes

object

Represents changes to the model which have not yet been committed to the database via save().

A simple object mapping of row Ids to rows that have changed. Each row is a simple map of field names to values that have changed.

cancel() empties changes. If no changes have been made since the last save() or cancel(), this will be an empty object.

skuid.model.Model.createRowIfNoneFound

boolean

Indicates if a row will be created when no records are returned by the model’s query or if the model is set not to query for records on page load, as defined in the Page Composer.

skuid.model.Model.conditionLogic

string

Defines the logic to use when combining the Model conditions. If no conditionLogic is specified, Skuid will combine all conditions using AND logic, e.g. 1 AND 2 AND …

Example: “(1 AND 2) OR (3 AND 4)”

skuid.model.Model.conditions

Skuid Model Condition Metadata Object[]

An array of Condition Metadata Objects associated with the model.

skuid.model.Model.data

object[]

An array of rows within the model. To retrieve this array directly, use getRows().

Each element within the array is a simple map of field names to values. For example, a row within a model with three fields, two from the object, “Name” and “CustomField__c”, and one from a lookup relationship, “skuid__AttachmentId__c” from the sObject “skuid__Image__c” via the relationship “Image__r”, would be represented as:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    'CustomField__c' : '<custom field value>',
    'Id' : '<18 character record Id>',
    'Id15' : '<15 character record Id>',
    'Image__c' : '<image Id>',
    'Image__r' :
        {
            'Id': '<image Id>',
            'skuid__AttachmentId__c': '<attachment Id>'
        },
    'Name' : '<name value>'
}

Note

It is typically not best practice to use this object to work with rows or their data. Instead, use the getter APIs getFirstRow() or getRowById() when attempting to work with a row using custom code.

skuid.model.Model.dataMap

object

Read-only. Use getRowById() to request a particular row by its Id and createRow() or adoptRows() to add new data to a model.

For the data array, see the documentation for the Skuid Model Metadata Object

Note

Direct use of this property is not recommended.

skuid.model.Model.fields

Skuid Model Field Metadata Object []

An array of Field Metadata Objects, one for each field explicitly defined in the model. For example, a model with three fields, two from the object, “Name” and “CustomField__c”, and one from a lookup relationship, “skuid__AttachmentId__c” from the sObject “skuid__Image__c” via the relationship “Image__r”, would have three elements in this array.

Note

Unlike the data and dataMap properties, an object’s Id field is not included unless explicitly included in the model.

Note

Fields are not guaranteed to be in any particular order.

skuid.model.Model.fieldsMap

object

Read-only. A simple object map of field names to Skuid Model Field Metadata Objects.

Note

It is recommended to use getField() to request field metadata for a particular field by its name, rather than directly accessing fieldsMap.

You can access the Field Metadata either by standard hierarchical objects (i.e. fieldsMap.Object__r.FieldName) or by using the fully qualified name via array syntax (i.e. fieldsMap[‘Object__r.FieldName’]). For example, a Model with three fields, two from the object, “Name” and “CustomField__c”, and one from a lookup relationship, “skuid__AttachmentId__c” from the sObject “skuid__Image__c” via the relationship “Image__r”, would be represented as:

1
2
3
4
5
6
7
8
9
{
    'CustomField__c' : { <Field Metadata Object> },
    'Image__r' :
        {
            'skuid__AttachmentId__c' : { <Field Metadata Object> }
        },
    'Image__r.skuid__AttachmentId__c' : { <Field Metadata Object> },
    'Name' : { <Field Metadata Object> }
}

For the field array, see the documentation for the Skuid Model Field Metadata Object.

Note

Unlike the data and dataMap properties, fieldsMap does not include Id fields unless they are explicitly included in the model.

skuid.model.Model.groupByFields

Skuid Model Field Metadata Object []

An array of Field Metadata Objects used to group an aggregate model. For basic models, this property is null.

skuid.model.Model.groupByMethod

string

A description of the grouping method. One of:

  • simple
  • rollup
skuid.model.Model.hasChanged

boolean

Read-only. Indicates if the model contains changes that have not been committed to the database.

skuid.model.Model.id

string

The unique identifier assigned to the model in the Skuid Page Composer.

skuid.model.Model.orderByClause

string

The Fields to Order Records By Clause defined from the Page Composer. Defines the ORDER BY clause in the model’s generated SOQL query.

skuid.model.Model.originals

object

A corollary to changes. Contains the original value for each field value change which has not yet been committed to the database.

A simple object mapping of row Ids to rows that have changed. Each row is a simple map of field names to the original values before they were changed.

skuid.model.Model.readonly

boolean

Indicates whether the model should be treated as read-only.

skuid.model.Model.recordsLimit

number

An integer value indicating the maximum number of rows to fetch from the database, as defined in the Page Composer. If the value given was less than 0, then the default is 1. If no value was given, then value will be null (and no limit will be placed on the query).

Note

When attempting to query for more data, updating the recordsLimit property directly is not recommended and may result in inaccurate data. Instead, consider using the batchSize property of loadAllRemainingRecords().

skuid.model.Model.registeredEditors

object

Read-only. A simple object map of Skuid Unique Ids to skuid.ui.Editor objects registered with the model.

skuid.model.Model.registeredFields

object

Read-only. A simple object map of Skuid Unique Ids to skuid.ui.Field objects registered with the model.

skuid.model.Model.registeredItems

object

Read-only. A simple object map of Skuid Unique Ids to skuid.ui.Item objects registered with the model.

skuid.model.Model.registeredLists

object

Read-only. A simple object map of Skuid Unique Ids to skuid.ui.List objects registered with the model.

skuid.model.Model.soql

string

The complete generated SOQL statement used to populate the model’s data, including requested fields and conditions, as well as any GROUP BY, ORDER BY and LIMIT clauses.

skuid.model.Model.type

string

The Model Type as defined in the Page Builder. One of:

  • For aggregate models: “aggregate”
  • For basic models: in most cases null, though under some circumstances a zero-length string (“”)

Prototype Functions

Every Skuid model created will be able to perform the following functions.

skuid.model.Model.abandonRow(row)

Removes a row from a model without requesting that it be deleted from the database.

When this function is called, the row will be removed from the data array, the dataMap, and the changes and originals maps. The item associated with the row will be removed from the registeredItems array. Any fields associated with the row will be removed from the registeredFields array. Any lists that contained the item will be notified that the item was deleted (via the handleRowDeletion function). Finally, the hasChanged property will be reassessed to determine whether the model still has changes.

Arguments:
  • row (object) – The row object to be removed from the model. The row object itself must belong to the model. For example, the row object was retrieved using getRowById() or getFirstRow().
Returns:

The abandoned row object.

Note

Attempting to abandon a row from another model or the clone of a row is unsupported and may cause unexpected behavior.

skuid.model.Model.abandonRows(rows)

Removes an array of rows from a model without requesting that that the rows be deleted from the database. Bulk version of abandonRow(). It is highly recommended to use abandonRows() rather than abandonRow() if you are removing more than one row from a model.

When this function is called, the rows will be removed from the data array, the dataMap, and the changes and originals maps. The items associated with the rows will be removed from the registeredItems array. Any fields associated with the rows will be removed from the registeredFields array. Any lists that contained the items will be notified that the items were deleted (via the handleRowDeletion function). Finally, the hasChanged property will be reassessed to determine whether the model still has changes.

Arguments:
  • rows (object) – Array of row objects: The row objects to be removed from the model. The row objects themselves must belong to the model. For example, the row objects should be retrievable using getRowById() or getRows().
Returns:

The array of abandoned row objects (if provided) or undefined if no rows or an empty array of rows was provided.

Note

Attempting to abandon rows from another model or the clones of rows is unsupported and may cause unexpected behavior.

skuid.model.Model.abandonAllRows()

Removes all rows from the Model, and cancels all changes. Fires handleDataRefresh() on registered skuid.ui.Editors and publishes the ‘models.loaded’ event for the Model. Identical to emptyData().

skuid.model.Model.activateCondition(condition, affectPersonalization)

Activates a condition so that it will be applied to future queries on this model.

Use getConditionByName() to retrieve a condition.

To immediately apply the condition after activating it, call updateData().

Arguments:
  • condition (skuid.model.Condition) – The condition to activate.
  • affectPersonalization (boolean) – Optional. If true, and if the condition has a name, then the Skuid Personalization Framework will store the value of this condition indefinitely (if the Page’s Personalization Mode is set to Server-side) or for the duration of the browser session (if the Page’s Personalization Mode is Client-side) so that the condition’s current value will be pulled from the stored value for the running user the next time that the page is loaded.

Note

Use activateCondition() for “toggle” style conditions. If the condition uses a value (such as filtering by Product Family on the Product2 sObject), then use setCondition().

skuid.model.Model.adoptRows(rows[, options])

Used for incorporating “external” rows into a Skuid model, e.g. rows coming from an external data source or web service, rows created/modified in Salesforce and then returned to Skuid via a non-Skuid Apex controller method, or rows manually created in JavaScript through a non-Skuid API method. Adopted rows will be matched against existing rows by their Id field/property.

If a matching existing row is found, it will be merged with the matching incoming row object, with the incoming row object’s properties taking precedence. If no corresponding existing row is found, then the incoming row will be prepended / appended to the Model’s data array. If an incoming row does not contain an Id, then Skuid will generate a unique Id for the row.

Unless the doAppend option is set to true, model rows will be prepended to the model data in order.

Note

In versions of Skuid below v11, rows would be prepended in reverse order.

For example:

  1. A model contains

    • [Row A]
    • [Row B]
  2. adoptRows() is used to adopt the following:

    • [Row 1]
    • [Row 2]
    • [Row 3]
  3. The model’s rows will now be:

    • [Row 1]
    • [Row 2]
    • [Row 3]
    • [Row A]
    • [Row B]

    If doAppend is true, the rows will be:

    • [Row A]
    • [Row B]
    • [Row 1]
    • [Row 2]
    • [Row 3]
Arguments:
  • rows (object[]) – Required. An array of JavaScript objects to merge in as rows into the model.
  • options (object) –

    Optional. A simple object with the following properties:

    • doAppend (boolean): Optional. By default, adoptRows() will prepend adopted rows to the Model’s existing data rows. if doAppend is set to true, however, then this row will be appended to the end of the model’s data rows.
    • notify (boolean): Optional, defaults to true. If false, then Skuid will not publish any events or notify any bound components about this event.
Returns:

The row objects that were adopted into the model, post-adoption.

Return type:

object[]

skuid.model.Model.cancel()

Reverts all changes made to this model since it was last saved or updated, using values stored in originals and emptying changes. Unsaved newly-created rows that are flagged for deletion are immediately removed from data.

Returns:Returns this model to enable function chaining.
Return type:skuid.model.Model
skuid.model.Model.createRow(options)

Creates a new row and attaches it to this model.

Arguments:
  • options (object) –

    A simple object with the following properties:

    • doAppend (boolean): Optional. By default, createRow() prepends new rows to the model’s data. if doAppend is set to true, however, then this row will be added to the end of the model’s data
    • editModeForNewItems (boolean): Optional, defaults to false. If true, then any skuid.ui.Items created in response to this new row’s creation will be placed into edit mode initially, rather than read mode.
    • additionalConditions ( skuid.model.Condition() [] ): Optional. Condition objects that should be applied to the new row in addition to any active conditions already on the model
Returns:

The newly created row object.

Return type:

object

skuid.model.Model.deactivateCondition(condition, affectPersonalization)

Deactivates the given skuid.model.Condition() so that it will not be applied to future queries on this model.

Use getConditionByName() to retrieve a condition.

Arguments:
  • condition (skuid.model.Condition) – The condition to deactivate
  • affectPersonalization (boolean) – Optional. If true, and if the condition has a name, then the Skuid Personalization Framework will store the value of this condition indefinitely (if the Page’s Personalization Mode is set to Server-side) or for the duration of the browser session (if the Page’s Personalization Mode is Client-side) so that the condition’s current value will be pulled from the stored value for the running user the next time that the page is loaded.
skuid.model.Model.deleteRow(row)

Marks the given row for deletion. The row will not be deleted from the database until the save() method is called.

To un-mark a row for deletion, see undeleteRow().

Arguments:
  • row (object) – The row object to mark for deletion.

Note

The row object only requires an Id field. If you have a row Id and want to mark it for deletion, you can call deleteRow( { Id: <row Id> } );

skuid.model.Model.emptyData()

Removes all rows from the model, and cancels all changes. Fires handleDataRefresh() on registered skuid.ui.Editors and publishes the ‘models.loaded’ event for the model. Identical behavior to abandonAllRows().

skuid.model.Model.exportData(options)

Exports either all or a subset of the rows in the model to a CSV file. The CSV file will be automatically downloaded to the user’s device when this method is called.

Arguments:
  • options (object) –

    A simple object containing one or more of the following configuration options:

    • additionalConditions ( skuid.model.Condition() ): An array of skuid.model.Condition() objects to limit the data in your model that actually gets exported. These conditions will be applied to rows (if rows is provided), or to all rows in the model (e.g. to model.getRows()), if rows is not provided.
    • doNotAppendRowIdColumn (boolean): Defaults to false. Ordinarily, the Id of each row will be appended as the final column in the exported CSV file, but if this is set to true, then this column will be omitted.
    • fields (object[]): An array of the particular model fields that you want to have included in the export (as the columns). If the model field is a child relationship field, then a template property is required on the field object in order for Skuid to know what fields to show in the column for each row in the child relationship. If a template property is provided and the field is not a valid field in the model, then Skuid will assume that this is a “Template field” and will process merge syntax within the template property in context of each row to compute the value to populate for the given cell.
    • fileName (string): the name of the file that will be generated, e.g. “MyLeads”. Defaults to the Id of the model plus “-export-” plus the timestamp in milliseconds, e.g. ‘MyLeads-export-128493010283’
    • rows (row[]): an array of the particular data rows in the model that you want to export. If not provided, all rows in the model (filtered optionally by additionalConditions) will be exported.
    • useAPINamesForHeaders (boolean): Defaults to false, but if true, the API names for fields will be used as column headers instead of the labels. Useful for doing data imports/exports/ETL operations to move data between systems, as opposed to outputting for human readability.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
var model = skuid.model.getModel('LeadData');

model.exportData({
    fileName: 'UnconvertedLeads',
    fields: [
        model.getField('FirstName'),
        model.getField('LastName'),
        model.getField('Company'),
        model.getField('Email')
    ],
    doNotAppendRowIdColumn: true,
    additionalConditions: [
        {
            field: "IsConverted",
            value: false,
            operator: '=',
            encloseValueInQuotes: false
        }
    ]
});

var moreCode = null;
skuid.model.Model.getConditionByName(conditionName, searchSubconditions)

Searches this Model for a Condition whose name property equals conditionName.

Arguments:
  • conditionName (string) – The name of the Condition, as defined in the Page Composer. A Condition’s State must be set to “Filterable, Default On/Off” in order for a name to be given to the Condition.
  • searchSubconditions (boolean) – Optional, defaults to false. When false, getConditionByName only searches top-level Conditions for name matches. If true, getConditionByName will search Sub-Conditions as well, returning the first Condition or Sub-Condition whose name is conditionName.
Returns:

The Condition associated with the given name, or false if the Condition name was not recognized.

Return type:

skuid.model.Condition()

skuid.model.Model.getField(fieldName)

Returns metadata about a field in this model.

Arguments:
  • fieldName (string) – The API name of a field. Can use dot notation to refer to related fields (e.g. “Image__r.Name”)
Returns:

Returns metadata about a field, or false if the field name was not recognized.

Return type:

Skuid Model Field Metadata

skuid.model.Model.getFieldValue(row, field, noEscape)

Returns the value for a particular field in a row from this model or returns undefined if the requested field is not found in the model.

Use model methods that return rows such as getFirstRow( ) to retrieve an instance of a row.

Arguments:
  • row (object) – The row object from which to extract the value.
  • field (string) – The name of the field. Use dot-notation to traverse relationships. (See below)
  • noEscape (boolean) – Optional. If true, Skuid will not HTML-escape the field value.
Returns:

The value of the field for the given row in this Model, or undefined if there is no value for the field on the row.

Return type:

The value of the field, which may be a string, number, object, array, etc.

EXAMPLE:

The benefit of using this method is that field can be specified as a string in relational syntax, e.g. ‘Account.Parent.Owner.Name’, and Skuid will automatically traverse the object hierarchy in that row. For example, if your data row looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    Account: {
        Parent: {
            Owner: {
                Name: "George Bailey",
                Id: "005000000000123AAA"
            },
            OwnerId: "005000000000123AAA",
            Name : "The Parent Account",
        Id: "001000000000011AAA"
        },
        ParentId: "001000000000011AAA",
        Name: "Main Account"
    }
}

then model.getFieldValue( row, ‘Account.Parent.Owner.Name’ ) will return ‘George Bailey’.

skuid.model.Model.getFirstRow()
Returns:The first row in this model’s data array
Return type:object
skuid.model.Model.getRowById(id)

Returns the row in this model identified by the given Id.

Arguments:
  • id (string) – The Id of the row. Typically an 18-character Salesforce Id, though may also be a Skuid Unique Id for newly created rows that have not been added to the database yet.
Returns:

A row object

Return type:

object

skuid.model.Model.getRows(dataConditions, context)

Returns all rows in this Model’s data array. This is the officially supported way to retrieve all rows in a Model.

Arguments:
  • dataConditions (array) – Optional array of skuid.model.Condition objects to apply to filter the Model’s rows.
  • context (object) – Optional object of context to use for evaluating the supplied dataConditions.
Returns:

An array all row objects in this Model.

Return type:

array of row objects

skuid.model.Model.isRowChanged(row)

Checks whether there are any unsaved changes associated with a particular row in a Model.

Arguments:
  • row (object) – Required. The Model row object to check for unsaved changes.
Returns:

Returns true if the row has any unsaved changes, otherwise returns false.

Return type:

boolean

skuid.model.Model.isRowMarkedForDeletion(row)

Checks whether a Model row has been marked for deletion.

Arguments:
  • row (object) – Required. The Model row object to check.
Returns:

Returns true if the row has been marked for deletion, otherwise returns false.

Return type:

boolean

skuid.model.Model.isRowNew(row)

Checks whether a Model row has not yet been committed to the Model’s associated data service.

Arguments:
  • row (object) – Required. The Model row object to check.
Returns:

Returns true if the row has not yet been committed, otherwise returns false.

Return type:

boolean

skuid.model.Model.isRowUnsavedClone(row)

Checks whether an unsaved / new Model row was originally cloned from a preexisting, saved record via Skuid’s model cloning functionality.

Arguments:
  • row (object) – Required. The Model row object to check.
Returns:

Returns true if the row is new / unsaved and was originally cloned from a preexisting, saved record. Otherwise, returns false.

Return type:

boolean

skuid.model.Model.loadAllRemainingRecords(options)

If the Model had a LIMIT clause applied to it and there are records in the database which were not retrieved in the prior/initial query, then loadAllRemainingRecords will call loadNextOffsetPage until the Model indicates that there are no more records available for retrieval.

Arguments:
  • options (object) –

    Optional. An object containing optional callbacks to be called:

    • stepCallback (function(offsetStart,offsetEnd): Optional. Callback function called immediately after a new “page” of records is retrieved and added into the Model. Two parameters are passed to the callback: offsetStart and offsetEnd, the start and end of the range of database records that were retrieved with the step. Skuid will load N records at a time, where N is the value of the “Max # of Records to Retrieve (Limit)” setting on your Model.
    • finishCallback (function(totalRecordsRetrieved): Optional. Callback function called when Skuid has finished loading all possible records from the database into a Model, i.e. there are no records in the database that match the Model’s Conditions that are not already in the Model. This method is passed one parameter, the final number of rows in the Model, which is equivalent to model.getRows().length at that moment in time.
    • batchSize (numberOfRecordsToRequest): Optional. Determines the number of records Skuid will request with each query. This option typically defaults to between 10-20 records, but larger batch sizes may be more ideal for services with long query wait times.

EXAMPLE

Scenario: Your Model “Accounts” has a limit of 50, and there are a total of 271 rows in the database that meet the Model’s Conditions. Running the following:

1
2
3
4
5
6
7
8
9
skuid.$.blockUI({ message: 'Loading all available Accounts...' });
skuid.$M("Accounts").loadAllRemainingRecords({
   stepCallback: function(offsetStart,offsetEnd) {
      skuid.$.blockUI({ message: 'Loading Accounts ' + offsetStart + ' to ' + offsetEnd + '...' });
   },
   finishCallback: function(totalRecordsRetrieved) {
      skuid.$.blockUI({ message: 'Finished loading all ' + totalRecordsRetrieved + ' Accounts!', timeout: 2000 });
   }
});

Will produce the following sequence of Block UI messages:

  1. “Loading all available Accounts…”
  2. “Loading Accounts 51 to 100…”
  3. “Loading Accounts 101 to 150…”
  4. “Loading Accounts 151 to 200…”
  5. “Loading Accounts 201 to 250…”
  6. Loading Accounts 251 to 300…”
  7. “Finished loading all 271 Accounts!”
skuid.model.Model.loadNextOffsetPage(callback)

If the Model had a LIMIT clause applied to it and there are rows in the database which were not fetched in a prior query then loadNextOffsetPage fetches the next “set” of data based on the LIMIT clause size.

Arguments:
  • callback (function) – Optional. A function to be called when the data has been loaded.
skuid.model.Model.removeRowById(id)

Calls abandonRow( ) for the row in the Model with the given Id.

Arguments:
  • id (string) – The Id of the row to abandon.
Returns:

The abandoned row object.

Return type:

object

skuid.model.Model.resetCondition(condition)

Will reset the value of a model’s condition to the default value of that condition.

Use getConditionByName() to retrieve a Condition.

To immediately apply the Condition after activating it, call updateData().

Arguments:
skuid.model.Model.save(options)

Sends all changes to this model to the server.

Arguments:
  • options (object) –

    Optional. A simple object with the following properties:

    • callback (function): Optional. A function to be called upon completion of the save operation.
Returns:

A Promise object which is resolved upon completion of the save operation.

Note

Check the totalsuccess property on the result object to confirm that the save operation was successful. The Promise will be rejected if the network request failed.

Return type:

jQuery Deferred Promise

skuid.model.Model.setCondition(condition, value, affectPersonalization)

Sets the value of a Condition on the Model and activates the Condition so that it will be applied to future queries on this Model.

Use getConditionByName() to retrieve a Condition.

To immediately apply the Condition after activating it, call updateData( ).

Arguments:
  • condition (skuid.model.Condition) – The Condition to set and activate.
  • value(s) (string or array) –

    The value(s) to use with the Condition.

    Note

    This can be either a single value or an Array of values.

    • If it is a single value and the condition’s operator is a multivalue operator (e.g. “in” or “includes”), then “Condition.values” will be set to an Array containing this value.
    • If it is an Array of values and the condition’s operator is multivalue, then “Condition.values” will be set to this Array of values.
  • affectPersonalization (boolean) – Optional. If true, and if the Condition has a name, then the Skuid Personalization Framework will store the value of this Condition indefinitely (if the Page’s Personalization Mode is set to Server-side) or for the duration of the browser session (if the Page’s Personalization Mode is Client-side) so that the Condition’s current value will be pulled from the stored value for the running User the next time that the page is loaded.

Note

Use setCondition( ) for Conditions that filter on a specific value, such as filtering by Product Family on the Product2 sObject. For “toggle” style Conditions, use activateCondition( ).

skuid.model.Model.undeleteRow(row)

Unmarks the given row for deletion. This function has no effect on rows that have already been deleted on the server.

Arguments:
  • row (object) – The row object to un-mark for deletion.

Note

The row object only requires an Id field. If you have a row Id and want to un-mark it for deletion, you can call undeleteRow( { Id: <row Id> } );

To recover a record deleted on the server, see Salesforce’s Recycle Bin documentation

skuid.model.Model.updateData(callback)

Requests an update (or “refresh”) for this Model from the server.

This function will throw a JavaScript error if there are unsaved changes in the Model. To cancel unsaved changes, see cancel( ).

Arguments:
  • callback (function) – A function to be executed upon completion of the update operation.
Returns:

The Promise object is resolved upon completion of the update operation.

Return type:

jQuery Deferred Promise

skuid.model.Model.updateRow(row, updates[, options])

Updates the value of the given row and fields, then notifies all registered UI elements that changes took place.

Note

If updating several rows within a loop, it is much more efficient to use the updateRows( ) function.

Changes made will not be sent to the server until the save( ) method is called.

Arguments:
  • row (object) – The row object to update. (Only the Id field is required.)
  • updates (object) – A simple object map of one or more API field names to values. For example:
1
2
3
4
{
    Name: 'New Name',
    CustomField__c: 'New Value'
}
Arguments:
  • options (object) –

    OPTIONAL. A simple object map of additional settings to pass in to this method call. Supported options include:

    • initiatorId (string): The page-unique identifier of the Component, Model, skuid.ui.Field, skuid.ui.Item, skuid.ui.List, or skuid.ui.Editor that initiated this updateRow( ) call, as obtainable via a call to .id( ) or a reference to ._GUID on the initiating object. This is essential to use when using updateRow( ) from within a Custom Field Renderer Snippet, in order to prevent infinite rendering loops, since the render( ) method is called on skuid.ui.Field objects whenever their associated row has had an update on the associated field. For example if you use updateRow( ) the Name field on an Account row all skuid.ui.Fields associated with that row and the Name field will have their render( ) method called after the update has been applied to the row in the Model.
Returns:

The updated row object.

Return type:

object

EXAMPLE:

Given a row Id, update the row’s Name and Custom Field values:

1
2
3
4
5
6
7
updateRow(
    { Id: '<row Id>' },
    {
        Name: 'New Name',
        CustomField__c: 'New Value'
    }
);
skuid.model.Model.updateRows(updates[, options])

Updates the value of the given rows and fields, then notifies all registered UI elements that changes took place.

Changes made will not be sent to the server until the save( ) method is called.

Arguments:
  • updates (object) – A map of row Ids to row objects. Each row object is a map of changed field names to new values.
  • options (object) –

    OPTIONAL. A simple object map of additional settings to pass in to this method call. Supported options include:

    • initiatorId (string): The page-unique identifier of the Component, Model, skuid.ui.Field, skuid.ui.Item, skuid.ui.List, or skuid.ui.Editor that initiated this updateRows( ) call, as obtainable via a call to .id( ) or a reference to ._GUID on the initiating object. This is essential to use when using updateRows( ) from within a Custom Field Renderer Snippet, in order to prevent infinite rendering loops, since the render( ) method is called on skuid.ui.Field objects whenever their associated row has had an update on the associated field. For example if you use updateRows( ) the Name field on an Account row all skuid.ui.Fields associated with that row and the Name field will have their render( ) method called after the update has been applied to the row in the Model.
Returns:

The updated row objects.

Return type:

object

EXAMPLE:

Update the Name and Custom Field values of all rows loaded into myModel:

1
2
3
4
5
6
7
var rowsToUpdate = {};

$.each( myModel.getRows(), function(){
    rowsToUpdate[this.Id] = { Name: 'New Name 1', CustomField__c: 'New Value 1' };
});

myModel.updateRows( rowsToUpdate );
skuid.model.Model.validateRequiredFields()

Calls validateRequiredFields() on each skuid.ui.List registered on the Model. For each required field defined on each List, the List will validate each of its Rendered Items to ensure that the row has values for each required field. If any required fields do not have values, a Message object is created. This method returns a list of all Message objects returned by any registered List on the Model.

Returns:Message object properties:
  • severity: the Severity of the Message. Will be “ERROR” for all required field validation messages.
  • status: a Status Code for the Message. Will be “REQUIRED_FIELD_MISSING” for all required field validation messages.
  • message: a String describing the error that occurred. Will be “Required fields have no value: ” + comma-separated list of Field labels.
  • fields: An array of the Labels of the Fields that do not have values.
Return type:Array of Message objects

Example: Accessing Models, Rows, and Updating Data

It is common to use skuid.model APIs to obtain information about a specific model, and then use skuid.model.Model APIs to interact with that specific model’s data.

For example, let’s create a new contact record:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
// The most common uses of skuid.model APIs are
// to retrieve a list of page models
skuid.model.map()
// and to obtain a reference to a specific model
var contactModel = skuid.$M('ContactModel');
var accountModel = skuid.$M('AccountModel');
// With a references set to a skuid.model.Model,
// it's easier to use skuid.model.Model APIs to access
// the first rows of those models, which are probably
// existing rows from a database.
var firstAccount = accountModel.getFirstRow();
var firstContact = contactModel.getFirstRow();
// Now to create a new contact in our Contact model,
// passing in additional conditions so that new contact
// has default values. If there are other existing conditions
// or default field values, those will be applied to the new row as well.
var georgeBailey = contactModel.createRow({
    additionalConditions: [
        { field: 'FirstName', value: 'George'},
        { field: 'LastName', value: 'Bailey'},
        { field: 'Birthdate', value: '1942-03-24'}
    ], doAppend: true
});
// First create a shortcut to Skuid's version of jQuery
var $ = skuid.$
// Next, change each contact in the Contact model
// to be associated the first account in the Account model.
$.each(contactModel.data,function(i,row){
    contactModel.updateRow(row,{
        AccountId: firstAccount.Id,
        Account: firstAccount
    });
});
// Save all changes in our Contact model
contactModel.save({callback: function(result){
    if (result.totalsuccess) {
        // Get the 15-digit Id of our newly-saved George Bailey Contact,
        // which will have had its Id and other fields updated after save
        console.log(georgeBailey.Id15);
        // Show the entire George Bailey Contact record
        console.log(georgeBailey);
    } else {
        console.log('The save failed.');
        console.log(result.insertResults);
        console.log(result.updateResults);
        console.log(result.deleteResults);
    }
}});

If this snippet takes places within a set of actions in the Action Framework, be sure to return the result of the model save function. Otherwise the Action Framework will continue before the save request completes.

Replace the lines 35-48 with this code:

1
2
3
4
5
6
7
return contactModel.save({callback: function(result){
    if (result.totalsuccess) {
        // Success logic
    } else {
        // Failure logic
    }
}});

Warning

Your set of actions continue regardless of whether the save fails or succeeds. This logic simply tells Skuid to wait until the save request is complete—regardless of success.

If you require more advanced logic based on the save’s success, you need to adjust your code accordingly, potentially using promises.