Server-Sent Events are real-time events emitted by the server and received by the browser. They’re similar to WebSockets in that they happen in real time, but they’re very much a one-way communication method from the server.

These events are similar to ordinary JavaScript events that occur in the browser — like click events — except we can control the name of the event and the data associated with it.

All the code for this article is available on github, and a live demo is available online.

† Is it Server-Sent Events or EventSource? Well, they both work. Server-Sent Events is the name of the API and specification. EventSource is the name of the JavaScript object you’re instantiating. It’s a bit like Ajax and XHR, where XHR refers to the XMLHttpRequest object…kinda.

Two notes: a) the uptime for this example is, I’m afraid, usually rather low — good for my server, bad for you. If you test the demo locally it will give you more interesting figures. b) IE6 isn’t supported in any of this article.

var source = new EventSource('/stats');
source.onopen = function () {
  connectionOpen(true);
};

source.onerror = function () {
  connectionOpen(false);
};

source.addEventListener('connections', updateConnections, false);
source.addEventListener('requests', updateRequests, false);
source.addEventListener('uptime', updateUptime, false);

source.onmessage = function (event) {
  // a message without a type was fired
};

data: this is a simple message
<blank line>

data: this is line one
data: and this is line two

id: 33
data: this is line one
data: this is line two

id: 34
data: Remy is awesome

id: 35
data: Bruce is stinky

id: 36
event: price
data: 103.34

id: 37
event: news
data: Bruce sells his collection of replica bananas

function stats(request, response) {
  // only response to an event-stream if the request 
  // actually accepts an event-stream
  if (request.headers.accept == 'text/event-stream') {

    // send the header to tell the client that we're going
    // to be streaming content down the connection
    response.writeHead(200, {
      'content-type': 'text/event-stream',
      'cache-control': 'no-cache',
      'connection': 'keep-alive'
    });

    // support the polyfill - we'll come on to this later
    if (request.headers['x-requested-with'] == 'XMLHttpRequest') {
      response.xhr = null;
    }

    // if there was a lastEventId sent in the header, send
    // the history of messages we've already stored up
    if (request.headers['last-event-id']) {
      var id = parseInt(request.headers['last-event-id']);
      for (var i = 0; i < history.length; i++) {
        if (history[i].id >= id) {
          sendSSE(response, history[i].id, history[i].event, history[i].message);
        }
      }
    } else {
      // if the client didn't send a lastEventId, it's the
      // first time they've come to our service, so send an
      // initial empty message with no id - this will reset
      // their id counter too.
      response.write('id\n\n');
    }

    // cache their connection - the response is where we write
    // to send messages
    connections.push(response);

    // send a broadcast message to all connected clients with
    // the total number of connections we have.
    broadcast('connections', connections.length);

    // if the connection closes to the client, remove them
    // from the connections array.
    request.on('close', function () {
      removeConnection(response);
    });
  } else {
    // if the client doesn't accept event-stream mime type,
    // send them the regular index.html page - you could do
    // anything here, including sending the client an error.
    response.writeHead(302, { location: "/index.html" });
    response.end();
  }
}

// send the data (event type, id, message, etc)
response.write(data);

// if our response contains our custom xhr property, then...
if (response.hasOwnProperty('xhr')) {
  // clear any previous timers using the xhr prop as the value
  clearTimeout(response.xhr);

  // now set a timer for 1/4 second (abritrary number) that
  // then closes the connection and removes itself from the
  // connection array.
  // The delay is in place so that a burst of messages can 
  // go out on the same connection *before* it's closed.
  response.xhr = setTimeout(function () {
    response.end();
    removeConnection(response);
  }, 250);
}

Server-Sent Events originally appeared on HTML5 Doctor on January 24, 2012.

This post is about the Web Storage API. Technically it’s been shifted out of the HTML5 specification and can now be found in it’s very own dedicated spec. But if it counts at all – it used to be part of the Web Applications spec.

Web Storage is a very, very simple way to store data in the client – i.e. the browser. What’s more, the support is fabulous: IE8 and upwards has support natively, and there’s lots of good polyfills in the wild already.

This post however will just focus on the features of Web Storage and hopefully show you a trick or two you may not have known about.

What Web Storage Does

Using JavaScript, Web Storage makes it possible to easily store arbitrary values in the browser. Storage is different from cookies in that it’s not shared with the server. It’s also different from cookies in that it’s dead simple to work with.

There are two versions of Web Storage: local and session. Local means that it’s persistent, and session is simply that the data is lost when the session ends (i.e. when you close you browser window or tab). It’s also worth noting that a session is tied to a single browser window or tab. The session doesn’t leak out in to other open windows on that same domain.

Any data stored is tied to the document origin, in that it’s tied to the specific protocol (http or https, etc), the host (html5doctor.com) and the port (usually port 80).

Get Storing

The API for localStorage and sessionStorage is exactly the same, and distills down to the following methods:

• .setItem(key, value);
• .getItem(key)
• .removeItem(key)
• .clear()
• .key(index)
• .length

You can probably guess what most of those methods do, maybe not the last two, but ignore all that syntax for a moment.

Due to the way that the storage API has been defined, the set/get/remove methods all are getters, setters and deleters. What that means to you is you can use localStorage as follows:

localStorage.name = 'Remy';

If you tried using the link above, this will save a property called “name” against localStorage. Completely closing your browser, and going back to http://jsconsole.com and test the name property again:

console.log(localStorage.name);

Still holds the value doesn’t it? Pretty easy eh? And no faffing around with cookies, for that, we can be thankful!

Equally deleting data is very easy:

delete localStorage.name;
console.log(localStorage.name);

You’ll see the value is undefined.

