Convert SharePoint 2010 master page to HTML5

I recently refreshed my Just the Essentials SharePoint 2010 master pages and a part of that refresh included the addition of HTML5 versions of the master page files. In this post I am going to step through how to convert a SharePoint 2010 master page to HTML5.

The basics

  1. Simplify the DOCTYPE
    Before the DOCTYPE was:

    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    With HTML5 you only need:

    <!doctype html>

    Please note that using this DOCTYPE can cause issues with JavaScript in IE8. Use at your own risk.

  2. Removed xmlns from the HTML tag
    Before the HTML tag was:

    <html lang="" dir="" runat="server" xmlns:o="urn:schemas-microsoft-com:office:office" __expr-val-dir="ltr">

    We can omit xmlns because it is not required by HTML5 (it is required by XHTML). Our new HTML tag is:

    <html lang="" dir="" runat="server"  __expr-val-dir="ltr">
  3. Removed trailing slashes from self closing tags within the HEAD element that are not SharePoint controls
    That was a mouthful. HTML5 doesn’t require that you self close tags. You certainly can if you want to, it will still validate.  I took them out for the fun of it.  Here is an example of before:

    <meta http-equiv="Expires" content="0"/>

    And then after:

    <meta http-equiv="Expires" content="0">
  4. Changed X-UA-Compatible from IE8 to IE9
    IE8 doesn’t support HTML5 so we have to tell SharePoint to render based on IE9. Here is the tag before:

    <meta http-equiv="X-UA-Compatible" content="IE=8"/>

    Once the change is made:

    <meta http-equiv="X-UA-Compatible" content="IE=9">

    Please note that changing the IE meta tag can cause issues with JavaScript in IE. Use at your own risk. I have started a list of identified bugs at the end of this article that I will add on to as issues are discovered.

  5. Simplify the character encoding
    Another HTML5 gem, the character encoding can be much shorter. Here is the tag before:

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

    And you know the drill by now, here is the tag after the change:

    <meta charset="utf-8">
  6. Removed type=”text/css” from link tags and type=”text/javascript” from script tags
    In HTML5 is is assumed that your link tags are for CSS and script tags are for JavaScript. Here is the before:

    <script type="text/javascript">
    <link rel="stylesheet" type="text/css" href="file.css" />

    And the after:

    <script>
    <link rel="stylesheet" href="file.css" />
  7. Add the HTML5 shiv (shim)
    So far our changes have been pretty tame. But we are about to start adding new tags to the master page such as <section> and <nav>. Seeing these tags usually makes people assume they can’t use HTML5 until the year 2022 (I didn’t make that up… it is a real misconception). The truth is you can add a tag in your HTML that says <gettinjiggywithit> and use CSS to style it and almost every browser will render the page just fine (and no, it won’t validate). The exception being Internet Explorer version 8 and earlier. If you toss <gettinjiggywithit> to IE and add some styles, your styles will be completely ignored. This applies to our new HTML5 tags as well. In order for IE8 (and older) to properly render your page, you need to add the HTML5 shiv (also referred to as shim) to your master page. Here is the code:

    <!--[if lt IE 9]>
    <script type="text/javascript" src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>

    The first line is a conditional comment that is only read by IE. It translates to “if this is Internet Explorer lower than version 9, do the following”. For those of you who say “what about users who have JavaScript disabled?” – If your users have JavaScript disabled they aren’t going to be using SharePoint very well to begin with.

Adding and switching to HTML5 tags

The things you can do in the HEAD of your file are pretty straightforward. Now it is time to move on to adding HTML5 tags and converting existing tags to the new HTML5 tags. Here is where different people will interpret things in different ways and have opinions on what tags should be used and where. I am going to outline what I did to the master page and this is my opinion. With HTML5 there isn’t one single right way to do things. Your opinions may differ from mine.

If you are brand new to HTML5 I highly suggest you invest in a good book to help learn the in’s and out’s of the new tags.  Here is a brief introduction to get you started.

Short intro to HTML5

