Creating a Custom Composed Look for SharePoint

Intro

This is the 2nd in a series of articles that support the session that I am presenting at O365 Saturday events throughout Australia this year.  As a backdrop I am using a real customer, Adelaide Airport, although I did this work as a proof of concept for a different project and should point out that this is not their real intranet portal or anything like it.  I just got a bit fed up of using Acme and Contoso all the time.

Series looks like this:

• Branding for Non-Branders – Covers some fundamentals to get us started
• Creating Custom Composed Looks – This article
• Useful Tricks with Alternate CSS – You’ll probably need to set up the Alternate CSS as well as use a Custom Composed Look
• The Kaboodle Branding Infrastructure – This is a free branding accelerator solution for on-prem deployments of SP2013/16.
• My 10c worth on Image Rotators – When to use (and not to use) KISS or other image  rotators.

So in this post I’m going to walk through how to create a custom composed look.

What is a Composed Look?

Composed Looks were introduced in SharePoint 2013 as a way to simplify the application of a look and feel to a SharePoint web site.  They have been carried through unchanged to SharePoint 2016 and SharePoint Online in O365 so this article is relevant to all those environments.  If you are stuck on SharePoint 2010 (or before – is there anyone still in that boat) then you’re out of luck because the Composed Look concept didn’t exist at that time.

A Composed Look is nothing more than a collection of configuration settings that are packaged into a SharePoint list item and  stored in a special list called the Composed Looks Gallery.  You select a Composed Look using the Change to Look wizard which accessible from the Look and Feel group on the Site Settings page.  When you complete the process the Composed Look list item, which is just really a collection of URL pointers to other resources for the master page, a colour palette, font scheme and a background image, is consulted and the appropriate configuration settings as applied to the web site.  Conceptually it is a very simple idea and one which is very useful for those of us you need to apply some level of light branding.

Standard Composed Looks

If you drill into the Composed Looks Gallery (via Site Settings and the ‘Composed looks’ link in the Web Designer Galleries group) you will see the set of standard Composed Look list items.

Out of the box, Microsoft give us 17 to choose from and these are shown when you following the Change the Look wizard.

The standard default Composed Look, called ‘Office’ is perfectly usable, as are the Green and Orange colour variants.  Sadly, after that things go down hill and the rest of the standard templates are all but unusable, especially the dark ones, unless that is that your site is intended to sell adult erotica!

To be fair, these Composed Looks are not really intended to be the finished article but more like a start point and you can actually select any one of these standard Composed Looks and configure it to look like any one of the others.

Elements of a Composed Look Item

Each Composed Look list item has a number of key properties as shown and listed below:

• Title:  The list item title which will be displayed in the Change to Look Wizard.
• Name:  The name of the list item.
• Master Page URL:  The URL of the master page to be used when the Composed Look is applied.  As we are sticking with the standard master pages, this will be to either the oslo.master or seattle.master files.
• Theme URL:  The URL to the colour theme file that is to be used when the Composed Look is applied.  We will use the Microsoft Color Palette tool to generate one of these in just a minute.
• Image URL:  An optional URL to an image that will be used as a background for the web site.  I provide some guidance on this later in this article.
• Font Scheme URL:  The URL to a font scheme file that will be used when the Composed Look is applied.  If you don’t set a specific font scheme then a default font scheme will be used.
• Display Order:  Used to specify the order in which Composed Look list items will be displayed in the Change the Look Wizard.  Note that the currently applied Composed Look is always listed first and with the title ‘Current’ and a Display Order value of 0.

Before we can create a Custom Composed Look list item we need to create a custom colour theme file, as without one there is not really much point in creating a Custom Composed Look at all.

The Microsoft Color Palette Tool

Microsoft provide us with an unsupported tool, called the Microsoft Color Palette Tool,  to help generate a .spcolor file which is the type of file we need to specify a custom colour theme for the Custom Composed Look i.e. to be at the end point of the Theme URL property in the Composed Look list item.

