The WHATWG Blog

Please leave your sense of logic at the door, thanks!

Archive for the ‘Tutorials’ Category

The Road to HTML 5: contentEditable

Friday, March 6th, 2009

Welcome back to my semi-regular column, "The Road to HTML 5," where I'll try to explain some of the new elements, attributes, and other features in the upcoming HTML 5 specification.

The feature of the day is contentEditable, by which I mean client-side in-browser "rich text" editing. All major browsers support this now, including Firefox 3, Safari 3, Opera 9, Google Chrome, and Internet Explorer (since 5.5). Of course, the devil is in the details.

In this article:

What is contentEditable?

There are really two attributes involved, designMode and contentEditable. The designMode attribute governs the entire document (i.e. it makes the entire document editable, like a dedicated HTML editor). The contentEditable attribute governs just the element on which it appears, and that element's children -- like a rich text editor control within a page. In fact, that was the original use case: enabling web developers to build rich text editors. There are now a variety of such editors available under various licenses.

Both of these attributes, designMode and contentEditable, were originally designed and implemented by Microsoft in Windows Internet Explorer (5.5, to be exact). There was some superficial documentation on how to use them (so developers could develop rich text editors), but little thought of interoperability. So, no details on all the nitty gritty details of exactly what markup is generated when you press ENTER right here, or what the DOM looks like as you backspace your way through a start tag. Much of this sort of information was later reverse-engineered, and cross-browser support for basic operations is actually quite good. (Browsers still vary widely on the details.) The designMode and contentEditable attributes, and the APIs that drive rich text editors, are implemented in all major browsers, including Firefox, Opera, Safari, Google Chrome, and of course Internet Explorer.

How does it work?

Mark Finkle wrote a nice high-level summary of designMode, and later added a post about contentEditable once it appeared in the Firefox 3 alphas. (That was back in 2007.) Quoting Mark:

Mozilla has a rich text editing system (called Midas) and an API similar to Internet Explorer's. Mozilla, like Internet Explorer, supports the ability to make an entire document editable by setting the designMode property of the document object. Once in design mode, the document can be manipulated using various DHTML commands.

... Firefox 3 is expanding its rich WYSIWYG editing capabilities by adding support for the contentEditable attribute. Setting contentEditable to "true" allows you to make parts of a document editable. ...

The API for interacting with the document is:

document.execCommand
Executes the given command.
document.queryCommandEnabled
Determines whether the given command can be executed on the document in its current state.
document.queryCommandIndeterm
Determines whether the current selection is in an indetermined state.
document.queryCommandState
Determines whether the given command has been executed on the current selection.
document.queryCommandValue
Determines the current value of the document, range, or current selection for the given command.

Once you have an editable document (designMode) or element (contentEditable), you use this set of API calls to issue "commands" on the editable region, and to query the current state of the region. Commands are things like "bold," "italic," "underline," "create a link," "change foreground color," and so on -- all the commands you would expect from a rich text editor. Here's a test page with 36 commands.

In other words, "supporting the contentEditable attribute" is really just the tip of the iceberg. The real compatibility story is written in the commands which are passed to the document.execCommand() function. So which browsers support which commands?

As you can see from Peter's chart, basic stuff like bold, italic, creating links, and changing colors is well-supported across browsers. After that, the compatibility story gets hairy.

A brief and extremely biased timeline of standardization

Reverse-engineering and standardizing contentEditable and its associated APIs was one of the original goals of the WHAT working group, as part of (what at the time was called) "Web Applications 1.0" and is now known as "HTML 5."

Conclusion

The original use case for contentEditable -- building rich text editors -- is alive and well on the web. Cross-browser compatibility can be charitably described as "evolving," but we are long past the point where "only IE can do that fancy rich-text stuff." Standardization through the WHATWG has shaken out numerous interoperability bugs and led to thoughtful consideration of a wide variety of edge cases. Most of these benefits had to be realized through reverse engineering, rather than cooperation, but the work has been done and the web is better for it.

Further reading

Posted in Tutorials | 17 Comments »

The Road to HTML 5: spellchecking

Wednesday, March 4th, 2009

Welcome back to my semi-regular column, "The Road to HTML 5," where I'll try to explain some of the new elements, attributes, and other features in the upcoming HTML 5 specification.

