HTML5 Doctor » figure

Avoiding common HTML5 mistakes

Richard Clark — Tue, 26 Jul 2011 13:38:05 +0000

Between curating sites for the HTML5 gallery and answering readers’ questions here at HTML5 Doctor, I see a host of HTML5 sites and their underlying markup. In this post, I’ll show you some of the mistakes and poor markup practices I often see and explain how to avoid them.

Don’t use section as a wrapper for styling

One of the most common problems I see in people’s markup is the arbitrary replacement of

s with HTML5 sectioning elements — specifically, replacing wrapper

s (used for styling) with

s. In XHTML or HTML4, I would see something like this:



    
    My super duper page

Now, I’m instead seeing this:



    
    My super duper page

Frankly, that’s just wrong:

is not a wrapper. The

element denotes a semantic section of your content to help construct a document outline. It should contain a heading. If you’re looking for a page wrapper element (for any flavour of HTML or XHTML), consider applying styles directly to the element as described by Kroc Camen. If you still need an additional element for styling, use a

. As Dr Mike explains, div isn’t dead, and if there’s nothing else more appropriate, it’s probably where you really want to apply your CSS.

With that in mind, here’s the correct way to mark up the above example using HTML5 and a couple of ARIA roles. (Note: you may need one

depending on your design.)


    
    My super duper page

If you’re not quite sure which element to use, then I suggest you refer to our HTML5 sectioning content element flowchart to guide you along your way.

Only use header and hgroup when they’re required

There’s no sense writing markup when you don’t have to, right? Unfortunately, I often see

and being used when there’s no need for them. You can get up to speed with our articles on the

element and the element, but I’ll briefly summarise:

The
element represents a group of introductory or navigational aids and usually contains the section’s heading
The element groups a set of
—
elements representing a section’s heading when the heading has multiple levels, such as subheadings, alternative titles, or taglines

Overuse of header

As I’m sure you’re aware, the

element can be used multiple times in a document, which has popularized the following pattern:



    
    My best blog post

If your

element only contains a single heading element, leave out the

. The

ensures that the heading will be shown in the document outline, and because the

doesn’t contain multiple elements (as the definition describes), why write code when you don’t need to? Simply use this:

  
  My best blog post

Incorrect use of

On the subject of headers, I also frequently see incorrect uses of

. You should not use in conjunction with

when:

there’s only one child heading, or
the would work fine on its own (i.e., without the
).

The first problem looks like this:



    
    My best blog post
  
  by Rich Clark

In that case, simply remove the

and let the heading run free.


  My best blog post
  by Rich Clark

The second problem is another case of including elements when they’re not necessarily required.



    
    My company
    Established 1893

When the only child of the

is the , why include the

? If you don’t have additional elements within the

(i.e., siblings of the ), simply remove the

altogether.

  
  My company
  Established 1893

For more

examples and explanations, read the detailed article about it in the archives.

Don’t wrap all lists of links in

With 30 new elements (at the time of writing) introduced in HTML5, we’re somewhat spoilt for choice when it comes to creating meaningful, structured markup. That said, we shouldn’t abuse the super-semantic elements now made available to us. Unfortunately, that’s what I see happening with

. The spec describes

as follows:

The nav element represents a section of a page that links to other pages or to parts within the page: a section with navigation links.

Note: Not all groups of links on a page need to be in a nav element — the element is primarily intended for sections that consist of major navigation blocks. In particular, it is common for footers to have a short list of links to various pages of a site, such as the terms of service, the home page, and a copyright page. The footer element alone is sufficient for such cases; while a nav element can be used in such cases, it is usually unnecessary.

WHATWG HTML spec

The key phrase is ‘major’ navigation. We could debate all day about the definition of ‘major’, but to me it means:

Primary navigation
Site search
Secondary navigation (arguably)
In-page navigation (within a long article, for example)

While there isn’t any right or wrong here, a straw poll coupled with my own interpretation tells me that the following shouldn’t be enclosed by

Pagination controls
Social links (although there may be exceptions where social links are the major navigation, in sites like About me or Flavours, for example)
Tags on a blog post
Categories on a blog post
Tertiary navigation
Fat footers

If you’re unsure whether to mark up a list of links with

Common mistakes with the figure element

Ah,

. The appropriate use of this element, along with its partner-in-crime

, is quite difficult to master. Let’s look at a few common problems I see with

Not every image is a figure

Earlier, I told you not to write extra code when it’s not necessary. This mistake is similar. I’ve seen sites where every image has been marked up as a

. There’s no need to add extra markup around your images for the sake of it. You’re just creating more work for yourself and not describing your content any more clearly.

The spec describes

