Solutionizing .NET

Love them or hate them, SharePoint themes do have their uses in some approaches to branding. As Dan Lewis recently posted, the process to create a theme is pretty simple, but there’s one step that makes me cringe: edit SPTHEMES.XML. I’m not aware of any out-of-box mechanism to facilitate this change, so I figured it might be worthwhile to build one.

In researching the idea, I found this post by Rick Kierner. He’s on the right track, but his solution only deploys the theme to the local server and a web-scoped feature isn’t really appropriate for a server-wide change. Ultimately I came up with the following solution, which should be easier to maintain and is perhaps a bit more SharePointy.

The Feature

First, we create a farm-scoped feature with a single <ElementFile /> node:

<Feature
  Id="E2F8D046-607D-4BB6-93CC-2C04CF04099E"
  Title="SPHOLS Themes"
  Description="Installs SPHOLS and SPHOLSX themes on farm."
  Version="1.0.0.0"
  Scope="Farm"
  ReceiverAssembly="MyBranding, ..."
  ReceiverClass="MyBranding.MyThemesFeatureReceiver"
  xmlns="http://schemas.microsoft.com/sharepoint/">
  <ElementManifests>
    <ElementFile Location="SPTHEMES.XML" />
  </ElementManifests>
</Feature>

Then we create our own SPTHEMES.XML with the theme(s) we would like to add, saved in the same folder as feature.xml.

<?xml version="1.0" encoding="utf-8"?>
<SPThemes xmlns="http://tempuri.org/SPThemes.xsd">
  <Templates>
    <TemplateID>SPHOLS</TemplateID>
    <DisplayName>SharePoint Hands-On Labs</DisplayName>
    <Description>A glorious theme created for the SharePoint Hands-On Labs.</Description>
    <Thumbnail>images/SPHOLS/thSPHOLS.gif</Thumbnail>
    <Preview>images/SPHOLS/thSPHOLS.gif</Preview>
  </Templates>
  <Templates>
    <TemplateID>SPHOLSX</TemplateID>
    <DisplayName>SharePoint Hands-On Labs X</DisplayName>
    <Description>An XTRA glorious theme created for the SharePoint Hands-On Labs.</Description>
    <Thumbnail>images/SPHOLS/thSPHOLS.gif</Thumbnail>
    <Preview>images/SPHOLS/thSPHOLS.gif</Preview>
  </Templates>
</SPThemes>

And finally, our feature receiver:

namespace MyBranding {
  public class MyThemesFeatureReceiver : SPFeatureReceiver {
    private const string THEMES_FILE = "SPTHEMES.XML";

    public override void FeatureActivated(SPFeatureReceiverProperties properties) {
      if (properties == null)
        throw new ArgumentNullException("properties");
      FeatureThemesJob.InstallThemes(properties.Definition, THEMES_FILE);
    }

    public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {
      if (properties == null)
        throw new ArgumentNullException("properties");
      FeatureThemesJob.DeleteThemes(properties.Definition, THEMES_FILE);
    }

    public override void FeatureInstalled(SPFeatureReceiverProperties properties) { }
    public override void FeatureUninstalling(SPFeatureReceiverProperties properties) { }
  }
}

That’s it. When the feature is activated, the contents of the feature’s “themes file” are merged into the farm servers’ SPTHEMES.XML. While deactivating, those same themes will be deleted. The heavy lifting is handled by a reusable custom timer job.

FeatureThemesJob

Our custom job begins with a few persisted fields and constructors:

using System;
using System.Diagnostics;
using System.IO;
using System.Xml;
using System.Xml.XPath;
using Microsoft.SharePoint;
using Microsoft.SharePoint.Administration;
using Microsoft.SharePoint.Utilities;

namespace MyBranding {
  public class FeatureThemesJob : SPJobDefinition {
    [Persisted]
    private Guid _featureID = Guid.Empty;
    [Persisted]
    private string _themesFile = null;
    [Persisted]
    private bool _delete = false;

    public FeatureThemesJob() : base() { }

    public FeatureThemesJob(SPService service, Guid featureID, string themesFile, bool delete)
      : base("Feature Themes", service, null, SPJobLockType.None) {
      _featureID = featureID;
      _themesFile = themesFile;
      _delete = delete;

      Title = string.Format("{0} Themes for Feature {1}",
          (delete ? "Delete" : "Install"), featureID);
    }

The default constructor is required for internal use and our real constructor saves the field values and lets SPJobDefinition do its thing.

Our Execute override uses a helper method that takes two paths: the path to the server’s SPTHEMES.XML and the path to our feature’s themes file.

    private const string SPTHEMES_PATH = @"TEMPLATE\LAYOUTS\1033\SPTHEMES.XML";
    public override void Execute(Guid targetInstanceId) {
      SPFeatureDefinition fDef = Farm.FeatureDefinitions[_featureID];
      if (fDef != null)
        DoMerge(SPUtility.GetGenericSetupPath(SPTHEMES_PATH), Path.Combine(fDef.RootDirectory, _themesFile));
    }

First we open the XML files and do a bit of initial setup:

    public void DoMerge(string pathToSPThemes, string pathToMerge) {
      try {
        XmlDocument docThemes = new XmlDocument();
        docThemes.Load(pathToSPThemes);
        string nsThemes = docThemes.DocumentElement.NamespaceURI;

        XPathNavigator navThemes = docThemes.CreateNavigator();
        XmlNamespaceManager mgrThemes = new XmlNamespaceManager(navThemes.NameTable);
        mgrThemes.AddNamespace("t", nsThemes);

        XmlDocument docMerge = new XmlDocument();
        docMerge.Load(pathToMerge);

        XPathNavigator navMerge = docMerge.CreateNavigator();
        XmlNamespaceManager mgrMerge = new XmlNamespaceManager(navMerge.NameTable);
        mgrMerge.AddNamespace("t", docMerge.DocumentElement.NamespaceURI);

        bool shouldSave = false;

Now we use XPath to retrieve and iterate over a list of the themes in our feature.

        XmlNodeList mergeNodes = docMerge.SelectNodes("/t:SPThemes/t:Templates/t:TemplateID", mgrMerge);
        foreach (XmlNode mergeNode in mergeNodes) {

And use XPath again to find an existing theme with the same TemplateID.

          try {
            string xpath = string.Format("/t:SPThemes/t:Templates[t:TemplateID = '{0}']", mergeNode.InnerText);
            XmlNode node = docThemes.SelectSingleNode(xpath, mgrThemes);

If we’re deleting and we find the theme node, get rid of it.

            if (_delete) {
              if (node != null)
                node.ParentNode.RemoveChild(node);
            }

Otherwise create a Templates element for the new theme. I’m assuming this part could be cleaned up with a deeper understanding of the XML object model — help! For now I just copy the source XML into a new node in the destination document. I iterate through the new children and RemoveAllAttributes() to eliminate extra xmlns attributes that I can’t figure out how to prevent.

            else {
              XmlNode newNodeParent = mergeNode.ParentNode;
              XmlElement toInsert = docThemes.CreateElement(newNodeParent.Name, nsThemes);
              toInsert.InnerXml = newNodeParent.InnerXml;
              foreach (XmlElement xe in toInsert.ChildNodes)
                xe.RemoveAllAttributes();

              if (node == null)
                docThemes.DocumentElement.AppendChild(toInsert);
              else
                node.ParentNode.ReplaceChild(toInsert, node);
            }

If we get to this point, everything went fine and we should save our results.

            shouldSave = true;
          }
          catch (Exception ex) {
            Trace.WriteLine("Error merging theme " + mergeNode.InnerText);
            Trace.WriteLine(ex);
          }
        } // foreach mergeNode

        if (shouldSave)
          docThemes.Save(pathToSPThemes);
      }
      catch (Exception ex) {
        Trace.WriteLine("Failed to merge themes");
        Trace.WriteLine(ex);
        throw;
      }
    }

Now that the job is defined, we can add a few helpers. First, a method to run the job immediately—a technique borrowed from Vincent Rothwell—combined with a variation on AC’s technique to delete existing jobs:

    public void SubmitJobNow() {
      if (Farm.TimerService.Instances.Count < 1)
        throw new SPException("Could not run job. Timer service not found.");

      foreach (SPJobDefinition job in Service.JobDefinitions)
        if (job.Name == Name)
          job.Delete();

      Schedule = new SPOneTimeSchedule(DateTime.Now.AddHours(-2));
      Update();
    }

Next, the static methods we used earlier in the feature receiver.

    public static void InstallThemes(SPFeatureDefinition def, string themesFile) {
      MergeFeatureThemes(def, themesFile, false);
    }
    public static void DeleteThemes(SPFeatureDefinition def, string themesFile) {
      MergeFeatureThemes(def, themesFile, true);
    }

These share our final helper, which iterates through the web services on the farm and starts our job for each of them.

    private static void MergeFeatureThemes(SPFeatureDefinition def, string themesFile, bool delete) {
      if (def == null)
        throw new ArgumentNullException("def");

      SPFarm f = def.Farm;
      if (f == null)
        f = SPFarm.Local;

      foreach (SPWebService svc in new SPWebServiceCollection(f)) {
        FeatureThemesJob itj = new FeatureThemesJob(svc, def.Id, themesFile, delete);
        itj.SubmitJobNow();
      }
    }
  }
}

I’m sure there are improvements to be made, and I’m not certain I’ve properly handled all the multi-server scenarios, but it’s a start. What do you think?

Also, while we’re on the topic of features creating custom timer jobs, check out Vincent’s post on issues related to accounts and jobs. The gist is that features that create jobs should be scoped at the WebApplication or Farm level to ensure sufficient permissions to modify the configuration database.

Update 7/13/2008: Theme-amajig Refactored: Using Feature Properties

Update 11/28/2008: Bugs in the original post have been corrected. I also added a release on Codeplex with sample code: Sample Generated Theme Solution; you can generate your own with my STSDEV Theme Solution Generator.