The feature of the day is spell checking, by which I mean client-side in-browser checking of text in standard <textarea> and <input type=text> elements. Several browsers support this out-of-the-box, including Firefox 2 and 3, Safari 3, Opera 9, and Google Chrome. However, each browser has different defaults of which elements get spell-checked, and only a handful allow the web author to suggest whether browsers should offer checking on a particular element.

In this article:

A brief history of the spellcheck attribute

That last bit, by the way, is why this is relevant to HTML 5. Browser features are interesting, but are mostly outside the purview of spec-land. But the idea of a markup hint to suggest turning spell-checking on or off has been bounced around for years. To wit:

Examples

Getting down to the technical details, the spellcheck attribute is a bit of an oddball. Most boolean attributes (such as <option selected>) are false if they are absent, true if they are present, and true if they are present with a value the same as the attribute name (e.g. <option selected=selected>). The spellcheck attribute is not like that; instead, it requires an attribute value of either true or false.

So this is valid:

<textarea spellcheck="true">

And this is valid:

<textarea spellcheck="false">

But this is not valid:

<textarea spellcheck>

Browser support

Browser support is currently... limited.

MarkupFirefox 3.0.6Google Chrome 1.0.154.48Safari 3.2.1Opera 9.62
<input type=text>offer on right-clickno checkcheck as you typeoffer on right-click
<input type=text spellcheck=true>check as you typeno checkcheck as you typeoffer on right-click
<input type=text spellcheck=false>offer on right-clickno checkcheck as you typeoffer on right-click
<input type=text spellcheck> invalidoffer on right-clickno checkcheck as you typeoffer on right-click
<input type=text spellcheck=spellcheck> invalidoffer on right-clickno checkcheck as you typeoffer on right-click
<input type=text spellcheck=on> invalidoffer on right-clickno checkcheck as you typeoffer on right-click
<input type=text spellcheck=off> invalidoffer on right-clickno checkcheck as you typeoffer on right-click
<textarea>check as you typecheck as you typecheck as you typeoffer on right-click
<textarea spellcheck=true>check as you typecheck as you typecheck as you typeoffer on right-click
<textarea spellcheck=false>offer on right-clickcheck as you typecheck as you typeoffer on right-click
<textarea spellcheck> invalidcheck as you typecheck as you typecheck as you typeoffer on right-click
<textarea spellcheck=spellcheck> invalidcheck as you typecheck as you typecheck as you typeoffer on right-click
<textarea spellcheck=on> invalidcheck as you typecheck as you typecheck as you typeoffer on right-click
<textarea spellcheck=off> invalidcheck as you typecheck as you typecheck as you typeoffer on right-click

In other words:

Detecting support for the spellcheck attribute

Browsers that support the spellcheck attribute will always reflect the attribute in the .spellcheck property of the element's DOM node, even if the spellcheck attribute does not appear in the page markup. You can use this to construct a simple test to check whether the browser supports the spellcheck attribute:

if ('spellcheck' in document.createElement('textarea')) {
    alert('browser supports spellcheck attribute');
  } else {
    alert('browser does not support spellcheck attribute');
  }

This will pop up an alert stating "browser supports spellcheck attribute" in Firefox 2 and 3, or an alert stating "browser does not support spellcheck attribute" in Safari 3, Opera 9, Google Chrome, and Internet Explorer.

Note: Internet Explorer will reflect any attribute present in the page markup. If you include a spellcheck attribute on an element and then test whether that element's DOM node contains a .spellcheck property, IE will always return true. The safest way to check is to create a new element in script, like the example above, instead of testing a pre-existing element on your page.

Conclusion

You can start using the spellcheck attribute today, but it only affects the behavior of Firefox. However, it has no adverse effects in other browsers. Be sure to use either spellcheck="true" or spellcheck="false", as these are the only values supported by Firefox (and the only valid values according to the HTML 5 spec as it stands today).

Posted in Tutorials | 9 Comments »

The Road to HTML 5: character encoding

Friday, February 13th, 2009

Welcome back to my semi-regular column, "The Road to HTML 5," where I'll try to explain some of the new elements, attributes, and other features in the upcoming HTML 5 specification.

The feature of the day is character encoding, specifically how to determine the character encoding of an HTML document. I am never happier than when I am writing about character encoding. But first, here is my standard "elevator pitch" description of what character encoding is:

When you think of "text," you probably think of "characters and symbols I see on my computer screen." But computers don't deal in characters and symbols; they deal in bits and bytes. Every piece of text you've ever seen on a computer screen is actually stored in a particular character encoding. There are many different character encodings, some optimized for particular languages like Russian or Chinese or English, and others that can be used for multiple languages. Very roughly speaking, the character encoding provides a mapping between the stuff you see on your screen and the stuff your computer actually stores in memory and on disk.

In reality, it's more complicated than that. Many characters are common to multiple encodings, but each encoding may use a different sequence of bytes to actually store those characters in memory or on disk. So you can think of the character encoding as a kind of decryption key for the text. Whenever someone gives you a sequence of bytes and claims it's "text," you need to know what character encoding they used so you can decode the bytes into characters and display them (or process them, or whatever).

source

And once again, I'll repeat my standard set of background links for those of you who don't know anything about character encoding. You must read Joel Spolsky's The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) You should read Tim Bray's three-part series, On the Goodness of Unicode, On Character Strings, and Characters vs. Bytes, and anything written by Martin Dürst.

I should also point out that you should always specify a character encoding on every HTML page you serve. Not specifying an encoding can lead to security vulnerabilities.

So, how does your browser actually determine the character encoding of the stream of bytes that a web server sends? If you're familiar with HTTP headers, you may have seen a header like this:

Content-Type: text/html; charset="utf-8"

Briefly, this says that the web server thinks it's sending you an HTML document, and that it thinks the document uses the UTF-8 character encoding. Unfortunately, in the whole magnificent soup of the world wide web, very few authors actually have control over their HTTP server. Think Blogger: the content is provided by individuals, but the servers are run by Google. So HTML 4 provided a way to specify the character encoding in the HTML document itself. You've probably seen this too:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