What’s happening under the hood is that when you set a property on localStorage (or sessionStorage) it’s calling the .setItem method. When you get a property, it’s calling .getItem and when you delete, it’s calling removeItem. That way you can treat the Web Storage interface as any other regular object in JavaScript, except you’ll know it’ll hang around after the page has unloaded.

Hey everyone! I’m storing some data!

That’s what your browser does when you store some data. It announces it via events.

When you set some data on localStorage or sessionStorage, an event, called “storage”, fires on all the other windows on the same origin.

To listen for events the following code is used:

function storageEvent(event) {
  event = event || window.event; // give IE8 some love
  alert('Yo people! Something just got stored!');
}

if (window.attachEvent) { // ::sigh:: IE8 support
   window.attachEvent('onstorage', storageEvent);
} else {
    window.addEventListener('storage', storageEvent, false);
}

Note that as IE8 has support, if you don’t want to use onstorage you’ll want to double up your event listeners with attachEvent.

Clearly a massive alert box isn’t useful, but what is useful is what you capture inside of the event object:

• key – the property name of the value stored
• newValue – the newly set value (duh!)
• oldValue – the previous value before being overwritten by .newValue
• url – the full url path of the origin of the storage event
• storageArea – the storage object, either localStorage or sessionStorage

With this information, you can do a lot with the storage event, like perhaps keep tabs that are open synchronised. Here’s a simple, contrived example of using localStorage to echo a value across different windows on html5demos.com.

Or for a real world example, Font Deck recently implemented this very feature, if you change the sample text in one window, all other open tabs (or windows) mirror that same sample text.

Gotchas to watch out for

The main gotcha with Web Storage is that although the specification used to say^† that any object type can be stored, in fact all browsers currently coerce to strings. That means if you want to store a JavaScript object (or an array perhaps), you’ll need to use JSON to encode and decode:

var doctors = [
  'rem', 
  'rich_clark', 
  'brucel', 
  'jackosborne', 
  'leads', 
  'akamike', 
  'boblet'];
localStorage.doctors = JSON.stringify(doctors);

// later that evening…
var html5docs = JSON.parse(localStorage.doctors);
alert('There be ' + html5docs.length + ' doctors in the house');

† Edited thanks to feedback from zcorpan

When working with storage events, a couple of things to also watch out for – this is on purpose of course, but still just about qualify for gotcha status:

1. The event only fires on the other windows – it won’t fire on the window that did the storing.
2. The event won’t fire if the data doesn’t change, i.e. if you store .name = ‘Remy’ and set it to ‘Remy’ again it won’t fire the storage event (obviously, since nothing was stored).

and finally…

If you want to use web storage in browsers like IE6 and IE7 (or rather than want: need to in your particular case) – then there’s no shortage of polyfills for Web Storage. However be wary that you’ll need to stick to the regular setItem syntax rather than being able to use the sexy setter/getter syntax – and I’ve yet to see a polyfill that supports the storage events.

Maybe that isn’t a problem for you though – maybe the sheer simplicity and spiffingness of Web Storage is enough to just support IE8 and above with this enhanced client storage model.

Storing Data the Simple HTML5 Way (and a few tricks you might not have known) originally appeared on HTML5 Doctor on August 23, 2011.

Return of the HTML5 clinic

We’re proud to tell you that (most of) the HTML5 Doctors will be attending @media 2011 and taking your questions. We’ve got our own desk (like last year) and we’ll be available between the conference talks. That way you can fill your head with lots of juicy information, and then trundle your way over to the handsome guys in the white jackets and ask your best HTML5 question (for which there will be a reward!^†).

† Actually, we’re feeling kind, so anyone that asks a question, flashes us a kind smile or buys us a pint will get an exclusive little gift from your friendly doctor.

@media

If you’re wondering what @media is, you’ve either been hiding under a rock or you’re new to the business. None the less, we’re more than glad to tell you about it.

Founded in 2005, @media is recognised as one of the world’s leading conferences for web professionals. They pride themselves on keeping up to date on the latest moves in the design and development world. That means HTML5 has a big presence in their program of hand-picked world-leading experts.

Just some of the subjects that folks are speaking about during the two day conference:

• Our very own Bruce Lawson, talking on native multimedia with HTML5
• Mike Mahemoff (Google’s UK badass) speaking about HTML5 offline for fun and performance
• Dave Bulmer with Rockstar graphics with HTML5 (yes, we did say rockstar graphics!)
• Nicole Sullivan on Performance of CSS3 & HTML5

Our special discount code

For those of you that don’t have a ticket to this excellent conference already, you might be thinking you’ve missed the early bird prices – fret not my dear friend, we have your back! We’ve managed to procure you a special discount code that will get you £100 off the current asking price. Just use the code HTML5DOCTOR and it’ll knock the price down for you: book it now.

If you’re coming along, drop us a comment below and we’ll see you there!

- Rich, Remy, Mike, Bruce & Jack, xxx

Get your HTML5 prescription filled at @media originally appeared on HTML5 Doctor on May 3, 2011.

In the last year, riding the popularity of HTML5, a great number of JavaScript polyfills/shim/shams/what-have-you have been released, and the Modernizr project even maintains a list of these scripts.

But we've gone one step further.

What if you could include a single JavaScript library, and it automatically detected the state of the browser support for the latest technology, and where the browser is lacking, the JavaScript library plugs the missing gaps.

An über polyfill library if you will!

That's exactly what we've been working on for the last few months. Here today, we give you a new service from the HTML5 Doctors that will give your old and busted browser a kick up the backside and finally bring it up to scratch.

It goes without saying that this is a fairly mammoth task, so this is just the beta of the service, but we felt that it was in a good enough state to release to our loyal readers.

The Über Polyfill

So enough jibber-jabber, right? Let's get down and dirty with how to get using this library today.

<script src="http://html5doctor.com/uber.js?all"></script>

