spUtil - recordWatch(Object $scope, String table, String filter, Function callback)

Watches for updates to a table or filter and returns the value from the callback function.

Allows a widget developer to respond to table updates in real-time. For instance, by using recordWatch(), the Simple List widget can listen for changes to its data table. If records are added, removed, or updated, the widget updates automatically.

When passing the $scope argument into the recordWatch() function, be sure to inject $scope into the parameters of your client script function.

Tables that are periodically subject to a high frequency of database events are blacklisted from recordWatch() to prevent event storms.

Table 1. Parameters
Name Type Description
$scope Object The scope of the data object updated by the callback function.
table String Watched table.
filter String Filter for fields to watch.
callback Function An optional parameter to define the callback function.
Table 2. Returns
Type Description
Promise The return value of the callback function.
//A simple recordWatch function.
spUtil.recordWatch($scope, "live_profile", "sys_id=" + liveProfileId);

//In a widget client script
function(spUtil, $scope) {
  /* widget controller */
  var c =this;

  // Registers a listener on the incident table with the filter active=true, 
  // meaning that whenever something changes on that table with that filter, 
  // the callback function is executed.    
  // The callback function takes two parameters: name and data. 
  spUtil.recordWatch($scope, "incident", "active=true", function(name, data) {
    // Returns information about the event that has occurred 
    // Returns the data inserted or updated on the table