One of the main goals of HTML5 is to give meaning to our content.  To make our HTML more semantic. Essentially you are labeling your content based on it’s purpose. It is like taking the idea behind using H1 and H2 to specify an important heading (H1) and a slightly less important heading (H2) to the next level.  We are going to label headers, navigation, content, footers, etc.   The tags that are used are straightforward and if you read content marked up with HTML5 you can easily see what is serving what purpose.

When you are creating HTML5 you have to decide what tags to use for your content. When you are converting HTML to HTML5 you have to decide what tags to change and where to add new tags if needed. This is where different opinions will start to kick in.  SharePoint certainly doesn’t make this process any easier given the volume of HTML in the master page and content pages.

The DIV tag

One of the biggest changes for people moving to HTML5 is the use of the DIV tag.  A DIV tag has no semantic meaning.  It is a generic, block level element that you could see being used for numerous different purposes.  According to the W3C Specification for HTML5, “The div element has no special meaning at all. It represents its children. It can be used with the class, lang, and title attributes to mark up semantics common to a group of consecutive elements.”

A SharePoint master page is riddled with DIVs (as do most web sites so this isn’t necessarily a ding on SharePoint) so the biggest HTML5 conversion task is deciding what DIV tags in the master page should be converted to what HTML5 tags.  It all depends on the content within the DIV and if that content should have semantic meaning.

The tags I put to use in the master pages

NAV – Navigation for a site or page
SECTION – A section of the document/application. The content within is related to each other. For example, the body copy area of a site.
ARTICLE – An independant part of the section or of the site. If you were to see this content on it’s own, it would make sense. For example, a blog post.
ASIDE – An area of content that is tangentially related to rest of the content on the page, but isn’t required for that content. For example, Related Products.

Will this break SharePoint?

It shouldn’t.  I haven’t run into any issues with my conversions and if you do please by all means leave a comment for this post and I will look into it and make changes as needed.  Most of the CSS and JavaScript in SharePoint is looking for class names and IDs, so when you change the tag it doesn’t affect what those files are doing. Just be sure to leave the classes and IDs in place.

Getting down to business

