Semantics and the Web #

Semantics are the implied meaning of a subject, like a word or sentence. It aids how humans (and these days, machines) interpret subject matter. On the web, HTML serves both humans and machines, suggesting the purpose of the content enclosed within an HTML tag. Since the dawn of HTML, elements have been revised and adapted based on actual usage on the web, ideally so that authors can navigate markup with ease and create carefully structured documents, and so that machines can infer the context of the wonderful collection of data we humans can read.

Until — and perhaps even after — machines can understand language and all its nuances at the same level as a human, we need HTML to help machines understand what we mean. A computer doesn’t care if you had pizza for dinner. It likely just wants to know what on earth it should do with that information.

HTML semantics are a nuanced subject, widely debated and easily open to interpretation. Not everyone agrees on the same thing right away, and this is where problems arise.

What’s the point? #

Discussions over the importance of semantics are happening all the time, and every so often there’s an uproar over specific articles on the subject. Divya Manian caused a stir in her Smashing Magazine article Our Pointless Pursuit Of Semantic Value in November 2011, in which she argued we have become too caught up in trying to use HTML5′s semantics, and that the benefits aren’t worth it:

Allow me to paint a picture:

1. You are busy creating a website.
2. You have a thought, “Oh, now I have to add an element.”
3. Then another thought, “I feel so guilty adding a div. Div-itis is terrible, I hear.”
4. Then, “I should use something else. The aside element might be appropriate.”
5. Three searches and five articles later, you’re fairly confident that aside is not semantically correct.
6. You decide on article, because at least it’s not a div.
7. You’ve wasted 40 minutes, with no tangible benefit to show for it.

This generated a storm of responses, both positive and negative. In Pursuing Semantic Value Jeremy Keith argued that being semantically correct is not fruitless, and he even gave an example of how <section> can be used to adjust a document’s outline. He concludes:

But if you can get past the blustery tone and get to the kernel of the article, it’s a fairly straightforward message: don’t get too hung up on semantics to the detriment of other important facets of web development.

I’ll admit I’ve been in a situation where I’ve dug myself a mind hole, trying to decide which element is “correct” and then depressing myself with thoughts of how irrelevant it all seems. What gives me strength is the thought that I’m not marking this up for me, but for everyone who can benefit from the enhanced meaning. Whether it’s the browser, a search engine spider, an accessibility tool, the person you pass the project on to, or even future you returning to the project in six months time, the markup indicates how the content should be interpreted. As long as your markup makes sense and isn’t over the top (e.g., if you just replace all your HTML 4 <div>s with <section>s, you may be misunderstanding the element or even your content), then don’t worry so much about it all.

To help you choose the most appropriate element, we released a flowchart of HTML5 sectioning elements that you can print off and follow whenever you get stuck. If all else fails, don’t forget about your old buddy <div>. Then again, maybe you’ve stumbled across a need for something new…

Naming Things #

Of all the possible new element names in HTML5, the spec is pretty set on things like <nav> and <footer>. If you’ve used either of those as a class or id in your own markup, it’s no coincidence. Studies of the web from the likes of Google and Opera (amongst others) looked at which names people were using to hint at the purpose of a part of their HTML documents. The authors of the HTML5 spec recognised that developers needed more semantic elements and looked at what classes and IDs were already being used to convey such meaning.

Of course, it isn’t possible to use all of the names researched, and of the millions of words in the English language that could have been used, it’s better to focus on a small subset that meets the demands of the web. Yet some people feel that the spec isn’t yet doing so.

What about adding more elements? #

When I first met fellow HTML5 Doctor Bruce Lawson, I asked him this question: If we have elements like <article>, why don’t we have one for products of a shop? I understand more about HTML now than I did then, but at the time it seemed like a very logical element to add. Why restrict ourselves to documents with <article>s when the web has evolved beyond that with shops, applications, and games? I’m sure many of you have felt the same way. Some have even put cases to the WHATWG suggesting more elements like the often requested <comment>.

Recently, editor of the HTML5 spec Ian Hickson wrote responses to some of these requests for new elements for comments, explaining why <article> within <article> suffices for marking up comments:

<article> isn’t just for articles. That’s the point.

Note that its name is irrelevant here. It could be called <pineapple> — what matters is what it is defined to mean, not what its name is. And its definition is one that covers both articles and comments. They are both self-contained compositions.

As much as I am all for the much needed addition of <pineapple>, Ian makes a good case for why we don’t need <comment> (or similar). Dr Bruce often uses the following analogy when trying to explain <article>:

Don’t think of <article> as a magazine article. Think of it as an article of clothing, an independent entity that can be arranged in conjunction with other articles of clothing, but is a complete thing in itself.

I hear you ask, That’s all well and good, Mike, but what does understanding <article> have to do with adding new elements? To add something to the spec, you need to:

1. document actual use cases,
2. show how developers are working around the lack of this feature now, and
3. make a compelling case for why HTML5 needs it.

Step one is to make sure what you’re asking for can’t be achieved with what already exists. This is exactly the problem with the proposals for <comment>. Any difference from <article> is so minimal that it isn’t worth adding.

If every proposal for a minor deviation of an existing element was accepted, the spec would be bloated with far more elements than necessary. User agents would have to keep up with the vast array of markup possibilities for a given bit of content — as would you, the author. And think about this: at the end of the day, what are you actually going to use that new element for? Really?

That’s not to say you should be discouraged from putting your ideas forward. Take it as advice on what to look for when you want to contribute something to the spec. It may even help you to think differently about your work. Some problems just need a fresh perspective to help solve them.

HTML5 Doctor, or: How I Learned to Stop Worrying and Love HTML #

Once you learn to look past element names and think of their essential meaning, it gets a bit easier to write markup. Think of your chunks of content in terms of how they relate to each other and in which contexts they can be used. In our article archive, we’ve covered a lot of elements with examples of their use. If you’re ever in doubt, I highly recommend our flowchart of HTML5 sectioning elements to help you along.

Try to keep things simple. Overthinking your markup will only cause more problems than it’s worth. And let’s face it: it’s not like you can’t change it later!

You may also be interested in adopting Microformats, something Dr Oli Studholme has written about here on HTML5 Doctor. Extending HTML5 — Microformats is recommended reading for those who want to take their markup a bit further. Dr Oli has also looked at Extending HTML5 with Microdata, which gives us a whole new way to add extra semantic information.

Finally, try utilising HTML5 markup in ways that gain the benefit of these new elements. Create tools, use your own documents to test how well-formed and structured they are, and test how portable your content really is. Who knows, you may even find yourself writing a proposal for the next addition to the spec.

Do you know something the web needs that’s missing from HTML5? Let us know in the comments.

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.

What are document outlines? #

The document outline is the structure of a document, generated by the document’s headings, form titles, table titles, and any other appropriate landmarks to map out the document. The user agent can apply this information to generate a table of contents, for example. This table of contents could then be used by assistive technology to help the user, or be parsed by a machine like a search engine to improve search results.

The outlining algorithm has been clearly defined in the HTML5 spec, so once all browsers and assistive technologies play ball, there will be some major accessibility wins (more on support later). Before we take a look at how this new algorithm works, it’s time for a quick walk down memory lane.

Outlines in HTML4 #

Creating document outlines prior to HTML5 was simple. You had six heading elements, <h1> through <h6>. Lower-numbered headings were of a higher rank of higher-numbered ones — i.e. <h1> was ranked higher than <h2>:

<h1>My fantastic site</h1>
<h2>About me</h2>
<p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
<h3>What I do for a living</h3>
<p>I sell enterprise-managed ant farms.</p>
<h2>Contact</h2>
<p>Shout my name and I will come to you.</p>

This example would produce the following outline:

The <h2> titles are children of the <h1>, and the “About me” content has a further sub-heading using an <h3>. It’s simple but restrictive, as you have to ensure the heading levels are appropriate for the intended structure, and you’re limited to six levels. The latter restriction is usually not such a problem, but it still exists for all you heading fanatics (oh you guys!).

HTML5 does this as well. The above example would produce the same outline, but it can be taken even further using the new sectioning elements.

Sectioning elements #

The concepts behind HTML5 document outlines are actually older than you might think! Tim Berners-Lee posted to the www-talk mailing list back in 1991 (props to Dr Oli for digging that up), suggesting something quite close to what is demonstrated in this article.

The sectioning elements <section>, <article>, <aside> and <nav> can all help to create a more logical structure in the document outline. Let’s go crazy and rewrite our previous example using only <h1> elements for headings:

<h1>My fantastic site</h1>
<h1>About me</h1>
<p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
<h1>What I do for a living</h1>
<p>I sell enterprise-managed ant farms.</p>
<h1>Contact</h1>
<p>Shout my name and I will come to you.</p>

The outline would now look like this:

Clearly, that’s no good — we’ve lost our structure! With sectioning elements, we can make it look like before without changing those headings. In this particular example, I think <section> is most appropriate:

