SignalR JS Client Hubs

SignalR Javascript Client (Hubs)

Setup

Include the following scripts on your page:

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

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

Automatic Proxy Generation

If you navigate to signalr/hubs in your browser, you'll see a script that is dynamically generated based on the hubs declared on the server. Each hub on the server will become a property on the client side $.connection, e.g. $.connection.myHub.

How it works

SignalR registers some code to run at application start time that finds all hubs in your application. On the first request to signalr/hubs, the proxy is generated and cached for the lifetime of the application.

Programming Model

$.connection.hub

The connection for all hubs (url points to /signalr).

• Returns a connection

$.connection.hub.id

The client id for the hub connection.

$.connection.hub.logging

Set to true to enable logging. Default is false

$.connection.hub.start()

Starts the connection for all hubs.

• See other overloads to start()
• Returns jQuery deferred

Example

$.connection.hub.start()
.done(function(){ alert("Now connected!"); })
.fail(function(){ alert("Could not Connect!"); });

$.connection.{hubname}

Access a client side hub from the generated proxy.

• Returns a Hub.
• hubname - Name of the hub on the server.
• NOTE: The name of the hub is camel cased (i.e. if the server Hub is MyHub the property on connection will be myHub)

Example

var myHub = $.connection.myHub;

Exposing methods on the client for the server to invoke

The javascript client can declare methods that the server can invoke. To expose these methods, declare a function on the client side hub.

• NOTE: The function on the client side hub cannot be a method that exists on the server hub (i.e. if the server has a method called Send, you cannot define a client event called send).

myHub.client.{method} = callback

Declares a function the server can invoke.

• method - name of the client side method.

• callback - A function to execute when the server invokes the method.

• NOTE: In the callback, this points to the hub instance.

• NOTE: if you misspell you will NOT get any warning or notifications even when logging is enabled.

• NOTE: Unlike the name change in myHub, the function names here at the same as you call in Server code.

Example

 myHub.client.addMessage = function(value) {
    console.log('Server called addMessage(' + value + ')');
};

Round-tripping state

To set state on the hub. Just assign values to properties on the hub object:

myHub.state.name = "David";

Whenever a call to the hub the state will be sent to the server.

Similarly, you can access state set on the server using myHub.property:

var age = myHub.state.age;

Invoking methods on the server

The proxy will generate methods on each hub for the associated server methods. You can invoke these methods to call a server side hub method.

• Returns jQuery deferred
• NOTE: Method names will be camel cased similarly to hub names

Example

myHub.server.someMethod()
     .done(function(result) {
     })
     .fail(function(error) {
     });

Complete example

$.connection.hub.logging = true;

var myHub = $.connection.myHub;
myHub.state.someState = "SomeValue";

function connectionReady() {
    alert("Done calling first hub serverside-function");
};

myHub.client.SomeClientFunction = function() {
    alert("serverside called 'Clients.SomeClientFunction()'");
};

$.connection.hub.error(function() {
    alert("An error occured");
});

$.connection.hub.start()
                .done(function() {
                    myHub.server.SomeFunction(SomeParam) //e.g. a login or init
                         .done(connectionReady); 
                })
                .fail(function() {
                    alert("Could not Connect!");
                 });

Cross Domain Support

You can talk to SignalR servers either using websockets, cors enabled longpolling (not supported by all browsers) or jsonp longpolling.

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.

$.connection.hub.url = 'http://localhost:8081/signalr'

$.connection.hub.start();

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

$.connection.hub.url = 'http://localhost:8081/signalr'

$.connection.hub.start({jsonp: true});