SharePoint branding introduction

Sep 13 2015 No Comment by buli

SharePoint branding introduction

Why you might need this guide?

Are you about to start your first task of branding SharePoint portal to a client’s taste? This introduction is exactly what you might need to save yourself from confusion while making first steps. I suppose you know your tools well, CSS and JavaScript in the first place, then maybe some stylesheet preprocessors, jQuery or templating engines. This will be all useful, but the process of branding SharePoint is different than creating HTML template from scratch or developing a WordPress theme and it’s good to know the pitfalls in advance.

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

A little research shows that first SharePoint browser client was released in the times of Internet Explorer version 5. The design evolved over the years resulting in a nice, modern look in current version (SharePoint 2016 Preview, or its cloud-hosted version SharePoint online). However, it feels like you can find all the Internet history when you look into the HTML source or JavaScript environment. The page renders in IE8 Browser Mode for compatibility, even if you use the most current IE release (IE11 at the time of writing). That should give you an idea of what to expect.

But to make it clear: you will encounter markup mixed with JavaScript, long-forgotten HTML elements, JavaScript timing events doing strange things every N seconds and all that nasty stuff. And there’s really no way to discard it and replace with the new, but instead you have to build upon it.

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 seattle.master).

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.

Fig. 1. SharePoint 2013: content placeholders for the default seattle.master masterpage

What’s more, master pages have just become deprecated this year which should make you try to do the things in a different way. Which means – having no control over markup at all and using solely CSS and JavaScript.

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

The “hello world” part for branding process will be attaching a CSS and JavaScript file(s) to the SharePoint page. Then you will have the freedom to do anything that those languages permit.

Assuming that you have your own site collection dedicated you might attach JavaScript and CSS files to all pages in a site collection with a PowerShell script similar to the one below. This will cause for the appropriate <link rel='stylesheet' ...> and <script src='...' > tags to appear on the pages.

$site = Get-SPSite http://devserver:3456/

$action = $site.UserCustomActions.Add();
$action.Location ='ScriptLink';
$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.Update();

$action = $site.UserCustomActions.Add();
$action.Location ='ScriptLink';
$action.ScriptSrc = 'http://localhost:1234/SharePoint.Branding.js';
$action.Sequence = 10; # after jQuery
$action.Title = 'Branding - JS file';
$action.Description = 'Sharepoint.Branding JavaScript file';
$action.Update();

$web = Get-SPWeb http://devserver:3456/
$web.AlternateCssUrl = 'http://localhost:1234/SharePoint.Branding.css';
$web.Update();

$site = Get-SPSite http://devserver:3456/

$action = $site.UserCustomActions.Add();

$action.Location ='ScriptLink';

$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.Update();

$action = $site.UserCustomActions.Add();

$action.Location ='ScriptLink';

$action.ScriptSrc = 'http://localhost:1234/SharePoint.Branding.js';

$action.Sequence = 10; # after jQuery

$action.Title = 'Branding - JS file';

$action.Description = 'Sharepoint.Branding JavaScript file';

$action.Update();

$web = Get-SPWeb http://devserver:3456/

$web.AlternateCssUrl = 'http://localhost:1234/SharePoint.Branding.css';

$web.Update();

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.

Branding issues that may occur when upgrading to SharePoint 2013

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.

Tags:branding css javascript less microsoft office365 sharepoint web