What’s a Composed Look? – Part 2
Composed Looks were introduced with SharePoint 2013 as an answer to the complexities and issues that surrounded the use of Themes within SharePoint 2010. Don’t get me wrong, I loved the idea of Themes and what they were meant to represent. However, implementing them was difficult for experienced SharePoint professionals, much less the average SharePoint end user. As a result, the Composed Looks that are available for SharePoint 2013 are much easier to implement for end users and should be considered as a staple to any custom branding effort. Using the right deployment and management techniques, a well-deployed Composed Look can streamline the application of a consistent look and feel across an organization. Hopefully, this post will help to understand how best to deploy a Composed Look along with your solution.
Composed Looks List
The Composed Look list is part of the Web Design Galleries for a site. The list contains items that define the individual Composed Looks that will be available for that site. As Lori mentioned in her blog post, the Composed Looks item within the gallery is made up of the following references. These components are simply referenced from within this list and the actual artifacts are stored within various catalogs within the local site or site collection. To quickly recap, they are as follows:
- Master Page URL – A reference to either a custom master page or an out of the box version. Keep in mind, for the Composed Look to appear visually in the Change the Look page, it is required that each custom master page has an accompanying .preview file with the exact same name.
- SPFont File – This file contains all the font definitions for the Composed Look.
- SPColor File – Like the SPFont, this file contains all the color variations for the Composed Look. Again, as mentioned in Lori’s post, a great tool for creating this file is the Microsoft SharePoint Color Palette Tool
- Background Image – The image that will cover the entire background of the page.
Where are they? Just click the link…
The Composed Looks list is referenced in different locations depending on the current state of the site and the site collection. Regardless of the physical location in your site collection, simply clicking the Site Settings -> Web Designer Galleries -> Composed Looks will take you to the right place. If you’re really interested, in non-publishing enabled sites, the Composed Looks list is located locally within the current site. For publishing-enabled sites, the Composed Looks list is referenced to the root web of the site collection. This allows for the inheritance of the Composed Look by every site within the site collection.
Deploying a Composed Look
Before we start applying Composed Looks on all of our sites, the first thing that we need to do is get the necessary files and references into our site. Like most all custom development that I do, the best way to get these files out there is through the use of features. Even still, the choice must be made to either deploy declaratively or programmatically. Using the declarative approach, you would just have to create a couple of SharePoint Modules within your solution that would either deploy files to specific libraries or that would create items within the lists. Unfortunately, there are some limitations regarding the pure declarative approach that I’d rather not deal with so all of my deployments are done programmatically. These limitations are directly related to the master page URLs that are used within the Composed Look item definition. With the declarative approach, these master page URLs would have to be static which doesn’t fit a majority of my scenarios.
To handle the programmatic deployments, you would just have your file definitions within Modules in your solution. These modules would take care of getting the physical files onto the server. For the Composed Look definition, I create that item in code. This allows me to dynamically adjust the master page URL which is part of the Composed Look item.
Change the Look Using the UI
To apply the Composed Look through the UI, navigate to “Site Settings -> Change the Look”, select the new look to apply, and then click “Try it out”. After a quick confirmation, SharePoint will churn for a few (more on this later) then, boom goes the dynamite, the new look and feel is applied. Pretty straightforward, yes?
Figure 1: Change the Look
Applying a Composed Look Programmatically
Applying a Composed Look to a site programmatically is still very similar to how it was done with Themes in SharePoint 2010. In SharePoint 2013, you are basically applying the colors, fonts, and background image for your Composed Look. To apply a Composed Look programmatically, insert the following code in a feature or event receiver for a web.
// Parameters: (Color Palette, Font Scheme, Background Image, Share Generated)
web.ApplyTheme(colorPaletteUrl, spFontUrl, bgImageUrl, false);
Note in the code above that there's no mention of the master page when applying the Composed Look. In fact, the master page defined within the Composed Look item does not come into play at all. When applying the look programmatically, the master page is applied separately, which has great benefits.
As mentioned before, the Composed Look list is just for defining the Composed Look templates and used in the UI for organizing the Changing the Look page. Looking into the Composed Look list closer, there are a number of default ‘Looks’ included as part of SharePoint. Additionally, there's an item named Current that is there to reflect the current state of the Composed Look selection. Oddly enough, manually editing the Current item's values in SharePoint does nothing to the actual look and feel of the site. So basically, the Current item is nothing but a reflection of current Composed Look state. When a new ‘Look’ is activated, one of the things that SharePoint does is update this ‘Current’ item’s values. If you're updating the Composed Look programmatically, you will need to replicate this functionality manually.
Back to that SharePoint Churning
So, what exactly is happening when a new Composed Look is applied to a site? Well, since the items with the Composed Look list are just templates of what a Composed Look should be made, SharePoint takes the time to build out a full Composed Look based on this template each time a Composed Look is created for a site. Within the generation of the theme files, SharePoint will create a custom set of CSS files, images, and CSS sprites that are color coded according to the SPColor definition. Pretty nifty, yes? Of course, SharePoint doesn't do this out in the open, it creates all the theme artifacts and places them in a unique folder within the _catalogs list. For example, my current Composed Look was generated at:
Figure 2: SharePoint Generated Theme File Location
One simple way that you can see where your Composed Look theme files are being stored is by checking a quick source of a page within your site. Search for the _catalogs/theme URL in the HTML source code of your page and it should lead you right to some component of the theme. You can either navigate to it in your browser or within SharePoint Designer.
Try it Out…
Now that we know what happens behind the scenes when a Composed Look is changed, let's unpack that a little and break down what needs to happen when you apply a Composed Look programmatically:
- Add the Composed Look Files - Add the .spcolor, .spfont, .preview, and background image to their respective locations in the site. This can be done either programmatically or declaratively.
- Add the Master Page – Add a custom master page, if desired, to the Master Page Gallery. Again, this can be done programmatically or declaratively.
- Create a new Composed Look item – In the Composed Look Gallery, create a new item that references your .spcolor, .spfont, .masterpage, image URL, and the order in which the Composed Look should be displayed in the Change the Look page.
- Apply the Master Page – At this point, it’s safe to apply your master page for the site.
- Apply the Composed Look (aka. Theme) – You want to apply the theme to your site last. Due to the SharePoint churning that takes place, if you try to apply your theme, and then attempt to make changes to the local web, such as changing the master page, you risk getting an error that you’re attempting to make a change to a site that is currently being changed. You can make modifications to items within the site in lists or libraries, but you will be unable to make changes to properties related to the SPWeb object.
- Update the Current Composed Look Item – In the Composed Look gallery, you should update the ‘Current’ item to all the values from your custom Composed Look item. This will have the ‘Current’ item display the proper look if a user navigates to the Change the Look page.
Executing the application of your Composed Look in the order above ensures that it will be applied correctly and use a combination of your custom ‘Look’ along with your custom master page. About that master page, did you take note that in step 4 above, the master page is provisioned to the site independently of the Composed Look? One way that I’ve used this to my advantage is creating separate hidden features to deploy different versions of a Master page based on the current site template but still reusing the same Composed Look for all sites. Yes, convenient indeed.
Yes, Keep It
SharePoint 2013 Composed Looks are a nice step forward from the use of Themes in SharePoint 2010. Not only do they allow for more custom and consistent application of a look and feel on a site, they’re actually user friendly enough to where they might get used by some of those more advanced end users out there.
The sample scripts are not supported under any Summit 7 Systems standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Summit 7 Systems further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Summit 7 Systems, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Summit 7 Systems has been advised of the possibility of such damages.