The Color Palette Tool can be downloaded from https://www.microsoft.com/en-au/download/details.aspx?id=38182.  This tool is a Windows Forms application which can be installed and run on any recent Windows OS but it does not require to be run on the server because all you are doing is using it to generate a .spcolor file.  In fact I recommend that you install it on some client machine and not on the server, except maybe in development environments.

After installing the application you can launch it in the usual way and it will open like the screenshot below.

I must say, it is far from obvious what you should do next and Microsoft don’t really provide any documentation to guide you either!  However, what I think you are supposed to do is to set the primary colour for the theme.  To do that click the colour square highlighted in the above screenshot.  This then pops up a colour picker dialog as shown below.

You can then set the primary colour as required.

Sometimes you might have been given a style guide that can give you a clue as to what the primary colour should be but in this case I just used the useful colour pipette tool on the Adelaide Airport public facing web site which returned a nice deep purple.

Click Ok and the you’ll see that the colour square has changed and you can then click the Recolor button to set this is a primary colour for the theme as shown below.

The tool is then likely to return a whole bunch of colour contrast warnings and if you want a theme that will look really professional you should track down all these warnings and seek to irradiate them.

If you look at the warning messages in more detail you can see that it offers some contrast values for Current, Optimal and Minimum.

Anything sitting currently at Minimum or below probably needs fixing up so then you have to read the warning and find the offending item and set it to a better colour value.

However, the UI is far from intuitive in this regard and to track done and rectify an issue can take some digging.  This may involve using the UI Groups picker control which is underneath the colour square.

In the screenshot below, the UI reports that there is an issue with the Button Pressed Background colour.  I can change this value to something better (from purple to white in this case) and click the reload message to confirm that change was good because that warning message is no longer on the hit list.

When you are satisfied that you have resolved all (or enough) of the warnings you can then save out the file as shown below.

Just so that you know, a .spcolor file is nothing more than an XML file with a .spcolor extension.  If you open it in Notepad you can see that it’s structure is fairly simple.

Now that we have our spcolour file the final step is to upload it to the Theme Gallery accessible from the Themes link the Web Designer Galleries group in Site Settings.

Note that you must upload the spcolor file to the 15 folder in the library (and yes it is still the 15 folder in SP2016 and O365).  If you try and upload the file to a different location or a sub-folder it won’t work – I’ve tried.

You can see my uploaded spcolor file, highlighted below.

Note that this is where you have to park any custom font scheme files (.spfont) as well.

Creating a Custom Font Scheme

Whilst Microsoft help us out with creating a colour scheme we are out of luck if we need to import custom fonts.  Sadly we have to hand craft the font scheme, another XML file, (the .spfont file) ourselves.  However, more than this we have to acquire the font files ourselves and park them somewhere in SharePoint.  We could in theory link to font files hosted on a CDN but I reckon it is better to host these files locally then we can be sure that the user will see what we see.

For a more detailed discussion on the steps I am about to outline I strongly recommend this post from Elio Struyf

The steps are:

• Acquire the necessary font files
• Create font samples
• Upload the font files to somewhere sensible in SharePoint
• Handcraft a .spfont file which links to the necessary font files
• Upload the .spfont file to the Theme Gallery

Acquiring the necessary font files

You will need to acquire .eot, .svg, .ttf and .woff files for every custom font that you want to use in the Composed Look.  This might require your customer to lay out some cash or you can go grab them from a free font archive such as Google Fonts.  Note that GF does not play with IE so access it using Chrome or Edge.

I like GF because they provide fonts that you’d actually want to use and they are free.  But how do you download the actual font files.  We it seems that our hero, Elio comes to the rescue here as well as he has created an Azure Web App for just this purpose at http://webfonts.azurewebsites.net.

To get the Google Font files, you’ll first need to download the .ttf files from the GF web site.  You actually download the font as a zip which then needs to be unpacked and you then choose from the set of available variants.  I just used the standard .tff file.

To get the font files in the other formats that you need, head over to Elio’s application at the above link and then type in the name of your desired GF.  For this demo, I shall be downloading the Roboto and Open Sans fonts which I shall be setting up for headers and body text respectively.