That's it. By including this script in to a browser like, say IE6, it will have access to Web Storage, WebSockets, Web Forms and more.

We've also configured the service so that you can include just specific pieces of technology - so if you just want Web Forms, you would do:

<script src="http://html5doctor.com/uber.js?webforms"></script>

And if you wanted to mix Web Forms with full CSS3 support:

<script src="http://html5doctor.com/uber.js?webforms,css3"></script>

And so on.

This is a hosted service by HTML5 Doctor, so you'll need to hotlink the script in your site. It needs to be included before you try to access the "native" API in your JavaScript. So you can include this service in the head element, or just before your own JavaScript - as you like.

Support

Currently the service supports the following specifications:

• All of CSS3 (including selectors)
• PostMessage and related messaging APIs
• RDFa
• Includes all the new HTML5 elements - article, section, etc
• Live connections via: XHR2, EventSource and WebSockets
• File API
• Offline support
• Offline events
• Loading web pages APIs, most importantly, the History API (ref)
• Storage API, including the events (which most browsers currently lack)

Obviously sexy HTML5 things like native video and audio are supported, and specifically, we've been able to ensure that all browsers support WebM (yep, even gave Safari a bit of kick to support WebM) that way you only need to encode your videos once (finally). There's lots more we're planning to do in the future to make developing for the web with HTML5 so much easier.

The Future

There's still a lot that can be done with this service, and we're already working on the next exciting feature will be the full DAP implementation - yes that does mean you'll be able to access your camera from an input element:

<input type="file" accept="image/*;capture=camera">

Pretty exciting stuff, eh? Let us know what you'd like to be included that isn't in this and we'll look at including it in the full release.

How to get all the browsers playing ball originally appeared on HTML5 Doctor on April 1, 2011.

This post will be an overview of the technologies available, how well they’re currently supported, and, where possible, live demos. I’m going to touch on the following technologies:

• XHR & XHR2 with CORS
• Web Messaging
• Web Sockets
• Server Sent Events
• Web Workers

Before I get on to the APIs, I want to outline a fairly common communication model that several of these APIs use.

A common communication event model

All event handlers (with the exception of XHR) receive an event object containing a data property. This property includes the data sent as part of the message.

The event model (again with the exception of XHR) is mostly based around onmessage and postMessage or send. For example:

// in the recipient code
recipient.onmessage = function (event) {
  console.log('received message: ' + event.data);
};

// from the sender code
recipient.postMessage('hi there'); // or recipient.send('hi there');

This is just a common model and isn’t the exactly the same among all these technologies. The two key similarities are that they use:

• a sending method (postMessage or send) on the recipient object, and
• an event handler that listens for the message event and receives an event object containing a data property.

Very importantly, most browsers only support sending strings from sender to recipient, so we often need to JSON stringify and parse if we want to send anything other than a string.

XHR & XHR2 with CORS

XHR can be both synchronous and asynchronous. XHR is the only API that (purposely) supports synchronous requests, meaning the execution of code will block until the callback fires.

There’s nothing particularly new about XHR, but in XHR2 we can handle uploads, and there’s a progress event to tell you how the upload or download is getting on.

The super shiny new toy in XHR2 is its support for Cross-Origin Resource Sharing (CORS). This means you can make an XHR request across domains, but only if the server you’re connecting to allows it.

The request is as you’d expect from XHR:

var client = new XMLHttpRequest();
client.onreadystatechange = function () {
  if (this.readyState == 4 && this.status == 200) {
    alert('The most awesome-est person to follow: ' + this.responseText);
  }
};
client.open('GET', '/no-cors');
client.send();

If our server responds with a CORS header, however, we can put our XHR responder on another server. So on the URL http://remysharp.com/demo/cors.php, I have the following PHP script:

<?php
header('Access-Control-Allow-Origin: *');
?>
@rem

This says that anyone can make an XHR request to this particular script. Now when I run the following code in a browser that supports XHR2, the cross domain request succeeds!

var client = new XMLHttpRequest();
client.onreadystatechange = function () {
  if (this.readyState == 4 && this.status == 200) {
    alert('The most awesome-est person to follow: ' + this.responseText);
  }
};
client.open('GET', 'http://remysharp.com/demo/cors.php');
client.send();

Here’s a live example of CORS. (You can also edit it here.)

Note that IE8 supports CORS, but not XHR2 (no surprise there then). You need to use their proprietary (booo!) XDomainRequest object. Nicholas C. Zakas has an excellent article explaining how to handle these differences.

XHR usage is pretty common already, but XHR2 with CORS is a winner over JSON-P, particularly as you have finer control over the request, can handle timeouts, and can handle errors correctly.

Support for XHR & XHR2 with CORS

• XHR support is pretty solid nowadays (even though IE6 uses ActiveXObject to get it going)
• XHR2 with CORS: Safari & MobileSafari, Firefox 3.5, Chrome and IE8 (via XDomainRequest)

postMessage

This API is older, but it’s very useful if you want to get around the XHR same-origin rules. If you have an <iframe> document that can accept onmessage events from your origin (i.e., your site), then you can communicate across domains (and origins).

For example, a page that accepts an onmessage event might contain code such as this:

window.onmessage = function (event) {
  if (event.origin == 'mytrustedsite.com') {
    alert('my trusted site said: ' + event.data);
  }
};

Now you can include an <iframe> that contains that code, and using the <iframe> DOM node, you can post to the <iframe>:

// where iframe is the actual iframe DOM node
iframe.contentWindow.postMessage("hello there", location.host);

This gives you the ability to send strings across two mutually trusted domains. (Remember that you can use JSON.stringify and JSON.parse to convert to an object to and from string format.)

Support for postMessage

• Chrome
• Safari
• Opera
• Firefox
• IE8

Here’s a demo using postMessage.

