PageRenderTime 24ms CodeModel.GetById 18ms RepoModel.GetById 1ms app.codeStats 0ms

/Pi-GPIO-Server-master/pi_gpio/static/bower_components/angular-socket-io/README.md

https://gitlab.com/rickyvaughn2/Pi-GPIO-Server
Markdown | 243 lines | 180 code | 63 blank | 0 comment | 0 complexity | cc61fb357c29c882d413b9e41bfe5e0a MD5 | raw file
  1. # angular-socket-io [![Build Status](https://travis-ci.org/btford/angular-socket-io.png)](https://travis-ci.org/btford/angular-socket-io)
  2. Bower Component for using AngularJS with [Socket.IO](http://socket.io/),
  3. based on [this](http://briantford.com/blog/angular-socket-io.html).
  4. ## Install
  5. 1. `bower install angular-socket-io` or [download the zip](https://github.com/btford/angular-socket-io/archive/master.zip).
  6. 2. Make sure the Socket.IO client lib is loaded. It's often served at `/socket.io/socket.io.js`.
  7. 3. Include the `socket.js` script provided by this component into your app.
  8. 4. Add `btford.socket-io` as a module dependency to your app.
  9. ## Usage
  10. This module exposes a `socketFactory`, which is an API for instantiating
  11. sockets that are integrated with Angular's digest cycle.
  12. ### Making a Socket Instance
  13. ```javascript
  14. // in the top-level module of the app
  15. angular.module('myApp', [
  16. 'btford.socket-io',
  17. 'myApp.MyCtrl'
  18. ]).
  19. factory('mySocket', function (socketFactory) {
  20. return socketFactory();
  21. });
  22. ```
  23. With that, you can inject your `mySocket` service into controllers and
  24. other serivices within your application!
  25. ### Using Your Socket Instance
  26. Building on the example above:
  27. ```javascript
  28. // in the top-level module of the app
  29. angular.module('myApp', [
  30. 'btford.socket-io',
  31. 'myApp.MyCtrl'
  32. ]).
  33. factory('mySocket', function (socketFactory) {
  34. return socketFactory();
  35. }).
  36. controller('MyCtrl', function (mySocket) {
  37. // ...
  38. });
  39. ```
  40. ## API
  41. For the most part, this component works exactly like you would expect.
  42. The 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).
  43. ### `socket.on` / `socket.addListener`
  44. Takes an event name and callback.
  45. Works just like the method of the same name from Socket.IO.
  46. ### `socket.removeListener`
  47. Takes an event name and callback.
  48. Works just like the method of the same name from Socket.IO.
  49. ### `socket.removeAllListeners`
  50. Takes an event name.
  51. Works just like the method of the same name from Socket.IO.
  52. ### `socket.emit`
  53. Sends a message to the server.
  54. Optionally takes a callback.
  55. Works just like the method of the same name from Socket.IO.
  56. ### `socket.forward`
  57. `socket.forward` allows you to forward the events received by Socket.IO's socket to AngularJS's event system.
  58. You can then listen to the event with `$scope.$on`.
  59. By default, socket-forwarded events are namespaced with `socket:`.
  60. The first argument is a string or array of strings listing the event names to be forwarded.
  61. The second argument is optional, and is the scope on which the events are to be broadcast.
  62. If an argument is not provided, it defaults to `$rootScope`.
  63. As a reminder, broadcasted events are propagated down to descendant scopes.
  64. #### Examples
  65. An easy way to make socket error events available across your app:
  66. ```javascript
  67. // in the top-level module of the app
  68. angular.module('myApp', [
  69. 'btford.socket-io',
  70. 'myApp.MyCtrl'
  71. ]).
  72. factory('mySocket', function (socketFactory) {
  73. var mySocket = socketFactory();
  74. mySocket.forward('error');
  75. return mySocket;
  76. });
  77. // in one of your controllers
  78. angular.module('myApp.MyCtrl', []).
  79. controller('MyCtrl', function ($scope) {
  80. $scope.$on('socket:error', function (ev, data) {
  81. });
  82. });
  83. ```
  84. Avoid duplicating event handlers when a user navigates back and forth between routes:
  85. ```javascript
  86. angular.module('myMod', ['btford.socket-io']).
  87. controller('MyCtrl', function ($scope, socket) {
  88. socket.forward('someEvent', $scope);
  89. $scope.$on('socket:someEvent', function (ev, data) {
  90. $scope.theData = data;
  91. });
  92. });
  93. ```
  94. ### `socketFactory({ ioSocket: }}`
  95. This option allows you to provide the `socket` service with a `Socket.IO socket` object to be used internally.
  96. This 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.
  97. ```javascript
  98. angular.module('myApp', [
  99. 'btford.socket-io'
  100. ]).
  101. factory('mySocket', function (socketFactory) {
  102. var myIoSocket = io.connect('/some/path');
  103. mySocket = socketFactory({
  104. ioSocket: myIoSocket
  105. });
  106. return mySocket;
  107. });
  108. ```
  109. ### `socketFactory({ scope: })`
  110. This option allows you to set the scope on which `$broadcast` is forwarded to when using the `forward` method.
  111. It defaults to `$rootScope`.
  112. ### `socketFactory({ prefix: })`
  113. The default prefix is `socket:`.
  114. #### Example
  115. To remove the prefix:
  116. ```javascript
  117. angular.module('myApp', [
  118. 'btford.socket-io'
  119. ]).
  120. config(function (socketProvider) {
  121. socketProvider.prefix('');
  122. });
  123. ```
  124. ## Migrating from 0.2 to 0.3
  125. `angular-socket-io` version `0.3` changes X to make fewer assumptions
  126. about the lifecycle of the socket. Previously, the assumption was that your
  127. application has a single socket created at config time. While this holds
  128. for most apps I've seen, there's no reason you shouldn't be able to
  129. lazily create sockets, or have multiple connections.
  130. In `0.2`, `angular-socket-io` exposed a `socket` service. In `0.3`, it
  131. instead exposes a `socketFactory` service which returns socket instances.
  132. Thus, getting the old API is as simple as making your own `socket` service
  133. with `socketFactory`. The examples below demonstrate how to do this.
  134. ### Simple Example
  135. In most cases, adding the following to your app should suffice:
  136. ```javascript
  137. // ...
  138. factory('socket', function (socketFactory) {
  139. return socketFactory();
  140. });
  141. // ...
  142. ```
  143. ### Example with Configuration
  144. Before:
  145. ```javascript
  146. angular.module('myApp', [
  147. 'btford.socket-io'
  148. ]).
  149. config(function (socketProvider) {
  150. socketProvider.prefix('foo~');
  151. socketProvider.ioSocket(io.connect('/some/path'));
  152. }).
  153. controller('MyCtrl', function (socket) {
  154. socket.on('foo~bar', function () {
  155. $scope.bar = true;
  156. });
  157. });
  158. ```
  159. After:
  160. ```javascript
  161. angular.module('myApp', [
  162. 'btford.socket-io'
  163. ]).
  164. factory('socket', function (socketFactory) {
  165. return socketFactory({
  166. prefix: 'foo~',
  167. ioSocket: io.connect('/some/path')
  168. });
  169. }).
  170. controller('MyCtrl', function (socket) {
  171. socket.on('foo~bar', function () {
  172. $scope.bar = true;
  173. });
  174. });
  175. ```
  176. ## See Also
  177. * [ngSocket](https://github.com/jeffbcross/ngSocket)
  178. * [angular-socket.io-mock](https://github.com/nullivex/angular-socket.io-mock)
  179. ## License
  180. MIT