as being some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document. Therein lies the beauty of

, that it can be moved away from the primary content — to a sidebar, say — without affecting the document’s flow.

If it’s a purely presentational image and not referenced elsewhere in the document, then it’s definitely not a

. Other use cases vary, but as a start, ask yourself, Is this image required to understand the current context? If not, it’s probably not a

(an

, perhaps). If so, ask yourself, Could I move this to an appendix? If the answer to both questions is ‘yes’, it’s probably a

Your logo is not a figure

Segueing nicely on, the same applies to your logo. Here are a couple of snippets that I see regularly:



  
    
      
    
    My company name

There’s nothing else to say here. It’s just plain wrong. We could argue until the cows come home about whether your logo should be in an

, but that’s not what we’re here for. The real issue is the abuse of the

element.

should be used only when referenced in a document or surrounding sectioning element. I think it’s fair to say that your logo is rarely going to be referenced in such a way. Quite simply, don’t do it. All you need is this:

  
  My company name

Figure can be more than an image

Another common misconception regarding

is that it can only be used for images. This isn’t the case. A

could be video, audio, a chart (in SVG, for example), a quote, a table, a block of code, a piece of prose, or any combination of these and much more besides. Don’t limit your

s to images. Our job as web standards affectionadoes is to accurately describe the content with our markup.

A while back, I wrote about

in more depth. It’s worth a read if you want more detail or need a refresher.

Don’t include unnecessary type attributes

This is probably the most common problem we see in HTML5 Gallery submissions. While it isn’t really a mistake, I believe it’s best practice to avoid this pattern.

In HTML5, there’s no need to include the type attribute on

Instead, you can simply write:

You can also reduce the amount of code you write to specify your character set, amongst other things. Mark Pilgrim’s chapter on semantics in Dive into HTML5 explains all.

Incorrect use of form attributes

You may be aware that HTML5 has introduced a range of new attributes for forms. We’ll cover them in more detail in the coming months, but in the meantime, I’ll quickly show you a few things not to do.

Boolean attributes

Several of the new form attributes are boolean, meaning their mere presence in the markup ensures the behaviour is set. These attributes include:

autofocus
autocomplete
required

Admittedly, I only rarely see this, but using required as an example, I’ve seen the following:


required="true" />

required="1" />

Ultimately, this causes no harm. The client’s HTML parser sees the required attribute in the markup, so its function will still be applied. But what if you flip the code on its head and type required="false"?


required="false" />

The parser will still see the required attribute and implement the behaviour even though you tried to tell it not to. Certainly not what you wanted.

There are three valid ways for a boolean attribute to be applied. (The second and third options only apply if you’re writing XHTML syntax.)

required
required=""
required="required"

Applying that to our above example, we would write this (in HTML):

required />

Summary

It would be impossible for me to list here all the quirky markup patterns and practices I’ve come across, but these are some of the most frequently seen. What other common markup mistakes have you spotted around the web? Which areas of HTML5 require further clarification? We’d love to help get the wording or examples in the spec changed to make them a little more specific, so leave your thoughts below, and don’t forget to escape your HTML!

Thanks to Ian Devlin, Derek Johnson, Tady Walsh, the HTML5 Gallery curators, and the HTML5 Doctors for their input to this article.

Avoiding common HTML5 mistakes originally appeared on HTML5 Doctor on July 26, 2011.

Your Questions #17

Richard Clark — Tue, 19 Apr 2011 13:30:12 +0000

The clinic is packed this week with your HTML5 ailments! Today, we’ll discuss an HTML5 syntax dilemma, using sections within sections, semantics, describing the contents of a figure, and marking up web app toolbars.

HTML5 syntax dilemma

Manuel asked:

In theory, HTML5 syntax is very lazy but, in fact, when you write a HTML5 page you follow some conventions that originate in the XHTML era: lowercase code, double-quoted attribute values, properly closed elements, proper element nesting. While this practice is rational and admirable, some people take a further step towards a XHTML-style syntax: they don’t use attribute minimization and do terminate empty elements. Of course this further step is not necessary to write clear HTML5 code, but could be fostered if you look at the following points:

it makes [it] easier to upgrade legacy XHTML code (which represents the bulk of the web even if it’s generally served as text-html) to HTML5 (it’s just a matter of doctype change)

it makes [an] easier the shift to HTML5 for web developers, since they are generally used to write XHTML

it could set a coding standard in the field

What do you think about it?

I disagree. I think there’s nothing lazy about HTML5 syntax. You could say that it’s lazy that in HTML we write

rather than , but the fact is, it’s a specified part of the language.