There’s also a project called EasyXDM, which adds cross domain messaging to IE6 and upwards (along with all the other browsers) through the library’s abstraction. Definitely worth a look if this is a route you need to take.

Web Sockets

It’s my opinion that Web Sockets replaces Comet. Comet is a way of hacking the browser to giving us real-time server messages. The Web Sockets API provides that natively.

Web Sockets are used to send messages to and from the server — i.e., a bi-directional socket. In contrast to other similar technologies, with Web Sockets, you can go across domains, and you’re not bound by the same-origin policy. This means you can host your normal “apps” server while another server is for streaming content. Or you could host your own pages and connect to a live Twitter stream if your users turn on Web Socket support.

You can only send messages once the socket is open (duh). The communication model looks like this:

var ws = new WebSocket('ws://somesite.com/updates');

ws.onmessage = function (event) {
  alert(event.data);
};

ws.onopen = function () {
  ws.send('yay! we connected!');
};

Once the socket is closed, you can’t reuse it. Similarly, there’s no explicit method for opening a socket. That just happens when you create the WebSocket object.

This API is extremely simple. I most often get asked, “What do you put on the server side?” I personally use Node, but you could use an Nginx server or something like Jetty. I’m no expert on the latter servers, but I can vouch that a Node-based server is very, very simple to get going. The live demo below also includes a link to the code that I used to run the server.

Check out this demo of Web Sockets.

Support for Web Sockets

• Chrome
• Safari & MobileSafari

There’s also an excellent Flash poly-fill called web-socket-js. Drop this into an application and it provides Web Sockets support as if it were native. I’ve used this on a few projects of my own, and it works very well.

In early December 2010, there was a security notice posted about Web Sockets, and both Firefox and Opera pulled it from their upcoming releases. Mozilla have said that they expect Web Sockets to be back in Firefox by version 4.0.1.

Server-Sent Events

The Server-Sent Events API is something that originated from Opera back in 2006 and is used for pushing events from the server to the client. Note that the client cannot send messages to the server through an EventSource (SSE) — it can only listen for messages.

This API uses the onmessage model. It’s constructed using the EventSource object and is limited by the same origin rules:

var es = new EventSource('/sse');
es.onopen = function () {
  console.log('opened stream');
};

es.onmessage = function (event) {
  console.log('new message: ' + event.data);
};

The SSE automatically connects when you create the object (similar to Web Sockets), and once open will trigger the onopen event.

Here’s a live demo of Server-Sent Events

Here’s how this is to work: when a new message is pushed from the server to the client, it triggers the onmessage callback.

The key to your server is ensuring it doesn't close the connection on the client - the browser. Most of the examples around the web are doing this: closing the connection which tells the API to switch in to polling mode (note that this is the exact problem I hit when I first published this article).

When the API is in polling mode, it's no more different from an XHR poll, and the onopen will continually fire.

Support for Server-Sent Events

• Opera 11
• Safari & MobileSafari
• Chrome

Web Workers

Web Workers are a way of creating a new thread of execution inside the browser. I’m including this because you still need to communicate with your Web Workers, and the method of communication is similar to some of those techniques discussed above. Do note, however, that this is not a method communicating from a client (browser) to a server. It’s more like there’s another browser window executing a particular block of JavaScript.

As an example of when to use a Web Worker, say you’re running a lot of JavaScript and the UI becomes unresponsive. The browser UI hangs because, in a way, it’s a “single-threaded application”. (Under the hood it isn’t really, but from a rendering and JavaScript perspective it is). This JavaScript task could be given to a Web Worker so that the UI can continue functioning.

It’s vital to understand that a Web Worker lives in a sand-boxed environment that doesn’t have access to things like the DOM. What’s more, you can only communicate with it using the onmessage and postMessage functions.

Our application can create and send messages to a worker using the following code:

var worker = new Worker('bigjob.js');
worker.onmessage = function (event) {
  alert('Message from worker: ' + event.data); // remember event.data is a string!
};

worker.postMessage('task=job1');

In the JavaScript file bigjob.js, we run some computationally intensive task and listen for messages in a way similar to what we’ve done in the previous examples. We can also post messages back to the invoking application:

this.onmessage = function (event) {
  var job = event.data;
  if (job == 'task=job1') {
    job1();
  } else if (job == 'task=job2') {
    job2();
  }
};

// just a pseudo example
function job1() {
  // do some big task
  while (working) {
    // continue task
    this.postMessage('job1 ' + amountComplete + '% complete');
  }
  this.postMessage('job1 100% complete');
}

There’s a lot more to Web Workers than just running a couple of small tasks, and no doubt we HTML5 Doctors will be posting a detailed article soon. This example just demonstrates how to communicate with Web Workers and how similar that is to the other technologies we’ve discussed here.

Support for Web Workers

• Chrome
• Safari
• Opera
• Firefox

A final word

Hopefully you agree that this is just the tip of the iceberg of communicating between client and server in HTML5. We’re no longer stuck with the same origin policy we had with vanilla Ajax. In fact, when you think about it, since IE8, we’ve actually had decent cross-domain messaging.

I’m personally most excited about Web Sockets and the support of CORS in services that have APIs, like Flickr, Twitter, and URL shorteners. What could you build with this?

Methods of communication originally appeared on HTML5 Doctor on January 18, 2011.

<canvas> has a wealth of features, like:

• drawing shapes,
• filling colours,
• creating gradients and patterns,
• rendering text,
• copying images, video frames, and other canvases,
• manipulating pixels, and
• exporting the contents of a <canvas> to a static file.

In fact, the canvas API is so interesting, I wouldn’t be surprised to see entire books dedicated to it (and no, I don’t plan to write that book!).

It’s important when working with <canvas> to treat it like a real painting canvas. Say you lay down a strip of red paint on a real canvas. If you paint over it in blue, you can’t get back to your original red paint. It’s the same with the canvas element. There’s no concept of layers. The <canvas> element is a bitmap drawing API, and once you’ve committed to a set of pixels, you’re stuck with them.

