Edit Page

Sending realtime messages from the server to one or more clients

Overview

#

Sails exposes two APIs for communicating with connected socket clients: the higher-level resourceful pubsub API, and the lower-level sails.sockets API.

Resourceful PubSub

#

The Resourceful PubSub (Published/Subscribe) API provides a high-level way to subscribe sockets to Sails model classes and instances. It is entirely possible to create a rich realtime experience (for example, a chat app) using just this API. Sails blueprints use Resourceful PubSub to automatically send out notifications about new model instances and changes to existing instances, but you can use them in your custom controller actions as well.

Example
#

Create a new User model instance and notify all interested clients

// Create the new user
User.create({
  name: 'johnny five'
}).exec(function(err, newUser) {
  if (err) {
    // Handle errors here!
    return;
  }
  // Tell any socket watching the User model class
  // that a new User has been created!
  User.publishCreate(newUser);
});

sails.sockets

#

The sails.sockets API allows for lower-level communication directly with sockets, using methods like sails.sockets.join() (subscribe a socket to all messages sent to a particular "room"), sails.sockets.leave() (unsubscribe a socket from a room), and sails.sockets.broadcast() (broadcast a message to all subscribers in one or more rooms).

Example
#

Add a socket to the room "funSockets"

sails.sockets.join(someSocket, "funSockets");

Broadcast a "hello" message to the "funSockets" room. This message will be received by all client sockets that have (1) been added to the "funSockets" room on the server with sails.sockets.join() and (2) added a listener for the "hello" event on the client with socket.on('hello', ...).

sails.sockets.broadcast("funSockets", "hello", "Hello to all my fun sockets!");

Reference

#

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 repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Concepts