<h1>My fantastic site</h1>
<section>
  <h1>About me</h1>
  <p>I am a man who lives a fascinating life. Oh the stories I could tell you...</p>
  <section>
    <h1>What I do for a living</h1>
    <p>I sell enterprise-managed ant farms.</p>
  </section>
</section>
<section>
  <h1>Contact</h1>
  <p>Shout my name and I will come to you.</p>
</section>

Run it through the outliner and we’re back to normal:

But why? The sectioning elements act quite literally as their name suggests: they define sections of the parent element. These sections can be thought of as child nodes whose headings fall under their parent heading, regardless of their rank. The following example illustrates this further:

<h2>HTML5 Doctor articles</h2>
<article>
  <h1>The section element</h1>
  <p>We doctors are a bunch of chums using HTML5 and writing about how we do it...</p>
</article>
<article>
  <h1>The article element</h1>
  <p>We’ve discussed a lot of new elements here at HTML5Doctor...</p>
</article>

Even though the articles contain <h1>s, this produces the following outline:

Equally, owing to how the outliner works, the following examples (while probably not the best use of headings) produce the exact same above outline:

<h1>HTML5 Doctor articles</h1>
<article>
  <h3>The section element</h3>
</article>
<article>
  <h3>The article element</h3>
</article>

<h2>HTML5 Doctor articles</h2>
<article>
  <h2>The section element</h2>
</article>
<article>
  <h2>The article element</h2>
</article>

<h6>HTML5 Doctor articles</h6>
<article>
  <h1>The section element</h1>
</article>
<article>
  <h1>The article element</h1>
</article>

When choosing which heading to use in your documents, the spec has recommendations:

Sections may contain headings of any rank, but authors are strongly encouraged to either use only h1 elements, or to use elements of the appropriate rank for the section’s nesting level.

You should also make sure you’re aware of how differently ranked headings work when used as direct children of a sectioning element. It’s how it worked prior to HTML5:

The first element of heading content in an element of sectioning content represents the heading for that section. Subsequent headings of equal or higher rank start new (implied) sections, headings of lower rank start implied subsections that are part of the previous one. In both cases, the element represents the heading of the implied section.

<aside>
  <section>
    <h2>Twitter</h2>
  </section>
  <section>
    <h2>Recent comments</h2>
  </section>
</aside>

<aside>
  <h1>What you're saying</h1>
  <section>
    <h2>Twitter</h2>
  </section>
  <section>
    <h2>Recent comments</h2>
  </section>
</aside>

How does <hgroup> affect the outline? #

As Dr Richard Clark said in our <hgroup> article, <hgroup> is all about the document outline. The outliner will disregard all headings within <hgroup> except the one with the highest ranking. For example, if an <hgroup> contains an <h2>, an <h3> and an <h4>, only the <h2>’s text will be used as the section title in the outline. For example, the following markup:

<article>
  <hgroup>
    <h1>Title goes here</h1>
    <h2>Subtitle of article</h2>
  </hgroup>
  <p>Lorem Ipsum dolor set amet</p>
</article>

Would produce the following outline.

At the time of writing, <hgroup>’s future is a little uncertain. It was recently removed and then returned to the HTML5 spec, and there are proposals for its removal or replacement with an alternative. We’ll be sure to keep HTML5 Doctor up-to-date with any changes as they unfold.

Sectioning roots #

Sectioning roots, introduced in HTML5, isolate certain parts of a document to their own separate outlines. Headings within these elements will not show up in the main outline, where the sectioning root element is the <body>.

The other sectioning root elements are <blockquote>, <figure>, <details>, <fieldset>, and <td>. Each one of these elements is a descendant of the <body> element, but its headings are removed from the top-level outline, instead starting its own isolated outline.

<h1>Top of the outline</h1>

<section>
  <h2>A heading in the outline</h2>
  <p>Lorem ipsum dolor sit amet...</p>
</section>
<section>
  <h2>Another heading in the outline</h2>
  <p>Lorem ipsum dolor sit amet...</p>
  <blockquote>
    <h1>This quoted heading will not appear in the outline</h1>
    <p>Lorem ipsum dolor sit amet...</p>
  </blockquote>
</section>

This results in the following outline. Notice that it lacks the <blockquote>’s heading, which has been isolated:

Outlines in the real world #

Unfortunately, there is little support for the new outlining algorithms right now. Search engines may be experimenting with it in their crawling algorithms as you read this, but as far as we know, headings are treated just as they were before. You won’t be penalised for using them, even if you use multiple <h1>s (which have always been okay as far as the spec is concerned). Check out our HTML5 and Search Engine Optimisation article for more on search engines and HTML5.

