Creating a real-time widget

Transferring your JavaScript skills to server-side programming is simplified with this comprehensive cookbook. Each chapter focuses on a different aspect of Node, featuring recipes supported with lots of illustrations, tips, and hints.

(For more resources related to this topic, see here.)

The configuration options and well thought out methods of make for a highly versatile library. Let's explore the dexterity of by creating a real-time widget that can be placed on any website and instantly interfacing it with a remote Socket.IO server. We're doing this to begin providing a constantly updated total of all users currently on the site. We'll name it the live online counter (loc for short).

Our widget is for public consumption and should require only basic knowledge, so we want a very simple interface. Loading our widget through a script tag and then initializing the widget with a prefabricated init method would be ideal (this allows us to predefine properties before initialization if necessary).

Getting ready

We'll need to create a new folder with some new files: widget_server.js, widget_client.js, server.js, and index.html.

How to do it...

Let's create the index.html file to define the kind of interface we want as follows:

<html> <head> <style> #_loc {color:blue;} /* widget customization */ </style> </head> <body> <h1> My Web Page </h1> <script src = http://localhost:8081 > </script> <script> locWidget.init(); </script> </body> </html>

The localhost:8081 domain is where we'll be serving a concatenated script of both the client-side code and our own widget code.

By default, Socket.IO hosts its client-side library over HTTP while simultaneously providing a WebSocket server at the same address, in this case localhost:8081. See the There's more… section for tips on how to configure this behavior.

Let's create our widget code, saving it as widget_client.js:

;(function() { window.locWidget = { style : 'position:absolute;bottom:0;right:0;font-size:3em', init : function () { var socket = io.connect('http://localhost:8081'), style =; socket.on('connect', function () { var head = document.head, body = document.body, loc = document.getElementById('_lo_count'); if (!loc) { head.innerHTML += '<style>#_loc{' + style + '}</style>'; loc = document.createElement('div'); = '_loc'; loc.innerHTML = '<span id=_lo_count></span>'; body.appendChild(loc); } socket.on('total', function (total) { loc.innerHTML = total; }); }); } } }());

We need to test our widget from multiple domains. We'll just implement a quick HTTP server (server.js) to serve index.html so we can access it by and http://localhost:8080, as shown in the following code:

var http = require('http'); var fs = require('fs'); var clientHtml = fs.readFileSync('index.html'); http.createServer(function (request, response) { response.writeHead(200, {'Content-type' : 'text/html'}); response.end(clientHtml); }).listen(8080);

Finally, for the server for our widget, we write the following code in the widget_server.js file:

var io = require('')(), totals = {}, clientScript = Buffer.concat([ require('').source, require('fs').readFileSync('widget_client.js') ]); io.static(false); io.attach(require('http').createServer(function(req, res){ res.setHeader('Content-Type', 'text/javascript; charset=utf-8'); res.write(sioclient.source); res.write(widgetScript); res.end(); }).listen(8081)); io.on('connection', function (socket) { var origin = socket.request.socket.domain || 'local'; totals[origin] = totals[origin] || 0; totals[origin] += 1; socket.join(origin);'total', totals[origin]); socket.on('disconnect', function () { totals[origin] -= 1;'total', totals[origin]); }); });

To test it, we need two terminals; in the first one, we execute the following command:

node widget_server.js

In the other terminal, we execute the following command:

node server.js

We point our browser to http://localhost:8080 by opening a new tab or window and navigating to http://localhost:8080. Again, we will see the counter rise by one. If we close either window, it will drop by one. We can also navigate to to emulate a separate origin. The counter at this address is independent from the counter at http://localhost:8080.

How it works...

The widget_server.js file is the powerhouse of this recipe. We start by using require with and calling it (note the empty parentheses following require); this becomes our io instance. Under this is our totals object; we'll be using this later to store the total number of connected clients for each domain.

Next, we create our clientScript variable; it contains both the client code and our widget_client.js code. We'll be serving this to all HTTP requests. Both scripts are stored as buffers, not strings. We could simply concatenate them with the plus (+) operator; however, this would force a string conversion first, so we use Buffer.concat instead. Anything that is passed to res.write or res.end is converted to a Buffer before being sent across the wire. Using the Buffer.concat method means our data stays in buffer format the whole way through instead of being a buffer, then a string then a buffer again.

When we require at the top of widget_server.js, we call it to create an io instance. Usually, at this point, we would pass in an HTTP server instance or else a port number, and optionally pass in an options object.

