Note

All code samples below refer to the skuid object.

In the v2 API, this object is not directly accessible when working within a browser console—or when referring to another Skuid page runtime.

If you are experiencing issues, use the skuid.runtime API to target the appropriate page context.

skuid.events

skuid.events.publish(event, data)

Publishes an Event

Arguments:
  • event (string) – The name of the event that you are publishing. We recommend namespacing your event names to prevent conflicts, e.g. “acme.chart.refresh” instead of “chartRefresh”
  • data (array) – (Optional) A JavaScript Array containing any additional data that you want to provide to subscribers when your event is published. The items in the Array will become arguments passed in to functions that have subscribed to this event. We recommend that your Array contain only one item, and that this item be a JavaScript object.
skuid.events.subscribe(event, callback)

Establishes an Event subscription

Arguments:
  • event (string) – The name of the event that you are subscribing to, e.g. “chart.refresh”, “models.loaded”
  • callback (function(data)) – A function to call whenever the specified event is published. Depending on the event, this function may be passed a single argument or multiple arguments of data associated with the event.
Returns object:

A subscription “handle” which can be used to unsubscribe

Note

If using the Publish event action, this API can only subscribe to events published to All active pages or All active pages and Lightning Components.

skuid.events.subscribeOnce(event, callback)

Subscribe for a single event — after it happens once, unsubscribe

Arguments:
  • event (string) – The name of the event that you are subscribing to, e.g. “chart.refresh”, “models.loaded”
  • callback (function(data)) – A function to call whenever the specified event is published. Depending on the event type, this function may be passed a single argument containing additional data about the event.
skuid.events.unsubscribe(subscription)

Removes a particular event subscription, such that the registered callback will no longer be invoked when the associated event is published.

Arguments:
  • subscription (object|array) – A single subscription returned from calling subscribe(), or an Array of such subscriptions.

Skuid Events Reference

The following is a list of the standard Events published by Skuid. For each Event, two pieces of information are provided:

  1. The situation in which Skuid publishes the event
  2. The additional data that Skuid provides to event subscribers

Models

skuid.events.models.cancelled

Published:

at the end of a call to model.cancel() or skuid.model.cancel([modelsArray]) call, after all changes have been thrown out of the models and any original data has been restored

Data:

  • models (object): A JavaScript object containing the names of the Skuid models which were canceled as its keys and the actual skuid.model.Model objects as its values.
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the cancel() method.
skuid.events.models.loaded

Published:

at the end of a successful call to model.updateData() or skuid.model.updateData([modelsArray]) call, after the models have been updated to include the new data retrieved from the server at the end of a successful call to model.load() or skuid.model.load([modelsArray]) call, after the models have been updated to include the new data retrieved from the server

Data:

  • models (object): A JavaScript object containing the names of the Skuid models which were loaded or updated as its keys and the actual skuid.model.Model objects as its values.
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the updateData() or load() method.
skuid.events.models.saveInitiated

Published:

while a call to model.save() or skuid.model.save([modelsArray]) is still in progress and before any validation has been performed

Data:

  • models (object): A JavaScript object containing the names of the Skuid models as its keys and the actual skuid.model.Model objects as its values.

  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

skuid.events.models.saved

Published:

after a call to model.save() or skuid.model.save([modelsArray]) has finished, and—if the save was successful—after the models have been adjusted to reflect the successful changes, whether inserts, updates, or deletes, to the models involved

Note

Check the totalsuccess property to confirm that the save operation was successful.