Enough chatter. Here is what I changed and why in my Just the Essentials SharePoint 2010 master pages.

  1. Added the NAV tag around the accessibility links
    There are links at the top of the master page for accessibility use. I wrapped these tags within a single NAV tag and moved the style attribute and class attribute from each SPAN/DIV to the main NAV wrapper to cut down on redundancy.  Added NAV because this is site navigation.
  2. Added the NAV tag around the grouping of smaller menus
    This included the Welcome menu, Variations, My Links and multi-lingual. Added NAV because this is site navigation.
  3. Changed Site Actions wrapper SPAN tag to NAV tag
    This is the element that wraps the Site Actions control. Retained the siteactiontd ID and ms-siteactionsmenu class. Added NAV because this is site navigation.
  4. Added the NAV tag around Breadcrumb Popout/Hierarchy Tree
    This is the little folder icon you see in OOTB SharePoint sites. Added NAV because this is site navigation.
  5. Changed the ribbon wrapper DIV tag to SECTION tag
    This is the element that wraps various ribbon components. Retained the s4-ribbonrow ID and s4-pr/s4-ribbonrowhidetitle classes. When you break down a SharePoint master page you have the content within the ribbon and the content below the ribbon. I see this as two different sections of content within the page.
  6. Changed the ribbon children DIV tags to ARTICLE tags
    This included the ribbon (retained the s4-ribboncont ID), the notification area (retained the notificationArea ID and s4-noti class) and the Add Web Parts panel (retained the WebPartAdderUpdatePanelContainer ID). I switched these to ARTICLE because each is a separate component that could stand alone on the page.
  7. Changed the workspace wrapper DIV tag to SECTION tag
    This is the element that wraps everything outside of the ribbon, including your main content. Retained the s4-workspaceID. See #5 for reasoning.
  8. Left the wrapper DIV tag for s4-bodyContainer as a DIV
    This DIV doesn’t provide any semantic meaning and is there as a hook for SharePoint functionality and style.
  9. Changed the title area wrapper DIV tag to HEADER tag
    This wrapper contains the site logo, title, page title, description, etc. By default it is set to hide when the ribbon is activated. Retained the s4-titlerow ID and s4-pr/s4-notdlg/s4-titlerowhidetitlefrom classes. All of the elements within this wrapper are related to header information.
  10. Added a H1 tag around the site title – note this isn’t HTML5
    This was added since this is the site title. Other heading tags were not added to the other components (like page title) because the only thing in the master page is the content placeholder. The markup should be paired with the data itself, which is in the content page/page layout.
  11. Added the NAV tag around the page breadcrumb
    This is the page level breadcrumb you see in the content area. Added NAV because this is site navigation.
  12. Changed the first content wrapper DIV tag to ARTICLE tag
    Retained the MSO_ContentTable ID. This wrapper includes the main content area. If HTML5 will not be added to the content page/page layout, then adding the ARTICLE tag here makes sense.  But if the content page/page layout will have different stand alone components that deserve individual ARTICLE tags, then switch this back to DIV as it is not providing any semantic meaning. You should avoid nesting SECTION in another SECTION tag. Also avoid nesting ARTICLE in another ARTICLE tag unless the nested ARTICLE is another stand alone bit of content that is separate from the stand alone content within the parent ARTICLE tag.  So in short, don’t do this: <article><article>. This however is ok: <article>Blog post<article>Post Comment</article></article>
  13. Left the second content wrapper DIV tag as a DIV
    This DIV (assigned the MSO_ContentDiv ID) doesn’t provide any semantic meaning and is used to set up the Web Part Tool Pane.
  14. Added the ASIDE tag around the Quick Launch/Current Navigation components
    These are the left side bar components such as the Quick Launch menu, the Tree View menu and the Wiki navigator. Added ASIDE because these elements are related to the main content but not necessary in order to understand the main content.
  15. Added the NAV tag around the Quick Launch menu
    This is also known as Current Navigation. Added NAV because this is site navigation.
  16. Changed the tree view menu wrapper DIV tag to NAV tag
    Retained the ms-treeviewouter class. Changed to NAV since this is site navigation.
  17. Added the NAV tag around the extra navigation links under the Quick Launch
    These links include the Recycle Bin and View All Site Content. Added NAV because this is site navigation.

That is it!

Please keep in mind that this is a basic SharePoint master page that focuses on the components you need to start with for a SharePoint 2010 compatible master page. Your final code will be different and likely have more HTML5 elements.  Hopefully this will get you started and take out some of the mystery behind HTML5!

Bug list

A bug free web site is just boring. How else do we stay on our toes? Here is a list of identified bugs when making these changes to SharePoint. Please post any issues you come across in the comments and I will update the list accordingly.

  • Change IE meta tag from “IE=8″ (or IE=edge) to “IE=9″Please note these bugs only show up in IE!
    • In a document library, the “Send To” option in the context menu doesn’t doesn’t display the secondary menu (thanks to Brian for discovering this).
    • Rich text editor fields in dialog boxes do not allow text entry.
    • Save button in dialog boxes do not work.
    • The people picker save button is disabled (thanks to Shane Perran).
    • Web Parts cannot be moved from zone to zone, they go back to their default location when you stop editing the page (thanks to Shane Perran).
    • Site Permissions > Create a New Group (newgrp.aspx) page wont submit. The Rich Text entry box for the new group ‘About Me’ is greyed out. The page errors out in Office365 (thanks to John Mongell).
    • Instant Messaging presence pawn is broken (thanks to Sig Weber).
    • Event in calendar view can’t postback/create an item (thanks to @CStahl).
    • The mini calendars within the Modal Popup Dialog Box when the Week Day is enabled (“Show week numbers”…); the design for the calendar crashes (thanks to @CStahl).
    • Lookup fields with 20+ items will not display the dropdown list (thanks to @CStahl).
    • People Picker is broken (thanks to Sig Weber).