Edit Page

.publishUpdate()

Broadcast a conventional message indicating that the record with the specified id has been updated.

Something.publishUpdate( id, changes )

Or:

Something.publishUpdate(id, changes, req);
Something.publishUpdate(id, changes, req, options);

Usage

	Argument	Type	Details
1	`id`	,	The `id` of the record whose subscribers will receive this broadcast. e.g. `4`
2	`changes`		The dictionary of changed attributes and their new values to announce. This may consist of any JSON--serializable data you like, but must at-minimum contain the `id` (primary key) of the record.
3	`req`		If provided, then the requesting socket will be excluded from the broadcast.
4	`options`		A dictionary of additional options. See below.

Additional Options

If the options dictionary is provided, and it contains a previous property, then it is expected to be a representation of the record's values before they were updated. This may be used to determine whether or not to broadcast additional messages. See, by default if options.previous is provided, publishUpdate() will check whether any associated records were affected by the update, and possibly send out additional notifications (if a reflexive association was changed).

For example, let's say a Pet model has an owner association (a singular, or "model" association) which connects each Pet record with up to one distinct User record. Conversely, this means any User record could own several pets (or none). So if the data sent with the call to publishUpdate indicates that the value of a pet's owner association changed (e.g. from 4 to 7), then an additional publishRemove call would be made to inform client sockets subscribed to user 4 that this user has lost one of its pets. Similarly, a publishAdd call would be made to inform client sockets subscribed to user 7 that this user has gained a new pet.

To suppress automatic broadcasts for reflexive associations, set the options.noReverse flag to true.

Option	Type	Details
`noReverse`		If set, automatic broadcasts for reflexive associations will be suppressed.
`previous`		If provided, this dictionary will be understood as a set of previous values of updated attributes; from before they were updated, and it may be used to determine whether or not to broadcast additional messages as described above. It will also be included in the message broadcasted to subscribed client sockets.

Behavior

publishUpdate() broadcasts to all sockets subscribed to the record (e.g. via .subscribe()) and uses the model's identity as the event name. The broadcasted event data received by the subscribed sockets will be a dictionary with the following properties:

verb - a constant: 'updated'
id - the record's id which is a or
data - the of changed properties that was provided as changes when calling .publishUpdate() on the backend
previous - if present, this contains the previous values of the now-updated attributes for convenience

Example

In a controller+action... Find a user by username and broadcast a message back to all of its subscribers:

// Dye Bob's hair red.
User.update({username: 'bob'}).set({
  hairColor: 'red'
}).exec(function(err, bobs){
  if (err) return res.serverError(err);
  if (bobs.length > 1) return res.serverError('Consistency violation: somehow multiple users exist with the same username? There must be a bug elsewhere in the code base.');
  if (bobs.length < 1) return res.notFound();

  // Broadcast a message telling anyone subscribed to Bob that his hair is now red.
  // (note that we exclude the requesting socket from the broadcast, and also include Bob's previous hair color)
  User.publishUpdate(bobs[0].id, {
    hairColor: 'red'
  }, req, {
    previous: {
      hairColor: bobs[0].hairColor
    }
  });

  return res.ok();
});

The endpoint will respond with a simple 200 (because of res.ok()), but all subscribed client sockets will receive a user event:

// e.g. in the browser...
io.socket.on('user', function (event){
  switch (event.verb) {
    case 'updated':
      console.log(event);
      // => see below
      break;
    default:
      console.warn('Unrecognized socket event (`%s`) from server:',event.verb, event);
  }
});

In this case, the logged message would look something like this:

{
  verb: 'updated',
  id: 49,
  data: {
    hairColor: 'red'
  },
  previous: {
    hairColor: 'pink'
  }
}

Notes

This method works much in the same way as .message()-- it just represents a more specific use case and has a few special features as described above. For more conceptual background, see the overview on resourceful pubsub.

It is important to understand that this method does not actually do anything to your database-- it is purely a conventional way of announcing that changes have occurred. Underneath the covers, the resourceful pubsub methods are just using combinations of sails.sockets methods.

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Documentation

Reference

Built with Love

The Sails framework is maintained by a web & mobile studio in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!