Furthermore, “legacy XHTML” code does not represent the bulk of the Web; 61% of the Web is HTML4 according to the Opera MAMA study in 2008.

But it doesn’t matter. You say tom-ay-toes, I say to-mah-toes; you like XHTML syntax, I like HTML syntax. They’re all the same to a browser, if served as text/html.

Cheers, Bruce

Sections within sections

Corey asked:

Don’t know if this has been asked before or not, as I couldn’t find anything to tell me otherwise. I read through the article and section information and understand more or less how they function, but I’m wondering if there is a case to be made about having a section within a section. Your article doesn’t really touch on whether this is appropriate or not.

The reason I ask is because I have a page that is broken into different parts (introduction, description, requirements, etc) that are all part of the same overall article. Now if I wanted to break down say, the requirements section into sub-sections (technical, stylistic, semantic, etc) would it be all right to wrap those sub sections in a section tag (that is within a section itself), assuming I put the correct header on it?

Thanks a bunch,

Yes, you certainly can nest

s — in fact, that’s pretty much exactly what

is for! If you look at the source of some of our more recent articles — e.g., this article or our microformats article — you’ll notice how we’ve split the article into sections.

In theory, using nested sections means that we’ll be able to do away with

–

, since a new heading level is implied with each nested section. In practice, however, it’s not as simple as that, so we suggest sticking with the usual

–

heading structure even if you decide to nest sections.

For your example, this code would be entirely appropriate:


  Article name
  ...
  
    Introduction
    ...
  
  
    Description
    ...
      
        Technical
        ...
      
      
        Stylistic
        ...
      
  
  
    Requirements
    ...

Each part of the

is wrapped in a

. The one exception might be the introduction, unless you are explicitly declaring a heading with it. You don’t always need a

element if it would only contain a single

–
element. In that case, the heading on it’s own will be fine. Bruce has a good post on the difference between articles and sections.

Hope that helps, Rich

Since we’re being semantic…

Rob asked:

HTML5 is working towards being more semantic, but I don’t think the tag is semantic at all…especially for stylesheets! Has anyone ever suggested changing the specification for the

I think most implementors would say that the current way works well enough. Breaking backwards compatibility for the sake of theoretical purity was where XHTML 2 was heading before it was finally curtailed. HTML5 takes stock of where we are, warts and all, and builds on that. (I feel your pain: I always want to be .)

Cheers, Bruce

Describing the content of

Sverri asked:

A lot of things can be presented as figures (everything from a simple quote to an information-dense canvas). The first thing that came to my mind was using e.g. a “type” attribute. For example:
  Styling p tags
  p { margin-bottom: 1em }
That would be a dead simple way of succinctly telling user agents, search engines, etc. what kind of content they can expect to find in the figure. However, since this is not valid HTML5 (as far as I know) how would you recommend describing the contents of a figure, so as to make it more accessible to non-human agents?

Thank you.

Bruce replied:

What would be the purpose of doing so? For example, it’s easy for a non-human agent to see that your example contains code, or that:


  ...
  ...

contains video, or that:

...

contains an image. So I’m not sure of the use case for a type attribute.

Sverri then responded:

The way I think about this is that figures are images of sorts, or embedded content. A “type” attribute (or perhaps a more aptly named “of” attribute) would be the equivalent of the “alt” attribute of img. It is extra information, and as such would not always be needed, but sometimes it can be an important part in how you present the content.

As for use cases:

Aiding search engines better understand the content

Browsers can use such information to make browsing the internet richer

I realize that you can use some other way of describing the content, such as titles, itemscopes or other ways of adding metadata. A dedicated, but optional, attribute for this would not be such a bad idea in my opinion.

To sum up, I suppose what I am getting at is that content in a figure is not always so well defined on its own. A snippet of code, for example, is given more meaning if it is in a context, such as “css”, “algorithm” or “while loop”.

I hope I am being clear enough in what I am saying.

Bruce followed up once more:

You are clear. There have been many such discussions during the development of HTML5 (and preceding versions of HTML). For example, why not have a element for marking up people’s names, analogous to ? Why not have or or ?

The use cases you describe (aiding search engines and browsers) are equally applicable.

But it comes down to two factors:

First, HTML is not a specialised language. It’s a generalised language, and there are some cases that can’t be marked up with the existing crop of elements. (There are already over a hundred.)

Second is that minting new elements and attributes isn’t “free”. It’s more for authors to remember (and get wrong), it bloats parsers in browsers, and it makes regression testing harder. So if a new addition to the language doesn’t solve a very common problem, it isn’t added to the language.

As you said, microdata/microformats/RDFa can be used to extend the language for specialised cases.

Thanks, Bruce

Web app buttons and toolbars: anchors, buttons, or commands?

