Monday, October 22, 2012

Leveraging Themable CSS in SharePoint 2010

By Daniel Galant -  EPC Group's Director of Solutions and Services

There have been many changes and improvements with the release of SharePoint Server 2010 and how it implements a number of features and services. One of those features is the manner in which Themes are created, applied and customized in your SharePoint deployment. I came across a number of articles and posts dealing with how to create themes using Office applications, such as PowerPoint and Word. However, there were not many that dealt with the customization of your CSS through the use of the Theme Comments that SharePoint will leverage in order to apply your theme scheme to your customized Cascading Style Sheets (CSS).

This article deals with that very topic as I’ll endeavor to guide you through how to create and apply theme comments to your custom CSS so you can indeed leverage Themes in SharePoint 2010. To start off, let’s simply take a look at attaching some custom CSS to a Master Page in order to apply our own styles to the SharePoint site.

While there are several methods for attaching a custom style sheet to your Master Page, best practice dictates using the link in the of your Master Page. With SharePoint 2010 now supporting the After property, you can ensure that your custom CSS is applied after SharePoint’s core styles.

Master with attached CSS

Now we’ll also add a custom header image to the page so that we’ll be able to leverage the RecolorImage token as well later in the article.

Added Header Image

Let’s take a look at the CSS itself.

Original custom CSS

Notice the body #s4-ribbonrow setting the background-color as well as the TopHeader class pointing to our custom image. There are no theme comments added to the CSS yet, so the ribbon row color won’t be affected when you apply a theme to this site and no changes will be made to the header. Setting the new master page as our default master for the site will now render the site as in the image below.

Site Settings page with new master applied

If you then apply a theme to the site what happens? Let’s use the Vantage theme and see what the effect is.

Vantage applied no comments

Notice the changes to the TopLink, QuickLaunch and settings page, but the ribbon row and custom header remained the same. In order for these elements to also be affected by applying a theme, you must add the appropriate theme comments to your custom CSS.

In order to leverage theme comments when they are added to your custom CSS, you must first be sure to place your CSS files into the proper location within your site so that SharePoint will actually read them and apply the settings to your pages. For theme comments to be read by SharePoint when you apply a theme, you need to place your custom CSS files in a folder called Themable that you create in the Style Library of your site. This folder does not exist out of the box, nor will it be created magically for you when using custom CSS and theming.

The Style Library before:

Style Library before

The Style Library after creating the Themable folder:

Style Library after

Once you have created the Themable folder, import your custom CSS files into this location and be sure that your registration links are pointing to these files and not somewhere else in your site. Now to make your styles leverage themes when applied, you need to add the theme comments to your CSS.

There are three different tokens that can be leveraged by your CSS, ReplaceFont, ReplaceColor and RecolorImage. I’m not going to go into depth on the effects or properties of these elements here but ReplaceFont will let you change certain font elements to use one of the two available theme fonts, ReplaceColor allows you to substitute any of the 12 theme colors into your styles and RecolorImage will allow you to use any of the 12 theme colors in your images. We’ll see more on this later.

Right now we are going to add a comment so that the ribbon row will be effected when you apply a theme to the site. Since we are trying to leverage the theme’s colors to apply to the ribbon row, we’ll use the ReplaceColor token. The syntax for the comment is as follows:

/* [ReplaceColor(themeColor:”color”, property:”value”)] */

In the above comment, color represents one of the 12 theme color choices that you want to use to replace the color property of your style such as Dark1 or Accent5. For property you can use either themeShade or themeTint to darken or lighten (respectively) your color choice with a value between 0.0 and 1.0. Be aware that if you are not going to use the property:”value” option, do not include the comma in your comment. Doing so will cause SharePoint to skip your comment and you’ll be trying to figure out why your choices are not being applied.

The image below shows the theme comment added to the custom CSS file.

ReplaceColor comment added

This line simply tells SharePoint to replace the background-color #abc830 with the themes Dark2 color. You’ll now save your modified CSS and try applying a theme. Once again I used the Vantage theme. The image below shows you the 12 colors defined by this theme.

Vantage Color scheme

The result of applying this theme at this time is the following.

Vantage applied CSS not saved

Alright. So what happened to the ribbon row and the custom header we applied? Here you see the first of several issues you can run into when trying to use theme comments with your custom CSS. The site that I am working with in this example happens to be a publishing site and so the Style Library is under content approval. This means that any changes made to its files need to be published as a major version and approved before they can be properly used. Now while SharePoint seems to read and apply changes made to the CSS styles without having to go through all this, it does not process your theme comments until you have an approved major version of the file. As a matter of fact, as can be seen here, it seems to completely disregard the style altogether.

After publishing the file as a major version and approving it let’s apply the theme again. Theme comments are only processed at the time the theme is actually applied to the site. Therefore, any time you make a change to your file you will need to re-apply your theme to see the effect.

Theme applied and published

Here you can see that the ribbon row has now picked up the Dark 2 color of your theme, but the header is still the original green color. To change this you need to use the RecolorImage token in the header’s style declaration. The syntax for the RecolorImage token is as follows:

/* [RecolorImage(themeColor:”color”, method:”value”)] */

Once again color is the theme color you want to use with your image. Value can have one of three values, Tinting, Blending, or Filing. Tinting uses your theme color for the image colors, Blending mixes your theme color with the original color of the image and Filing completely fills the image shape with your selected color. In the image below you’ll note that I am going to recolor the image using the Accent 2 color and tint the image.

RecolorImage comment

Again you need to publish and approve the CSS file after making the change and then reapply the Vantage theme. The result is as follows:

Vantage applied tinting

If you choose to use the Blending option it would look like this:

Vantage applied Blending

One point I would like to make here, in my experience the value is case sensitive, Blending will work but blending will not.

So you can see that you have several options when it comes to themes and your custom CSS. Take some time and play around with the choices provided by using theme comments and see what effects you can come up with for your sites.

I hope this article helps you avoid some of the issues I ran into and gets you smoothly on the theme.

- Daniel Galant