PageRenderTime 29ms CodeModel.GetById 15ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 0ms

/reference/websockets/sails.io.js/io.socket.on.md

https://github.com/balderdashy/sails-docs
Markdown | 86 lines | 56 code | 30 blank | 0 comment | 0 complexity | b2c479a5ab315b47e98e2688369fe5e2 MD5 | raw file
 1# io.socket.on()
 2
 3Starts listening for server-sent events from Sails with the specified `eventIdentity`.  Will trigger the provided callback function when a matching event is received.
 4
 5
 6### Usage
 7
 8```js
 9io.socket.on(eventIdentity, function (msg) {
10  // ...
11});
12```
13
14|   | Argument   | Type         | Details |
15|---|------------|:------------:|---------|
16| 1 | `eventIdentity`      | ((string))   | The unique identity of a server-sent event, e.g. "recipe"
17| 2 | `callback` | ((function)) | Will be called when the server emits a message to this socket.
18
19##### Callback
20
21|   | Argument  | Type         | Details |
22|---|-----------|:------------:|---------|
23| 1 | `msg`     | ((object))        | Message sent from the Sails server
24
25
26Note that the callback will NEVER trigger until one of your back-end controllers, models, services, etc. sends a message to this socket.  Typically that is achieved one of the following ways:
27
28###### Resourceful Pubsub Methods
29+ server publishes a message about a record to which this socket is subscribed (see [Model.publishUpdate()](), [Model.publishDestroy()](), and [Model.subscribe()]())
30+ server publishes a message informing all permitted watcher sockets that a new record has been created in the model with the same identity as `eventIdentity` (see [Model.publishCreate()]() and [Model.watch()]())
31
32###### Low-Level Socket Methods
33+ server emits a message to all known sockets (see [sails.sockets.blast()]())
34+ server emits a message directly to this socket (`io.socket`) using its unique id (see [sails.sockets.emit()]())
35+ server [broadcasts]() to a room in which this socket (`io.socket`) has been allowed to [join]() (remember that a socket only stays subscribed as long as it is connected-- i.e. as long as the browser tab is open)
36
37
38
39### Example
40
41Listen for new orders and updates to existing orders:
42
43```javascript
44io.socket.on('order', function onServerSentEvent (msg) {
45  // msg => {...whatever the server published/emitted...}
46});
47```
48
49##### Another example, this time using Angular:
50
51> Note that this Angular example assumes the backend calls `publishCreate()` at some point.
52
53```javascript
54angular.module('cafeteria').controller('CheckoutCtrl', function ($scope) {
55
56  $scope.orders = $scope.orders || [];
57
58  if (!io.socket.alreadyListeningToOrders) {
59    io.socket.alreadyListeningToOrders = true;
60    io.socket.on('order', function onServerSentEvent (msg) {
61
62      // Let's see what the server has to say...
63      switch(msg.verb) {
64
65        case 'created':
66          $scope.orders.push(msg.data); // (add the new order to the DOM)
67          $scope.$apply();              // (re-render)
68          break;
69
70        default: return; // ignore any unrecognized messages
71      }
72    });
73  }
74});
75```
76
77### Notes
78>+ When listening for resourceful pubsub calls, the `eventIdentity` is the same as the identity of the calling model (e.g. if you have a model "UserComment", the identity is "usercomment".)
79>+ For context-- these types of server-sent events are sometimes referred to as ["comet"](http://en.wikipedia.org/wiki/Comet_(programming)) messages.
80
81
82
83<docmeta name="uniqueID" value="socketon682488">
84<docmeta name="displayName" value="io.socket.on()">
85
86