Possible Applications #

A few simple examples of applications that could make use of Server-Sent Events:

• A real-time chart of streaming stock prices
• Real-time news coverage of an important event (posting links, tweets, and images)
• A live Twitter wall fed by Twitter’s streaming API
• A monitor for server statistics like uptime, health, and running processes

We’ll use the server monitor for this article’s examples. If this application were to be used in the wild, we could also check the EventSource‘s connection state to indicate when there’s a potential problem connecting to the server.

Overview of the API #

The client-side API is rather simple, and it hands-down beats the insane hacks required to get real-time events to the browser back in the bad old days.

The main points of interest:

• new EventSource(url) — this creates our EventSource object, which immediately starts listening for events on the given URL.
• readyState — as with XHR, we have a readyState for the EventSource that tells us if we’re connecting (0), open (1), or closed (2).
• onopen, onmessage — two events that we can listen for on the new EventSource object. By default, the message event will fire when new messages are received, unless the server explicitly sets the event type.
• addEventListener — not only can we listen for the default message event, but we can also listen for custom messages using the addEventListener on the EventSource object, just as if we were listening for a click event.
• event.data — as with most messaging APIs, the contents of the message reside in the data property of the event object. This is a string, so if we want to pass around an object, we need to encode and decode it with JSON.
• close — closes the connection from the client side.

In the future, EventSource will also support CORS using an options argument to the EventSource object: { withCredentials: true }. But at the time of writing, no stable release includes this property.

Simple Example #

Our simple web app will notify us of server status messages — things like the load average, number of currently connected users, and most CPU-intensive processes. If I were using this application in anger, I’d probably build server modules that emit specific event types when they cross specific thresholds, so that I’m only notified when something gets to warning level.

This snippet of JavaScript connects to our server, listens for messages, and handles the data that comes with the messages:

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
};

Properties of Server-Sent Events #

Server-Sent Events are more than just a one-way web socket. They have some unique features:

• The connection stream is from the server and read-only. This suits lots of applications, some examples of which I listed above.
• They use regular HTTP requests for the persistent connection, not a special protocol, which means we can polyfill using vanilla JavaScript.
• If the connection drops, the EventSource fires an error event and automatically tries to reconnect. The server can also control the timeout before the client tries to reconnect.
• Clients can send a unique ID with messages. When a client tries to reconnect after a dropped connection, it will send the last known ID. Then the server can see that the client missed n messages and send the backlog of missed messages on reconnect.

Message Format #

A simple message doesn’t require much:

data: this is a simple message
<blank line>

Note that the end of a message is indicated by a blank line (obviously not the literal characters <blank line>).

For a message with multiple lines:

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

You can send message IDs to be used if the connection is dropped:

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

You can even send multiple messages in a single response so long as you separate the messages by blank lines:

id: 34
data: Remy is awesome

id: 35
data: Bruce is stinky

And you can specify your own event types (the above messages will all trigger the message event):

id: 36
event: price
data: 103.34

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

You don’t have to worry about this structure on the client side. It only applies to the server, which I’ll touch on next.

Typical Server #

I’m not going to give a full walkthrough of the server-side code, since this is an HTML5 web site But there are a few important and simple features that you need to know to build the server (you’ll need this part anyway if you’re going to use EventSource).

I’ve included all the files for this demo on GitHub for you to peruse at your own leisure, and I’ve also deployed a live example of this code.

Ideally, you should use a server that has an event loop. This means you should not use Apache, but instead use a platform such as Node.js (which I’ve used) or Twisted for Python.

Key properties:

1. You can only accept EventSource requests if the HTTP request says it can accept the event-stream MIME type.
2. You need to maintain a list of all the connected users in order to emit new events.
3. You should listen for dropped connections and remove them from the list of connected users.
4. You should optionally maintain a history of messages so that reconnecting clients can catch up on missed messages.

Here’s a sample of my Node.js based server. It’s using Connect (a simple webby framework for Node). When it receives a request for /stats, it calls the following function. I’ve commented the code so you can follow along:

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();
  }
}

The important trick on the server is to ensure you don’t close the connection to the EventSource object. If you do, it will of course handle the closed connection, fire an error event, and try to reconnect. So you’ll just want to maintain the persistent connection.

Polyfills and Tweaks to the Server #

There are two good polyfills I know of, and though I prefer the one I wrote, I’ll still lay them both out for you.

// 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);
}

Bugs? #

The error event should always fire when the readyState changes, assuming you didn’t explicitly call the close method. This works nearly all the time, but in writing this article, I found a few edge cases where it doesn’t fire. In Chrome, if I put my machine to sleep and then woke it back up, it would close the connection but not fire the event, therefore never triggering a reconnection. As I said, this is an edge case and I’ll file a bug against it, so I don’t expect it to hang around for long.

Why Not Use WebSockets? #

There are two reasons I’d advocate using EventSource over WebSockets, as they’re currently the two contenders for sending real-time events to the browser.

