Deploying and activating SharePoint 2013 themes using Visual Studio

I won’t deny it… I never was a big fan of theming SharePoint sites. In MOSS this was implemented absolutely awful and the SharePoint 2010 *slash* PowerPoint approach didn’t do it for me either. Glad to see both annoyances are gone now. Let’s take a look at how SharePoint 2013 changes the game and what we need to do to change its looks!

Themes in SharePoint 2013 consist of two things:

• A theme, as in colorscheme
• Optionally a fontscheme

Furthermore, a theme is part of what is called a “Composed Look”. These Composed Looks are essentially what is available to you when you click the “Change the look” under Site Settings.

Besides a color- and fontscheme the following items are part of a composed look:

• A master page, this can also be a custom master page
• Optionally a background image

The solution

Things I like to have changed in my custom look:

1. Some UI colors for specific elements, in this case the SuiteBar at the very top
2. Some of the fonts used
3. Add a custom background image

In the end, it should look like this:

I like the default look, but also want to include a background image. This default look is called the Office Look and it doesn’t use any specific font. For fonts, I favour the one used for “Sea Monster”. BTW, don’t you love that theme’s name? If you want to take a look at all the different OOTB themes, take a peek under “Change the look” in your site settings.

Most of these tasks can be done through the UI by uploading the artifacts manually. In this case (and almost any case) I like to use Visual Studio to ensure the correct deployment of these files. Theming, at least for me, is usually done for on premise or dedicated SharePoint solutions, so I don’t mind creating Farm solutions for this task.

Since the schema is pretty important, it is best to start with some of the OOTB parts:

1. First we copy the color pallette used by the Office Look, since we like most of this OOTB theme
2. Then we copy the fonts used by Sea Monster
3. And finally grab your custom background logo. Make sure you keep the size of this file under 150KB!

You can download the color palette and fontscheme from the links in the “Composed Looks” settings section.

To set this up using Visual Studio 2012, we create a new Solution and make it a Farm Solution.

Next, we add a mapped “Images” folder for our background image.

Then, we add a module (or two if you are including a custom master page) to deploy our Theme and Fontscheme. Add the artifacts and rename them appropiately (companylook-palette001.spcolor and companylook-fontscheme001.font in my case)
Modify the elements.xml so we deploy to the correct catalogs. Don’t forget to add GhostableInLibrary attribute!

This table lists the possible deployment options for our artifacts:

Note: The attribute Type=”GhostableInLibrary” indicates that the item is added to the content database. The Url attribute of the module specifies where to store the file in the content database.

This is what your solution structure should look like right now:

To create a “Composed Look” we actually need to insert a listitem in the “Composed Looks” list. To do this we use a Feature Receiver that adds the list item with the correct field values:

Add a feature receiver to our solution’s feature. Set the scope to “Web”

Then add the following code to insert our custom list item:

public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            var web = properties.Feature.Parent as SPWeb;
            var list = web.GetList(string.Format("{0}/_catalogs/design",web.ServerRelativeUrl));
            var item = list.AddItem();

            item["Title"] = "CompanyLook";
            item["Name"] = "CompanyLook";
            item["DisplayOrder"] = 1;

            var masterPageUrl = new SPFieldUrlValue();
            masterPageUrl.Url = masterPageUrl.Description = "/sites/dev/_catalogs/masterpage/seattle.master";
            item["MasterPageUrl"] = masterPageUrl;

            var themeUrl = new SPFieldUrlValue();
            themeUrl.Url = themeUrl.Description = "/sites/dev/_catalogs/theme/15/companylook-palette001.spcolor";
            item["ThemeUrl"] = themeUrl;

            var fontSchemeUrl = new SPFieldUrlValue();
            fontSchemeUrl.Url = fontSchemeUrl.Description = "/sites/dev/_catalogs/theme/15/companylook-fontscheme001.spfont";
            item["FontSchemeUrl"] = fontSchemeUrl;

            var imageUrl = new SPFieldUrlValue();
            imageUrl.Url = imageUrl.Description = "/_layouts/15/images/CompanyLook/Background.png";
            item["ImageUrl"] = imageUrl;

            item.Update();
        }

Remember to set the DisplayOrder, otherwise you will get the default value of 100 and your look will be hidden behind the “Grey” look.

This takes care of the deployment of our custom theme. Site owners can now activate it using the site settings, but you can also do it using code behind with another feature receiver.

Add a feature and feature receiver to our solution. Again, set the scope to “Web”. Add the following code to activate the custom look:

 public override void FeatureActivated(SPFeatureReceiverProperties properties)
        {
            var web = properties.Feature.Parent as SPWeb;
            var list = web.GetList(string.Format("{0}/_catalogs/design", web.ServerRelativeUrl));

            SPQuery query = new SPQuery();
            query.ViewFields = "<FieldRef Name='ThemeUrl' /><FieldRef Name='ImageUrl' /><FieldRef Name='FontSchemeUrl' />";
            query.Query = "<Where><Eq><FieldRef Name='Name' /><Value Type='Text'>CompanyLook</Value></Eq></Where>";

            SPListItemCollection listItems = list.GetItems(query);

            if (listItems.Count >= 1)
            {
                var theme = new SPFieldUrlValue(listItems[0]["ThemeUrl"].ToString());
                var font = new SPFieldUrlValue(listItems[0]["FontSchemeUrl"].ToString());
                var image = new SPFieldUrlValue(listItems[0]["ImageUrl"].ToString());

                if (theme != null && font != null && image != null)
                {
                    // In production code, make sure the files exist before applying the theme!
                    var themeUrl = (new Uri(theme.Url)).AbsolutePath;
                    var fontSchemeUrl = (new Uri(font.Url)).AbsolutePath;
                    var imageUrl = (new Uri(image.Url)).AbsolutePath;

                    web.ApplyTheme(themeUrl, fontSchemeUrl, imageUrl, true);
                }
            }
        }

That’s it! You can download the complete Visual Studio 2012 solution here.