Four of the Big Five browsers support canvas. We’re naturally missing IE8, but there’s hope: IE9 does support canvas. In fact, it supports hardware accelerated drawing to the canvas — other browsers currently don’t, making IE9 preview 3 the fastest (canvas) kid on the block!

Always consider the options

Before we dive in to the canvas API, I want to remind you to make sure you’re using the right technology for the job.

SVG is the alternative drawing API. It’s vector-based and does support layers. SVG also exists in the DOM, making it easy to attach event handlers for interactivity, and it’s easier to deal with collision detection (in games, for example). It also supports animation either through SMIL or JavaScript. There’s an excellent JavaScript library called Raphaël that uses SVG to render images and animations.

The <canvas> element is good for pixel manipulation and highly active animations. Brad Neuberg does a really good job of explaining the differences in his Google IO talk from back in 2009.

With all that in mind, let’s crack on with the canvas API.

Hello Canvas

The <canvas> element by itself is an invisible block of space, by default 300×150 pixels (in all browsers):

<canvas id="c"></canvas>

So now we’ve got a blank canvas in front of us. To draw, we need the drawing context, which we can get using JavaScript. Once we have the context, we can draw abominations to our hearts’ content:

<script>
// declare the two variables at once using a comma
var canvas = document.getElementById("c"),
    context = canvas.getContext("2d");

// now you're ready to draw
</script>

Code snippet

The context is our direct access to draw and paint on the canvas. Without it, we can’t paint a thing.

Painting Shapes

The 2D drawing API is fairly large (not too huge, but bigger than most other HTML-esque APIs), so I’m just going to show you how to draw something simple: a solid blue rectangle and a pink semi-circle.

Using the context object from earlier, we’re going to call fillRect(), passing the method the coordinates of the top left corner (x, y) and the width and height of the rectangle we want to paint:

<script>
var canvas = document.getElementById("c"),
    context = canvas.getContext("2d");

// x = 10, y = 20, width = 200, height = 100
context.fillRect(10, 20, 200, 100);
</script>

Code snippet

If you don’t specify a colour, the default fill and stroke colours will be black. So let’s change that to blue by setting the fillStyle() before we call fillRect(). We’re choosing our colour before drawing because this <canvas> is just like a real canvas — if you’re going to paint, you need to dip your brush in to the paint pot first:

var canvas = document.getElementById("c"),
    context = canvas.getContext("2d");

context.fillStyle = 'blue';
context.fillRect(10, 20, 200, 100);

Code snippet

Being the eagle-eyed HTML5 ninja that you are, you noticed that I’ve used the string blue as the fill colour. You can use any CSS colour properties in the canvas API. That means blue, #0000ff, #00f, rgb(0, 0, 255), and even rgba(0, 0, 255, 0.5) are all valid colours.

How about we turn this thing up to eleven? Let’s add a pink semi-circle. Oh yeah! Let’s do this!

var canvas = document.getElementById("c"),
    context = canvas.getContext("2d");

context.fillStyle = 'blue';
context.fillRect(10, 20, 200, 100);

// setup the line style
context.strokeStyle = '#fa00ff';
context.lineWidth = 5;
context.lineCap = 'round';

// draw the arc path
// (I'll walk you through these values momentarily - bear with me!)
context.arc(50, 50, 20, 0, Math.PI, false);

// colour the path
context.stroke();

Code snippet

There are three things that we’ve added to our JavaScript:

1. Configuring the line style
2. Drawing the semi-circle path
3. Stroking the path (i.e., painting the line)

When drawing paths, until you fill or stroke the path, nothing appears on the canvas. In this case, our path is an arc of a 180 degrees. The arc() method takes the following arguments: x coordinate, y coordinate, radius, start angle, end angle, and whether the arc should be drawn anti-clockwise. All of these arguments are required. (Technically, if you’re drawing a circle, it doesn’t matter whether you’re going clockwise or anti-clockwise, but you still need the argument.)

The tricky parts are the start and end angle. They’re both in radians. Remember those? I didn’t, so I’ll forgive you if you don’t! Here’s how to convert from degrees to radians:

var radians = degrees * Math.PI / 180;

It’s common to pass 360 degrees to the drawing methods, which is simply Math.PI * 2. Similarly, 180 degrees is Math.PI, which we used to create our semi-circle.

Once you have your path, you need to stroke (or fill) it. This applies the line style and colours to the path and completes our drawing. Do please remember that with this drawing: a) you can’t recover those lost blue pixels under the pink semi-circle, and b) this example would be much simpler in SVG!

So remember to choose the <canvas> element based on its strengths as I outlined at the top of this article.

Exporting & Saving

One thing that SVG can’t do is save the resulting image as a bitmap. It’s easy for <canvas> because the element is already a bitmap in the first place! The canvas can export its image to a data URL (e.g., data:image/png;base64,iVBORw0KGg...). This data may then be rendered in the browser, which could then be saved or dragged to the desktop, used in a new canvas, and so on.

The browser must support PNG images, and it may have varying support for GIF and JPG. For our example, we’ll stick with PNG since it supports alpha transparency, and where we haven’t drawn on the canvas, it’ll be transparent.

To get the data URL, we simply call canvas.toDataURL('image/png'). Note that we’re calling toDataURL() on the <canvas> element, not on the 2D context. This is because we’re getting all the pixels in the canvas, not just the pixels in a particular context.

So taking the example we’ve put together already, we’ll make the browser redirect to a PNG version of the image when a user clicks on the <canvas> element (a contrived example, I know!):

canvas.onclick = function () {
  window.location = canvas.toDataURL('image/png');
};

Code snippet