Briefly, this says that the web author thinks they have authored an HTML document using the UTF-8 character encoding. Now, you could easily imagine a situation where both the server and the document provide encoding information. Furthermore, they might not match (especially if they're run by different people). So which one wins? Well, there's a precedence order in case the document is served with conflicting information.

This is what HTML 4.01 has to say about the precedence order for determining the character encoding:

  1. User override (e.g. the user picked an encoding from a menu in their browser).
  2. An HTTP "charset" parameter in a "Content-Type" field.
  3. A META declaration with an "http-equiv" attribute set to "Content-Type" and a value set for "charset".
  4. The charset attribute set on an element that designates an external resource.
  5. Unspecified heuristic analysis.

And this is what HTML 5 has to say about it. I won't quote the whole thing here, but suffice to say it's a 7-step algorithm; step 4 has 2 sub-steps, the first of which has 7 branches, one of which has 8 sub-steps, one of which actually links to a separate algorithm that itself has 7 steps... It goes on like that for a while. The gist of it is

  1. User override.
  2. An HTTP "charset" parameter in a "Content-Type" field.
  3. A Byte Order Mark before any other data in the HTML document itself.
  4. A META declaration with a "charset" attribute.
  5. A META declaration with an "http-equiv" attribute set to "Content-Type" and a value set for "charset".
  6. Unspecified heuristic analysis.

...and then...

  1. Normalize the given character encoding string according to the Charset Alias Matching rules defined in Unicode Technical Standard #22.
  2. Override some problematic encodings, i.e. intentionally treat some encodings as if they were different encodings. The most common override is treating US-ASCII and ISO-8859-1 as Windows-1252, but there are several other encoding overrides listed in this table. As the specification notes, "The requirement to treat certain encodings as other encodings according to the table above is a willful violation of the W3C Character Model specification."

Two things should leap out at you here. First, WTF is a <meta charset> attribute? Well, it's exactly what it sounds like. It looks like this:

<meta charset=UTF-8>

I was able to find only scattered discussion about this attribute on the WHATWG mailing list.

The best explanation of the new <meta charset> attribute was given a few months later, in an unrelated thread, on a separate mailing list. Andrew Sidwell explains:

The rationale for the <meta charset=""> attribute combination is that UAs already implement it, because people tend to leave things unquoted, like:

<META HTTP-EQUIV=Content-Type CONTENT=text/html; charset=ISO-8859-1>

(There are even a few <meta charset> test cases if you don't believe that browsers already do this.)

Second, who the f— does the WHATWG think they are specifying "a willful violation of the W3C Character Model specification" This is a fair question. As with many such questions, the answer is that HTML 5 is only codifying what browsers do already. ISO-8859-1 and Windows-1252 are very similar encodings. One place they differ is in so-called "smart quotes" and "curly apostrophes" — the pretty little typographical flourishes that authors love and that Microsoft Word (and many other editors) output by default. Many authors specify a ISO-8559-1 or US-ASCII encoding (because they copied that part of their template from somewhere else), but then they use curly quotes from the Windows-1252 encoding. This mistake is so widespread that browsers already treat ISO-8859-1 as Windows-1252. HTML 5 is just "paving the cowpaths" here.

To sum up: character encoding is complicated, and it has not been made any easier by several decades of poorly written software used by copy-and-paste–educated authors. You should always specify a character encoding on every HTML document, or bad things will happen. You can do it the hard way (HTTP Content-Type header), the easy way (<meta http-equiv> declaration), or the new way (<meta charset> attribute), but please do it. The web thanks you.

Posted in Tutorials | 11 Comments »

The Road to HTML 5: getElementsByClassName()

Tuesday, November 11th, 2008

Welcome back to my semi-regular column, "The Road to HTML 5," where I'll try to explain some of the new elements, attributes, and other features in the upcoming HTML 5 specification.

The feature of the day is getElementsByClassName(). Long desired by web developers and implemented in Javascript libraries like Prototype, this function does exactly what it says on the tin: it returns a list of elements in the DOM that define one or more classnames in the class attribute. getElementsByClassName() exists as a method of the document object (for searching the entire DOM), as well as on each HTMLElement object (for searching the children of an element).

The HTML 5 specification defines getElementsByClassName():

The getElementsByClassName(classNames) method takes a string that contains an unordered set of unique space-separated tokens representing classes. When called, the method must return a live NodeList object containing all the elements in the document, in tree order, that have all the classes specified in that argument, having obtained the classes by splitting a string on spaces. If there are no tokens specified in the argument, then the method must return an empty NodeList. If the document is in quirks mode, then the comparisons for the classes must be done in an ASCII case-insensitive manner, otherwise, the comparisons must be done in a case-sensitive manner.

A Brief History of getElementsByClassName()

Can We Use It?

Yes We Can! As you can tell from the timeline, getElementsByClassName() is supported natively in Firefox 3, Opera 9.5, Safari 3.1, and all versions of Google Chrome. It is not available in any version of Microsoft Internet Explorer. (IE 8 beta 2 is the latest version as of this writing.) To use it in browsers that do not support it natively, you will need a wrapper script. There are many such scripts; I myself am partial to Robert Nyman's Ultimate GetElementsByClassName. It uses the native getElementsByClassName() method in modern browsers that support it, then falls back to the little-known document.evaluate() method, which is supported by older versions of Firefox (since at least 1.5) and Opera (since at least 9.27). If all else fails, Robert's script falls back to recursively traversing the DOM and collecting elements that match the given classnames.

And in conclusion

getElementsByClassName() is well-supported across all modern browsers except IE, and a performance-optimized open source wrapper script can cover IE and older browsers.

Posted in Tutorials, WHATWG | 7 Comments »

The Road to HTML 5 – Episode 1: the section element

Wednesday, November 5th, 2008

Welcome to a new semi-regular column, "The Road to HTML 5," where I'll try to explain some of the new elements, attributes, and other features in the upcoming HTML 5 specification.

The element of the day is the <section> element.

The section element represents a generic document or application section. A section, in this context, is a thematic grouping of content, typically with a header, possibly with a footer. Examples of sections would be chapters, the various tabbed pages in a tabbed dialog box, or the numbered sections of a thesis. A Web site's home page could be split into sections for an introduction, news items, contact information.

Discussion of sections and headers dates back several years. In November 2004, Ian Hickson wrote:

Basically I want three things:

  1. It has to be possible to take existing markup (which correctly uses <h1>-<h6>) and wrap the sections up with <section> (and the other new section elements) and have it be correct markup. Basically, allowing authors to replace <div class="section"> with <section>, <div class="post"> with <article>, etc.
  2. It has to be possible to write new documents that use the section elements and have the headers be automatically styled to the right depth (and maybe automatically numbered, with appropriate CSS), and yet still be readable in legacy UAs, without having to think about old UAs. Basically, the header element has to be header-like in old browsers.
  3. It shouldn't be too easy to end up with meaningless markup when doing either of the above. So a random <h4> in the middle of an <h2> and an <h3> has to be defined as meaning _something_.

At the moment what I'm thinking of doing is this (most of these ideas are in the draft at the moment, but mostly in contradictory ways):

The section elements would be:

<body> <section> <article> <navigation> <sidebar>

The header elements would be:

<header> <h1> <h2> <h3> <h4> <h5> <h6>

<h1> gives the heading of the current section.

<header> wraps block-level content to mark the whole thing as a header, so that you can have, e.g., subtitles, or "Welcome to" paragraphs before a header, or "Presented by" kind of information. <header> is equivalent to an <h1>. The first highest-level header in the <header> is the "title" of the section for outlining purposes.

<h2> to <h6> are subsection headings when used in <body>, and equivalent to <h1> when used in one of the section elements.

<h1> automatically sizes to fit the current nesting depth. This could be a problem in CSS since CSS can't handle this kind of thing well -- it has no "or" operator at the simple selector level.

<h2>-<h6> keep their legacy renderings for compatibility.

Further discussion:

Fast-forward to modern times. Using the <section> element instead of, say, <div class="section">, seems like a no-brainer. Unfortunately, there's a catch. (Hey, it's the web; there's always a catch.) Not all modern browsers recognize the <section> element, which means that they fall back to their default handling of unknown elements.

A long digression into browsers' handling of unknown elements

Every browser has a master list of HTML elements that it supports. For example, Mozilla Firefox's list is stored in nsElementTable.cpp. Elements not in this list are treated as "unknown elements." There are two fundamental problems with unknown elements:

  1. How should the element be styled? By default, <p> has spacing on the top and bottom, <blockquote> is indented with a left margin, and <h1> is displayed in a larger font.
  2. What should the element's DOM look like? Mozilla's nsElementTable.cpp includes information about what kinds of other elements each element can contain. If you include markup like <p><p>, the second paragraph element implicitly closes the first one, so the elements end up as siblings, not parent-and-child. But if you write <p><span>, the span does not close the paragraph, because Firefox knows that <p> is a block element that can contain the inline element <span>. So the <span> ends up as a child of the <p> in the DOM.

Different browsers answer these questions in different ways. (Shocking, I know.) Of the major browsers, Microsoft Internet Explorer's answer to both questions is the most problematic.

The first question should be relatively simple to answer: don't give any special styling to unknown elements. Just let them inherit whatever CSS properties are in effect wherever they appear on the page, and let the page author specify all styling with CSS. Unfortunately, Internet Explorer does not allow styling on unknown elements. For example, if you had this markup:

<style type="text/css">
  section { border: 1px solid red }
</style>
...
<section>
<h1>Welcome to Initech</h1>
<p>This is our <span>home page</span>.</p>
</section>

Internet Explorer (up to and including IE8 beta 2) will not put a red border around the section.

The second problem is the DOM that browsers create when they encounter unknown elements. Again, the most problematic browser is Internet Explorer. If IE doesn't explicitly recognize the element name, it will insert the element into the DOM as an empty node with no children. All the elements that you would expect to be direct children of the unknown element will actually be inserted as siblings instead. I've posted an ASCII graph that illustrates this mismatch.

Sjoerd Visscher discovered a workaround for this problem: after you create a dummy element with that name, IE will recognize the element enough to let you style it with CSS. You can put the script in the <head> of your page, and there is no need to ever insert it into the DOM. Simply creating the element once (per page) is enough to teach IE to style the element it doesn't recognize. Sample code and markup:

<html>
<head>
<style type="text/css">
  section { display: block; border: 1px solid red }
</style>
<script type="text/javascript">
  document.createElement("section");
</script>
</head>
<body>
<section>
<h1>Welcome to Initech</h1>
<p>This is our <span>home page</span>.</p>
</section>
</body>
</html>

This hack works in IE 6, IE 7, and IE 8 beta 1, but it doesn't work in IE 8 beta 2. (bug report, test case) The purpose of this illustration is not to blame IE; there's no specification that says what the DOM ought to look like in this case, so IE's handling of the "unknown element" problem is not any more or less correct than any other browser. With the createElement workaround, you can use the <section> element (or any other new HTML 5 element) in all browsers except IE 8 beta 2. I am not aware of any workaround for this problem.

And in conclusion

The <section> element is a very straightforward HTML 5 feature that you can't actually use yet.

Posted in Tutorials, Weekly Review | 8 Comments »