At the time of writing, screen readers do not support these new outlines, so if you do use multiple <h1>s in your documents, it may confuse your users. It’s best if you use logical heading levels — <h1>–<h6> — at least until the new outlines are more widely supported.

As for browsers, both recent releases of Firefox and Chrome have a user agent styles that support HTML5 document outlines. Try this bare-bones example in the latest Chrome or Firefox.

Final thoughts #

Despite the spotty support, it’s definitely worth thinking carefully about your document outlines so you’re prepared for the future, and tune in here for news of improved support.

Get to grips with the sectioning elements and sectioning roots and how each affects the outline. When marking up a new site, consider how you could take advantage of the new document outline algorithm. As user agent support strengthens, pages you made with your new-found knowledge of document outlines will be more accessible. Let us know what you think in the comments below!

The manifest file

Let’s start with an example of a full manifest file. (Don’t worry, I’ll explain it all in detail!)

CACHE MANIFEST
      
# This is a comment

CACHE:
/css/screen.css
/css/offline.css
/js/screen.js
/img/logo.png

http://example.com/css/styles.css

FALLBACK:
/ /offline.html

NETWORK:
*

Each directive is placed on a new line, with comments prefixed by a hash (#). The first line, CACHE MANIFEST, tells the browser that this is a manifest file. The uppercased lines with trailing colons are section headings.

There are three different sections in a manifest file:

CACHE

A list of explicit URLs to request and store

FALLBACK

What to do when an offline user attempts to access an uncached file

NETWORK

Which resources are available only while online

Each section serves a specific purpose that you must understand in order to successfully and effectively cache your resources.

CACHE MANIFEST

/css/screen.css
/css/offline.css
/js/screen.js
/img/logo.png

http://example.com/css/widget.css

CACHE MANIFEST

FALLBACK:
/status.html /offline.html

CACHE MANIFEST

FALLBACK:
/ /offline.html

CACHE MANIFEST

FALLBACK:
/images/avatars/ /offline_avatar.png

CACHE MANIFEST

NETWORK:
*

CACHE MANIFEST

NETWORK:
register.php
login.php

Serving the manifest

You can reference a manifest file on a web page by adding the manifest attribute to your opening <html> tag. The browser will only cache pages that include this attribute (in addition to those specified in the manifest itself, though in that instance, the user would have to visit a page including the manifest in order for the browser to be aware of it).

<!DOCTYPE html>
<html lang="en" manifest="/offline.appcache">
  // your html document
</html>

The linked file should also be served with a MIME-type of text/cache-manifest. If you’re using Apache as your web server, add this to your .htaccess file:

AddType text/cache-manifest .appcache

And there you have it! Supporting browsers will retrieve the manifest file and cache each item on the list for offline use. Won’t your parents be proud?

Triggering a cache refresh

Once a cache has been successfully downloaded, the browser will retain those assets until either the user clears the cache or you trigger an update. Triggering an update with your manifest file requires that the contents of that file change, not just the assets themselves.

Updating the assets on your server will not trigger a cache update. You must modify the manifest file.

If you’re adding or removing resources completely, you’ll have to edit your manifest file anyway. But what if you’re just amending an already cached stylesheet?

This is where comments come in handy. Just throw in a simple version number comment that you change when you want to trigger an update:

CACHE MANIFEST
      
# Version 9

CACHE:
/css/screen.css

The next time you want to trigger a cache refresh, just increment the version number. When the user next visits the online version of a page including this manifest, it will re-download the manifest file, notice the change, download the listed assets, and purge the existing cache.

Browser bug: Firefox caches the manifest file itself and will not update it even if the manifest has changed on the server. With some server config wizardry, you can tell browsers that the cache of the manifest file is instantly invalidated and should be requested from the server every time it’s referenced. Add this to your .htaccess to put Firefox in its place:

<IfModule mod_expires.c>
  ExpiresActive On
  ExpiresByType text/cache-manifest "access plus 0 seconds"
</IfModule>

Conclusion

The application cache is a powerful beast, and to tame it you need to be clear on what’s involved. Give thought to your CACHE, FALLBACK, and NETWORK sections to provide a suitable offline experience to your users.

In a future article, we’ll show you how to use the applicationCache JavaScript object to manipulate the cache. Until then, this should be enough to get you started on the path to offline web content.

You can see a live demo using the application cache over on Doctor Remy’s HTML5 Demos. Happy caching!