If you go to the live canvas example and click on the <canvas> element, it will load a PNG version of the canvas. Now you can save that to your desktop, email it to your friends, or even tweet it to your followers!

That’s just the start

This is just a small preview of what the canvas 2D API can do. There’s a whole lot more:

• Gradients, fills, and patterns
• Paths
• Text
• Pixel manipulation
• Animations (though old school, flip book style)

And don’t worry, the HTML5 Doctors will publish more articles explaining the canvas API in the future. We’ll even have special guest Tab Atkins explaining how he got a video to render entirely in ASCII!

In the meantime, here are a few useful resources to keep you going.

Further reading

• Mozilla’s canvas tutorial
• Opera’s canvas tutorial
• Breakout game live tutorial
• Mark Pilgrim’s Dive in to HTML5 canvas chapter — but don’t forget there are other good books you can buy too

  Related Posts:

  • video + canvas = magic
  • Your Questions #16
  • Your Questions #13
  • Your Questions Answered #11
  • Review: HTML5 Now (DVD)

An introduction to the Canvas 2D API originally appeared on HTML5 Doctor on August 3, 2010.

What’s in the box?

If you haven’t guessed from the overly verbose specification title, Web SQL Databases is a spec that brings SQL to the client side. If you have a back-end developer’s background, then you’ll probably be familiar with SQL and happy as a pig in muck. If not, you might want to learn some SQL before you start hacking around, Google’s your friend here.

The specification is based around SQLite (3.1.19), but having come from MySQL myself, it’s all pretty much the same (sorry for the sweeping statement!).

For an example of Web SQL Databases working, have a look at the Twitter HTML5 chatter demo I put together. It uses SQL and the WHERE clause to narrow down the recent chat about HTML5 on Twitter (it will work in Safari, Chrome and Opera 10.50).

There are three core methods in the spec that I’m going to cover in this article:

1. openDatabase
2. transaction
3. executeSql

Support is a little patchy at the moment. Only Webkit (Safari, SafariMobile and Chrome) and Opera 10.50 (ATOW alpha on Mac) support web databases. Fellow Doctor Bruce Lawson has told me that Firefox are holding off as they feel there’s a better implementation than SQLite (though I hope it’s similar, whatever they pick). Either way, I’d definitely recommend checking out the SQLite documentation for the functions that are available.

Because of this patchy support and the simple fact that Webkit had implemented the database spec some time ago, the spec on the W3C is now slightly ahead of the implementations in Safari, while Webkit is still catching up. On the other hand, since Opera has only just added support, it’s closer to the spec (I’ll mention the differences as we go along).

Nonetheless, it’s fun to play with, so let’s get playing!

Creating and Opening Databases

If you try to open a database that doesn’t exist, the API will create it on the fly for you. You also don’t have to worry about closing databases.

To create and open a database, use the following code:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);

I’ve passed four arguments to the openDatabase method. These are:

1. Database name
2. Version number
3. Text description
4. Estimated size of database

The missing feature of openDatabase (I’m not sure when it was added) is the fifth argument:

5. Creation callback

The creation callback will be called if the database is being created. Without this feature, however, the databases are still being created on the fly and correctly versioned.

The return value from openDatabase contains the transaction methods, so we’ll need to capture this to be able to perform SQL queries.

Estimated database size

From the tests I’ve run, only Safari prompts the user if you try to create a database over the size of the default database size, 5MB. The prompt is shown the image below, asking whether you want to grant the database permission to scale up to the next size of database — 5, 10, 50, 100 and 500MB. Opera, on the other hand, builds the database without complaining, which I expect might change later as it’s still in alpha.

Versions

I could be wrong, but everything I’ve tested so far says that versioning in SQL databases is borked. The problem is this:

If you upgrade your database to version 2.0 (e.g., there are some important schema changes since version 1.0), how do you know which visitors are on version 1.0 and which are on version 2.0?

The version number is a required argument to openDatabase, so you must know the version number before you try to open it. Otherwise, an exception is thrown.

Also, changeVersion, the method to change the database version, is not fully supported in Webkit. It works in Chrome and Opera, but not in Safari or Webkit. Regardless, if I can’t determine which version of database the user is on, then I can’t upgrade the user.

A possible workaround is to maintain a state database, something like the ‘mysql’ database in MySQL. This way, you would only have one version of this state database, and within this you would record the current version of any databases that control your application. It’s a hack, but it works.

Transactions

Now that we’ve opened our database, we can create transactions. Why bother with transactions instead of just running our SQL? Transactions give us the ability to rollback. This means that if a transaction — which could contain one or more SQL statements — fails (either the SQL or the code in the transaction), the updates to the database are never committed — i.e. it’s as if the transaction never happened.

There are also error and success callbacks on the transaction, so you can manage errors, but it’s important to understand that transactions have the ability to rollback changes.

The transaction is simply a function that contains some code:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  // here be the transaction
  // do SQL magic here using the tx object
});

I recently uploaded a demo to html5demos.com that demonstrates a transaction rollback in action: Web SQL database rollback demo

In the nightly builds of the browsers, we also have db.readTransaction, which allows only read statements to run on the database. I assume there are performance benefits to using a read-only readTransaction instead of a read/write transaction, most probably to do with table locking.

Now that we’ve got our transaction object (named tx in my example) we’re ready to run some SQL!

executeSql

This is the funnel of love for all your SQL goodness. executeSql is used for both read and write statements, includes SQL injection projection, and provides a callback method to process the results of any queries you may have written.

Once we have a transaction object, we can call executeSql:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  tx.executeSql('CREATE TABLE foo (id unique, text)');
});

This will now create a simple table called “foo” in our database called “mydb”. Note that if the database already exists the transaction will fail, so any successive SQL wouldn’t run. So we can either use another transaction, or we can only create the table if it doesn’t exist, which I’ll do now so I can insert a new row in the same transaction:

var db = openDatabase('mydb', '1.0', 'my first database', 2 * 1024 * 1024);
db.transaction(function (tx) {
  tx.executeSql('CREATE TABLE IF NOT EXISTS foo (id unique, text)');
  tx.executeSql('INSERT INTO foo (id, text) VALUES (1, "synergies")');
});

Now our table has a single row inside it. What if we want to capture the text from the user or some external source? We’d want to ensure it can’t compromise the security of our database (using something nasty like SQL injection). The second argument to executeSql maps field data to the query, like so:

tx.executeSql('INSERT INTO foo (id, text) VALUES (?, ?)', [id, userValue]);

id and userValue are external variables, and executeSql maps each item in the array argument to the “?”s.

Finally, if we want to select values from the table, we use a callback to capture the results:

tx.executeSql('SELECT * FROM foo', [], function (tx, results) {
  var len = results.rows.length, i;
  for (i = 0; i < len; i++) {
    alert(results.rows.item(i).text);
  }
});

(Notice that in this query, there are no fields being mapped, but in order to use the third argument, I need to pass in an empty array for the second argument.)

The callback receives the transaction object (again) and the results object. The results object contains a rows object, which is array-like but isn’t an array. It has a length, but to get to the individual rows, you need to use results.rows.item(i), where i is the index of the row. This will return an object representation of the row. For example, if your database has a name and an age field, the row will contain a name and an age property. The value of the age field could be accessed using results.rows.item(i).age.

That’s all you should need to get started with Web SQL Databases. I’m certain that mini JavaScript libraries are going to emerge to help support working with databases. If you want to find out more about SQL databases (shameless self promotion begins) I just finished the storage chapter for Introducing HTML5, which I’m writing with fellow Doc Bruce, so check that bad boy out too!

Demos

• HTML5 demo showing simple database usage
• HTML5 demonstration of a transaction rolling back
• Demo showing time range selection using SQLite

Introducing Web SQL Databases originally appeared on HTML5 Doctor on February 24, 2010.

Although not immediately obvious why it’s the right choice, it appeared to work for our needs…at first. Of course now, it’s been discovered that it’s actually a pretty bad idea.

How we got here

In short, details and figure solve a common design pattern and provide nice new semantic tags to solve that problem. A figure could be an image you’re referring to in an article or chapter of a book, and the details element allows the user to interactively show and hide the details of some piece of information.

Both elements can contain a heading element to label up the contents. For some reason, beyond this author’s understanding, these two elements, completely different in meaning, have been historically tied to using the same solution solve the problem how to markup the heading.

As I mentioned earlier, originally the proposed solution for the headings was to use the legend element, which proved to completely break in every browser (in new and interesting ways).

Skip forward to mid-September, and Jeremy Keith proposes that we solve the legend issue with the dt/dd combo, and Ian Hickson says:

That’s not a bad idea actually. Ok, done.

Before this was proposed there was lots of discussion about why we couldn’t introduce a new element to solve this problem, and Ian points out already 18 (or 22, I forget!) elements that represent some sort of heading. This is the argument for not introducing another new heading type element to solve the details and figure problem.

The problem with dt/dd

Ironically the problem isn’t with the dt part of the solution, it’s actually with the dd.

Dean Edwards (genius behind some very cool JavaScript and something that will soon blow your minds) has been testing these elements in detail and found a very serious issue with the dd in, guess what, IE6 & 7. I want to explain and draw attention to what Dean has found.

Styling a dd within details or figure (and probably other elements) bleeds to the next element.

By styling a dd red, and only the dd, here’s what it should look like (and does in IE8):

Where as in IE7 (and IE6), the red style bleeds in to the following p element (note the “this paragraph shouldn’t be red”):

