io.socket.on()
Start listening for socket events from Sails with the specified eventName. Triggers the provided callback function when a matching event is received.
io.socket.on(eventName, function (msg) {
// ...
});
Usage
| Argument | Type | Details | |
|---|---|---|---|
| 1 | eventName | The name of the socket event, e.g. 'recipe' or 'welcome'. |
|
| 2 | handlerFn | An event handler that will be called when the server broadcasts a notification to this socket. Will only be called if the incoming socket notification matches eventName. |
Event handler
| Argument | Type | Details | |
|---|---|---|---|
| 1 | msg | The data from the socket notification. |
When is the event handler called?
This event handler is called when the client receives an incoming socket notification that matches the specified event name (e.g. 'welcome'). This happens when the server broadcasts a message to this socket directly, or to a room of which it is a member. To broadcast a socket notification, you need to either use the blueprint API or write some server-side code (e.g. in an action, helper, or even in a command-line script). This is typically achieved in one of the following ways:
Low-level socket methods (sails.sockets)
- server blasts out a message to all connected sockets (see sails.sockets.blast())
- server broadcasts a message directly to a particular socket using its unique ID or to an entire room full of sockets (see sails.sockets.broadcast())
Resourceful Pubsub Methods
- server broadcasts a message about a record, which multiple sockets might be subscribed to (see Model.publish()
- server broadcasts a message as part of the "Create" blueprint action (only relevant if using blueprints)
Example
Listen for the "order" event:
io.socket.on('order', function onServerSentEvent (msg) {
// msg => {...whatever the server broadcasted...}
});
Realtime cafeteria
Imagine you're building an ordering system for a chain of restaurants:
// In your frontend code...
// (This example uses jQuery and Lodash for simplicity. But you can use any library or framework you like.)
var ORDER_IN_LIST = _.template('<li data-id="<%- order.id %>"><p><%- order.summary %></p></li>');
$(function whenDomIsReady(){
// Every time we receive a relevant socket event...
io.socket.on('order', function (msg) {
// Let's see what the server has to say...
switch(msg.verb) {
case 'created': (function(){
// Render the new order in the DOM.
var newOrderHtml = ORDER_IN_LIST(msg.data);
$('#orders').append(newOrderHtml);
})(); return;
case 'destroyed': (function(){
// Find any existing orders w/ this id in the DOM.
//
// > Remember: To prevent XSS attacks and bugs, never build DOM selectors
// > using untrusted provided by users. (In this case, we know that "id"
// > did not come from a user, so we can trust it.)
var $deletedOrders = $('#orders').find('[data-id="'+msg.id+'"]');
// Then, if there are any, remove them from the DOM.
$deletedOrders.remove();
})(); return;
// Ignore any unrecognized messages
default: return;
}//< / switch >
});//< / io.socket.on() >
});//< / when DOM is ready >
Note that this example assumes the backend calls
.publish()or.broadcast()at some point. That might be through custom code, or via the blueprint API.
The 'connect' event
By default, when the Sails socket client is loaded on a page, it begins connecting a socket for you automatically. When using the default, auto-connecting socket (io.socket), you don't have to wait for the socket to connect before using it. In other words, you can listen for other socket events or call methods like io.socket.get() immediately. The Sails socket client will queue up anything you do in the meantime and then replay it automatically once the connection is live.
Consequently, direct usage of the 'connect' event is not necessary for most apps. But in the spirit of completeness, it is worth mentioning that you can also bind your own 'connect' handler:
io.socket.on('connect', function onConnect(){
console.log('This socket is now connected to the Sails server.');
});
The 'disconnect' event
If a socket's connection to the server was interrupted—perhaps because the server was restarted, or the client had some kind of network issue—it is possible to handle disconnect events in order to display an error message or even to manually reconnect the socket again.
io.socket.on('disconnect', function onDisconnect(){
console.log('This socket lost connection to the Sails server');
});
Sockets can be configured to reconnect automatically. However, as of Sails v1, the Sails socket client disables this behavior by default. In practice, since your user interface might have missed socket notifications while disconnected, you'll almost always want to handle any related custom logic by hand. (For example, a "Check your internet connection" error message).
Notes
- Remember that a socket only stays subscribed to a room for as long as it is connected—e.g. as long as the browser tab is open—or until it is manually unsubscribed on the server using
.unsubscribe()or.leave().- When listening for socket messages from resourceful PubSub calls and blueprints, the event name is always the same as the identity of the calling model. For example, if you have a model named "UserComment", the model's identity (and therefore the socket event name used by
UserComment.publish()) is "usercomment".- For context, socket notifications are also sometimes referred to as "server-sent events" or "comet) messages".
For a better experience on sailsjs.com, update your browser.
Reference
- Application
- Blueprint API
- Command-line interface
-
Configuration
- sails.config.*
- sails.config.blueprints
- sails.config.bootstrap()
- sails.config.custom
- sails.config.datastores
- sails.config.globals
- sails.config.http
- sails.config.i18n
- sails.config.log
- sails.config.models
- sails.config.policies
- sails.config.routes
- sails.config.security
- sails.config.session
- sails.config.sockets
- sails.config.views
-
Request (`req`)
- req._startTime
- req.body
- req.cookies
- req.fresh
- req.headers
- req.hostname
- req.ip
- req.ips
- req.isSocket
- req.method
- req.options
- req.originalUrl
- req.params
- req.path
- req.protocol
- req.query
- req.secure
- req.signedCookies
- req.socket
- req.subdomains
- req.url
- req.wantsJSON
- req.xhr
- req.accepts()
- req.acceptsCharsets()
- req.acceptsLanguages()
- req.allParams()
- req.file()
- req.get()
- req.is()
- req.param()
- req.setLocale()
- req.setTimeout()
- req.host
- Response (`res`)
- Waterline (ORM)
- WebSockets
Reference
Built with Love
The Sails framework is built by a web & mobile shop 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!
© 2012-2024 The Sails Company.
The Sails framework is free and open-source under the MIT License.
Illustrations by Edamame.