Data:

  • messages (array of Message objects): An array containing a Message object for any messages that were applied during the save

  • models (object): A JavaScript object containing the names of the Skuid models as its keys and the actual skuid.model.Model objects as its values.

  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

  • totalsuccess (boolean): A Boolean that is true only if all save operations (whether inserts, updates, and/or deletes), on all rows, on all models involved, had no errors. This is the property that ensures the save was successful.

  • insertResults (array of objects): An array of Skuid InsertResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the newly-inserted record
    • oldId (string): The temporary ID of the record before it was saved
    • success (boolean): True if the record was successfully inserted, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save)
    • errors (array of Message objects): An array containing a Message object for each blocking data source error that occurred on this record, preventing it from being inserted
    • messages (array of Message objects): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)
  • updateResults (array of objects): An array of Skuid UpdateResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the record for which an update was attempted
    • success (boolean): True if the record was successfully updated, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save)
    • errors (array of Message objects): An array containing a Message object for each blocking data source error that occurred on this record, preventing it from being updated
    • messages (array of Message objects): an array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)
  • deleteResults (array of objects): An array of Skuid DeleteResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the record for which a delete was attempted
    • success (boolean) True if the record was successfully deleted, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save
    • errors (array of Message objects): An array containing a Message object for any blocking data source errors that occurred on this record while saving
skuid.events.models.saveHandled

Published:

at the end of any call to model.save() or skuid.model.save([modelsArray]) call, regardless of whether the save call succeeded or failed

Data:

  • messages (array of Message objects): An array containing a Message object for any messages that were applied during the save

  • models (object): A JavaScript object containing the names of the Skuid models as its keys and the actual skuid.model.Model objects as its values

  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally initiated the save. This is generally present, and is usually the ID of a skuid.ui.Editor, useful for preventing infinite loops.

    For example, your component is involved in two save operations: it causes a model to save, but it also wants to subscribe to the save event as a way of responding to save events triggered by a different Ui Component on the same model. In this instance, it is helpful to know whether it was your component, or a different component, which initiated the save operation.

  • totalsuccess (boolean): A Boolean that is true only if all save operations (whether inserts, updates, and/or deletes), on all rows, on all models involved, had no errors.

  • insertResults (array of objects): An array of Skuid InsertResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the newly-inserted record
    • oldId (string): The temporary ID of the record before it was saved
    • success (boolean) true if the record was successfully inserted, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save
    • errors (array of Message objects): An array containing a Message object for each blocking data source errorthat occurred on this record, preventing it from being inserted
    • messages (array of Message objects): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)
  • updateResults (array of objects): An array of Skuid UpdateResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the record for which an update was attempted
    • success (boolean): True if the record was successfully updated, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save
    • errors (array of Message objects): An array containing a Message object for each blocking data source error that occurred on this record, preventing it from being updated
    • messages (array of Message objects): An array containing a Message object for any non-blocking info or warning messages that were applied to this row using skuid.utils.AddRowWarning(rowIndex,message)
  • deleteResults (array of objects): An array of Skuid DeleteResult objects, which have the following properties:

    • id (string): The 18-digit Salesforce ID of the record for which a delete was attempted
    • success (boolean): True if the record was successfully deleted, false if there were errors, whether on the individual record, or, if the “Rollback entire save on any error” option was saved, if there was an error on some other record that was part of the save
    • errors (array of Message objects): An array containing a Message object for any blocking data source errors that occurred on this record while saving

Rows

skuid.events.row.created

Published:

at the end of a call to model.createRow()

Data:

  • modelId (string): The ID of the model where the new row was created
  • rowId (string): The page-unique ID of the row that was just created.
  • row (object): The data row that was created, containing any default field values that may have been applied
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the createRow() method
skuid.events.row.updated

Published:

at the end of a call to model.updateRow() or model.updateRows() — for calls to updateRows(), row.updated will be published separately for each row

Data:

  • modelId (string): The ID of the model where the row was updated
  • rowId (string): The ID of the row that was updated
  • row (object): The data row that was updated, containing any updated field values
  • updates (object): A JavaScript object containing, as keys, the API Names of the Fields that were updated, and as values, the new values that were applied to those fields on this row, e.g. { “Amount__c”: 5000, “Stage__c”: “Qualified” }
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the updateRow() method
skuid.events.row.deleted

Published:

at the end of a call to model.deleteRow()

