SharePoint 2013: The Branding Dilemma – Conflicting Guidance on Themes with Custom CSS vs Master Pages

The Background

We are working with a global client who has a hybrid SharePoint 2013 environment that is growing in scale that will soon consist of many in-country SharePoint farms, as well as having a ‘global’ data centre and using Office 365-D. Within a couple of years these farms will host hundreds of thousands of site collections created based on our template solutions.

These solutions need to be able to be deployed to any one of these SharePoint farms including Office 365-D and so cannot use full-trust server-side solutions, as these are not permitted in these environments, with Office 365-D initially driving the need to avoid full-trust solutions, particularly when considering the planned move to Office 365-D vNext, so we need to try to avoid potential upgrade problems as much as we can.

For this we are embracing the Cloud App Model, i.e. client-side object models and APIs – CSOM, JSOM, REST, and where appropriate create SharePoint Apps/Add-Ins.

Standardised Solution Deployments Using CSOM & XML

Early last year we developed a remote deployment solution that allows us to create and deploy SharePoint artefacts entirely using CSOM and REST, with the solution defined as simple XML, so being able to create complete solutions built on top of out of the box team sites deployed remotely via CSOM, avoiding creating Site Definitions or Web Templates that have dependencies on WSP solutions (which Microsoft are trying to move away from). We designed this deployment solution such that the same package can be deployed into O365-D, O365-Tenanted, or On-Premises without any change to the code/package. Of course we still have to consider the nuances of each type of environment and make sure our solutions will work with those. These differences are largely handled within the deployment solution, using the APIs appropriately for each type of environment.

This is all working well and we have deployed many solutions using this approach. We are following Microsoft guidance, patterns and practices, and industry good practices. I don’t like the term ‘best practice’ as it seems arrogant to me if I might say one approach is the ‘best’ – this can be considered subjective where there might be more than one good approach and another might be better depending on the circumstances. Indeed there are several Microsoft Patterns & Practices that achieve a similar outcome.

Determining Branding & UI Customisation Guidance

Anyway, on to the main point of this post! Our client often requires a complex customised user interface built on SharePoint. We’re trying to formulate guidance on user interface customisations that we can give to design agencies, which often have no SharePoint experience and therefore produce fancy UI designs that generally do not fit SharePoint very well. The guidance will also be given to the developers who need to implement these designs in SharePoint using our recommended approaches. We want to define approaches that are consistent with Microsoft and industry good practice, and while we have been able to deal with most issues and have managed to get the CSOM APIs extended in some cases, we have encountered a dilemma with what appears to be conflicting guidance vs what the client-side APIs currently support around branding a site, or customising the UI.

Note that the solutions need to be fully automated for deployment as well as upgrades, and so changes/upgrades to UI must also be able to be applied through an automated approach without use of server-side code. Our remote deployment solution handles this, so we just need to determine the client-side methods to achieve the required branding/custom UI outcomes.

I will first explain the guidance that I am considering, then follow with why I believe these are incompatible…

Guidance #1: Use Themes

The first piece of guidance from Microsoft I’d like to consider is to use themes for minor UI customisations, where simply changing the colours of existing elements on the page will be sufficient. Without ‘customising’ any aspect of the site the colours can be configured simply by selecting some new theme colours, or pick/create a Composed Look with a new colour theme. Therefore this appears to be a good approach to use that does not require any development if this is sufficient to meet the requirements.

Guidance #2: Make Custom CSS Themable

More complex UI customisations usually require some custom CSS. No problem! Custom CSS files can be used in SharePoint, however they often include hard-coded colours. Given SharePoint has a great theming engine that provides a configurable colour palette it seems appropriate that those colour palette entries are used directly in the CSS rather than hard-coding colours in CSS, so colours can be updated without reworking the CSS. Microsoft guidance also seems to recommend this.

This approach seems particularly useful for light to medium UI customisations where a Theme does not quite cover all of the UI needs, and a little CSS may be needed – perhaps some additional elements to be shown on the page needs to have some theme colours applied to them.

For details on how to create a Themable CSS file and applying the Theme, see “How to: Make custom CSS files themable in SharePoint 2013“.

In simple terms, you mark-up the CSS with annotations in the form of specific CSS comments that indicate which colour palette entry to be used, with some other abilities such as recolouring images, changing fonts, and so on. SharePoint 2013 Themes also now provide the ability to define new colour entries in the palette and reference those in CSS – this was sorely missing from SharePoint 2010 Themes, and is a welcome addition in SharePoint 2013. This now also makes it possible to consider using Themes for more complex UI customisations where we can now define new colours that are not tied to colours already used for out of the box components which was a significant limitation I encountered in SP 2010.

