Case study how to use same master page in Office 365 and on-premises

This is not a tutorial how to customize the master page in Office 365. Microsoft doesn’t recommend to create your own master page because they will constantly evolve the user interface and this might break your branding.

The reason I created this case study is to show that it is yet possible to use the same master page in Office 365 and on-premises. This master page also takes into account that the Ribbon and Suite Bar are completely different in both environments.

Another important thing is to show how the master page might evolve in future so that it provides two things. Enables Microsoft to implement and add new features and allows custom branding as we currently do it on-premises.

Problem with Suite Bar and Ribbon in seattle and oslo master page

Right after my first SharePoint 2013 installation I took a look at the master page and to check what was changed or added. I found the newly added suite bar and recognized that the controls of the ribbon are still inside the master page. In general, you have to be careful with those code blocks not to break SharePoint.

On the other side those code blocks are an enormous problem for Microsoft because if they like to change or customize the suite bar or ribbon, as happened in Office 365 over the past few months, they need to replace the complete code there. It is an easy task to customize their master pages because all they need to do is to replace the ghosted master page files on the tenant. Similar what we do with custom master pages on-premises.

With custom master pages this would be tricky. What Microsoft needs to do is to search, compare and replace partially the content of the custom master pages in every tenant. This is nearly impossible to do. Therefore, they gave the order don’t customize the master page.

The question now is:
Is there a better way to add things like suitebar or the ribbon to the master page?
Yes there is an it currently exist in SharePoint On-premises and Office 365.

Ribbon.ascx – Suite Bar and Ribbon in a custom control

I’m not sure how, when or why I discovered the “ribbon.ascx” control, but it contains nearly the same content as ribbon and suite bar in the master page. This control also supports anonymous and authenticated user. Made possible through two security trimmed controls that render different content for each user group.
I don’t know the reason why this won’t be used in the master pages instead of the big code blocks, but that control allows to update the content of the master page independently of the master page. Changing the “ribbon.ascx” file will automatically reflect on every master page that consumes this control.

If you like to take a closer look at this control, it can be found on every on-premises installation under the path “HIVE15\templates\controltemplates\ribbon.ascx”.

The following question came to my mind a couple of times throughout the last month. Would it be possible to use this control in Office 365 too? Can it be used in a custom master page? Will this control be updated and maintained by Microsoft containing the new features?

One master page for both environments

To find out if it is possible to use a single master page that matches the on-premises world as well as the Office 365, I defined the following tasks.

  • Replace Ribbon and suite bar with Ribbon.ascx on-premises
  • Take this master page and add it to Office 365 to see if it works there too.

Let’s start with a new custom master page. The first thing I create was a copy of the “seattle.master” and opened it with Visual Studio directly out of SharePoint. To make use of the “ribbon.ascx” control it first needs to be registered inside the master page. In my case I registered this directly below the already existing “welcome.ascx”.

I simply copied the registration of the welcome control and then corrected the properties. For the “tagprefix” I used “csRibbon”. The abbrevation for “case study ribbon”. The “tagname” property I changed to “Ribbon” and finally the “src” property I set to reference the file in the control templates with “~/controltemplates/15/ribbon.ascx”.

Registration of ribbon control in header

Registration of ribbon control in header

Now everything is set up to replace the suite bar and the ribbon with this control. Therefore, all that needs to be done is to remove the original container shown in the screenshot below.

Original suite bar and ribbon

Original suite bar and ribbon

Both sections are grayed out because I collapsed them. The next step is to add the ribbon control instead of those code sections as shown in the screenshot below.

Replaced suite bar and ribbon

Replaced suite bar and ribbon

Theoretically, we should now have a master page that works in Office 365 and SharePoint on-premises without any limitation in all cases, also if you got your cheap MS Office in Aus and just started to figure out what the master page was.

Test run the master page

To make sure that these modifications will be loaded correctly, I colored the background of the workspace with a bright yellow directly inside the master page. I know it doesn’t look nice, but yellow is always a great signal caller. I also added a text table that matches the name of the master page.
The following screenshot shows the loaded master page in an on-premises environment.

On premise with changed master page and ribbon

On-premises with changed master page and ribbon

The user interface of SharePoint looks correct so far. Let’s check if the functions of the ribbon still works.

On premise with changed master page and ribbon in edit mode

On-premises with changed master page and ribbon control in edit mode

Everything looks and works correctly. You might recognize the small gap between the notification bar and the content in the edit mode. This comes from a small CSS issue, but have no impact on the functionality.

I did some additional testing too and everthing worked as expected.
As mentioned earlier, I would like to use the same on-premises master page in Office 365. To test this I uploaded the master page and published a major version. After assigning the custom master page it looked like this.

Office 365 with changed master page and ribbon control

Office 365 with changed master page and ribbon control

The screenshot above meets my expectations and it seems that the ribbon.asx is maintained and provides the same functionality as the one directly embedded. Does this work in edit mode too?

Office 365 with changed master page and ribbon control in edit mode

Office 365 with changed master page and ribbon control in edit mode

After the first test it was no big surprise that the ribbon works in edit mode too. Mission accomplished a master page that matches both scenarios. On-premises and Office 365.


The strategy of Microsoft is clear. Cloud first. New features will be implemented in Office 365. Later we might see them on-premises too. For example the newly introduced app launcher would make sense there too.
I don’t want to deny the fact that not properly implemented master page can break the user experience and during the last year I had to fix a couple of them too to restore the default functionality. For example master pages where the ribbon has been trimmed down to a width of 960px because the content was set to 960px. Mentioned in my blog post “Centered fixed width design in SharePoint 2010 – The fast way” back in 2011.

I hope that I’ve shown in this blog post that it is possible to implement new features based on web controls instead of directly embedded code. This master page I created in this case study is likely to be future safe. Especially if those feature will eb added to the suite bar and the ribbon. Maybe we will see more web controls that we can be placed on new master pages to meet the recommendations by Cathy Dew. She documented this in her blog post “Is the Future of UI Customizations for Office 365 Doomed?“.

Finally I need to address on thing the last time. Currently don’t customise the master page in Office 365. Use CSS and JavaScript instead. More important. Don’t change suite bar or ribbon.
You might have heard argument not to brand SharePoint because you wouldn’t brand any other Office Application. This is partially correct. To me suite bar and ribbon are parts of that office application. Below is the content and this should be able to be breanded in a responsible way.