Data:

  • modelId (string): The ID of the model where the row was marked for deletion
  • rowId (string): The page-unique ID of the row that was just marked for deletion
  • row (object): The data row that was marked for deletion
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the deleteRow() method
skuid.events.row.undeleted

Published:

at the end of a call to model.undeleteRow()

Data:

  • modelId (string): The ID of the model where the row was un-marked for deletion
  • rowId (string): The page-unique ID of the row that was just un-marked for deletion
  • row (object): The data row that was un-marked for deletion
  • initiatorId (string): The page-unique ID of the Ui Component, if any, that originally called the undeleteRow() method

Conditions

In addition to being available as an initiating event for model actions within the Action Framework, model condition changes and their respective JavaScript functions now fire JavaScript events. These events and their payloads contain useful data for JavaScript snippets and custom components.

When the setCondition() method—which both sets a value for a condition and then activates it for any future re-queries—is called, the condition.valueChanged event is published, which contains the following data as the event payload:

{
  event: "condition.valueChanged",
  conditionName: <Condition Name>,
  modelId: <Model Id>,
  newValue: The new "value" property on the condition, unless it is a multi-value condition, then this would be the new "values" property
  oldValue: The old "value" property on the condition, unless it is a multi-value condition, then this would be the old "values" property
}

When the activateCondition() method—used to simply activate toggle style conditions—is called, the condition.activated event is published, which contains the following data as the event payload:

{
  event: "condition.activated",
  conditionName: <Condition Name>,
  modelId: <Model Id>
}

When the deactivateCondition() method is called—such as when the Deactivate Filterable Conditions action occurs, the condition.deactivated event is published, which contains the following data as the event payload:

{
  event: "condition.deactivated",
  conditionName: <Condition Name>,
  modelId: <Model Id>
}

Examples

Subscribing to a Skuid Model event

One common use case for the Skuid Publish / Subscribe API, with standard events, would be as a more generic alternative to using skuid.ui.Editor and skuid.ui.Field to listen for structured changes to particular Skuid models and rows.

For instance, if you wanted to perform certain logic any time that rows were updated in a particular subset of Models, you could do it like this:

1
2
3
4
5
skuid.events.subscribe('row.updated',function(updateResult){
   if ((updateResult.modelId === 'OpportunityData') && (updateResult.rowId===someRecordId)) {
       // Run my logic
   }
});

Or if you wanted to automatically requery a certain set of models whenever other models were saved, you could do this:

1
2
3
4
5
skuid.events.subscribe('models.saved',function(saveResult){
   if (('NewOpportunity' in saveResult.models)&&(saveResult.totalsuccess)) {
       skuid.model.updateData([skuid.model.getModel('AllOpportunities')];
   }
});

To unsubscribe from the event, keep a reference to the subscription returned when you subscribed, and then call unsubscribe():

1
2
var subscription = skuid.events.subscribe('row.updated', function() { ... });
skuid.events.unsubscribe(subscription);

Publishing / subscribing to a custom event

Another common use case for the Skuid Events API is to publish and subscribe to custom events relevant to your application. For instance, you may have a custom visualization component that subscribes to the “acme.page.resize” event. Because your component subscribes to this custom event, this event can now be easily invoked by other areas of the application, either via JavaScript or via the Skuid Action Framework’s “Publish Event” action.

Example Component code that subscribes to the event:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
skuid.componentType.register('acme__chart',function(element,xmlDef,component){
    // Subscribe to a custom Page Resize event
    skuid.events.subscribe('acme.page.resize',function(config,eventDetails){
        if (eventDetails && eventDetails.direction==='vertical') {
            // Adjust for vertical resize
        }
        if (config && config.doSomething) {
            // Do something special
        }
    }
});

And then somewhere else in the application that performs “page resize” functionality would publish the event, causing the chart’s subscription to be invoked:

1
2
3
4
5
6
7
var config = {
    doSomething: true
};
var eventDetails = {
    direction: 'vertical'
};
skuid.events.publish('acme.page.resize',[config,eventDetails]);