To keep our top variables tidy, however, we use some configuration methods available on the io instance after all our requires. The io.static(false) call prevents from providing its client-side code (because we're providing our own concatenated script file that contains both the client-side code and our widget code).

Then we use the io.attach call to hook up our server with an HTTP server. All requests that use the http:// protocol will be handled by the server we pass to io.attach, and all ws:// protocols will be handled by (whether or not the browser supports the ws:// protocol).

We're only using the http module once, so we require it within the io.attach call; we use it's createServer method to serve all requests with our clientScript variable.

Now, the stage is set for the actual socket action. We wait for a connection by listening for the connection event on io.sockets. Inside the event handler, we use a few as yet undiscussed qualities.

WebSocket is formed when a client initiates a handshake request over HTTP and the server responds affirmatively. We can access the original request object with socket.request. The request object itself has a socket (this is the underlying HTTP socket, not our socket; we can access this via socket.request.socket. The socket contains the domain a client request came from. We load socket.request.socket.domain into our origin object unless it's null or undefined, in which case we say the origin is 'local'.

We extract (and simplify) the origin object because it allows us to distinguish between websites that use a widget, enabling site-specific counts.

To keep count, we use our totals object and add a property for every new origin object with an initial value of 0. On each connection, we add 1 to totals[origin] while listening to our socket; for the disconnect event, we subtract 1 from totals[origin].

If these values were exclusively for server use, our solution would be complete. However, we need a way to communicate the total connections to the client, but on a site by site basis.

Socket.IO has had a handy new feature since Socket.IO version 0.7 that allows us to group sockets into rooms by using the socket.join method. We cause each socket to join a room named after its origin, then we use the method to instruct to only emit to sockets that belongs to the originating sites room.

In both the io.sockets connection and socket disconnect events, we emit our specific totals to corresponding sockets to update each client with the total number of connections to the site the user is on.

The widget_client.js file simply creates a div element called #_loc and updates it with any new totals it receives from widget_server.js.

There's more...

Let's look at how our app could be made more scalable, as well as looking at another use for WebSockets.

Preparing for scalability

If we were to serve thousands of websites, we would need scalable memory storage, and Redis would be a perfect fit. It operates in memory but also allows us to scale across multiple servers.

We'll need Redis installed along with the Redis module.

We'll alter our totals variable so it contains a Redis client instead of a JavaScript object:

var io = require('')(), totals = require('redis').createClient(), //other variables

Now, we modify our connection event handler as shown in the following code:

io.sockets.on('connection', function (socket) { var origin = (socket.handshake.xdomain) ? url.parse(socket.handshake.headers.origin).hostname : 'local'; socket.join(origin); totals.incr(origin, function (err, total) {'total', total); }); socket.on('disconnect', function () { totals.decr(origin, function (err, total) {'total', total); }); }); });

Instead of adding 1 to totals[origin], we use the Redis INCR command to increment a Redis key named after origin. Redis automatically creates the key if it doesn't exist. When a client disconnects, we do the reverse and readjust totals using DECR.

WebSockets as a development tool

When developing a website, we often change something small in our editor, upload our file (if necessary), refresh the browser, and wait to see the results. What if the browser would refresh automatically whenever we saved any file relevant to our site?

We can achieve this with the method and WebSockets. The method monitors a directory, executing a callback whenever a change to any files in the folder occurs (but it doesn't monitor subfolders).

The method is dependent on the operating system. To date, has also been historically buggy (mostly under Mac OS X). Therefore, until further advancements, is suited purely to development environments rather than production (you can monitor how is doing by viewing the open and closed issues at

Our development tool could be used alongside any framework, from PHP to static files.

For the server counterpart of our tool, we'll configure watcher.js:

var io = require('')(), fs = require('fs'), totals = {}, watcher = function () { var socket = io.connect('ws://localhost:8081'); socket.on('update', function () { location.reload(); }); }, clientScript = Buffer.concat([ require('').source, Buffer(';(' + watcher + '());') ]); io.static(false); io.attach(require('http').createServer(function(req, res){ res.setHeader('Content-Type', 'text/javascript; charset=utf-8'); res.end(clientScript); }).listen(8081));'content', function (e, f) { if (f[0] !== '.') { io.sockets.emit('update'); } });

Most of this code is familiar. We make a server (on a different port to avoid clashing), generate a concatenated plus client-side watcher code file, and deliver it via our attached server. Since this is a quick tool for our own development uses, our client-side code is written as a normal JavaScript function (our watcher variable), converted to a string while wrapping it in self-calling function code, and then changed to Buffer so it's compatible with Buffer.concat.

The last piece of code calls the method where the callback receives the event name (e) and the filename (f).

We check that the filename isn't a hidden dotfile. During a save event, some filesystems or editors will change the hidden files in the directory, thus triggering multiple callbacks and sending several messages at high speed, which can cause issues for the browser.

To use it, we simply place it as a script within every page that is served (probably using server-side templating). However, for demonstration purposes, we simply place the following code into content/index.html:

<script src = http://localhost:8081/ > </script>

Once we fire up server.js and watcher.js, we can point our browser to http://localhost:8080 and see the familiar excited Yay!. Any changes we make and save (either to index.html, styles.css, script.js, or the addition of new files) will be almost instantly reflected in the browser. The first change we can make is to get rid of the alert box in the script.js file so that the changes can be seen fluidly.


We saw how we could create a real-time widget in this article. We also used some third-party modules to explore some of the potential of the powerful combination of Node and WebSockets.

Resources for Article:

Further resources on this subject:

Books to Consider

comments powered by Disqus

An Introduction to 3D Printing

Explore the future of manufacturing and design  - read our guide to 3d printing for free