1# angular-socket-io [![Build Status](https://travis-ci.org/btford/angular-socket-io.svg)](https://travis-ci.org/btford/angular-socket-io)
  2
  3Bower Component for using AngularJS with [Socket.IO](http://socket.io/),
  4based on [this](http://briantford.com/blog/angular-socket-io.html).
  5
  6
  7## Install
  8
  91. `bower install angular-socket-io` or [download the zip](https://github.com/btford/angular-socket-io/archive/master.zip).
 102. Make sure the Socket.IO client lib is loaded. It's often served at `/socket.io/socket.io.js`.
 113. Include the `socket.js` script provided by this component into your app.
 124. Add `btford.socket-io` as a module dependency to your app.
 13
 14
 15## Usage
 16
 17This module exposes a `socketFactory`, which is an API for instantiating
 18sockets that are integrated with Angular's digest cycle.
 19
 20
 21### Making a Socket Instance
 22
 23```javascript
 24// in the top-level module of the app
 25angular.module('myApp', [
 26  'btford.socket-io',
 27  'myApp.MyCtrl'
 28]).
 29factory('mySocket', function (socketFactory) {
 30  return socketFactory();
 31});
 32```
 33
 34With that, you can inject your `mySocket` service into controllers and
 35other serivices within your application!
 36
 37### Using Your Socket Instance
 38
 39Building on the example above:
 40
 41```javascript
 42// in the top-level module of the app
 43angular.module('myApp', [
 44  'btford.socket-io',
 45  'myApp.MyCtrl'
 46]).
 47factory('mySocket', function (socketFactory) {
 48  return socketFactory();
 49}).
 50controller('MyCtrl', function (mySocket) {
 51  // ...
 52});
 53```
 54
 55
 56## API
 57
 58For the most part, this component works exactly like you would expect.
 59The only API addition is `socket.forward`, which makes it easier to add/remove listeners in a way that works with [AngularJS's scope](http://docs.angularjs.org/api/ng.$rootScope.Scope).
 60
 61### `socket.on` / `socket.addListener`
 62Takes an event name and callback.
 63Works just like the method of the same name from Socket.IO.
 64
 65### `socket.removeListener`
 66Takes an event name and callback.
 67Works just like the method of the same name from Socket.IO.
 68
 69### `socket.removeAllListeners`
 70Takes an event name.
 71Works just like the method of the same name from Socket.IO.
 72
 73### `socket.emit`
 74Sends a message to the server.
 75Optionally takes a callback.
 76
 77Works just like the method of the same name from Socket.IO.
 78
 79### `socket.forward`
 80
 81`socket.forward` allows you to forward the events received by Socket.IO's socket to AngularJS's event system.
 82You can then listen to the event with `$scope.$on`.
 83By default, socket-forwarded events are namespaced with `socket:`.
 84
 85The first argument is a string or array of strings listing the event names to be forwarded.
 86The second argument is optional, and is the scope on which the events are to be broadcast.
 87If an argument is not provided, it defaults to `$rootScope`.
 88As a reminder, broadcasted events are propagated down to descendant scopes.
 89
 90#### Examples
 91
 92An easy way to make socket error events available across your app:
 93
 94```javascript
 95// in the top-level module of the app
 96angular.module('myApp', [
 97  'btford.socket-io',
 98  'myApp.MyCtrl'
 99]).
100factory('mySocket', function (socketFactory) {
101  var mySocket = socketFactory();
102  mySocket.forward('error');
103  return mySocket;
104});
105
106// in one of your controllers
107angular.module('myApp.MyCtrl', []).
108  controller('MyCtrl', function ($scope) {
109    $scope.$on('socket:error', function (ev, data) {
110
111    });
112  });
113```
114
115Avoid duplicating event handlers when a user navigates back and forth between routes:
116
117```javascript
118angular.module('myMod', ['btford.socket-io']).
119  controller('MyCtrl', function ($scope, socket) {
120    socket.forward('someEvent', $scope);
121    $scope.$on('socket:someEvent', function (ev, data) {
122      $scope.theData = data;
123    });
124  });
125```
126
127
128### `socketFactory({ ioSocket: }}`
129
130This option allows you to provide the `socket` service with a `Socket.IO socket` object to be used internally.
131This is useful if you want to connect on a different path, or need to hold a reference to the `Socket.IO socket` object for use elsewhere.
132
133```javascript
134angular.module('myApp', [
135  'btford.socket-io'
136]).
137factory('mySocket', function (socketFactory) {
138  var myIoSocket = io.connect('/some/path');
139
140  mySocket = socketFactory({
141    ioSocket: myIoSocket
142  });
143
144  return mySocket;
145});
146```
147
148### `socketFactory({ scope: })`
149
150This option allows you to set the scope on which `$broadcast` is forwarded to when using the `forward` method.
151It defaults to `$rootScope`.
152
153
154### `socketFactory({ prefix: })`
155
156The default prefix is `socket:`.
157
158
159#### Example
160
161To remove the prefix:
162
163```javascript
164angular.module('myApp', [
165  'btford.socket-io'
166]).
167config(function (socketProvider) {
168  socketProvider.prefix('');
169});
170```
171
172
173
174## Migrating from 0.2 to 0.3
175
176`angular-socket-io` version `0.3` changes X to make fewer assumptions
177about the lifecycle of the socket. Previously, the assumption was that your
178application has a single socket created at config time. While this holds
179for most apps I've seen, there's no reason you shouldn't be able to
180lazily create sockets, or have multiple connections.
181
182In `0.2`, `angular-socket-io` exposed a `socket` service. In `0.3`, it
183instead exposes a `socketFactory` service which returns socket instances.
184Thus, getting the old API is as simple as making your own `socket` service
185with `socketFactory`. The examples below demonstrate how to do this.
186
187### Simple Example
188
189In most cases, adding the following to your app should suffice:
190
191```javascript
192// ...
193factory('socket', function (socketFactory) {
194  return socketFactory();
195});
196// ...
197```
198
199### Example with Configuration
200
201Before:
202
203```javascript
204angular.module('myApp', [
205  'btford.socket-io'
206]).
207config(function (socketProvider) {
208  socketProvider.prefix('foo~');
209  socketProvider.ioSocket(io.connect('/some/path'));
210}).
211controller('MyCtrl', function (socket) {
212  socket.on('foo~bar', function () {
213    $scope.bar = true;
214  });
215});
216```
217
218After:
219
220```javascript
221angular.module('myApp', [
222  'btford.socket-io'
223]).
224factory('socket', function (socketFactory) {
225  return socketFactory({
226    prefix: 'foo~',
227    ioSocket: io.connect('/some/path')
228  });
229}).
230controller('MyCtrl', function (socket) {
231  socket.on('foo~bar', function () {
232    $scope.bar = true;
233  });
234});
235```
236
237
238## FAQ
239
240[Closed issues labelled `FAQ`](https://github.com/btford/angular-socket-io/issues?labels=faq&page=1&state=closed) might have the answer to your question.
241
242
243## See Also
244
245* [ngSocket](https://github.com/jeffbcross/ngSocket)
246* [angular-socket.io-mock](https://github.com/nullivex/angular-socket.io-mock)
247
248
249## License
250MIT