Why did this happen?

A few months ago, I explained how WSS deploys and retracts solution packages. In that explanation, I explored how the WSS run-time checks the solution manifest of the solution package (WSP file) and removes any files, features, and other solution components from the file system and content databases. This includes both the SPTHEMES.XML and OOB_SPTHEMES.XML files that were specified in the solution manifest of the theme package. Take a look at the bold-ed lines in the manifest excerpt below:

<?xml version=“1.0” encoding=“utf-8“ ?>
<Solution xmlns=“http://schemas.microsoft.com/sharepoint/”
          DeploymentServerType=“ApplicationServer”
          ResetWebServer=“TRUE”
          SolutionId=“D250636F-0A26-4019-8425-A5232D592C10“>
 <TemplateFiles>
  <TemplateFile Location=“LAYOUTS/1033/SPTHEMES.XML“/>
  <TemplateFile Location=“LAYOUTS/1033/OOB_SPTHEMES.XML“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/MYNEWTHEME.INF“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/mossExtension.css“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/theme.css“/>
  <!–Additional images and icons (gif, jpg, png files)
       can be added here using <TemplateFile> elements –>
 </TemplateFiles>
</Solution>

So when I retracted my theme solution, both the SPTHEMES.XML and OOB_SPTHEMES.XMLfiles were deleted from the file system and the original SPTHEMES.XML was not restored. Luckly, I had a copy of the themes WSP file from which I extracted the OOB_SPTHEMES.XML file and manually copied back to the 12/LAYOUTS/1033 directory. This resolved the odd theme behavior that my environment was experiencing.

Lesson learned?

If you are going to modify files in the SharePoint HIVE in an unsupported manner (such as was the case with the theme package), make sure you have a back up of the original file system files. Like we did with the OOB_SPTHEMES.XML file and make a note on additional steps, aside from solution retraction and deletion, that need to be taken to restore the file system to it’s original state. This means don’t just test the deployment, but also the retraction process before using this type of solution in a production environment.

Packaging SharePoint Themes

SharePoint themes are an interesting feature in SharePoint that allow site owners to quickly change the appearance of colors, icons, and images buy injecting an additional style sheet that overrides some of the existing styles found in the core.css style sheet. Creating a custom theme involves a couple of simple steps:

1. Creating a new folder in the 12/TEMPLATE/THEMES directory
2. Creating a theme.css file to override the out of the box styles defined in the core.css style sheet in the directory created in the previous step
3. Creating a mossExtension.css file which is appended to theme.css file to create a the actual style sheet that is actually used when viewing pages in the SharePoint site
4. Creating a <directory name>.inf file that contains some basic setup information about the theme
5. Adding all the images and icons referenced in the custom style sheets in step 2 and 3 to the new directory created in step 1
6. Modifying the SPTHEMES.XML file in the 12/TEMPLATE/LAYOUTS/1033 directory

A word of caution! Modifying the SPTHEMES.XML is not a recommended customization practice since this file maybe overwritten by future SharePoint service packs.

It’s easy enough to take an existing theme directory out of the 12/TEMPLATE/THEMES directory, make a copy of it, rename the directory, rename the INF file, edit the INF, theme.css, and mossExtension.css file to create a new theme. However, this approach is not practical in a production SharePoint farm. The practical approach is to use the WSS solution framework to create our own solution package to deploy the custom theme. For more information, I covered the creation of solution packages (WSP files) in detail in a previous post. Let’s take a quick look at the solution manifest for our theme package:

<?xml version=“1.0” encoding=“utf-8“ ?>
<Solution xmlns=“http://schemas.microsoft.com/sharepoint/”
          DeploymentServerType=“ApplicationServer”
          ResetWebServer=“TRUE”
          SolutionId=“D250636F-0A26-4019-8425-A5232D592C10“>
 <TemplateFiles>
  <TemplateFile Location=“LAYOUTS/1033/SPTHEMES.XML“/>
  <TemplateFile Location=“LAYOUTS/1033/OOB_SPTHEMES.XML“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/MYNEWTHEME.INF“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/mossExtension.css“/>
  <TemplateFile Location=“THEMES/MYNEWTHEME/theme.css“/>
  <!– Additional images and icons (gif, jpg, png files)
       can be added here using <TemplateFile> elements –>
 </TemplateFiles>
</Solution>

