SignalR JS Client

SignalR JavaScript Client (Persistent Connections)

The SignalR JavaScript client comes in the form of a jQuery plugin.

Setup

Include the following scripts on your page:

<script src="Scripts/jquery-1.6.4.min.js" type="text/javascript"></script>
<script src="Scripts/jquery.signalR.min.js" type="text/javascript"></script>

NOTE: In an MVC application use Url.Content to reference scripts.

Programming Model

$.connection( url )

Creates a new connection.

• Returns a connection.

Example

var connection = $.connection('/echo');

connection.received( handler(data) )

• handler(data) - A function to execute each time data is received.

• Returns a connection.

• NOTE: data is a JSON object

Example

connection.received(function(data) {
    console.log(data);
});

connection.error( handler(error) )

• handler(error) - A function to execute each time an error occurs.

• Returns a connection.

Example

connection.error(function(error) {
    console.warn(error);
});

connection.stateChanged( handler(change) )

• handler() - A function to execute each time the connection state changes.

• Returns a connection.

Example

connection.stateChanged(function (change) {
    if (change.newState === $.signalR.connectionState.reconnecting) {
        console.log('Re-connecting');
    }
    else if (change.newState === $.signalR.connectionState.connected) {
        console.log('The server is online');
    } 
});

connection.reconnected( handler() )

• handler() - A function to execute each time the connection has successfully reconnected.

• Returns a connection.

Example

connection.reconnected(function() {
    console.log('Reconnected');
});

connection.starting( handler )

• handler - A function to execute before the transport establishes a connection to the server.

connection.start()

Starts the connection using the default settings.

• Returns a deferred.

• NOTE: A connection cannot send or receive messages until the start method has been called and the connection successfully established.

Example

connection.start();

connection.start( callback )

Starts the connection using the default settings and executes the passed callback once the connection has been established.

• callback - A callback function to invoke when the connection has been successfully established.**

Example

connection.start(function() {
    console.log("connection started!");
});

connection.stop();

// The callback will be raised again!
connection.start();

NOTE: This callback attaches an event handler that will be raised every time the connection is started. This means that subsequent calls to start raise the callback. To avoid this, see below.

Example

// This callback will only run once
connection.start().done(function() {
    console.log("connection started!");
});

connection.start( settings )

Starts the connection using the passed settings.

• settings - A set of key value pairs that configure the connection. All settings are optional.
  • transport - Details of the transport to use. Can be a known transport name (that maps to a member on signalR.transports), a transport object, or an array of each. If an array, each transport will be tried until one succeeds or all fail. Defaults to "auto", which will try all transports on signalR.transports until one succeeds or all fail.
  • callback - A callback function to invoke when the connection has been successfully established. Defaults to undefined (no callback).
  • waitForPageLoad - Determines if SignalR should wait until the page is entirely loaded to start the connection (defaults to true).

NOTE: If you are loading the SignalR JavaScript client asynchronously after page load, set waitForPageLoad to false (Required for 0.5.3).

Example

// Only try longPolling, by name  
connection.start({ transport: 'longPolling' });

// Only try webSockets, by object 
connection.start({ transport: signalR.transports.webSockets }); 

// Try longPolling then webSockets  
connection.start({ transport: ['longPolling','webSockets'] });

// Auto select transport and start connection immediately  
connection.start({ waitForPageLoad: false });

connection.start( settings, callback )

Starts the connection using the passed settings, and executes the passed callback once the connection has been established.

• settings - A set of key value pairs that configure the connection. All settings are optional.
  • transport - Details of the transport to use. Can be a known transport name, a transport object, or an array of each. If an array, each transport will be tried until one succeeds or all fail. Defaults to "auto", which will try all transports on signalR.transports until one succeeds or all fail.
  • callback - A callback function to invoke when the connection has been successfully established.
  • waitForPageLoad - Determines if SignalR should wait until the page is entirely loaded to start the connection (defaults to true).
• callback A callback function to invoke when the connection has been successfully established.

NOTE: If you are loading the SignalR JavaScript client asynchronously after page load, set waitForPageLoad to false (Required for 0.5.3).

Example

connection.start({ transport: 'longPolling' }, function() {
    console.log('connection started!');
});

connection.stop()

Stops the connection.

connection.stop();

connection.send( data )

• data - data to send over the connection.

Example

connection.send("Hello World");

connection.id

• Gets or sets the client id for the current connection.

connection.messageId

• Gets or sets the message id for the current connection.

Cross Domain Support

You can talk to SignalR servers via the jsonp transport or by using cors (not supported by all browsers).

Cross domain urls are auto detected. We'll use xhr by default if the client (your browser) supports it. Otherwise it'll fall back to jsonp longpolling.

var connection = $.connection('http://localhost:8081/echo');

connection.start();

To use jsonp longpolling, you can specify that option explicitly:

var connection = $.connection('http://localhost:8081/echo');

connection.start({jsonp: true});