Christian asked:

If you’re creating a toolbar for a web app, or perhaps even a “Share this page” widget, should one use anchors, buttons or commands?

A toolbar should be HTML5

with nested s, but browser support is zilch. I’d use a list of buttons, personally. I think

Got a question for us?

That wraps up this round of questions. If you’ve got a query about the HTML5 spec or how to implement it, you can get in touch with us and we’ll do our best to help.

Your Questions #17 originally appeared on HTML5 Doctor on April 19, 2011.

Your Questions #15

Richard Clark — Fri, 14 Jan 2011 14:30:23 +0000

The clinic is busy as ever with more HTML5 ills. This week, we’ll cover marking up Wikipedia infoboxes, anchors in

for avatars, header(s), and how to use

 and .


  Wikipedia Infoboxes
  Andrés asked:
  
    Hello. I want to ask how I can code some stuff based on Wikipedia infoboxes with HTML5, which most of the time uses tables. I think that all of these can be surrounded by a figure tag, but I’m not sure about the subtleties.

    Reference page: http://en.wikipedia.org/wiki/Help!_%28album%29. It has a main infobox that:

    
    	Has a heading
    	Has a thumbnail image
    	Has 3 sections each separated by a faux table heading:
    		
    			One that has a table with two columns, one with keys and other with labels, which I believe that can be done better with definition list but not sure if table is suited too
    			One that has a list of links of magazines that have reviewed the disc. I believe it is fine as is coded but still
    			One with a “chronology”, which is like a navigation menu in a table with the previous, current (no link) and next installment. Not idea if there’s an ideal way to markup it
    		
    	
    

    There’s a 2nd infobox that feature a long list of links of related contents divided by some kind of table headings. I suppose it may better done by lists but there’s may be another approach. The 3rd infobox repeats the chronology noted above.
  
  
  It’s a blessing and curse of HTML that there is often more than one correct answer. This is even more true with HTML5. Let’s look at the Help! album page:

  
  	Is the infobox essential to understanding? If yes, use ; if no, use  (inside ). If this data is just a summary of information already in the article,  would be appropriate. If it contains unduplicated data, I prefer . I don’t think  is the best container element for the infobox.For the “studio album” details section, either  or 

  	
 would be appropriate.“Professional reviews” and “chronology” both look like lists, although either could also be a table.
I actually find the chronology formatting quite strange, as it’ll only work well for 1–3 items. Assuming this would be used for a full chronology, an ordered list would be more suitable. I guess that this is only to list the previous and next albums (a partial chronology). I don’t think it’s suitable for  as the Beatles released more than three albums (but might be if all albums were listed). It’d be good to use rel="previous" and rel="next" attributes on these links.
The blue background titles would be best represented by –
  titles, ideally titling each .
