Why you might need this guide?
I’ve done quite a few SharePoint-based projects for different companies. In some of them I was implementing branding myself based on guidelines or images. In some other I was providing guidance to the professional front-end developers, and some of them have never worked with SharePoint before.
How SharePoint is different
A big mess in code
Limited control over generated markup
If you have ever created a theme for WordPress, or perhaps any other decent open-source CMS, you know that you can usually have perfect control over generated markup on pages. A system that is friendly for theme developers has a fine-grained approach, where you can prepare a html layout, and then fill it with some placeholders like blog title, blog entry author, blog post date etc.
Sharepoint is definitely coarse-grained. There’s a concept of master pages which control the general layout of each page. Fig. 1 shows all the placeholders highlighted on a default master page file (called
The biggest placeholder in the image is PlaceHolderMain. This mean that you can put PlaceHolderMain somewhere on your master page to change the layout, but all the contents inside this placeholder are generated on the server-side by SharePoint’s closed source DLL’s and you can’t make a template for the stuff that lands inside them.
Proprietary standards for themes
SharePoint pages out of box provide user with a choice of a colour and a font scheme for the site (they can be set in a browser). Those preferences are used by platform’s engine to create CSS files. In SharePoint 2013 this process doesn’t involve any popular CSS preprocessors, but is based on XML configuration files, that get merged into CSS by SharePoint engine.
Color scheme can be edited with a little outdated Color scheme palette tool, while font scheme needs to be edited manually if necessary.
Even if you try to do all your branding in CSS file, you will not want to override all the possible places where a color (or font) might be used. The system and default stylesheet is too big for that. You will need to learn about those schemes, and how to edit and deploy them.
Development requires resources
As I stated before, the process of branding SharePoint portal is more about modifying what you find rather that creating something from scratch. To do this, you will need a development environment running SharePoint. And this is not something that you would want to install on your laptop, as it has a lot of dependencies and hardware requirements: operating system from a Windows Server family, SQL Server, 8GB RAM or more, a lot of software installed. Even if you are comfortable with Virtual Machines, this could be quite heavy for a typical developer’s machine.
The most popular approach to setting up dev environment in on-premises scenario is to:
- Install SharePoint instance on some physical or virtual machine in your company, and provide developers with access via RDP or only by HTTP,
- Create dedicated virtual machine on Windows Azure – quick to set, but it might produce some more costs.
And for scenarios where SharePoint is going to be deployed in the cloud, the natural development environment seems to be SharePoint Online service in Office365.
Setting up development environment
Using familiar technologies
<link rel='stylesheet' ...> and
<script src='...' > tags to appear on the pages.
$site = Get-SPSite http://devserver:3456/
$action = $site.UserCustomActions.Add();
$action.ScriptSrc = 'http://localhost:1234/jquery-1.11.3.min.js';
$action.Sequence = 5; # somewhere before other attached scripts
$action.Title = 'Branding - jQuery';
$action.Description = 'Sharepoint.Branding jQuery file';
$action = $site.UserCustomActions.Add();
$action.ScriptSrc = 'http://localhost:1234/SharePoint.Branding.js';
$action.Sequence = 10; # after jQuery
$action.Title = 'Branding - JS file';
$web = Get-SPWeb http://devserver:3456/
$web.AlternateCssUrl = 'http://localhost:1234/SharePoint.Branding.css';
You might notice that I put the links for JS and CSS files pointing at some resources on localhost server. This trick can allow you to develop branding code on your own machine and using your own browser (which is always most comfortable), and at the same test it with SharePoint located on some other machine, physical or virtual – it’s enough for you to have access to it in your browser after you set up those URL’s.
The alternative way to attach your assets would be to create your own master page based on default master page, and insert those tags yourself. However, this approach is no longer recommended, as custom master pages are now deprecated.
Thinking ahead: migration to a newer version
So far, migration from older version to a newer (eg. from SP2010 to SP2013) was totally destructive to custom branding solutions. Microsoft documentation on the subject states it clearly:
When you upgrade your site collection to SharePoint 2013, these types of customizations will not work as is because the default CSS styles, themes, and master pages have changed. Instead, you must create your custom branding again. This requires you to use the new styles, themes, or master pages available in SharePoint 2013, and then apply the newly re-created design to the upgraded site collection.
The good news is that there seems to be much less difference between current stable version 2013 and upcoming 2016. Also, SharePoint Online is offered as a service that gets regular updates, and those updates are trying not to break anything. This means that the default way SharePoint looks now and how the master page is constructed is somewhat frozen and might stay this way for some time.
To be honest, there’s not much you can do to prepare your branding solution for eventual big future changes. The preferred way would be to stick to what is offered by the platform — changing colour theme, font set and logo. The practice shows that clients want more aggressive changes, and those might just need to be done again when the UX philosophy in underlying system changes.