WebSync Tutorials - Frozen Mountain
Note: these tuturials are for WebSync 2 only.

If you are using WebSync 3, you want our WebSync 3 tutorials.

WebSync 2 Tutorials


On-Demand:
Basic
Meta
Proxies
Publishers
Advanced
   Server:
Basic
Events
Advanced


Server: Basic

In this tutorial you will learn how to integrate WebSync Server into your projects.

Configuring your project

Before you can start coding, you need to have the correct project references.
  1. Add a reference to FM.WebSync.Server (available as part of the WebSync Server downloads).

Exposing the client handler

The JavaScript client is embedded in FM.WebSync.Server. To expose it, we have to add an HTTP handler.
  1. Add a handler to configuration/system.web/httpHandlers in Web.config for IIS6 and IIS7 in Classic mode.
  2. Add a handler to configuration/system.webServer/handlers in Web.config for IIS7 in Integrated mode. 
<configuration>
<system.web>
    <httpHandlers>
        <!-- IIS6 and IIS7 Classic -->
        <add verb="GET,POST" path="client.ashx" type="FM.WebSync.Server.ClientHandler" />
    </httpHandlers>
</system.web>
<system.webServer>
    <handlers>
        <!-- IIS7 Integrated -->
        <add name="ClientHandler" preCondition="integratedMode"
             verb="GET,POST" path="client.ashx" type="FM.WebSync.Server.ClientHandler" />
    </handlers>
</system.webServer>
</configuration>
After adding the handler entries, client.ashx should return the JavaScript client.

Creating the request handler

One other handler needs to be set up - the request handler. This handler is different from the client handler in that it has a code file representation in your project's namespace.
  1. Create a class named RequestHandler and inherit from FM.WebSync.Server.Handler.
using FM.WebSync.Server;

namespace Tutorials
{
    [HandlerProvider(ProviderType.Basic)]
    public class RequestHandler : Handler<RequestHandler>
    {
    }
}
The next step is exposing the newly created request handler.

Exposing the request handler

To expose the request handler, we will add Web.config entries again.
  1. Add a handler to configuration/system.web/httpHandlers in Web.config for IIS6 and IIS7 in Classic mode.
  2. Add a handler to configuration/system.webServer/handlers in Web.config for IIS7 in Integrated mode. 
<configuration>
<system.web>
    <httpHandlers>
        <!-- IIS6 and IIS7 Classic -->
        <add verb="GET,POST" path="request.ashx" type="Tutorials.RequestHandler" />
    </httpHandlers>
</system.web>
<system.webServer>
    <handlers>
        <!-- IIS7 Integrated -->
        <add name="RequestHandler" preCondition="integratedMode"
             verb="GET,POST" path="request.ashx" type="Tutorials.RequestHandler" />
    </handlers>
</system.webServer>
</configuration>
With the request handler exposed, the clients now have a path to direct their requests.

Setting up an HTML page

To get started, we need to create an HTML page to host our JavaScript client.
  1. Create a new HTML page.
  2. Add a reference to the client script in the <head> element.
<head>
...
<script type="text/javascript" src="client.ashx"></script>
...
</head>
Now we can initialize the client and start doing interesting things.

Connecting the client

The first step is to initialize and connect the client.
  1. Add a new <script> element to the page somewhere after the script element we just added.
  2. Call initialize().
  3. Call connect() with optional onSuccess and onFailure handlers.
<body>
    ...
    <script type="text/javascript">
        var client = fm.websync.client; // shortcut
        var util = fm.websync.utilities; // shortcut
        
        client.initialize();
        
        client.connect({
            onSuccess: function(args) { // optional
                util.log('Connected!', true);
            },
            onFailure: function(args) { // optional
                util.log('Connect failed: ' + args.error, true);
            }
        });
    </script>
    ...
</body>
Ensure you pass in the correct public key for your domain.

Subscribing and publishing

Now that the client is connected, it can subscribe to channels and publish data.
  1. Call subscribe() with an onReceive handler and optional onSuccess and onFailure handlers.
  2. Call publish() with optional onSuccess and onFailure handlers.
<body>
    ...
    <script type="text/javascript">
        // ... continued from above
        
        var json = fm.websync.utilities.json; // shortcut
        
        client.subscribe({
            channel: '/test',
            onSuccess: function(args) { // optional
                util.log('Subscribed!', true);
            },
            onFailure: function(args) { // optional
                util.log('Subscribe failed: ' + args.error, true);
            },
            onReceive: function(args) {
                util.log('Received data: ' + json.stringify(args.data), true);
            }
        });
        
        function publishData() {
            client.publish({
                channel: '/test',
                data: {
                    text: document.getElementById('text').value
                },
                onSuccess: function(args) { // optional
                    util.log('Published!', true);
                },
                onFailure: function(args) { // optional
                    util.log('Publish failed: ' + args.error, true);
                }
            });
        }
    </script>
    ...
</body>
Since the call to publish() is wrapped in a function, we need a UI element to trigger it.
  1. Add a button that invokes publishData().
<body>
    ...
    <input type="text" id="text" />
    <button onclick="publishData()">Publish</button>
    ...
</body>

Testing

Open the page in a couple web browsers and click Publish a few times to see the synchronization!