I’m guessing the second infobox you refer to is the large table of links at the bottom of the page. This seems appropriate as a series of inline lists (ordered by time or alphabetically) in a table.
I’m also guessing the third infobox you refer to is the “US Release” one that uses the same template as the first. The first infobox notes apply here too.
Peace — Oli

	No anchor elements allowed in  elements
	Daniel asked:
	
		Consider the following code:




  Title
  Sub Title



    When using http://html5.validator.nu/ to validate my page, it says that this is invalid “Error: Element a  not allowed as child of element hgroup  in this context.”

    I know that this validator is in beta (at least I think so), so maybe it’s wrong, but would you tell me if this is really valid or invalid? If it is invalid, would putting the anchor tags inside the heading tags fix it (despite having to use more markup  
    
	
	
	This example is in fact invalid. Only 
– elements can be a child of .

	You can get around it using block-level links like so (but bear in mind some browsers have trouble with block-level links):



  Title
  Sub Title



  Hope that helps.

  Rich

	Using  and  as the avatar/id in a blog comment
	BigAB asked:
	
		Would this be a proper use of the figure and figcaption tags: representing the common case of avatar/username on comments (or forum entries) as a figure? Example:

   Comment on The Blog Article
   
       
       My Name
   
   I am commenting on our blog article. This is my comment. I have much to comment on and am doing so in this comment.
   Thank you for letting me comment here.  I think it good that we can comment.  Feel free to comment on my comment.

	

	Doesn’t feel right to me. The spec says this:
	
	
	  “The figure element represents some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document.
    
    The element can thus be used to annotate illustrations, diagrams, photos, code listings, etc, that are referred to from the main content of the document, but that could, without affecting the flow of the document, be moved away from that primary content, e.g. to the side of the page, to dedicated pages, or to an appendix.”
    
    
      W3C Specification
    
  

  By “referred to”, I understand that to be “See figure 9″, but your example doesn’t do that. Personally, I’d just write:

  Bob Smith

  Cheers, Bruce

	HTML5 Header
	Josh asked:
	
		I have read up a lot on the header element, and nesting numbered headers inside the hgroup element, and so forth. I’ve put a lot of the things I’ve seen on HTML5Doctor.com into practice on my own site, but was wondering if I can actually put the numbered header anywhere in the header, instead of having the numbered header (eg, h1-h6) first.

    I was also wondering if putting links inside an h1-h6 itself would actually damage either page rank or usability. I mean, I don’t imagine how it would, but I like to be very careful, almost too careful with how I do things. I do auto-validations of all my markup constantly, and do manual validation once in a while. So, I’m a little OCD when it comes to items such as the header. Of course, putting the a element around the header itself may not hurt either – but like I said, I love to be careful.

    Plus, great work on the site and the organization, folks! Some friends and myself make some articles on topics such as CSS and XHTML, more-recently HTML5, and it’s refreshing to come here to see a view from some real experts!
	
	
	Thanks for your e-mail.
	
  
  	– elements can go anywhere inside , although we advise you to mark up your content first before thinking about CSS, so your page makes sense even without CSS.
  	If you have more than one – as children of a , wrap them in . If there’s nothing else in the , just use the  and not the .
  	If you only have one – and no other heading content, you don’t need either  or , although they might still be useful for a CMS template (where more stuff might be inserted) or as CSS hooks.
  	Links inside – don’t affect page ranking or usability in isolation (but might affect usability if, for example, the link is to the current page).
  	You can use block-level links around a  or , but test and be careful of Firefox’s vomit bug.
  

  Finally, while we applaud your studious approach to coding, do keep in mind that HTML is quite forgiving   As long as you validate occasionally and follow the spec, you’ll be fine. The web stack is a deep rabbit hole to go down, so while it’s great to do the best you possibly can, we also prescribe going outside once in a while  

  Peace — Oli

	 vs 

	Daniel asked:
	
		Dear HTML5doctors,

    How should I markup code example correctly? I have some that are inline inside my text, I think that’s code then, but others are multi lined. I need them to be white-spaced correctly as they would get them with pre, but isn’t that semantically wrong?

    Or do I put  inside 
?  inside ? Or is  to  as  is to ?

    Many thanks
	

	
	For inline code, just use ..., a phrasing (inline) element. For multi-line code, use 
...
.  is a flow (block-level) element. Finally, the entities < and > map to < and >, which you’ll need to escape inside any HTML code snippets (although you only really need to do the first one).

  Peace — Oli

	Got a question for us?
	That wraps up this round of questions. If you’ve got a query about the HTML5 spec or how to implement it, you can get in touch with us and we’ll do our best to help.
Related Posts:
Your Questions #14
The hgroup element
Your Questions Answered #7
Your Questions Answered 9
Avoiding common HTML5 mistakes
Your Questions #15 originally appeared on HTML5 Doctor on January 14, 2011.

Your Questions Answered 9
Richard Clark — Fri, 14 May 2010 14:15:57 +0000
 The Doctor is in with another round of patient questions about HTML5. This week, we’ll cover offline viewing on requests, the drag-and-drop API, using href on any element, the 
 element, and headings.
Offline viewing on requests
Johan asked:
It is possible to let Firefox 3.5/3.6 save a page for offline viewing with the manifest file?

In that case Firefox asks for permission to save the site the same second you arrive – not very user-friendly.
Is it possible to send the save-it-locally request via Javascript on a click?
Basically I want a link/button which will fire the request – and not on document load.

While it isn’t possible to make Firefox 3.5/3.6 save a page for offline viewing with the manifest file, there is a way to do this. It all depends on how you write the “save-it-locally request” code. You have two options:

If you want to store an arbitrary document that is not explicitly listed in your manifest, you could run an Ajax request for that document and store its contents in localStorage. When you want to view that document, load it from localStorage and overlay it on the existing page.
Dynamically manage a manifest file for individual users, so that if a user requests a new file that isn’t in their manifest, register this on the server side and add it to the manifest — which is bespoke to this specific user — on the fly.

I’m not sure what you’re seeing with regards to the permissions error. When I test the manifest (offline **cache**), it doesn’t ask twice.
Note: you asked about Firefox 3.5 — the offline manifest doesn’t work properly at all in this version.
Thanks, Remy
Question about dragging
Marc asked:
Evening,
I’m trying to get my head around the drag and drop (DnD) possibilities of HTML5. I have a “simple” task: Read the content of a XML file, using JavaScript, and do some manipulations of he XML. Without the use of server side scripts.
I tried my way with Google, but apart from people complaining about the DnD specs, I wasn’t able to find much insightful informations.
Can you point me toward resources to understand the DnD possibilities of HTML5?
Thank you Doctor, a French canadian HTML5 fan  

Absolutely! There’s actually an HTML5 Doctor article covering native drag-and-drop. It also includes links for further reading and related posts (such as accessibility experiments).
I hope that helps.
Cheers, Remy
About the href on any element
Luan asked:
I’ve heard a long ago that href would work in any tag, such as a 
 or a h1, even a div and others… but I don’t see anything about this in the last days. Do you know if this is going to work?

That was in XHTML2 (on which the W3C have now stopped work).
The HTML5 equivalent is to wrap an  around the other tags. It’s called block-level linking, and we’ve written an article about it.
Cheers, Bruce
W3C Validator for the  element
Fjpoblam asked:
I have a (prospective) structure containing 8 figures: each an image with a caption. My goal is an image gallery, each image clickable toward an individual htm file containing a slide show. (In html4 I structured each “figure” as a div: figure seemed ideal for the task.)
Problem is, I tried to follow the *validator* hint with a dd for the image and a dt for the caption (each surrounded by an a). Upon doing so, the validator pops up an error. When I try a straight image with a legend, it is also rejected for want of a dd and an optional dt.
What gives? Do you have a hint? Or better, simply, point me doofus to the correct doc so’s you’ll “teach a man to fish”.

I’m not sure if the validator is up to date or not, but you shouldn’t be using 
/
 in  anymore. Please use .
See our article on the 
 and  elements for more.
Also see our glossary for more examples.
Cheers, Rich
Headings
Thomas asked:
Dear Doctors,
you covered the new header tag in an article. The header tag should contain a heading element, like h1-6. So far so good, but how do I structure my headings further on. E.g. I’ve got this:

	
		My major heading
		Subheading
		Abstract text...
	
	... lorem ipsum ....
	Heading within my article
	... dolor sit amet ...
	Subheading in my article

Which heading-level would be appropriate in my example? h1 because it starts again? or h3 because it continues?
Thank you

If the first  is a new subheading and not related to the 
 already there, then  would be an . Then  would be an  if it is a subheading of the above .
However, if you’re splitting the article into sections, then you could use an 
 each time. See our article on the section element for more.
Thanks, Tom
Got a question for us?
That wraps up this round of questions! If you’ve got a query about the HTML5 spec or how to implement it, you can get in touch with us and we’ll do our best to help.

Related Posts:

Go offline with application cache
Your Questions Answered #10
Your Questions Answered #7
Your Questions Answered #11
Your Questions Answered #4


Your Questions Answered 9 originally appeared on HTML5 Doctor on May 14, 2010.


The figure & figcaption elements
Richard Clark — Tue, 13 Apr 2010 13:45:20 +0000
In traditional printed material like books and magazines, an image, chart, or code example would be accompanied by a caption. Before now, we didn’t have a way of semantically marking up this sort of content directly in our HTML, instead resorting to CSS class names. HTML5 hopes to solve that problem by introducing the 
 and  elements. Let’s explore!

The  element

The 
 element is intended to be used in conjunction with the  element to mark up diagrams, illustrations, photos, and code examples (among other things). The spec says this about :

The figure element represents a unit of content, optionally with a caption, that is self-contained, that is typically referenced as a single unit from the main flow of the document, and that can be moved away from the main flow of the document without affecting the document’s meaning.
W3C Specification

The  element

The 
 element has been the subject of much debate. The spec initially wanted to repurpose  rather than introduce a new element. Other suggestions included , 

  	
  	
  	

  

  

  

    













,  or the 
– elements.  was changed, so we then used a combination of  and 
 inside  at Jeremy’s suggestion. Most of these suggestions failed since there was no backwards compatibility for styling with CSS.

Regular readers will know that a new element was recently introduced, namely 
. Who knows if it’ll stick, but for now here’s what the spec says about :

The figcaption element represents a caption or legend for a figure.
W3C Specification

The 
 element is optional and can appear before or after the content within the . Only one  element may be nested within a , although the  element itself may contain multiple other child elements (e.g.,  or ).

Using  and 

So we’ve seen what the spec says about these elements. How do we use them? Let’s look at some examples.

Figure with an image

An image within a 
 element without a caption:



Here’s the code for that:


  


Figure with an image and caption

An image within a 
 element with an explanatory caption:

A cheeky macaque, Lower Kintaganban River, Borneo. Original by Richard Clark


and the code that we used:


  
  A cheeky macaque, Lower Kintaganban River, Borneo. Original by Richard Clark


A figure with multiple images

Nesting multiple images within one 
 element with a single caption:

Australian Birds. From left to right, Kookburra, Pelican and Rainbow Lorikeet.
Originals by Richard Clark


The code:


  
  
  
  Australian Birds. From left to right, Kookburra, Pelican and Rainbow Lorikeet. Originals by Richard Clark


Figure with a code block

The 
 element may also be used for code examples:

Creative Commons Attribution Share-alike license
Using  around a Creative Commons license link with rel="license"


Here’s the code for that:


<small><a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution Share-alike license</a></small>
Using <small> around a Creative Commons license link with rel="license"


Differences between  and 

We covered 
 in an earlier article, but it is important to note the difference between the two. You should choose between  or  by asking yourself if the content is essential to understanding the section:


  If the content is simply related and not essential, use .
  If the content is essential but its position in the flow of content isn’t important, use .


Having said that, if its position relates to previous and subsequent content, use a more appropriate element — e.g., a 
, a plain old , a , or possibly even , depending on its content.

Don’t stop there!

No need to constrain your 
s to images and code examples. Other content suitable for use in  includes audio, video, charts (perhaps using  or ), poems, or tables of statistics.

It may not always be appropriate to use the 
 element, though. For example, a graphic banner should not be marked up with . Instead, simply use the  element.

Summary

As we’ve illustrated in this article, there are a lot of possibilities for the 
 element. Just remember to make sure it’s the most appropriate element for the job. But you already do that for all your markup, right?  
Related Posts:
HTML5 Simplequiz #4: figures, captions and alt text
The small & hr elements
HTML5 Simplequiz 6: Zeldman’s fat footer
September HTML5 spec changes
Review: HTML5 Now (DVD)
The figure & figcaption elements originally appeared on HTML5 Doctor on April 13, 2010.



Hello, summary and figcaption elements
Bruce Lawson — Mon, 01 Feb 2010 10:42:38 +0000
This weekend saw the minting of not one but two new elements. The summary element (not the summary attribute on the table element) goes inside the details element:

More information
Here is the source data that is discussed in the article ... 

This is designed to produce an “expando” box that is closed by default (but can be open by default using the boolean open attribute), only displaying the text specified by the summary as a control. Activating that control opens the whole details element; re-activating closes it again. If no summary text is present, the browser defaults to the rubric “details”. (Added 4 Feb 10:) In browsers that support details, this behaviour does not depend on author scripting, and should work even if JavaScript is disabled or not present.
figcaption lives inside the figure:

 (or video, table etc)
A rabid unicorn goring a fairy.

If you want some history, continue reading. Otherwise, bye bye!
Previously, the legend element was specified to do the job of both. Unfortunately, every browser had parsing problems re-using it outside forms. Similar problems were encountered attempting to re-use the caption element outside tables. At Jeremy Keith’s  suggestion, the spec then re-used dd and dt, but that breaks too.
Now, two new elements are minted. (I quite fancied one new element – rubric for both, but it’s a pretty esoteric word.)
One of the objections to details, as described by Shelley Powers in her bug to remove it is
the use of JavaScript for the purpose of expanding or collapsing a section is both well-defined and common among web applications. More importantly, following the concept of progressive enhancement, these types of expanding sections are expanded by default if script is turned off. To have a section that is dynamic but not controlled by script is going to cause confusion, particularly among people who turn scripting off and are assuming that there are no “expando” sections in the web page.
In fact, I don’t see how this element will make developing web applications that much simpler. This type of functionality is trivial with JS.

My counter-argument was that an expanding/ collapsing area on the page is a very common requirement. I’ve seen sites pull in a whole JavaScript library just to accomplish this (presumably as the developer was unfamiliar with JS), which bloats the page size for the user. I’ve seen pages where the “details” information is set to display:none by default, and the user cannot expand the information without JS, thereby making the contents inaccessible if JS is not present.
Reinstating this element would be advantageous to developers, who wouldn’t need to learn JS to accomplish a common task; advantageous to users who would get an accessibility bonus from having this behaviour natively in the browser.
While I like to think that the irrefutable logic of my argument, coupled with the tear-jerking rhetorical flourishes in  my prose captured both the heart and the head of the editor, I suspect what persuaded him was Apple’s Maciej Stachowiak saying that “the webkit community” were interested in implementing details once the spec was nailed down. Implementation wins the day.

Related Posts:

Legend not such a legend anymore
The details and summary elements
dd-details wrong again
HTML5 Doctor Speaking and Training Appearances
HTML5 Reset Stylesheet


Hello, summary and figcaption elements originally appeared on HTML5 Doctor on February 1, 2010.



dd-details wrong again
Remy Sharp — Mon, 12 Oct 2009 12:00:57 +0000
You may recall that I blogged about legend not being so legend as the heading element for details or figure. After enough noise was made the spec was changed so that the heading and contents of these elements can now be marked up using the dt/dd combo.

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



How we got here

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

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

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

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


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


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

The problem with dt/dd

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

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

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

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



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

![dd styled in IE7](

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

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

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

The problem here is that:


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


Is there hope?

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

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

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

Dean went on to test this, and he found:


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


The really freakin’ important bit:


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


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

We want the details

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

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

What are our current options?


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


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

Reference links


Dean’s original details test (my modified tests to fire the innerHTML on load: details, figure)
Litmusapp browser screenshots of the results: details, figure
whatwg mailing list thread: September, OctoberRelated Posts:
Legend not such a legend anymore
Hello, summary and figcaption elements
How to get HTML5 working in IE and Firefox 2
September HTML5 spec changes
2022, or when will HTML 5 be ready?

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



September HTML5 spec changes
Remy Sharp — Thu, 17 Sep 2009 12:00:20 +0000
September being one month before the HTML5 spec goes to last call in October, there’s been a few significant changes to the HTML5 spec that we wanted to briefly share with our patients.



Clarification over section and article

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

footer now works like header

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

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

details and figure saved

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

Example:


 
 
Exhibit B. The Rough Copy trailer.


aside has better examples

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

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

Dropped Elements

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


dialog
bb
datagrid


Ch-ch-changes

We’ll be posting in more detail about some of these changes, and as further changes come out of the editing process we’ll no doubt keep you all up to date, either via our Twitter account (which you should follow) or feel free to let us know too!
Related Posts:
Legend not such a legend anymore
The section element
The figure & figcaption elements
dd-details wrong again
The Footer Element Update

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



Legend not such a legend anymore
Remy Sharp — Fri, 31 Jul 2009 12:00:26 +0000
Lately I decided I was going to recreate the interactive features of the details element using JavaScript (apparently the same day as fellow Brightonian Jeremy Keith).

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



Overview of the details element

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

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

The markup would roughly be this:


  Terms & Conditions
  You agree to xyz, etc.


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

The issues

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

Other problems include:


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


Legend treatment

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

Internet Explorer

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

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



Opera

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

Safari

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

Firefox

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



Impact on other elements

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

Conclusion

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

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

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

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

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

It’s fine to think that Gecko will update, but it’s IE that I’m worried about, they won’t turn out their render engine, and the result is we’ll have to avoid using the legend in any element other than fieldset.
Related Posts:
dd-details wrong again
Hello, summary and figcaption elements
September HTML5 spec changes
The figure & figcaption elements
The details and summary elements

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

HTML5 Doctor » figure

Avoiding common HTML5 mistakes

Don’t use section as a wrapper for styling

My super duper page

Only use header and hgroup when they’re required

Don’t wrap all lists of links in

Common mistakes with the figure element

Not every image is a figure

Your logo is not a figure

Figure can be more than an image

Don’t include unnecessary type attributes

Incorrect use of form attributes

Boolean attributes

Summary

Related Posts:

Your Questions #17

HTML5 syntax dilemma

Sections within sections

Article name

Introduction

Description

Technical

Stylistic

Requirements

Since we’re being semantic…

Describing the content of

Web app buttons and toolbars: anchors, buttons, or commands?

Got a question for us?

Related Posts:

Your Questions #15

Wikipedia Infoboxes

Title

Sub Title

Title

Sub Title

Headings

. However, if you’re splitting the article into sections, then you could use an

each time. See our article on the section element for more. Thanks, Tom

Got a question for us?

Related Posts:

The element

The element

Using and

Figure with an image

Figure with an image and caption

A figure with multiple images

Figure with a code block

Differences between and

Related Posts:

Hello, summary and figcaption elements

Related Posts:

dd-details wrong again

How we got here

The problem with dt/dd

Is there hope?

We want the details

Reference links

Related Posts:

September HTML5 spec changes

Clarification over section and article

footer now works like header

details and figure saved

aside has better examples

Dropped Elements

Ch-ch-changes

Related Posts:

Legend not such a legend anymore

Overview of the details element

The issues

Legend treatment

Internet Explorer

Opera

Safari

Firefox

Impact on other elements

Conclusion

Related Posts:

.

However, if you’re splitting the article into sections, then you could use an

each time. See our article on the section element for more.

Thanks, Tom

The
element

The
element

Using
and

Differences between
and

Clarification over `section` and `article`

`footer` now works like `header`

`details` and `figure` saved

`aside` has better examples