To make SharePoint take notice of these theme annotations, i.e. to generate and use a themed version of the CSS automatically, involves having to register the CSS on the site. This is achieved by adding a element in the head of the Master Page pointing to the CSS file, ensuring the CSS file is placed in the Themable folder in the Style Library, and having all necessary theme annotations in the CSS. Then whenever another theme is selected, SharePoint will auto-generate a themed copy of the custom CSS with colours substituted, and the CssRegistration element will output the correct CSS link on each page.

This approach therefore requires modifying the Master Page, which brings us to the next piece of Microsoft guidance…

Guidance #3: Try To Avoid Modifying Master Pages

While through a quick search I cannot easily find any direct written guidance on this, I have heard this guidance direct from several Microsoft sources, and read the same advice on several blogs and forum posts – it makes sense. The following Microsoft Patterns & Practices articles provide patterns for adding CSS without modifying a master page, and the 2^nd article confirms this guidance saying “Custom master pages should be avoided to ensure that any updates or enhancements added to the out of the box master pages are automatically in use of the sites”.

SharePoint upgrades usually come with updated master pages, and increasingly in SharePoint Online, smaller upgrades are being rolled out more regularly, which form time to time may include updates to the master pages. Any time we modify a master page to add our own components, or add links to scripts or CSS, we effectively lock ourselves into the current modified version of the out of the box master page so it will not pick up any further enhancements as SharePoint evolves. This could mean we do not benefit from some improvements, whole new features, or even in the worst case, for a significant upgrade, the master page having to be redeveloped just to keep it working in the new version of SharePoint (or maybe we remain locked to an ‘old’ UI as many will have found when upgrading from SP 2010 to SP 2013). So where possible it would be better to avoid changing the master page and use other ways to add any necessary customisations, such as injection of JavaScript or CSS as discussed in the following Patterns & Practices:

CSS INJECTION PATTERN – Uses JavaScript injection via a User Custom Action to add a CSS link without directly modifying the master page. A problem found with this approach is that the page loads completely before this JavaScript is executed which then loads the CSS, so the net effect of this is the page flickers as it first renders the page then updates the page afterwards with the new CSS. Using this approach for loading JavaScript may be more acceptable in many cases as the delay may not cause any noticeable visual problems if the JavaScript does not result in restructuring or recolouring the page. Dynamic loading ‘spinners’ can be used to indicate when a component is still loading without significantly impacting the overall user experience.

ALTERNATECSSURL & SITELOGOURL PROPERTIES IN WEB OBJECT – It is now possible to set an Alternate CSS URL via CSOM since April 2014 CU, so this now seems a better alternative to the CSS Injection Pattern where the CSS is loaded and applied during page load and applies to all pages in the site. While the UI only makes this setting available on Publishing Sites (or sites with Publishing Infrastructure features enabled), it seems via the CSOM API it is now possible to set Alternate CSS URL via CSOM on all types of sites.

The Dilemma – We Can’t Apply A Themed CSS File Without Modifying A Master Page

My problem with using these patterns is that they still do not apply the theme to the CSS. It seems only use of the CssRegistration element added to the master page will actually ensure that the CSS has the theme correctly applied to it. Both CSS Injection and AlternateCssUrl approaches will not apply a theme to the CSS.

So we appear to be stuck between conflicting guidance. On the one-hand we should use Themes more, especially for more simple UI customisations, and where necessary implement Themable CSS to keep the site looking consistent when the theme colours are changed. However on the other hand, we cannot actually apply a Themable CSS without modifying the master page to add a CssRegistration element, which we are also advised that we should try to avoid.

At present if we were to try to follow Microsoft guidance around both theming custom CSS and not modifying a master page, we will fail as this seems to be a gap in SharePoint. I will be encouraging Microsoft to fill this gap, but won’t expect this to be covered any time soon.

Given that we would not want to have to rectify master pages on hundreds of thousands of site collections, we would prefer not to have to add CssRegistration to each master page. So it seems the ‘lesser evil’ will have to be adopted, and that is to consider dropping the recommendation to make your Custom CSS Themable as it would not be able to pick up the theme colours. This does not sit nicely with me, but until we receive an update for this in SharePoint, there does not seem to be any other way we can achieve our aims.

Update: 24th July 2015

Microsoft has acknowledged this issue and has raised a Design Change Request but they now need to identify other clients who are also affected by this, and have requested this to be logged in ‘user voice’ so others can vote it up to raise the priority. Here is the link if you would like to help raise the profile of this issue: Issue logged in user voice – please vote.