The solution includes a modified SPTHEMES.XML file where we added an element to define the custom theme named MYNEWTHEME. You can also see that we included a copy of the original SPTHEMES.XML file and renamed it OOB_SPTHEMES.XML since it’s always a good idea to have back up copy of the file we modified. Finally, you see the critical MYNEWTHEME.INF, mossExtension.css, and theme.css files. For the sake of brevity, additional image and icon files were excluded on purpose.

The WSP file was then generated using a directive file and the MAKECAB utility (directive files and the MAKECAB utility are also covered in my previous post) and deployed using the STSADM utility.

Packaging Branding

There are many different SharePoint Products and Technologies branding techniques. In the presentation, I demonstrated how quickly and easily we can use a solution to deploy custom style sheets, master pages, and page layouts and how we can use a feature receiver to programmatically apply the branding using the object model. Again for the sake of brevity, the demonstration illustrated how a master page can be deployed and applied. However, a similar approach can be used for page layouts, cascading style sheets, XSL files, image files, and any other branding components and artifacts.

The solution manifest to accomplish our task is relatively basic. Here it is:

<?xml version=“1.0” encoding=“utf-8“ ?>
<Solution xmlns=“http://schemas.microsoft.com/sharepoint/”
          DeploymentServerType=“WebFrontEnd”
          SolutionId=“A250636F-0A26-4019-8425-A5232D592C10“>
 <FeatureManifests>
  <FeatureManifest Location=“MyBranding\feature.xml“/>
 </FeatureManifests>
 <Assemblies>
  <Assembly DeploymentTarget=“GlobalAssemblyCache”
            Location=“CustomThemeFeature.dll“ />
  </Assemblies>
</Solution>

As you can see, the solution manifest only includes a feature manifest and an assembly that will be deployed to the GAC. The assembly only contains a custom feature receiver class that programatically applies the custom master page and the custom theme discussed earlier in this post.

Let’s take a look at the feature manifest:

<Feature xmlns=“http://schemas.microsoft.com/sharepoint/”
         Id=“D250636F-0A26-4019-8425-A5232D592C11”
         Description=“My custom master page feature.”
         Title=“My Custom Branding”
         ReceiverAssembly=“CustomThemeFeature, Version=1.0.0.0, PublicKeyToken=1ff5d2fddf39f61b, Culture=neutral”
         ReceiverClass=“CustomThemeFeature.FeatureReceiver”
         Scope=“Web“>
 <ElementManifests>
  <ElementManifest Location=“elements.xml“/>
  <ElementFile Location=“mycustom.master“/>
 </ElementManifests>
</Feature>

The feature manifest is also pretty simple as it includes one element manifest and one element file. The element file is the custom master page that was created. The element manifest will declare a module that will be used to populate the master page gallery with the custom master page. An important thing to notice here is the ReceiverAssembly and ReceiverClass attributes in the Feature element. These attributes tell the WSS solution framework to use a custom assembly and feature receiver class to handle the feature related events. We will look at the feature receiver class in a bit. First lets take a look the element manifest:

<Elements xmlns=“http://schemas.microsoft.com/sharepoint/“>
 <Module Name=“MasterPages“
         List=“116”
         Url=“_catalogs/masterpage“>
  <File Url=“mycustom.master“
        Type=“GhostableInLibrary“ />
 </Module>
</Elements>

The element manifest is simploy responsible for populating the master page gallery with the custom master page. If our solution and feature also had custom page layouts, those can be added to the master page gallery by adding File child elements to the Module element. Additionally, we could add more modules to populate the style library with custom style sheets and/or XSL files or add other media files to other SharePoint libraries.

Finally let’s take a look at the custom feature receiver class:

using Microsoft.SharePoint;

namespace CustomThemeFeature {
 public class FeatureReceiver: SPFeatureReceiver {
  public override void FeatureActivated(SPFeatureReceiverProperties properties) {
   SPWeb site = (SPWeb)properties.Feature.Parent;
   site.MasterUrl = “/_catalogs/masterpage/mycustom.master”;
   site.CustomMasterUrl = “/_catalogs/masterpage/mycustom.master”;
   site.ApplyTheme(“MYNEWTHEME”);
   site.Update();
  }
  public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {}
  public override void FeatureInstalled(SPFeatureReceiverProperties properties) {}
  public override void FeatureUninstalling(SPFeatureReceiverProperties properties) {}
 }
}

The class simply takes advantage of the feature activated event and to set the values of the master pages and apply a theme to the SPWeb object where the feature is activated.

Similar to the custom theme discussed earlier in this post, a WSP solution file was created using a directive file and the MAKECAB utility. The solution was then deployed with the STSADM utility. The feature was installed with the STSADM utility as well.