Updating your SharePoint Master Page in SharePoint Online

In this post, I am going to describe how I took a heavily customized SharePoint Online (SPO) master page that had been left behind in terms of Office 365 updates and brought it back from the dark ages. This is a bit off-topic for this blog but since I don’t contribute to any other blogs, I decided to temporarily hijack it.

First, your mileage will vary with the specifics I provide here. Depending on the point in time you customized your master page and the customizations you made to it, you may have to do a deeper analysis. However, I hope you will benefit from the process I followed.

Before

The Process

The first thing I did was download the latest master page from a new site collection in SharePoint Online and compared it with our customized master page using WinMerge. This was pretty tedious and as someone who has only done limited customizations of master pages, it proved not to be very effective. My breakthrough came when I was pointed to this CodePlex project by Randy Drisgill. In this project, he dissects and labels the various elements of the master page. The samples he provides aren’t up-to-date with SPO but they still helped me decompose the elements of our master page and compare that to similar sections of the latest master page I pulled from SPO.

Ultimately, I zeroed in on the HTML div with the id=’'suiteBar” in both master pages. In the latest version, you’ll see that this div is wrapped in two SharePoint custom controls, AjaxDelta and FlightedContent. The latter really caught my eye.

Once I picked these notable discrepancies out, I reviewed the markup within them and felt pretty confident that I could essentially replace everything within the suiteBar div with the content contained in, and including, the SharePoint custom control, AjaxDelta. I also had to register the following two tag prefixes:

<%@ Register TagPrefix="wssucmui" TagName="MUISelector" Src="~/_controltemplates/15/MUISelector.ascx"%>

<%@ Register TagPrefix="wssucw" TagName="Welcome" src="~/_controltemplates/15/Welcome.ascx" %>

Roll Out

The development process for Office 365 is still an evolving story. Some companies are using separate tenants for dev, test, etc. while others are simply leveraging separate site collections within their tenant. For this, I am using a separate site collection, which serves my needs pretty well. I was able to configure a new site collection with the customizations from our production site collection by exporting a design package from the production site collection and importing it into the test environment. This created an apples-to-apples environment for testing. I copied the updated master page over the custom one and the new suite bar appeared.

After

For our next step, we’re going to push the update into one of our other affected production site collections and let users hammer it. Since this is only a subset of our sites, if there are issues that we have not yet discovered, hopefully the impact will be minimal. Once we’re comfortable there, we’ll push to our other five or six site collections. Unfortunately, our main site collection is also our most complex so we’re going to push there last and dedicate time for our internal team to hammer at it and identify issues before the general user base gets at it.

Hope this helps. Any questions, comments or feedback are welcome.