Note that you’ll have to get the spelling exactly right and case exactly right.

Click on the links to download the font files and save them locally.  You won’t need the .woff2 files as SharePoint doesn’t have a slot for these, so in the end you should have 8 font files in total.

That is to say you need:

• .ttf
• .svg
• .wof
• .eot

Files for both your fonts.

Create font samples

When you go through the Change the Look Wizard you may have noticed the font picker control.

Actually, the font picker is a bit of smoke and mirrors as it goes.  What you see in the font picker is not the font name as sample text, rendered in the font but rather it is a graphic file (2 of them actually), the location of which is specified in the .spfont file.

Now, creating these graphics file is optional but hey we want to do thing properly don’t we.  So what we need to do is to create 2 graphics as follows:

• Large Image Source: Which must be 109 x 16 pixels
• Small Image Source: Which must be 75 x 10 pixels

You might think you can be a bit flexible with these graphic sizes but you can’t.  If your graphics are anything other than these exact measurements then they just won’t render.

So how to generate these graphics?  Well first you’ll probably need to install the font on a client computer somewhere.  That’s done easily enough just but navigating to:

Control Panel\Appearance and Personalisation\Fonts

Then copy/paste the .ttf files you just downloaded from GF into the folder and Windows will install them as fonts which can then be used on any text and graphic package you have to hand.

I used the GIMP but you can use Photoshop or whatever to create the graphics.  This can be fiddly work.  The convention is to type the name of the font in that font and save that as a graphic file (.png or .jpg) but I suppose you could type any text, if you wanted to confuse everyone that is.

You don’t have to provide these graphic files at all and if you don’t then SharePoint will just render the font name text in its place.  It will try and use the specified font but that probably won’t be available on the user’s machine and so will fall back to using a standard font.

Not bothering with font graphic files might be an easier option if you are not worried about showing what the font will look like in the Change the Look Wizard, or if you can be confident that the target font will be installed on the user’s client computer.

Upload the font files to SharePoint

Next we have to upload all these files to SharePoint somewhere.  Elio recommends creating a fonts folder in the master page gallery and saving everything there.  When doing this manually (as I am in this post) then I guess that’s as good a place as any.  So now we have 10 files uploaded to somewhere that can be referenced from SharePoint.

However, I should point out that I actually only do this manually when working with O365.  When on-prem with SP2103/16 I usually go to the effort of creating a branding deployment package and when I do so, I use a Feature to park these font files in an application folder under _layouts/.

Not only does this mean that an over eager site admin can’t easily delete my font files by mistake but also, I’m a great one for believing that developers, and that includes branders,  should clear up after themselves and on feature deactivation the files in an application folder get swept away without us having to do anything.  So it’s a self-cleaning system – nice.

On an aside, I have seriously lost count of the number of one-way branding deployment packages that I have seen out there, created by people who really should know better.  What I mean by one-way is that a branding solution throws artefacts out there when the feature is activated but leaves them behind when the feature is deactivated like jetsam left on a beach after a high tide.  This is very sloppy in my mind.  One day I’ll write a blog post on how to create a proper branding deployment package.

Handcraft the .spfont file

Now, this is quite a tricky step because you have to hand craft some XML and that is always going to be error prone.  I could just repeat what Elio has already provided but what would be the point of that, so please read his article for details.

However in summary, start by editing a downloaded and renamed copy of one of the existing standard .spfont files and although these files look long and complex, as Elio explains you will find that you can actually dispense with large chunks of it.  Use your favourite XML editor, Visual Studio will do if you have it available.  Your .spfont file should end up looking something like the fragment shown below:

As Elio says in his post, you will need to provide absolute URLs to the font files and the graphic files.  You can only get away with specifying relative URLs to the font files if you can be certain that the user client machine will have your target fonts already installed.  I’m guessing what happens is that the browser first looks for locally installed fonts and uses them if they are found and will only download the font file from the server if it can be found locally.

 This confused me initially because I thought Elio had got it wrong and you could indeed use relative URLs but then I remembered that to create the font graphic files I installed the fonts locally hence the use of relative URLs appeared to work.