![dd styled in IE7](

What’s more, if you look back at the screen shots you can see the last paragraph says “Contents of first <dd>”. The result of that test is being generated by the following JavaScript:

document.getElementsByTagName('dd')[0].innerHTML

Notice how in IE7, the contents of the first dd‘s innerHTML is empty.

The problem here is that:

1. IE7 and below can’t style a dd properly without it breaking and the style bleeding in to adjacent elements.
2. JavaScript, randomly, can’t see the contents of the dd.

Is there hope?

There is a hack that fixes this issue. It’s pretty mad, but it does fix the styling issue. However the side effects from this hack are outright unacceptable and are so serious I would argue that the hack solution itself is a bug.

The hack is over at the public-html of W3.org, and involves stuffing an open object tag just before we close the head tag.

This isn’t a clean solution for including in HTML by hand, authors won’t remember or might get it wrong, so it needs to be perhaps automated as part of the HTML5 enabling script, right? It would have to be inserted using document.write() as the last part of the head element.

Dean went on to test this, and he found:

There is a nasty side effect though. As you mentioned the document.write() should be the last thing in the <head>. If there are any scripts following the document.write() then they are not executed.

The really freakin’ important bit:

If there are any scripts following the document.write() then they are not executed

So, to answer the question: is there hope? No, not for the dd/dt combo. It can’t be styled properly and hacks will break JavaScript.

We want the details

We, as authors, want to make use of details and figure today. Waiting for IE7 to fall out of circulation before we start using these elements (as it’s been proposed a number of times on the IRC channel and mailing boards) is outright not going to happen. IE6 & 7 are going to be around for a good more number of years, certainly IE7 (IE6 has at least another 5 years in the beast).

We are going to start enabling the details interactive UI pattern using JavaScript whilst we wait for vendors bake it in to the browser, so the final proposed markup needs to work in all the browsers, including IE6 and IE7.

What are our current options?

1. Give new meaning to an existing element (as we’ve already tried to), legend, label and dt/dd have been tried, tested and failed. What else could we use?
2. Repurpose one of the existing new elements (keeping in mind that the dt/dd was repurposed so it should be a consideration).
3. Create another heading element to solve this problem.

The problem is that the conversation seems to have lost steam (or certain Dean was starting to see the conversation go in circles). If you want to see these two elements make it the final spec, and correctly, head over to either the IRC channel or the mailing list, and get heard.

Reference links

• Dean’s original details test (my modified tests to fire the innerHTML on load: details, figure)
• Litmusapp browser screenshots of the results: details, figure
• whatwg mailing list thread: September, October

  Related Posts:

  • Legend not such a legend anymore
  • Hello, summary and figcaption elements
  • How to get HTML5 working in IE and Firefox 2
  • September HTML5 spec changes
  • 2022, or when will HTML 5 be ready?

dd-details wrong again originally appeared on HTML5 Doctor on October 12, 2009.

Clarification over section and article

The spec has been clarified to help authors correctly choose between when to use section and when to use article, and Bruce’s section post has also been updated.

footer now works like header

This was a big one and causing confusing to people coming to HTML5 for the first time. Originally you couldn’t include a nav element inside a footer, or a section.

Now the spec has been changed to match the header element.

details and figure saved

Instead of using legend, which didn’t work, Jeremy suggested (although slightly tongue in cheek) to use dt for the title and dd for the body. Ian Hickson agreed, and it’s in

Example:

<figure>
 <dd><video src="ex-b.mov"></video>
 <dt>Exhibit B. The <cite>Rough Copy</cite> trailer.
</figure>

aside has better examples

The documentation has been updated to specify better examples of how the aside element can be used.

Better examples help us authors understand how it can be used.

Dropped Elements

The following elements have been dropped from the HTML5 spec (though bb and datagrid were some time ago, and datagrid has been postponed rather than dropped entirely):

• dialog
• bb
• datagrid

Ch-ch-changes

We’ll be posting in more detail about some of these changes, and as further changes come out of the editing process we’ll no doubt keep you all up to date, either via our Twitter account (which you should follow) or feel free to let us know too!

September HTML5 spec changes originally appeared on HTML5 Doctor on September 17, 2009.

However I ran in to some very serious issues with the tag, so serious, in it’s current state, it’s unusable.

Overview of the details element

The details element, by default, is a collapsed element whose summary, or label, is the first child legend (if no legend is used, the UA provides a default, such as “Details”), with a triangular button to indicate it’s current open state.

If you include the open attribute, then the element is open by default. In theory, you could attach a click event to the legend, and switch the open attribute.

The markup would roughly be this:

<details open="open">
  <legend>Terms & Conditions</legend>
  <p>You agree to xyz, etc.</p>
</details>

Here’s the details test page I was working from: HTML 5 details test

The issues

The biggest problem, and the show stopper for me, is that the browser’s treatment of the legend element completely breaks this markup pattern – this is true for all the major browsers: Opera, Safari, Firefox and IE (tested in all the latest and some older browsers). I’ll go in these issues in detail in a moment.

Other problems include:

• Styling the legend element is exceptionally difficult, particularly positioning
• Using the WHATWG guidelines to styling the details element prove both difficult to interpret and difficult to implement.
• When using CSS to style the open state of the details element using: details[open] { height: auto; }, meant that once I changed the open state using JavaScript, it wouldn’t trigger the browser to redraw (as it would if I had added a class). I’ve run in to this before, CSS 2.1 is styling source, not the DOM.

Legend treatment

Surprisingly Firefox is the worst one out in these issues, the rest of the browsers have fairly same treatment of the issue. In the screenshots, I’ve included a fieldset and nested legend for reference.

Internet Explorer

IE7 & IE8 closes the legend element it encounters when it’s not inside a fieldset element and move it’s contents out to an adjacent text node.

What’s also strange, is that looking at the DOM it also creates another empty(?) closed legend element after that text node. It doesn’t have any effect, but just looked odd:

Opera

Opera (9 & 10b) is very similar to IE in it’s treatment of the legend in the details element, except it doesn’t create the second closing legend node. It just closes the legend, and creates the adjacent text node.

Safari

Safari simply strips the legend all together out of the DOM. So much so, that if you open the web inspector, then the error console, you’ll see it warning out that it’s encountered an illegal element, ignoring it, then encountering the closing tag, so it ignores that too. You’re left with just the text node.

Firefox

The best for last. Firefox goes one step beyond the other browsers. It assumes you’ve forgotten to include the fieldset element. So when it hits the legend element, Firefox inserts an opening fieldset up until it finds (I believe) the closing fieldset element, which obviously it doesn’t so the result is the rest of the DOM, after the first illegally placed legend ends up eaten by fieldset element, which leaves my DOM in a mess:

Impact on other elements

details isn’t the only element that reuses the legend element for labelling, the figure element also is supposed to support the legend element. The result is obviously going to be the same.

Conclusion

We can’t style the legend element when the text is being thrown out by all the browsers, and Firefox’s DOM mangling is just too painful to look at.

This basically means that we can’t, in any reasonable amount of time, use the legend element inside both the details and figure element in the spec’s current state.

For me, I’ll be using an alternative element, probably just a p element styled to look like a legend, but that’s really not the point. Ideas anyone?

It turns out we weren’t the only ones looking at this and Ian Hickson has responded on the issue:

My plan here is to continue to wait for a while longer to see if the parsing issues can get ironed out (the HTML5 parser in Gecko for instance solves this problem for Firefox). If we really can’t get past this, we’ll have to introduce a new element, but I’m trying to avoid going there.

It’s fine to think that Gecko will update, but it’s IE that I’m worried about, they won’t turn out their render engine, and the result is we’ll have to avoid using the legend in any element other than fieldset.

Legend not such a legend anymore originally appeared on HTML5 Doctor on July 31, 2009.