Composed Looks in SharePoint 2013, MatchPoint 4 and MatchPoint Snow

Date: 03. Oct 2014

Since version 2013 SharePoint ships with a feature named composed looks. This enables site admins to easily style a site without writing a single line of CSS. The condition is that the solution is implemented to work with composed looks.

This blog post will explain the concept of composed looks and how they are implemented. It might not cover every single detail, but instead serve as a good starting point addressing all the different topics around this subject.

Introduction

Lots of companies have their own corporate design guidelines, that define the colors, the fonts and the icons which can (or maybe must?) be used on magazines, brochures and of course in corporate IT systems. SharePoint has its well-known white/blueish out-of-the-box look. This might not match the design standards defined within an enterprise. To enable customers to easily change the appearance of SharePoint without fiddling with the actual solution, Microsoft has introduced the concept of composed looks.

The printscreens below of MatchPoint Snow show two different composed looks in action. The first one is the out-of-the-box MatchPoint Snow look, the other one is a composed look created with a couple of clicks (yes, I know it's not a beauty, but you get the idea ;)).

The classic MatchPoint Snow look...
Figure 1: The classic MatchPoint Snow look...
An extremely nice MatchPoint Snow look in frog-green...
Figure 2: An extremely nice MatchPoint Snow look in frog-green...

From a technical point of view, a composed look basically is a list item in the composed look gallery (/___catalogs/design) which specifies the different components of a composed look. We will have a detailed look at these components later in this post. For the moment it’s important to know that the main components are a master page (specifying the structure of the page), an .spcolor file (specifying the colors) and an .spfont file (specifying the fonts).

The site admin can choose Site settings / Change the look and select an item from the composed look gallery, which is then applied to the current site. He even has the possibility, to combine different elements to create his own composed look.

You might ask yourself, how all of this works, for example how SharePoint knows what to do with the above elements during the application of a composed look. Good question! It all starts with CSS...

CSS Annotations

Normally the way a page looks is defined within a CSS file. This means that we define the colors and the fonts we would like to use on a web page in such a style sheet, which is applied to the HTML by the browser while the page is being rendered on the client. As we have heard before, when working with composed looks, these colors and fonts are each specified in their own file. The question is, how are these elements added to the CSS file which is finally sent to the client and which defines the look of a page? The answer is. With the help of "Annotations" that are added to the original CSS file.

An annotation is a comment that is added to a line in the CSS file before the actual CSS statement:

  css-selector
  {
    /* [Annotation] */ css-statement: value;
  }

Then annotation tells the SharePoint Theming Engine (by the way, this is the guy who does all the work for us) which replacement, e.g. which color or font, to use.

There a four annotations available. We will have a guick look at them and see some examples to understand, what is going on. For more details you can visit MSDN.aspx).

ReplaceColor

This annotation can be used in CSS properties defining a color. The color slots used here need to be defined within the .spcolor file. There are additional parameters like opacity, themeShade and themeTint. You can find more details on MSDN.aspx).

Example: The following annotation defines that the element with the id sideNavBox shall use the DisabledBackground slot:

  #sideNavBox
  {
    /* [ReplaceColor(themeColor:"DisabledBackground")] */ background-color: #EDEEF2;
  }

You might ask if it actually matters, which color you use in your CSS file, as it is replaced anyway? That is true, but it is only replaced, if a theme is actually applied to a site. If there isn't, then the normal value (in above case #EDEEF2) is used. This counts for all the other annotations as well.

ReplaceFont

This annotation can be used with font and font-family properties.

Example: Following annotation defines that for all h1 elements, the title font from the .spfont file shall be used:

h1
{
    /* [ReplaceFont(themeFont:"title")] */ font-family: "Segoe UI";
}

RecolorImage

The RecolorImage annotation is used to adjust images (e.g. icons) to the current look.

There are three different RecolorImage methods available when working with the SharePoint Theming Engine. According to a presentation by Jonathan Keslin, this is what they do:

  • Original image:
    Original Image
  • Tinting: "Maintain the luminance and alpha channels of each pixel, but replace the hue and saturation."
    Tinting
  • Filling: "For each pixel, average the red, blue, and green channels between the old and new colors, while maintaining the alpha channel."
    Filling
  • Blending: "Set each pixel to the new color, but maintain the original alpha channel."
    Blending

There are other properties like includeRectangle available, please see MSDN for more details.

Example: Following annotation defines that the background-image of the element with id logo-container shall be colored using the HeaderSiteTitle slot:

#logo-container
{
    /* [RecolorImage(themeColor:"HeaderSiteTitle",method:"Filling",hashOverride:"MyLogoKey")] */ background-image: url("/_layouts/15/images/MySolution/Images/Logo.png");
}

ReplaceBGImage

According to MSDN, "The ReplaceBGImage annotation replaces the background image in the CSS file with the themed background image. It can be used with the background and background-image CSS properties."

After having looked at the different annotations, we now know how to write themable CSS. But we still don't know, where to actually put it. "In a CSS file" you might say. Well, that's true, but it can't just be any CSS file in any location...

