Edit Page

.publishAdd()

Broadcast a conventional message indicating that a record has been newly added to one of this parent record's collections.

Something.publishAdd(id, association, added);

Or:

Something.publishAdd(id, association, added, req);
Something.publishAdd(id, association, added, req, options);

Usage

	Argument	Type	Details
1	`id`	,	The id (primary key) of the parent record.
2	`association`		The name of the association that the child record was added to (e.g. `"comments"`)
3	`added`	,,	Either a number or string to represent the id (primary key) of the child record being added, or a dictionary of properties describing it (must contain an `id` key!). Either way, this information will be bundled in the socket message which is broadcasted.
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 publishAdd() is called, it checks whether any associated records were also affected by the addition, 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 aka "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.publishAdd(4, 'pets', 9) is called under these circumstances, then not only will it broadcast the normal "addedTo" message to user 4, it will also broadcast an "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

By convention, this message indicates that a new child record has been added to the specified collection association of this parent record (and that client-side sockets receiving the message should update their user interface to match). In other words, if a Tutorial model has an associated collection of "comments" (referring to records of the Comment model), then you might call Tutorial.publishAdd() to notify connected clients that a new comment has been added to the tutorial.

When your app calls publishAdd(), a socket message is broadcasted to all sockets subscribed to the record's room (i.e. via the subscribe() resourceful pubsub method) and the model identity is used as the event name.

The socket message is an object with the following properties:

id - the id attribute of the parent record
verb - always provided as the string: "addedTo"
attribute - the name of the model attribute (collection association) that was added to
addedId - the id of the newly added child record
added - Not guaranteed. Will only be present if a dictionary of properties for the newly added child record was provided, rather than just its id.

Example

// Broadcast a message to all client-side sockets subscribed to the tutorial record w/ id=3
// letting them know that a new child record with id=17 has been associated and is now one of the
// tutorial's "comments".
Tutorial.publishAdd(3, 'comments', 17);

// Broadcast a message to all client-side sockets subscribed to the tutorial record w/ id=3
// letting them know that a new child record with the specified properties has been associated
// and is now one of the tutorial's "comments".
// (Note that we also pass in `req` to prevent the requesting socket from receiving the broadcast.)
Tutorial.publishAdd(3, 'comments', {
  id: 17,
  message: 'I love this show!'
}, req);

Meanwhile, on the front-end, you might do something like this:

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

In the case of the first example call to publishAdd above, the logged message would look like:

{
  verb: 'addedTo',
  id: 3,
  attribute: 'comments',
  addedId: 17
}

Whereas in the latter case, note that added is also present thanks to the usage:

{
  verb: 'addedTo',
  id: 3,
  attribute: 'comments',
  addedId: 17,
  added: {
    id: 17,
    message: 'I love this show!'
  }
}

Notes

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.

Under the covers, resourceful pubsub methods use sails.sockets.* methods. When/if you encounter a need for customization beyond what is supported out of the box in a resourceful pubsub method, you should use the methods exposed in sails.sockets.* directly.

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.

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.

If you are using Sails' blueprint API, this resourceful pubsub method is called automatically by built-in code within the blueprints hook in Sails core. The cleanest way to customize this, or any other behavior bundled in a blueprint API, is to override it with a custom action.

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!