The first is that EventSource (as we saw earlier) works over regular HTTP and can therefore be replicated entirely using JavaScript if it’s not available natively. That means that we can polyfill browsers without support, like IE9.

The second is probably more important: you should always use the right technology for the job. If your real-time data is sourced from your web site, and the user doesn’t interact in real-time, it’s likely you need Server-Sent Events.

I recently saw a cool demo of snowflakes drifting down a web site. Each snowflake is a tweet based around the Christmas theme — like if someone mentions a particular Christmas-y term, it’s sucked in to the snowflake. Don’t get me wrong, I know this is a demo, and it’s very cool (if you wrote it, this is me sending you hugs), but it’s based on WebSockets. I’d suggest this demo should be based on EventSource since all the data is read-only and the user doesn’t interact with it at all.

The point: evaluate the technology against your problem, and aim to get good fit.

The Basics #

First, let’s check out the spec:

The contenteditable attribute is an enumerated attribute whose keywords are the empty string, true, and false. The empty string and the true keyword map to the true state. The false keyword maps to the false state. In addition, there is a third state, the inherit state, which is the missing value default (and the invalid value default).

The contenteditable attribute was mainly intended for providing an in-browser rich-text or WYSIWYG experience. You’ve likely seen this sort of thing in blog-based authoring tools like Symphony or sites like Flickr where you can begin editing page content simply by clicking in a given area.

As mentioned above, contenteditable has three possible states:

contenteditable="" or contenteditable="true"

Indicates that the element is editable.

contenteditable="false"

Indicates that the element is not editable.

contenteditable="inherit"

Indicates that the element is editable if its immediate parent element is editable. This is the default value.

When you add contenteditable to an element, the browser will make that element editable. In addition, any children of that element will also become editable unless the child elements are explicitly contenteditable="false".

Code Example #

Here’s some example code to get us started:

<div id="example-one" contenteditable="true">
<style scoped>
  #example-one { margin-bottom: 10px; }
  [contenteditable="true"] { padding: 10px; outline: 2px dashed #CCC; }
  [contenteditable="true"]:hover { outline: 2px dashed #0090D2; }
</style>
<p>Everything contained within this div is editable in browsers that support <code>HTML5</code>. Go on, give it a try: click it and start typing.</p>
</div>
    

Live examples #

Here are two basic-but-live examples showing what you can do with contenteditable.

Browser Support #

Browser support for contenteditable is surprisingly good:

We have to give credit where it’s due and point out that Internet Explorer has supported this attribute since IE5.5. In fact, a very early iteration of contenteditable was designed and implemented by Microsoft in July 2000.

For a more in-depth compatibility table, visit When Can I Use….

Storing the Changes #

For this section, I went straight to Doctor Remy for help, as he is much more knowledgeable than me when it comes to storing your data everything.

Depending on the complexity of your editable block, your code could be listening for the enter key (keyCode 13) to save the changes, and the escape key (keyCode 27) to undo the changes.

When the user hits enter (assuming it’s a single line of editable content), it would grab the innerHTML of the editable field and send an Ajax post to your server with the change.

A simple example of this can be seen on JS Bin: contenteditable saving to Ajax

Conclusion #

We’ve repeated the phrase “paving the cowpaths” all over this site, and I’m mentioning it again with the introduction of the contenteditable attribute. The spec finally makes official something that’s been implemented by browser makers for years.

Although this is one of the lesser-known new attributes, I bet you’ll find yourself using it more often than you would think.

Imagine being able to simply click a block of content and start making changes instantly: making quick corrections to an article in-place, allowing users to edit their comments, or even building spreadsheets within company applications that aren’t hooked up to any sort of back-end user interface.

If you can think of other uses for this attribute, then head on down to the comments section and tell us where else you think this could be implemented.

Related Reading #

• What is contenteditable?
• Expanding Images Using HTML5’s contenteditable

The Definition #

The <output> element, new in HTML5, is used in forms. The WHATWG HTML specification describes <output> very simply:

The output element represents the result of a calculation.

Along with the standard global attributes, <output> also accepts the following:

for

A space-separated list containing the IDs of the elements whose values went into the calculation.

form

Associates the <output> element with its form owner. The value must be the ID of a form in the same document. This allows you to place an <output> element outside of the <form> with which it is associated.

name

The name of the element.

Implementing <output> #

We’ll start by creating a simple example that adds two whole numbers together (Figure 1). We’ll use the new-in-HTML5 number input type and the parseInt JavaScript function to convert the input strings to integers:

<form onsubmit="return false" oninput="o.value = parseInt(a.value) + parseInt(b.value)">
  <input name="a" type="number" step="any"> +
  <input name="b" type="number" step="any"> =
  <output name="o"></output>
</form>

See a live example of the code in Figure 1.

As you’d expect, if you only enter a single value, the function returns NaN. It’s effectively trying to add a number and an undefined value, and 1 + undefined = undefined.

<form onsubmit="return false" oninput="o.value = parseInt(a.value) + parseInt(b.value)">
  <input name="a" id="a" type="number" step="any"> +
  <input name="b" id="b" type="number" step="any"> =
  <output name="o" for="a b"></output>
</form>

<form onsubmit="return false" oninput="o.value = a.valueAsNumber + b.valueAsNumber">
  <input name="a" id="a" type="number" step="any"> +
  <input name="b" id="b" type="number" step="any"> =
  <output name="o" for="a b"></output>
</form>

Invoicing Calculator: An In-depth Example with Fallbacks #

For a more realistic example, let’s create an invoicing calculator that multiplies the number of hours by the hourly rate and adds tax to give an overall total (Figure 4):

<form onsubmit="return false" oninput="amount.value = (hours.valueAsNumber * rate.valueAsNumber) + ((hours.valueAsNumber * rate.valueAsNumber) * vat.valueAsNumber)">
  <legend>Invoice</legend>

  <p><label for="hours">Number of hours</label>
  <input type="number" min="0" id="hours" name="hours"></p>

  <p><label for="rate">Rate</label>
  <span>£</span><input type="number" min="0" id="rate" name="rate"></p>

  <p><label for="vat">VAT</label>
  <input type="number" min="0" id="vat" value="0.20" name="vat"></p>

  <p>Total: <strong>£<output name="amount" for="hours rate vat">0</output></strong></p>
</form>

See a live example of the code in Figure 4.

Nothing too complicated going on there. In fact, the scripting is so simple that even I can do it

A Mildly Controversial Example Using <input type="range"> #

HTML5 also introduces the range input type, which renders as a slider control in supporting browsers. With this input type, a user can enter an approximate value within a given range without having to be completely precise or directly type a numeric value. For cross browser compatibility, see Remy’s input range polyfill.

While researching this article, I found a number of examples using the <output> element in conjunction with <input type="range"> as shown in Figure 5:

<form onsubmit="return false" oninput="level.value = flevel.valueAsNumber">
  <label for="flying">Flying Skill Level</label>
  <input name="flevel" id="flying" type="range" min="0" max="100" value="0"> 
  <output for="flying" name="level">0</output>/100
</form>

See a live example of the code in Figure 5.

Using <output> to show the current value to the user seems like a perfectly reasonable use case to me, but it isn’t the result of a calculation as the spec describes. I haven’t spoken directly to Hixie about this, but a couple of people on the IRC channel seemed to agree with, so I filed a bug report to request the definition be amended. I’ll update this article if something changes.

Browser Support and Polyfills #

The good news is that all modern browsers support the <output> element to some extent. The bad news is that there are still a few gotchas.

* Firefox does support the <output> element and the oninput event, but it doesn’t support the valueAsNumber property.

All the examples we’ve seen so far should work perfectly in Opera 11.5+, Safari 5.1+, and Chrome 13+. IE, as you might expect, is lagging somewhat, but support for <output> is in IE10 Platform Preview 2, and support for oninput is already in IE9.

In order to work around this in our simple examples, we’ll need to revert to the tried-and-trusted getElementByID and parseFloat (Figure 6):

<form onsubmit="return false" oninput="document.getElementById('o').innerHTML = parseFloat(document.getElementById('a').value) + parseFloat(document.getElementById('b').value)">
  <input name="a" id="a" type="number" step="any"> +
  <input name="b" id="b" type="number" step="any"> =
  <output name="o" id="o" for="a b"></output>
</form>

See a live example of the code in Figure 6.

While this isn’t ideal, it’s workable until those less-capable browsers die a slow and painful death. Alternatively, you can use polyfills to plug the gaps.

To check support in your current browser, open up Mike Taylor’s support test page.

Summary #

You probably won’t find yourself using the <output> element all the time, but it’s useful in a whole host of situations. Calculating values on financial sites spring to mind, or outputting the current mouse position, or perhaps the goal difference in a table of sports teams. What other use cases can you think of for <output>? Let us know in the comments!

Related reading #

• WHATWG HTML Specification for <output>
• W3C Elements Wiki Page for <output>
• Wufoo HTML5 Forms Tests for <output>
• Mozilla Developer Network docs on <output>
• Is onforminput Deprecated in HTML5 Forms? (And Why Should I Care Anyways?) by Zoltan Hawryluk
• A HTML5 Browser Maze: oninput Support by Daniel Friessen
• Fixing oninput in IE Using html5Widgets by Zoltan Hawryluk

How to Make and Link to a WebVTT file #

All you need to make a WebVTT file is a simple text editor. Type WEBVTT as the first line of the file and save it as a .vtt file. In the future, we expect existing captioning tools such as Universal Subtitles to export to WebVTT format.

WEBVTT

That’s all you need to get started. Next, we have to link to the file in the HTML document. We do this via the <track> element, which is a child of the video element. The <track> element has several optional attributes:

• the source WebVTT file (src),
• the language of the track (srclang),
• a user-readable label, and
• what kind of track it is. The values of the kind attribute come from the list above (i.e., subtitles, captions, etc.).

In the following example, we’re using a <track> element for subtitles:

<video width="640" height="480" controls>
  <source src="video.mp4" type="video/mp4" />
  <source src="video.webm" type="video/webm" />
  <track src="subtitles.vtt" kind="subtitles" srclang="en" label="English" />
  <!-- fallback for rubbish browsers -->
</video>

A few notes about the attributes:

• If no kind is specified, the default is subtitles.
• If the kind is subtitles, then srclang is required.
• There should not be two tracks of the same kind with the same label.

In the above example, we use a <video> element with two different <src> elements (for cross-browser loveliness). After the sources comes the <track> element. You can have several <track> elements as you might have subtitles, captions, and descriptions all in different languages.

<track> doesn’t presuppose a particular file format. Microsoft supports the TTML format, but this format will not be implemented by other browser vendors.

WebVTT Contents #

We now know how to make a WebVTT file and how to reference it in an HTML document, but what goes inside it? Within the file, we list what are known as “cues”. The WebVTT file might only have one cue, but it can contain as many as you want. Each cue starts with an ID, followed by the time settings, followed by the text. Each cue is separated by a blank line. Here’s an example of captions:

WEBVTT

1
00:00:01.000 --> 00:00:10.000
This is the first line of text, displaying from 1-10 seconds

2
00:00:15.000 --> 00:00:20.000
And the second line of text
separated over two lines

The above example has two cues. Times must be written in hh:mm:ss.mmm format, so the timings in this example occur in the first twenty seconds. The second cue will split the text over two lines automatically.

If you have a segment of text that needs to appear in a karaoke/paint-on caption style, then you can place timers inline with text:

1
00:00:01.000 --> 00:00:10.000
Never gonna give you up <00:00:01.000> Never gonna let you down <00:00:05.000> Never gonna run around and desert you

Styling Options #

The previous examples specify the minimum configuration you need for subtitling and captioning, but you can style your captions too. Let’s start with the cue settings, which are done on the same line as the time settings:

D:vertical / D:vertical-lr

Display the text vertically rather than horizontally. This also specifies whether the text grows to the left (vertical) or to the right (vertical-lr).

L:X / L:X%

Either a number or a percentage. If a percentage, then it is the position from the top of the frame. If a number, this represents what line number it will be.

T:X%

The position of the text horizontally on the video. T:100% would place the text on the right side of the video.

A:start / A:middle / A:end

The alignment of the text within its box – start is left-aligned, middle is centre-aligned, and end is right-aligned.

S:X%

The width of the text box as a percentage of the video width.

To make use of these settings, put them alongside the time settings, like this:

00:00:01.000 --> 00:00:10.000 A:middle T:50%
00:00:01.000 --> 00:00:10.000 A:end D:vertical
00:00:01.000 --> 00:00:10.000 A:start T:100% L:0%

which would result in something like the following:

Along with the above cue settings, you can use inline styles for text:

Bold text

<b>Lorem ipsum</b>

Italic text

<i>dolor sit amet</i>

Underlined text

<u>consectetuer adipiscing</u>

Ruby text

<ruby>見<rt>み</rt></ruby>

You can even apply a CSS class to a section of text using <c.myClass>Lorem ipsum</c>, giving us many more styling options.

Finally, you can add a declaration representing the name of the voice: <v Tom>Hello world</v>. This declaration accomplishes three things:

1. The caption will display the voice (Tom) in addition to the caption text.
2. The name of the voice can be read by a screenreader, possibly event using a different voice for male or female names.
3. It offers a hook for styling so that, for example, all captions for Tom could be in blue.

<track src="chapters.vtt" kind="chapters" srclang="en" />

WEBVTT

Chapter 1
00:00:01.000 --> 00:00:10.000>
Introduction to HTML5

Browser Support #

One slight glitch with WebVTT: not a single browser currently supports it. All major browsers have started working on implementations, so we should see some results soon. Thankfully, in the meantime, there are several JavaScript polyfills available:

• js_videosub
• Playr
• MediaElementJS
• LeanBack player (and upcoming new version)
• Captionator 

Demo #

We’ve put together a quick demo which uses the Playr polyfill. We started using MediaElementJS, but it doesn’t sport as many features as Playr, such as separate lines of text and CSS classes. In the demo, the subtitles start at 2 seconds and 15 seconds and use bold, underline, and custom styles. Here’s the associated WebVTT file.

Conclusion #

This article covers the basics of creating a WebVTT file suitable for subtitles or captions for a video. We know how to add cues and chapters and how to add styles and change how the text appears on the video. Although no browser yet supports it, there’s a lot more to come for accessible video, so stay tuned to the W3C Web Media Text Tracks Community Group.

What are your thoughts on WebVTT? Are any of you using it now? How can it be improved?

Finally, let’s thank @silviapfeiffer for taking the time to answer some questions about WebVTT and for her tremendous work in this field.

Reading #

• Follow @silviapfeiffer
• W3C Web Media Text Tracks Community Group
• Recent developments around WebVTT
• Presentation: HTML5 video accessibility and the WebVTT file format
• HTML5 video accessibility and the WebVTT file format – Audio Described
• A review with notes and thoughts for LeanBack Player
• WebVTT validator
• WebVTT and Video Subtitles
• The Open Video Alliance
• Understanding WebVTT file format (draft)
• Creating subtitles and audio descriptions with HTML5 video

What’s the point? #

It goes without saying that URLs are important. They’re the method of accessing the vast collections of information and resources on the web, and more recently, they’ve begun representing the intended state of a web application. You can copy these URLs and share them with your friends or use them to create links from any HTML document. They’re the veins of the web, and they need to be looked after.

Previously, the JavaScript History API offered some very simple functionality:

// Check the length of the history stack
console.log(history.length);

// Send the user agent forward
console.log(history.forward());

// Send the user agent back
console.log(history.back());

// Send the user agent back (negative) or forward (positive)
// by a given number of items
console.log(history.go(-3));

With dynamic Ajax web applications, where the browser updates the page in parts instead of changing location entirely, it’s difficult to give the user a URL to bookmark or share the current application state. Fragment identifiers, like those used on this article’s headings via the id attribute, provide some state information, but they’re entirely dependent on client-side scripts.

The changes to the History API are intended to give developers ways to push history items to the browser so the native back and forward actions can cycle through those items. These history items can also hold data that you can later extract to restore the page state.

Pages can add state objects between their entry in the session history and the next (“forward”) entry. These are then returned to the script when the user (or script) goes back in the history, thus enabling authors to use the “navigation” metaphor even in one-page applications.

If the user copies or bookmarks a stateful URL and visits it later, your back-end can be configured to interpret such a URL and jump the user right to the correct page and/or state.

In this article, I’ll cover the client-side use of the History API, so make sure you set up your server to work with the new URLs. If you’ve already built an accessible website that provide these entry points, you’re laughing!

Making History #

These examples will build on top of each other. We’ll start with a basic HTML document with some inline styles and scripts for your convenience.

Save this file and open it in your favourite editor. It must be accessed via HTTP, so that means you need either a local server (e.g. http://localhost/) or an online web server you can upload to. Viewing the file directly using your browser’s Open File function will not work, since it uses the file:// protocol and not HTTP. Also be sure to update the href attributes on each of the navigation links to ensure the correct directory structure is used. Personally, I’m viewing the demo locally at http://localhost/history.

We’ll be working exclusively within the <script> element at the end of the <body>. The code includes some simple styles and dynamically changes the content as you click the links. In reality, this could be loaded from your server via XMLHttpRequest, but for the purposes of this demonstration I’ve bundled it up into a self-contained file. The important part is that we have a quick-and-dirty dynamic page to work with, so let the fun begin!

At the moment there, is no bookmarkable URL for the different states of this page. If you click around the navigation items, then click Back in your browser, you won’t be taken back to the previous state and may even be taken away from the page to whatever you viewed before (depending on your browser). It would be nice if you could share “Socks” with your friends, right? We can do that via history.pushState().

The history.pushState() method takes three parameters:

data

Some structured data, such as settings or content, assigned to the history item.

title

The name of the item in the history drop-down shown by the browser’s back and forward buttons. (Note: this is not currently supported by any major browsers.)

url (optional)

The URL to this state that should be displayed in the address bar.

With these parameters, you can define the state of the page, give that state a name, and even provide a bookmarkable address, as if the page had reloaded entirely. Let’s dive right in and add this to the clickHandler function, right above the return statement:

function clickHandler(e) {
  /* Snip... */

  // Add an item to the history log
  history.pushState(data, event.target.textContent, event.target.href);

  return event.preventDefault();
}

The single line of code we added informs the history object that:

• we want to add an item to the log,
• it should remember the data that we’ve already loaded,
• it should assign a name to this state based on the text of the link we clicked (even though this isn’t used — it’s good to get into the habit of recording a name for the state), and
• it should update the address bar with the href attribute of that link.

Reload the page in your browser and click a few of the links, keeping an eye on the address bar. Notice how it changes on each click, despite the fact that you aren’t actually navigating away from this page. If you also have a look at your history log, you’ll see a long list of page titles (in this case ”Kittens!” over and over). Provided your server is set up to serve the correct page upon access, the user could copy that URL and paste it into a new browser window to jump straight to that kitten.

At the moment, clicking the back button will pop you through the history items, but the page won’t react to these changes. That’s because so far, we’ve only created the history records. How can we allow active users to return to a previous state? We listen to the popstate event.

Historical Events in Navigation #

The user agent fires a popstate event when the user navigates through their history, whether backwards or forwards, provided it isn’t taking the user away from the current page. That is, all those pushStates we called will keep the user on the current page, so the popstate event will fire for each history item they pop through.

Before the closing </script> tag, add a new listener for the popstate event:

// Revert to a previously saved state
window.addEventListener('popstate', function(event) {
  console.log('popstate fired!');

  updateContent(event.state);
});

We attach the event listener to the window, which is responsible for firing the event, and pass this event into our handler. We log a message (so we can see when this event is firing), and then we update the content using the state we saved previously. The state is attached to the event object via the state property.

Open up the page fresh in your browser, click around like before, and then click back. As before, the URL in the address bar changes as you cycle through states, but now the content is also restored back to what it should be. Click forward, and the content is likewise correctly restored.

Rewriting history #

Unfortunately, as fantastic as HTML5 is, it doesn’t allow us actual time travel. If it did, I would be going back to my childhood and telling a younger me, “Yes, you should have a slice of cake”. Take that as you will.

The History API does, however, allow us to make amends to our history log items. For example, we could update the current state in response to fresh user input in a form. We can do this with history.replaceState.

replaceState works just as pushState does, with the exact same parameters, except that it updates the current entry instead of adding a new one. I can think of one situation in our demo where this could be used: the initial page load. If you click back for long enough, you’ll find that going back to the original URL doesn’t provide you the original content. Let’s fix that by adding the following to the bottom of our script:

// Store the initial content so we can revisit it later
history.replaceState({
  content: contentEl.textContent,
  photo: photoEl.src
}, document.title, document.location.href);

As this runs when the page loads, it saves the initial page state. We can later load this state when the user browses back to this point via the event listener we set up previously. You can try it out by loading up the page, clicking a few links, and then hitting back until you return to the original URL. The initial content has returned!

Demo #

I’ve set up a demo of our completed code. I’ve also added a little back-end magic to make our history.pushState URLs work like a real site. Remember that the URLs you push should be live URLs that the user can bookmark and share as real entry points to your site.

View the History API demo

Browser support #

Up-to-date copies of Chrome (5+), Safari (5.0+), Firefox (4.0+), and Opera (11.50+) have support for the new History API. Even some mobile browsers work just fine, like Mobile Safari on iOS 4+. Unfortunately, IE 9 and below lack support, but it should work in IE 10 when it arrives.

Safari 5.0 sometimes exhibits one oddity: navigating between states causes the loading spinner to appear and stay even when the state has been loaded. This stops when you navigate away using a link or action that does not involve a state saved by the History API.

Closing thoughts #

URLs go beyond just the browsing session of a user. They’re historically important markers for resources that could very well remain in use for many years to come. Before you embark on developing your site’s JavaScript, you should give thought to the design of your URLs. Make them meaningful and organised. Make sure you can directly access them without JavaScript. Only then should you add your JavaScript to enhance the browsing experience.

Chinese proper name marks #

And what exactly are those you ask? I had to ask Wikipedia myself:

In Chinese writing, a proper name mark (Simplified Chinese: 专名号, zhuānmínghào; Traditional Chinese: 專名號) is an underline used to mark proper names, such as the names of people, places, dynasties, organizations. … This method of recognizing proper names in text is similar to the English use of a capital letter.

Wikipedia gives the following example, which I’ve formatted using <u>:

<u class="pnm">屈原</u>放逐，乃賦<cite class="bnm">離騒</cite>。<u class="pnm">左丘</u>失明，厥有<cite class="bnm">國語</cite>。（司馬遷 《<cite>報任安書</cite>》）

If you’re using Firefox 6+ you’ll also see the appropriate wavy underline for a Chinese book name mark on the quote’s source, courtesy of CSS3’s text-decoration-style: wavy;. I’ve used <cite> for book name marks as it’s more appropriate than <u>. You can find out more about wavy in CSS Text Level 3.

Using <u> for spell-checking feedback #

While you’re probably not marking up classical Chinese prose, a more familiar use case is for a spell-checker to indicate incorrect text. The default formatting in word processors is typically a red underline for spelling errors, and a green underline for grammatical errors:

.spelling-error {
  text-decoration: none;
  border-bottom: 1px dashed red;
}
.grammatical-error {
  text-decoration: none;
  border-bottom: 1px dashed green;
}
<p>hello doctor i am having a huge body <u class="spelling-error">oder</u> <u class="grammatical-error">it is smell really bad</u></p>

While we’ve turned off the default text-decoration style, <u> will back us up if CSS is disabled, and potentially provide more information for assistive technology. After all, if it’s semantic it should be in HTML, not CSS.

Some word processors use wavy underlines. This CSS would have the same effect in a supporting browser:

.spelling-error {
  text-decoration-line: underline;
  text-decoration-style: wavy;
  text-decoration-color: red;
}
.grammatical-error {
  text-decoration-line: underline;
  text-decoration-style: wavy;
  text-decoration-color: green;
}

Or, using text-decoration as a shorthand property, and adding a default declaration for non-supporting browsers:

.spelling-error {
  text-decoration: underline; /* for backwards compatibility */
  text-decoration: underline wavy red;
}
.grammatical-error {
  text-decoration: underline; /* for backwards compatibility */
  text-decoration: underline wavy green;
}

Again, you can read more about the upgraded text-decoration properties in CSS Text Level 3.

Using <u> for indicating family names #

Another use for <u> is to annotate a family name when this might be confusing — Chinese, Japanese, Korean and Vietnamese (among others) all traditionally write names in a different order than the western-centric “given-name family-name”. While applying a blanket western ordering is fairly common (especially when publishing in English), it’s good form to use culturally appropriate ordering. If the audience might misunderstand, the family name can be underlined, capitalised, or otherwise annotated to make the name order explicit. For example, the CIA’s World Fact Book capitalises the family name:

After World War II, the Communists under MAO Zedong established an autocratic socialist system …

This ties in nicely with the hCard microformat, as the “implied n optimisation” doesn’t work with these non-western ordered names, and we need a wrapper element to indicate each part of the name anyhow.

<style>
  .family-name {text-decoration: underline;}
</style>
<p>
  <span class="vcard" lang="ja-latn">
    <span class="fn n">
      <u class="family-name">Son</u> <span class="given-name">Goku</span>
    </span>
  </span>
   is the main protagonist in 
  <span class="vcard" lang="ja-latn">
    <span class="fn n">
      <span class="given-name">Akira</span> <u class="family-name">Toriyama</u>
    </span>
  </span>’s <i lang="ja-latn">manga</i> “Dragon Ball”.
</p>

Of course you can then change the style via CSS, for example

.family-name {
  text-decoration: none;
  text-transform: uppercase;
}

The benefit of using <u> for this is the family name will be indicated even when CSS is disabled, ensuring the annotation isn’t lost. Assistive technology may also be able to inform the user of this in the future.

But do we need <u>? #

A lot of people bitten by the web standardista bug have somewhat of an allergic reaction to ex-presentational elements in HTML5, after influential articles like Tantek Çelik’s “<b>ed and <br>eakfast markup”. Given <u>’s ignoble past, I expect the reaction to its return will also lead to some poo-pooing. As we already mentioned, however, if it imparts meaning, it should be in HTML. These use cases involve semantic meaning, and even without assistive technology support, <u> conveys some meaning to sighted users via the browser-default style text-decoration: underline;.

Regardless of whether an element is deprecated (HTML 4, XHTML 1) or non-conforming (HTML5) or just plain uncool, browser makers still have to support it for backward compatibility with all those awesome web pages from the days when <blink> was hawt. Because of this, if there’s a semantic use case for an ex-presentational element, it’s definitely better to reform it rather than minting a new element with no backward compatibility. You might think <mark> sounds pretty similar, but the default browser styling would be completely wrong for proper name marks, and semantically less appropriate for spelling errors too.

As Ian Hickson explains:

The presentational markup that was <u>, <i>, <b>, <font>, <small>, etc, is gone. However, there are certain use cases that did not yet have elements yet were important enough to warrant us supporting them. By reusing existing elements, we are able to support them without having to wait for new elements to be implemented. By doing so in a way that closely matches how those elements were actually used in practice (at least to the same extent as other elements have been correctly used in practice) we can not only have older UAs support these new elements automatically, but we can do so in a way that does not introduce an undue volume of invalid pages.

Conclusion

Given the potential to confuse underlined text with links, using text-decoration: underline; on anything other than <a> is bad pretty much all the time. Generally <u> is not the element you’re looking for, even for Chinese book name marks (<cite> would be more appropriate). However, for at least these three use cases, it’s good to have a semantic option, something better than <span>.

So…in a hypothetical world where you did need to code for one of these situations, would you use <u> or something else like <span>? Let us know in the comments!

Overview

Personally, I’ve never been keen on video-based learning like this. As such, I wasn’t sure what I’d make of HTML5 Now. It turns out I was pleasantly surprised by the format, the content, and the presentation.

Tantek has an natural, engaging presentation style, and his knowledge of the subject area ranks up there with the best of them. He begins with an interesting historical look at HTML and in turn how HTML5 came to be. This section is full of things you might not know about HTML, let alone HTML5.

A few other thoughts:

• Tantek constantly urges you to get involved and share your experiences.
• The early parts of the DVD contain in-depth background information on elements and attributes.
• Tantek presents a clear, concise introduction to <ruby> and friends, even explaining how it’s worked in IE for 10+ years!
• He introduces his bulletproof HTML5 syntax (using <div>s with class names inside new elements).
• The accompanying booklet effectively takes notes for you so you don’t have to. Just sit back and enjoy!
• The DVD also contains the slides shown throughout the presentation and a PDF of the booklet.
• A few tongue-tied moments help keep it real, not staged or forced. It shows Tantek really cares about the subject.
• You’ll get some good tips on when to use the new elements. Additionally, some elements are more stable since the DVD was released.
• Each section is concluded by a brief summary recapping what you’ve learnt.

Words of warning

As is the case with any book or DVD based on the constantly evolving HTML5 specification, parts of the DVD are now out of date. (It was originally released in July 2010.) Look out for these gotchas:

• Certain sections don’t mention browser support.
• <u> is now a part of the HTML5 specification.
• The WebM video codec didn’t exist at the time of production.
• There is no mention of form attributes and support for the new input types.
• <canvas> is incorrectly described as a vector format (it’s bitmap).
• It’s a shame that Tantek only scratches the surface of <video>, <audio>, <canvas>, and SVG. They each deserve their own DVD!

Summary

I’m still not convinced that DVD is the best format for this type of content. As with print, it goes out of date very quickly. Alternatively, you could simply publish the video(s) on a website and make them available on a subscription basis. That way, outdated information could be updated more regularly. That’s a discussion for another day, though, and I’m sure Tantek would be keen to see it happen.

In my opinion, the DVD is better suited to someone who has some prior knowledge of HTML and HTML5. It’s certainly not for beginners, but it does come recommended. You’ll definitely learn something. I’ll leave you with a video of Tantek (Figure 2) discussing the state of HTML5 at the Voices that Matter Conference just before the DVD was released:

Isn’t this bad practice?

For years, we’ve been told (and have actively told others) to separate content and presentation layers. So why would we introduce something that seems to go against everything we’ve been preaching?

The separation of these layers is still vitally important, but let’s look at a few use cases to shed some light on why this attribute has been introduced. Scoped style provides a W3C-approved way to:

• Add one-off CSS styles.
• Add user-defined styles to wiki or CMS content.
• Add theme-defined styles via CMS plugins.
• Keep syndicated content together (e.g., keeping example code together with the example).

How does it work?

In this section, I’ll show you how this new attribute will work when it gets rolled out to browsers.

<article>
  <h1>Style Scoped</h1>
  <p>The scoped attribute for the style element will eventually allow for you to include style elements mid-document. To do this, you must mark up your style element with the scoped attribute.</p>
  <section>
    <h2>How does it work?</h2>
    <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  </section>
</article>

Adding the scoped attribute

In the next example, we’ll change the foreground color of the second paragraph to red (from whatever was defined in the master CSS file):

<article>
  <h1>Style Scoped</h1>
  <p>The scoped attribute for the style element will eventually allow for you to include style elements mid-document. To do this, you must mark up your style element with the scoped attribute.</p>
  <section>
    <style scoped>
      p { color: red; }
    </style>
    <h2>How does it work?</h2>
    <p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  </section>
</article>

This screenshot shows how things might render in the browser:

Can I apply scoped to <link>?

While I was writing this article, Dr. Rich asked whether it was possible to add this attribute to <link> elements. Turns out you can’t, but I stumbled across this tidbit in the WHATWG mailing list:

You can use <style scoped>@import url(whatever);</style>

And this even enables you to add some specific styles ([be they embedded] or from another external sheet) on a per-use basis if the need arises. For example, a long dissertation relying on many quotes may benefit from adding stronger visual highlights on the <em> elements within the last quote to reinforce the final conclusion.

Backwards compatibility

Unfortunately, scoped style isn’t all puppy dogs and kittens.

Since this newly introduced attribute isn’t understood by current browsers, CSS rules in <style scoped> are just added to the page’s CSS. Therefore, if you were to include a scoped style block mid-page, its declarations would be applied to every matching element in the document, regardless of whether the element were inside or outside of the scope’s range.

For the sake of backwards compatibility, Louis Lazaris has suggested a brand new element called <scopedstyle>. This new element would only be recognised by supporting browsers and ignored by everything else. This way, scoped styles wouldn’t be added to the whole document. Instead, the browser would just throw away the unrecognised <scopedstyle> element and move on.

Browser support

Currently, the scoped attribute isn’t working in any of the browser alpha versions (Opera.Next, Mozilla Aurora, or WebKit nightly builds). There’s work in progress by Roland Steiner for support in WebKit.

Using <style scoped> today

So you’ve read this article and decided that you need scoped style in your life. What now? Well, just like every other new HTML5 thing, we have a polyfill for it. Simon Madine has created a jQuery scoped CSS plugin on GitHub.

You could also assign a CSS prefix to target the section of your document you want to style. You’d still be able to stick your styles inline, but you’ve also provided a fallback for the older browsers. In fact, Dr. Oli has done just that on his latest article. (View source and search for <div class="faint">.)

Opinions

There’s no denying that we’re breaking backwards compatibility by introducing <style scoped>. To me, this just doesn’t make any sense. I feel this needs to be addressed by either creating a new element like <scopedstyle> or using some protective mechanism like the <!-- and --> delimiters that have been used within <style> and <script> elements.

Let’s not end this article with negative sentiment, though. As with anything, it’s what you make of it. Scoped style is pretty plain vanilla, but if people abuse it, it’ll end up with a bad rap. Dr. Oli has spoken at length about his love for this attribute as it allows him to have live code examples with the CSS in <pre> and also in a <style scoped> within a <figure>.

So now it’s time for you to express your views. What do you think about the new scoped attribute? Do you think it has a future? Should it be fast-tracked into the spec? Or do you think it’s a waste of time that could ultimately end up mixing our content and presentation layers together again? Let us know in the comments!