Themable CSS files

All themable CSS files, i.e. CSS files that contain annotations, need to be stored in a specific folder in the SharePoint-hive:

C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\STYLES\Themable

Once a composed look is applied to a site, all CSS files in this folder will be processed. This means, they will be picked up by the Theming Engine, all annotations will be replaced based on the elements of the composed look (.spcolor and .spfont-files as well as the images) and the generated CSS will be stored in the Theme gallery of the web. These automatically generated, themed CSS files will be loaded by SharePoint with all pages of the site.

Themable Images

As mentioned, a very nice feature of the SharePoint Theming Engine is the possibility to recolor images based on the composed look. This can be done by using the RecolorImage-annotation within a CSS file. But how can you make an image themable, that is not described within a CSS file (i.e. is not a background-image)?

As the Theming Engine only picks up the CSS files from the Themable folder, the images somehow need to be linked from within such a CSS file. This can be done by adding "dummy entries" to the CSS file. These dummy entries have the single purpose of defining an appropriate RecolorImage-annotation in a themable CSS file. They do not need to be referenced anywhere on the page. A possible dummy entry could be:

.my-dummy-class
{
    /* [RecolorImage(themeColor:"HeaderSiteTitle",method:"Filling",hashOverride:"/_layouts/15/images/MySolution/Images/MyImage.png")] */ background-image: url("/_layouts/15/images/MySolution/Images/MyImage.png");
}

In case you only use a themed image from within the CSS file, you do not need to bother where the themed image is physically stored, i.e. what it’s URL is, as all of this is handled by the engine and stored in the resulting CSS.

However if you would like to reference the image from within a custom control, an .aspx-page or let’s say a MatchPoint transformer (PatternTransformer, UserControlTransformer, etc.), you need to resolve its URL. Thankfully SharePoint provides a method on the SPUtility class which handles this for you. The method is named GetThemedImageUrl and has two parameters:

  • originalUrl: the URL to the image that needs to recolored.
  • themeKey: the key that is used to generate a hash which is part of themed image file name. The themeKey corresponds to the hashOverride defined in the CSS file.

Please note that this method always returns a value, even if the originalUrl points to a file which doesn’t exist.

Components of a Composed Look

We have clarified, how composed looks work and which elements are actually required to build one. We do not yet know however, how SharePoint is aware of which composed looks are available on a system and where and how the replacement values are actually defined.

Composed Look Item

A composed look item is regular list item that is added to the Composed looks gallery of an SPWeb. This item defines the composed looks that are available on the web. The composed look gallery has following required fields:

  • Title: To be honest, I do not know where this field is actually used, because as far as I can see, the Name field is used everywhere (see below)...
  • Name: This is the name of the composed look that is displayed to the user when browsing the composed looks
  • Master Page URL: This is the URL of the master page that should be applied to the site
  • Theme URL: This is the URL pointing to the color palette to be used with this composed look (.spcolor)

Even though the last two fields are actually not mandatory, a composed look item is not valid without these fields being set. If they have no value, or point to a non-existing file, they will not appear in the Change the look page.

The following fields are optional:

  • Image URL: This is the URL pointing to the background image
  • Font Scheme URL: This is the URL pointing to the font scheme file (.spfont). If this value is set and points to an inexistent file, then the item will not appear in the Change the look-page
  • Display Order: This defines the position of the composed look when browsing the available composed looks. The sort order is ascending

Master page

The master page defines the main structure of the page and doesn’t need any further description in this context.

Color Palette (.spcolor file)

The color palettes are stored per site collection in the Themes gallery (/__catalogs/theme/15) and contain the different color slots (i.e. colors) that will be used once a composed look is applied. So basically a color palette contains HTML colors mapped to ColorSlots.

For more details on all the available options within an .spcolor file, please refer to MSDN.aspx#color).

Font Scheme (.spfont file)

Similar to the color palette, the font scheme contains the fonts that will be replaced in the CSS file, once the composed look is applied.

For more details on all the options available within an .spfont file, please refer to MSDN.aspx#font).

Creating a Composed Look

When creating an own composed look, there are basically two steps you need to execute:

  1. Ensure that all the required resources are available on the site on which the composed look will be applied.
    In order for the composed look to be created, the referenced master page needs to be available within the current site (SPWeb) and the .spcolor and a potential .spfont file needs to be available within the site collection (SPSite). In case you are not referencing out-of-the-box files, you need to ensure they are somehow available at the mentioned scope. For example by activating a feature which deploys these resources.

    Resource Deployment Scope
    master page web
    spcolor site
    spfont site

  2. Ensure the item in the composed look gallery is created.
    This can be created by code (e.g. by feature receiver) or via a module which deploys the composed look item to the site.

If these pre-requisites are met, the composed look can be applied. This is either done programmatically (for example with a feature receiver) or manually by a site admin choosing Settings / Change the look.

Please note that from a code-point-of-view the composed look is basically an SPTheme that is applied to a specific SPWeb as well as the master page which is set on the web.

This can be achieved by following code:

public static void ApplyComposedLook(SPWeb web)
{
    // note that to programmatically apply a composed look
    // to a web, we need to set the master page on the web (step 1),
    // as well as apply the theme to the web (step 2)

    // step 1: set master page
    // the master page needs to available on the web
    // on which we are applying the composed look.
    web.MasterUrl = "urlToMasterPage";
    web.CustomMasterUrl = "urlToMasterPage";
    web.Update();

    // step 2: apply theme
    // the .spcolor and .spfont files need to available
    // on the site collection/root web (this might not be the web on 
    // which the composed look is currently being applied)
    SPWeb rootWeb = web.Site.RootWeb;
    SPFile spColor = rootWeb.GetFile("urlToSpColorFile");
    SPFile spFont = rootWeb.GetFile("urlToSpFontFile");

    SPTheme theme = SPTheme.Open("My Theme Name", spColor, spFont);
    theme.ApplyTo(web, true);
}

In case you are planning to use custom code when working with composed looks, don't forget to have a look at the other (static) methods on the SPTheme class, some of them might be of use for you.

Composed Looks in MatchPoint

In a MatchPoint provisioning configuration within the WebDefinition-node, composed looks can be defined.

If a composed look item with the defined name is found on the web being provisioned, then the existing look is applied, otherwise a new look with the specified properties is created.

Please pay attention to the scope at which the elements need to be deployed. You need to ensure the .spcolor- and _.spfont-_files as well as the master page are available at the desired scope.

Composed Looks in MatchPoint Snow

MatchPoint Snow provides its own composed look with its own master page. This is applied on all webs that are part of the application.

The .spcolor file provides a set of color slots which can be used within a themable CSS. In case there aren't enough slots or you want to define your own slots, you can do so. As sometimes it's difficult to find the appropriate slot (with a correct and speaking name) we are thinking about adding our own slots to be used in MatchPoint Snow. This would make it even easier to implement a composed look for MatchPoint Snow.

The icons used within MatchPoint Snow and within any Snowflakes (top navigation bar, contextual actions, welcome screen) are all themable and thus change their color once a different look is applied to a site.

This is achieved by creating a CSS file (named MatchPoint.Snow.Themable.Images.css) that is stored in the Themable folder in the hive and that contains dummy entries for all the mentioned icons. The MatchPoint Snow controls then use the MPSUtility.GetHtmlEncodedThemedImageUrl method that wraps the SPUtility.GetThemedImageUrl method.

The CSS file is updated every time a Snowflake configuration changes, as then a new themable image might be defined. This means, that as soon as a new icon is defined in a Snowflake configuration, the composed look needs to be reapplied in order for all themable images to be created on the applicable sites. This can be done either manually, by writing custom code or by using a CmdLet introduced with MatchPoint Snow 1.0.3 named Reapply-MPSComposedLook.

If you use the CmdLet and you specify a WebApp, all MatchPoint Snow relevant site collections and all their sub-sites will be processed. If you specify a Web, then only the specified site will be processed. In case you add the Recursive-flag, its sub-sites will be processed too.

Should you like to add some images that need to be themable too, you can add them to a Snowflake configuration (respectively to the MatchPointSnowConfiguration.xml). They will be added to the themable images CSS and consequently themed images will be created. You can use these images in your configurations, user controls, etc. by resolving the URL using the MPSUtility.GetHtmlEncodedThemedImageUrl method.

As an example we can reuse our dummy entry from above:

.my-dummy-class
{
    /* [RecolorImage(themeColor:"HeaderSiteTitle",method:"Filling",hashOverride:"/_layouts/15/images/MySolution/Images/MyImage.png")] */ background-image: url("/_layouts/15/images/MySolution/Images/MyImage.png");
}

If we want to get the URL of the themed image, for example to use it in a PatternTransformer, we can call the GetHtmlEncodedThemedImageUrl as follows:

MPSUtility.GetHtmlEncodedThemedImageUrl("/_layouts/15/images/MySolution/Images/MyImage.png");

This will then return something like:

/sites/mpsnow/_catalogs/theme/Themed/9F2DD4DA/MyImage-9F18774.themedpng?ctag=68

9F2DD4DA corresponds to unique name of the currently applied theme (see SPWeb.ThemedCssFolderUrl) and 9F18774 is the hash that is generated based on the hashOverride value from the CSS file.

Summary

Even though at first it might seem a bit intransparent and hard to understand, what is going on behind the scenes, composed looks actually is a great feature of SharePoint 2013. It enables you to easily change the appearance of a site. A cool feature is that even images can be adjusted accordingly. This is helpful for solutions like MatchPoint Snow, where the icons should match the general appearance of the page.

Please note that this blog post tries to give an overview over composed looks in general and explains how MatchPoint and MatchPoint Snow make use of this feature. In case you are interested and want to read something more detailed, you can check out the links below. By the way: Surprisingly enough, the MSDN links are actually really good... ;)

In case you have any questions, feedback or suggestions for MatchPoint or MatchPoint Snow, please feel free to contact us.

Further Reading and Sources

results matching ""

    No results matching ""