Monday, September 30, 2013

Free WebSocket JavaScript Code and Tutorial

Visit the High Level Logic (HLL) Website
— Home of XPL (eXtensible Process Language)

It's like XML, but you can store source code in it.

By Roger F. Gay

WebSockets are finally coming of age. Implemented in most major browsers and promised soon by Microsoft, developers are itching to use native bidirectional (full-duplex) communication within their browser applications. No more cranky bloated work-arounds to do what obviously needs to be done in order to use browsers as a real application GUI. Along with that, comes a host of new functionality with HTML 5 and the already popular tricks of CSS 3.

Yet, because WebSockets are still quite new to most developers, the technology and how it is used still seems a bit mysterious to many. This tutorial should help lift the fog around what WebSockets are and how to use them in browser applications. All the JavaScript code in this tutorial is free and without registration. You will even have access to a live HLL WebSocket server to try it out on your own. (Note: Server is temporarily down.) If you've not yet learned to use WebSockets in browser apps, it's likely a lot easier than you think.

So, briefly, what the heck is a WebSocket anyway? Let's review a tiny bit of compressed history just to put things in context. Don't worry, you won't be tested on this section. Hopefully, you'll just find it a bit interesting and informative.

You've heard of HTTP. Functionally, that's when you click on a button and then sit and wait for a response while your browser is locked up. Then came AJAX, which solved the lock-up problem without ever leaving the world of point and click; also known as “request-response.” Request-response is the pattern you find in the vast majority of existing web pages. You click on something to get a response. You don't get information from the server unless you click to update. What if the server wants to send you some information without waiting for you to ask?

The desire to let the server communicate more freely has been so strong that there have been work-arounds for what became known as “push” technology. Still relying on HTTP, it was a trick. "Long-polling" is one of the techniques used to "push" information to browsers. The browser page is set-up to send a request to the server via AJAX. Then it just waits for a response. AJAX doesn't lock up the browser. You can continue to play in the page while AJAX waits. But you don't really need to do anything. Examples include email message notifications and stock price trackers that do not require that you click in order to update.

But enough goofing around, a group of developers finally said. Old-fashioned push work-arounds are inefficient and often cranky. What we really need is full-duplex that's easy for every app developer to use. That means browsers can receive messages from the server at any time, even if the browser is sending messages at the same time. Besides that, we can do this in a way that is much more efficient than old-fashioned HTTP. That latter consideration is a sign of our age. People care a lot nowadays about the amount of data being shipped around, and the efficiency of communication processes, much of which is wasteful. We just don't need repeated HTTP connections to maintain a communication channel. We can also implement message passing more efficiently. That's what they did with WebSockets.

Messages go either way at any time. So, for example, if you want to build a multi-player game in a browser, you can get updates based on what other players are doing at any time. No cranky bloat-ware work-arounds to get it done and no need to install special software on your own computer. WebSockets are supported directly by browsers. You have a browser installed on a variety of different devices, not just your PC. If it's up-to-date with WebSocket support, you're ready to go. And your small devices will love you for the efficiency of WebSocket technology. Faster action, less energy use, less heat.

Besides this tutorial, you can also look at a running demonstration in a more complex web page by following the link of my two year old blog article on the original HLL WebSocket demo. When you get to the demo, you can click “Download HTML source code” at the top if you wish, but the demo code you find there needs to be run under an http server. And you can look at my previous article running a simple game using the HLL WebSocket server to drive one of the game characters. Christian verses Flying Spaghetti Monster - HTML 5 Games, WebSockets, and AI

The part of any of the demos that actually addresses WebSocket communication is very similar to the tutorial code. It's always that way. It doesn't matter where you get your JavaScript code or how it's built into development tools and frameworks. Browsers do the technical heavy lifting. Application developers use the browser's capabilities through a few simple-to-use methods.

OK, so let's get to the meat of the tutorial. I'm going to show you how to set-up the JavaScript in any browser application to make use of WebSockets. I'll give you all the code in this tutorial. I'll give you the direct explanation and you should see how really simple it is. The full code for this tutorial is here. You can simply copy-paste it into a text editor and save it to your computer using a name with an .htm or .html extension (Windows: File Type "All Files" and explicitly type the whole file name, including extension) and then click on the file to run it. You should see some text spill out onto the page very quickly.

