JetFault / sails.io.js

Browser SDK for communicating w/ Sails via sockets

Sails JavaScript Client SDK

   

JavaScript SDK for communicating w/ Sails via sockets from Node.js or the browser.

========================================

Contents

	Jump to...
I	Browser
II	Node.js
III	Version Notes
IV	License

========================================

For the Browser

Installation

$ bower install sails.io.js

Basic Usage

    <!-- .... -->
  </body>
  <script type="text/javascript" src="./path/to/bower_components/sails.io.js"></script>
  <script type="text/javascript">
  
    // `io` is available as a global.
    // `io.socket` will connect automatically, but it is not ready yet (think of $(document).ready() from jQuery).
    // Fortunately, this library provides an abstraction to avoid this issue.
    // Requests you make before `io` is ready will be queued and replayed automatically when the socket connects.
    // To disable this behavior or configure other things, you can set properties on `io`.
    // You have one cycle of the event loop to change `io` settings before the auto-connection behavior starts.
    
    io.socket.get('/hello', function serverResponded (body, sailsResponseObject) {
      
      // body === sailsResponseObject.body
      console.log('Sails responded with: ', body);
      console.log('with headers: ', sailsResponseObject.headers);
      console.log('and with status code: ', sailsResponseObject.statusCode);
    });
  </script>
</html>

========================================

For Node.js

Why would I use this from a Node script?

Most commonly, this SDK is useful on the backend when writing tests. However, any time you'd want to use a WebSocket or Socket.io client from Node to talk to a Sails server, you can use this module to allow for the ordinary usage you're familiar with in the browser-- namely using the socket interpreter to simulate HTTP over WebSockets.

Installation

$ npm install socket.io-client
$ npm install sails.io.js

Basic Usage

var socketIOClient = require('socket.io-client');
var sailsIOClient = require('sails.io.js');

// Instantiate the socket client (`io`)
// (for now, you must explicitly pass in the socket.io client when using this library from Node.js)
var io = sailsIOClient(socketIOClient);

// Set some options:
// (you have to specify the host and port of the Sails backend when using this library from Node.js)
io.sails.url = 'http://localhost:1337';
// ...

// Send a GET request to `http://localhost:1337/hello`:
io.socket.get('/hello', function serverResponded (body, sailsResponseObject) {
  // body === sailsResponseObject.body
  console.log('Sails responded with: ', body);
  console.log('with headers: ', sailsResponseObject.headers);
  console.log('and with status code: ', sailsResponseObject.statusCode);
  
  // When you are finished with `io.socket`, or any other sockets you connect manually,
  // you should make sure and disconnect them, e.g.:
  io.socket.disconnect();
  
  // (note that there is no callback argument to the `.disconnect` method)
});

See the tests in this repository for more examples.

========================================

Version

This repository holds the socket client SDK for Sails versions 0.10.0 and up. If you're looking for the SDK for the v0.9.x releases of Sails, the source is located here.

========================================

License

MIT © 2014 Mike McNeil, Balderdash & contributors

This module is part of the Sails framework, and is free and open-source under the MIT License.