Note that you have 2 preview slots to play with.  The preview slots identify the font slots that will be displayed in the Change the Look wizard.  Whilst you can identify any of the font slots as previewSlot1 or previewSlot2 by their name, the convention seems to be that you should select the ‘title’ and ‘body’ slots as the preview targets as I have done above.

You only need to set the largeimgsrc and smallimgsrc tags to the target URL where you actually need them, the rest of time they can be set to an empty string.  Unfortunately, you can’t dispense with these tags altogether.  If you try, then your composed look will be considered invalid on the grounds that your .spfont file is invalid and simply won’t show up in the Change the Look Wizard.

Upload the .spfont file

The final step is to upload the hand crafted .spfont file to the 15 folder in the Theme Gallery.  So now we have both the new .spcolor file and the new .spfont file in the gallery as shown below:

Background Image

The final element that might go to make up a composed look is the background image.  This is optional, some themes have them others do not.  There are a few things that need consideration:

• You must use a standard graphic file format which most means .png or .jpp.
• There is a maximum permissible file size of 500Kb which is really not very much at.  If you try and link to a larger graphic file then SharePoint will spit the dummy!  I presume that this measure is in place to ensure that page loading can be achieved in a reasonable timeframe.  I guess this is understandable but as most SharePoint deployments are for intranets and caching is likely to be enabled I think this is a little bit draconian.
• You background image will be stretched, which poses no problems if you are using this approach to set a single background colour but in most cases you will want a repeating pattern or you background will be a photo or a graphic scene of some kind.
• So most of the time you will need to ensure that your background graphic is large enough to look good for the largest screen size/resolution that will access your web site.  All the standard Microsoft provided backgrounds are 1024px by 768px and so I would start there.
• It’s actually quite hard to find a high quality .png file at this size that comes in under the 500Kb size threshold, so save yourself the anguish and source a .jpg.
• When you set a background image SharePoint will automatically set the opacity so that the image will appear semi-transparent.  This is so that the image sort of fades into the background rather than distract the eye with blaringly vivid colours in the chrome.  I have found that for most photograph based backgrounds the opacity is still set too high (for my liking) and so it may be necessary to GIMP or Photoshop the source image so that already starts out life with less than 100% opacity.
• There is no substitute for experimentation.  Play around until it looks right.

Of course, where you store the background graphic is up to you.  When in O365 and doing this by hand then the Site Assets library is the obvious choice.  For on-prem I usually create a deployment package that creates the Composed Link in code and follow Microsoft’s lead and store the graphics in the sub-folder beneath the /_layouts/15/images/ folder for reasons of auto-cleaning on feature de-activation as explained previously.

Pulling it altogether

Now that we have all the pieces in place, all that remains is to create a new Compose Look list item in the gallery which will very look like that shown below.

So I set a unique name and title and point to the oslo.master master page.  I also point to my custom .spcolor and .spfont files in the themes gallery and finally pick up a background image from Site Assets.

Setting the display order to 5 will ensure that your new Composed Look will appear first in the Change the Look wizard as shown below:

If you Composed Look does not show up it is most likely that you pasted in an invalid URL in one of the Composed Look list item or you made an error when hand crafting the XML in the .spfont file.

Once your Composed Look shows up simply follow the wizard to its conclusion and marvel at your own creativity.

I have found that you need to be patient with the Change the Look wizard.  If you rush any of the steps and click a next button prematurely before the preview page loads fully this can cause SharePoint to throw a wobbly.  If this happen just sigh and try again, this time with a little more patience.

Next Up

Creating a custom Composed Look is a huge step forward as it means that we can potentially offer site owners a range of corporate Composed Looks which might be tweaked for different spaces.  For example, I often choose a different primary colour for the portal and team sites, community sites and project workspaces.  I find that the use of colour really helps users to quickly understand where they are in the system.

Unfortunately, you can’t do everything you might want to with Composed Looks alone and in the next article in this series I will look at your new best friend the Alternate CSS file.