Edit Page

.publishRemove()

Broadcast a conventional message indicating that a record has been removed from one of this parent record's collections.

Something.publishRemove( id, association, fk )

Or:

Something.publishRemove(id, association, fk, req)
Something.publishRemove(id, association, fk, req, options)

Usage

	Argument	Type	Details
1	`id`	,	The `id` of the parent record whose subscribers will receive this broadcast. e.g. `4`
2	`association`		The name of the collection association. e.g. `'pets'`
3	`fk`		The foreign key value (e.g. `id`) of the associated record being removed. e.g. `9`
4	`req`		If provided, then the requesting socket will be excluded from the broadcast.
5	`options`		A dictionary of additional options. See below.

Additional Options

By default, when publishRemove() is called, it checks whether any associated records were also affected by the removal, and possibly sends out additional notifications (if a reflexive association was changed).

For example, let's say a User model has a pets association (a plural, or "collection" association) which connects each User record with none, one, or several distinct Pet records. On the other side, let's say each Pet record has an owner association (a singular or "model" association), which means it can have exactly zero or one owners. If User.publishRemove(4, 'pets', 9) is called under these circumstances, then not only will it broadcast the normal "removedFrom" message to user 4, it will also broadcast a "updated" message to pet 9 (indicating that its owner has changed).

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

Option	Type	Details
`noReverse`		If set, automatic broadcasts for reflexive associations will be suppressed.

Behavior

publishRemove() 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: 'removedFrom'
id - the parent record's id which is a or
attribute - the name of the collection association from whence the removed record was pulled ()
removedId - the id of the record that was removed (i.e. fk) which is a or

Example

Find Elixabeth by her username and steal her favorite cat, then broadcast a message about it to all of her subscribers:

User.findOne({username: 'elizabeth'})
.populate('pets', { limit: 5 })
.exec(function(err, liz){
  if (err) return res.serverError(err);
  if (!liz) return res.notFound();

  // The Pet with id=3 is Liz's favorite cat, Humphrey.
  liz.pets.remove(3);
  liz.pets.save(function (err){
    if (err) return res.serverError(err);

    // Broadcast a message telling anyone subscribed to Liz that Humphrey ran away.
    // Note that we exclude the requesting socket from the broadcast.
    // Also note that, since we set `noReverse`, no "pet" events will be broadcasted
    // to Humphrey's subscribers (Liz wouldn't want us to worry them).
    User.publishRemove(liz.id, 'pets', 3, req, { noReverse: true });

    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) {
    'removedFrom':
      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 like this:

{
  verb: 'removedFrom',
  id: 194,
  attribute: 'pets',
  removedId: 3
}

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.

Be sure and check req.isSocket === true before passing in req to refer to the requesting socket. If used, the provided req must be from a socket request, not just any old HTTP request.

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!