The tutorial program will automatically connect to the WebSocket server, send a message to it, receive a message from it, and then disconnect. So, basically, it goes through all the basic steps in WebSocket communication, posts messages to you on the html page as it goes along, and then stops. I'll also explain where to alter the code for your application.

Just for completeness, let me explain that the tutorial code is written in HTML 5; that is, any browser with HTML 5 capabilities sees it as such. Here's why.

<!DOCTYPE html>

That's it. Declaring doctype html simply, means to all modern browsers that the code within can be interpreted according to the most up-to-date standard.

Now let's go through the code. At the top of the tutorial application, you'll see a few variables defined and a simple initialization function.

var wsUri = "ws://";
var output;
var websocket;
var connected=false;

function init() {
 output = document.getElementById("output");

wsUri provides the IP address of the HLL WebSocket server used in this tutorial, with its application name “echo”. It will become apparent as we move through the tutorial that the variable “output” is used for printing text to your page, “websocket” is a variable that will be used for the WebSocket object, and “connected” just keeps track of whether we're connected (true) or not (false).

The function init() is automatically called when the page is loaded because of a line of code at the very bottom of the JavaScript section: “window.onload = init;” (When the page is loaded, call init().) init() sets the value of “output” to a <div> at the bottom of the html page. That's where the text will appear. It then calls function “doConnect()” whose name gives away at least part of its purpose. doConnect() is actually simpler than it might first appear. I will explain.

The doConnect() function is the most complicated part of the tutorial; and yet, when you get through it, you'll look back and wonder how it could be so simple. By the time you've finished the tutorial, you'll know why. Scan through it and then read the detailed explanation below.

function doConnect() {
 if (connected) {
   writeToScreen("<span style="color: red;">You're already connected!</span>");
 } else if (typeof MozWebSocket != "undefined") {
   websocket = new MozWebSocket(wsUri);
 } else if (window.WebSocket) {
   websocket = new WebSocket(wsUri);
 } else {
   writeToScreen('<strong style="color: red;">ERROR: This browser does not support WebSockets.</strong>');
 websocket.onopen = function(evt) { onOpen(evt) };
 websocket.onclose = function(evt) { onClose(evt) };
 websocket.onmessage = function(evt) { onMessage(evt) };
 websocket.onerror = function(evt) { onError(evt) };

Within all the conditions, look for “websocket = new WebSocket(wsUri);”. This is how you tell all the most up-to-date browsers to make the connection. As you saw above, the argument “wsUri” is the address of the WebSocket server application. Let me go over the necessary distractions above.

if (connected): I simply want to know first if we're already connected. If we are, the tutorial app says so. No need to connect again.

typeof MozWebSocket: “MozWebSocket” has to do with the integrity of the Mozilla browser team. There are browser versions that support development versions of WebSockets. These don't conform to the final finished standard and as active members in guiding development of the standard they also did some of their own experiments. They didn't want to confuse anyone by calling any of those things WebSockets, so they called them MozWebSockets instead. By leaving this condition in, even some older versions of Firefox should still be able to run the tutorial; but not if they're too old.

if (window.WebSocket): What you're looking for in up-to-date browsers is whether they support standard WebSockets in a standard way and this test can be given simply as “if (window.WebSocket)” (or if ("WebSocket" in window)). If the three tests fail, then the browser doesn't support WebSockets. We could do something then beyond simply sending a strong message about the old browser. We could initiate a fall-back such as long-polling or, perhaps more wisely, provide information about getting an up-to-date browser.

The final four lines in doConnect() are telling your browser session what to do when certain events occur. These events are connection opened, connection closed, message received from server, and error occurs. Each corresponding standard event, onopen, onclose, onmessage, and onerror, is attached to the “websocket” object that was defined just above in “websocket = new WebSocket(wsUri);”. We then specify what “handler functions” are called when each of these events happen. (“Handlers” handle the events … doing whatever you program them to do.)

“websocket.onmessage = function(evt) { onMessage(evt) };” for example, says that says that when a message comes in from the server, call the onmessage event handler function named onMessage(evt). “evt” is an object containing the incoming message.

Once doConnect() is complete, we have a running WebSocket connection, ready to send and receive messages until you close the connection. The tutorial program is set up to automatically run through three more of the events; sending and receiving messages, and closing.

function onOpen(evt) {
  connected = true;
  doSend("WebSocket rocks!");

onOpen(evt) is one of the event handler functions specified in doConnect(). Now that we have attached it to the websocket object, it will be automatically called by the browser when a connection is made. So, when your connection is made, the three things that I have programmed into the tutorial onOpen(evt) function will happen. (In your app, you can program it to do whatever you want it to do.) First, the variable “connected” will be set to true. Second, the word “CONNECTED” will be written so that you will know that you are connected. And third, it will send a text message, “WebSocket rocks!” to the WebSocket server, using the function doSend(). (As far as I know, Kaazing made the phrase “WebSocket rocks!” popular among WebSocket nerds like me. I also believe that Kaazing was the only organization with a final standard WebSocket server before HLL.)

function doSend(message) {
 writeToScreen("SENT: " + message);

doSend() is not a WebSocket event handler. It is a function that sends messages to the server at your command. Call this function (written as you wish) any time you want to send a message to the server. The tutorial function doSend() writes the message for you to see on your web page, and then calls the standard, browser supported websocket.send method with the message as the argument. That's it! That's how messages are sent from browser applications. … send(message);

At the server end of the tutorial application, the response will be a message sent back. I always feel a little funny at this point in the simplest demonstration of WebSockets. This is after all, a request-response pattern that could be done with AJAX. OK, so you can use WebSockets for things that have been done using AJAX. But of course, that's not all you can do. The server can send messages any time that it wants to. The WebSocket onmessage event handler function is always waiting to receive and perform in full-duplex. Nope, AJAX doesn't do that. AJAX is asynchronous HTTP. It needs a request in order to send a response.

function onMessage(evt) {
 writeToScreen('<span style="color: blue;">RESPONSE: ' +'</span>');

The tutorial's onMessage(evt) message event handler function simply writes the message from the server to the browser display, and then it calls the browser method websocket.close(). Note that “evt” is, in this context, an object containing the message from the server. The actual text message is accessed from “”. Again, just to be sure there's no confusion here. Unless you're writing a chat application, you're going to want something different to happen in response to message events. Put whatever application code you need inside the event handlers.

function onClose(evt) {

The browser will understand when the connection has been closed and will automatically call the onclose event handler, onClose(evt), which will simply write “DISCONNECTED” to your browser display.

Hopefully, you've seen all this happen very quickly without ever seeing what onError(evt) does.

function onError(evt) {
 writeToScreen('<span style="color: red;">ERROR:</span> ' +;

If you do get an error, you will be told about it in your browser display, in red text.

Let's summarize and take in how simple this all is. You connect and tell the browser about your event handler functions. You also have a send function that uses the browsers websocket.send() method. When an event occurs, the related event handler functions are automatically called to do whatever you've programmed them to do. As far as browser-side WebSocket communications are concerned; you make the connection and then go about the simple business of sending and receiving messages, at any time, in no particular order, as much as you like. The rest of your coding is application specific.

Wednesday, September 25, 2013

Christian verses Flying Spaghetti Monster - HTML 5 Games, WebSockets, and AI

Visit the High Level Logic (HLL) Website
— Home of XPL (eXtensible Process Language)

It's like XML, but you can store source code in it.

By Roger F. Gay

Three demo games with WebSockets presented; the first is an HLL original. Use WebSockets for multiplayer games, AI from a server, or just because you can (replacing http in some cases).

HLL and HLL WebSockets are ripe for game development. I have so far done a simple proof of concept controlling a Construct 2 sprite via WebSocket, and this article presents a from-scratch HTML 5 PC game with WebSockets. To run it, your browser needs to support HTML 5 and WebSockets. An up-to-date version of Chrome seems to give best results even if your graphics driver might be a bit old. I've also run the demo on up-to-date versions of Firefox and Safari.

My goal in this round of activity is to bring HLL technology to game developers, many of whom are not programmers or spend enough time designing and building games that they just don't need a lot of programming overhead in their process. The objective with this game was simply to build a game from scratch, my first time. I learned a great deal in the process and have a much stronger vision of how to achieve the goal.

The game: A man tentatively named "Christian" is your character. He's a simple stick figure humanoid that can walk in one direction (right arrow key), raise and lower one of his arms (up and down arrow keys), and fire commands (enter key). Well aimed commands are a defense against being taunted by the Flying Spaghetti Monster.

Click on screen-shot to play the game.


The Flying Spaghetti Monster (FSM) is not of this world. His "mind" actually resides on the WebSocket server. I decided to use an autonomous AI (no matter how cheap) instead of building a multi-human game demo because there's no guarantee that another human will be trying the demo when you are. The autonomous FSM will be there at any time anyone looks at the demo.

FSM shows up when his distant remote self decides to visit you. (Actually a simple random timer, set between 0-8 seconds.) He also decides beforehand (on the server) which taunting behavior he will use and how long the taunt will last. And because he's also acting as a substitute human player, news is sent back to the server to let him know he's been hit and he withdraws in acknowledgement.

It's a quick demo game to be sure, but includes some basic essentials; the infamous (or at least a) game loop (with good clean CPU use characteristics), independent motion and control of characters, background movement, etc. I'm interested in simulating humanoids, so I created a very simple walking stick figure as the first tiny step toward that end. I'm not an artist, so feel free to laugh at the man as long and as hard as you want.

The point is that FSM is an external player that moves in and interacts without the old familiar need to click for an update. This is the great tactical advantage of WebSockets. In addition, WebSockets transmit data much more efficiently than normal HTTP. (So much so, that you'll help the Internet work better and reduce energy use by switching to WebSockets.)

The second game I'll mention here was presented as a demo with WebSockets by Mozilla at least a year and a half ago; created by Little Workshop website development company. You will be able to play alone if there doesn't happen to be anyone else trying the demo when you are.

Finally, have a look at Nomo Racer from Hungary. It was developed using MIT open source WebGL tools. (You'll need a modern browser that supports WebGL as well as WebSockets. If you've been ok so far, they give it a try.) "The aim in creating this game," according to the Nomo Racer Facebook page, "was to see what the WebGL and WebSocket technologies are capable of, and find out whether these tools could provide real-life solutions."

The WebSocket connection seems to time out when you're not playing and I found steering difficult using the arrow keys. But it's an impressive experiment / demo nonetheless. I also found a YouTube video showing two cars racing (multiplayer capability), with a driver who could steer better than I could. :)

There are actually a number of other game demos using WebSockets out there. Perhaps I will highlight them in this blog at a later date. But as you can see, there are a number of people demonstrating a range of games using WebSockets.

Monday, September 2, 2013

Riding New Ground (Part 1): Web Browser Application with HTML 5, CSS 3, JavaScript, Microdata, and Mopeds

Visit the High Level Logic (HLL) Website
— Home of XPL (eXtensible Process Language)

It's like XML, but you can store source code in it.

This is part 1 of a tutorial, or commentary at least, related to my recent experience building the Mopedum Webshop. The software is licensed for Mopedum's use and may be generalized and put into an open-source project by the HLL Project. Aside from title technologies, Tomcat, Java, and database systems have also been used, and I will comment about listings in search engines like Google. But the real breath-taking game-changer right now is in web pages; HTML 5 and dynamic coding that uses the browser, without applets, as a real application interface. I think we should talk about that.

Part 1: The Job

The webshop was built for a small business in Nynäshamn, Sweden that features a nostalgia museum, nostalgic café, nostalgic music and other events, retro boutique, and an art hall. The grand opening of the museum, which focuses on “the golden age of mopeds 1952-1979” (and contains much more than mopeds, providing a nostalgia trip through the era) took place on May 26, 2012. Throughout the entire day, the crowds overflowed onto the front deck of the renovated old community bathhouse and sidewalk, reflecting both a strong national interest in "veteran" mopeds and quite possibly the special appearance of Swedish pop icon “Lill Babs” Barbro Svensson. (Image with The Beatles: 1963) The café was also packed throughout the evening for the after-party.

The facility also includes a workshop for stripping down mopeds and preparing parts for sale as well as a stock room and a part-time sales and shipping office. Recycling at its best!

For confused American readers, let me explain the importance of mopeds in Swedish cultural history. While you drove a car to Blueberry Hill to find your freedom, mopeds gave greater freedom of movement, allowing a range of activities, to Swedes and other Europeans during the “golden age.” No wonder then that a nostalgia museum built around this theme would be a hit or that it won a best contribution to local culture award after its first year. It's no wonder that there are active veteran moped clubs throughout the county and no wonder that this small business invested in 40 metric tons of old mopeds and parts.

With that as background, creation of a moped parts web shop became my slow-season winter project while others spent time preparing parts and entering information into an existing sales-system database. It was a completely custom project. Except for some occasional copy-pasting (come on, we all do it), everything in the web pages, XML files, and Java programs was typed character by character into a text editor. Java programs are written in SE 7 (plus javax.servlets). I am a tool builder who doesn't believe in relying much on other people's tools. I want efficient cutting-edge code. I want to fiddle with details myself and even blog about things. :)

Web shops are supported on some hosting sites and there are open-source web shop projects. At first glance, it may seem unreasonable to put a small business through a from-scratch custom software project. The first suggestion of a custom project came from the need to use data from their legacy database system, which is tied to their sales system, which is an nondetachable part of the business operation. They had been using the system for sale of food and drinks in the café, boutique items, and tickets to the museum. There were no plans to structure product data for a sophisticated drill-down such as is normally supported by manufacturers and distributors of new parts; for example: category → brand → model → subsystem → parts + alternatives and related items. For best results, perhaps even just useful results, design needed to be tailored to the details and character of the actual available data.

I decided that I wanted to build web shop technology anyway and offered a license arrangement involving minimal support when I worked, extended into improvements and support after the system went on-line. With “We Are the Champions” playing in the nostalgia café (really, it was and still regularly is), the Mopedum Webshop went live on schedule, according to plan, in April, and thanks to a bit of pre-launch marketing, veteran moped parts were being shipped to customers the very next day.

This level of success was predictable. The business plan was good and had been expertly implemented and built upon. Although it is my first web shop, it's not the first web shop ever built. I've been buying things from web shops for years and there are plenty of “best practice” tips available.

If you want to try building your own web shop from scratch over the weekend as your first experimental programming project, I'd say … naaah …. better wait on that. It's not that easy. But for a seasoned professional, it isn't a high risk software project. Especially with an adaptive business model, such projects can be within reason even for small businesses. And of course, now that I have web shop technology, I'll have a head-start on the next one (or similar project).

To this point, Internet technologies have largely been built in support of commercial activities; cat pictures and web shops. Although I plan to address triumphs and challenges in “emerging” (actually emerging to actually use now) technologies in this series, the web shop also hangs on a tried-and-true backbone of such things as AJAX calls, Servlets, and JDBC, automated email messages and Google Maps.

Not only was is possible to take things from an empty instance of Notepad++ to a running system on time, the new system has been ticking like a clock ever since the launch, restarted only occasionally to bring upgrades on-line. It's been running long enough now, that together with webmaster duty, I can see the whole experience pretty clearly in hindsight.

From that view, I'm not going to teach you how to write detailed lines of code; and you may be disappointed after having read this far that there won't be any code to copy-paste. New technologies are becoming available that can change the Internet experience dramatically. I really think we, the tool and app builders, should talk about how the emerging web technologies can effect design, and even the type of applications that should now be using web browsers.

A web shop, which is very much tied to the traditional mainstream (RESTful request-response) browser based web-apps, may be one of the best cases to start that discussion; with one foot in the old world while dropping the other foot into the new.

(to be cont.) Part 2: Draft title: “The Technology” is expected … link will appear here.