Site Template Configurator utility

This is the newest Windows forms tool that uses the famous TreeView-PropertyGrid combo (a long time favorite of mine). I called it the “Site template configurator” and as its name suggests it is designed to provide an easy to use UI for creating, updating and maintaining SharePoint site templates (with a focus on portal site templates). You can download the source code of the tool from here. Here is a small teaser screenshot:

Let me start first with a few words about site templates in SharePoint. We have the normal (ONET.XML) site template which configures the functionality for a single SharePoint site. And we also have the so called portal site templates which specify not the configuration of a single site but rather a site hierarchy – this includes which ONET site template should be used for the root site of the hierarchy and then for the sub-sites in the site hierarchy. In SharePoint 2010 there’re already two ways of provisioning ONET site templates – the old one available in SharePoint 2007 with folders under the TEMPLATE\SiteTemplates SharePoint system folder and a WEBTEMP*.XML file under the TEMPLATE\[LCID]\XML folder; and the new one – with “WebTemplate” features (which works for both farm and sandbox solutions as opposed to the “SiteTemplates” approach). The portal site templates are provisioned with “WebManifest” XML files as the one available in the TEMPLATE\SiteTemplates\WebManifest SharePoint folder for the standard “Collaboration Portal” portal site definition (plus an entry in a WEBTEMP*.XML file much like the “SiteTemlates” type ONET site definitions).

The obvious purpose of site templates is to automate the process of creating SharePoint sites with the same functionality (or site hierarchies with the same structure). Although the ONET.XML provides many different configuration options it can basically come down to specifying only which site scoped and web scoped features should be activated in the site – I think that ONET elements like the “Lists” and “Modules” ones should be deprecated in favor of the corresponding “ListInstance” and “Module” feature elements. So if we assume that SharePoint features are the smallest blocks of functionality then site templates can be viewed as simply sets of features that should deploy these various functionality items to a SharePoint site. This is a neat conceptual frame but when it comes to real life implementation it may turn really difficult to maintain site definitions especially if they grow rapidly in number. And here comes the tool I will present in this posting that will hopefully help address at least some of the issues of creating and maintaining site templates.

The tool is developed in Visual Studio 2010 and targets SharePoint 2010. It uses only a small set of classes from the SharePoint object model so it can be easily recompiled for SharePoint 2007, meaning that it can be used for the older version of SharePoint as well. To start with an important note – the tool doesn’t modify existing SharePoint site templates and doesn’t change any standard configuration files under the SharePoint 14\TEMPLATE folder. It allows you to create new site templates and select and configure site and web features for them and all configurations are saved in a so called project file, which is an XML file with a custom format. The project file can be opened in the tool at later times for further updating and maintaining of your site templates. From the project file the tool can generate SharePoint site template definitions that can be deployed to a SharePoint installation where they can be used. I think that keeping all configurations in a single file is definitely an advantage at least in terms of maintainability (unfortunately in SharePoint we should deal with much more configuration files).

And here is a quick overview of the tool’s commands starting with the tool’s toolbar:

• “Actions” menu – this menu is context dependant – it displays commands that apply for the currently selected node in the TreeView control
• “Project” menu:
  - “New Project …”
  - “Open Project”
  - “Save Project”
  - “Save Project as …”
  - “Close Project”
  These are all self explanatory – they handle the creating, opening, updating and closing of the project file.
  - “Generate artifacts …” – this command generates the SharePoint site definitions that are configured in the project file – I will explain this in more detail below.

The tool displays several entities in a hierarchical view in the left side pane, these are: “Project”, “Template”, “Web”, “Feature” and “Feature property”. Each of these contains a number of configuration properties that are displayed in the right side property grid pane (they can also be modified in the property grid) and also each entity comes with a number of “actions” that are available as menu items under the “Actions” toolbar menu or in the context menu which appears on right mouse click on the tree node.

• “Project” entity – it contains some general settings for the project and your templates. It has the following properties:
  - “ID” – automatically generated GUID – internal unique identifier of the project, used when the SharePoint  artifacts get generated
  - “Name” – internal name of the project
  - “DisplayName” – display name of the project (for reference purposes only, not used internally)
  - “Description” – description of the project (for reference purposes only, not used internally)
  - “DefaultDisplayCategory” – this specifies the display name of the group under which your site templates will appear in the SharePoint “create site” page
  - “Locale” – set to English US by default (1033) – this specifies the target locale of your site templates
  - “StartTemplateID” – this one is important – this number will be used for the “ID” attributes of your site templates in the generated WEBTEMP*.XML file – note that these should be unique throughout all WEBTEMP*.XML files otherwise you will get an error when you create a site with your templates.
  The commands for the “Project” entity:
  - “Add template” – adds a new site template to the project
  - “Paste template” – after you use the “copy” command of an existing template you can paste it as a new template using the Windows clipboard.
• “Template” entity – it contains the settings for a site definition with the following properties:
  - “BaseTemplateName” – you can specify an existing ONET or portal site definition here and also one of the other templates in the project. Note that currently you cannot use “WebTemplate” feature site definitions (you won’t see these in the “site templates” drop-down control in the “Add template” dialog form). Note also that you can use portal site templates as well – nesting these is not a problem. The tool will also generate portal site templates for your site definitions.
  - “BaseTemplateConfiguration” – this is used in conjunction with the “BaseTemplateName” property to specify the configuration ID of the base site definition within its ONET.XML.
  - “Name” – internal name of the template (as it is used to create a site with code)
  - “DisplayName” – display name of the template (as it appears on the standard “create site” page)
  - “Description” – description of the template (as it appears on the standard “create site” page)
  - “DisplayCategory” – this specifies the display group of the template as it appears on the standard “create site” page, if empty the “DefaultDisplayCategory” property of the “Project” entity will be used instead during artifact generation.
  - “Hidden” – specifies whether the template is hidden
  - “RootWebOnly” – analogous to the “RootWebOnly” attribute in the WEBTEMP*.XML
  - “SubWebOnly” – analogous to the “SubWebOnly” attribute in the WEBTEMP*.XML
  - “IncludeLists” – specifies whether the Configuration/Lists element from the ONET.XML of the base site definition (specified in the “BaseTemplateName” property) should be copied to the new definition
  - “IncludeModules” – specifies whether the Configuration/Modules element from the ONET.XML of the base site definition (specified in the “BaseTemplateName” property) should be copied to the new definition
  The “Template” entity has the following commands:
  - “Add web” – allows you to add a sub-web to the template’s site hierarchy
  - “Delete template” – deletes the template
  - “Copy template” – copies the definition of the template to the clipboard (see “Paste template” above)
  - “Copy template (shallow)” – the same as “Copy template” but copies the template’s definition without its sub-webs
  - “Paste web” – pastes a “Web” definition from the clipboard as a new sub-web
• “Web” entity – you can have “Web” elements under your “Template” elements and also nest “Web” elements under other “Web” elements. This way you can specify a site hierarchy for your template (since it is a portal site template). The “Web” entity contains a subset of the properties of the “Template” entity. There is one difference here – the usage of the “Name” property – here it specifies the URL of the sub-web relative to the template’s root or its parent “Web”. The “Web” entity has the following commands:
  - “Add web” – adds a sub-web under the current web
  - “Delete web” – deletes the current web
  - “Copy web” - copies the definition of the web to the clipboard (see “Paste web” above)
  - “Copy web (shallow)” – the same as “Copy web” but copies the web’s definition without its sub-webs
  - “Paste subweb” – pastes a “Web” definition from the clipboard as a new sub-web
• “Feature” entity – it represents a SharePoint feature that should be activated for the site based on the template or some of the “Web” elements available in the template’s portal hierarchy. The “Feature” elements appear under the “SiteFeatures” and “WebFeatures” sub-nodes of “Template” and “Web” elements. When you add a new “Template” or “Web” element all available site and web features from the “Configuration” element of the base template’s (“BaseTemplateName” property) ONET.XML are copied and will appear in your definition. Note that when the base template is a portal site definition (this includes the templates in the current project) the feature nodes won’t be available – portal site definitions are treated as “sealed” by the tool. The “Feature” entity has the following commands:
  - “Add feature property” – adds a new “Feature property” element for the current “Feature”
  - “Delete feature” – deletes the current “Feature”
  - “Copy feature” – copies the current “Feature” definition to the clipboard
  - “Paste feature property” – creates a new “Feature property” from a copied to the clipboard “Feature property” definition. If a “Feature property” with the same “Key” property exists it will be overwritten.
  The following “Feature” commands are available for the “SiteFeatures” and “WebFeatures” nodes:
  - “Add/remove features” – this command opens a dialog form with a multi-select control that allows you to quickly add and remove many features at a time and also allows you to change the ordering of the features.
  - “Paste feature” – pastes a “Feature” definition from the clipboard. If the feature already exists it will be overwritten (the feature properties if available will be overwritten actually).
• “Feature property” entity – it represents a property of a SharePoint feature. It has the following properties:
  - “Key” – represents the “Key” attribute of the ONET.XML “Property” element
  - “Value” - represents the “Value” attribute of the ONET.XML “Property” element
  The “Feature property” entity has the following commands:
  - “Delete feature property” – deletes the selected “Feature property”
  - “Copy feature property” – copies the definition of the “Feature property” to the clipboard.

Generation of the SharePoint site definitions

And a few words about the generation of the real SharePoint definitions from the tool’s custom template definition XML format: initially I was considering several approaches to get the site templates functionality available (site templates in the most general sense as I mentioned above – getting a set of features applied to a site) including these scenarios:

• doing this programmatically using the SharePoint object model (either with a custom feature receiver or using the new SharePoint 2010 “web provisioned” event). A problem with this was that the object model provides methods to activate a feature but you can’t specify the feature properties that should be applied with the activation (there is an internal method for that but I didn’t want to resort to reflection).
• using the “WebTemplate” feature approach – it seems a little bit more economical – you can pack many site definitions into a single feature and you don’t need the WEBTEMP*.XML with an extra entry there so that the definition becomes available. A small but annoying problem with “WebTemplate” features is that you can’t specify for example that the site definition is hidden – the moment you install the “WebTemplate” feature in the farm all site definitions in it become globally available.

So in the end I decided to use the good old “SiteTemplates” type of site definitions coupled with “WebManifest” files for the portal site definitions. And here is what you will get when you click the “Generate artifacts …” command – first you will need to select a target folder (it’s better to use a temporary one rather than the standard 14\TEMPLATE folder), then the tool will output all necessary SharePoint artifact files in two main folders below the target folder: “[LCID]\XML” and “SiteTemplates”.

The first one will contain a single WEBTEMP*.XML file – the asterisk will be replaced by a Guid like sequence of characters (starting with “G” and followed by thirty two alphanumeric characters – this is actually the auto-generated “ID” property of the “Project” element). The WEBTEMP*.XML file will contain entries for all portal site templates generated from the “Template” elements in the project file and also hidden “Template” entries for all base site templates (actually copies of these – see below) that were used in the template project.

The “SiteTemplates” folder – this will contain one folder named G[32 characters project GUID]_WebManifest and several folders named G[32 characters project GUID]_[base template name]. The former will contain “WebManifest” XML files for all templates in the project and the latter ones – there will be one folder per base template used – a folder will be created only for non-portal base templates – this will be an exact copy of the original folder of the base template containing all files and sub-folders, the only difference will be the ONET.XML file – it’s “Configurations” element will be completely changed and will contain one “Configuration” element for every “Template” and “Web” element in the project that use this base template. The individual “Configuration” elements will contain the selected site and web features for the parent element in your project file plus optionally the “Lists” and “Modules” element from the base configuration.

The tool just outputs the SharePoint artifact files without creating a WSP file (one of the directions for improving the tool should be the built-in generation of CAB files (the WSP is a CAB) although this is a little bit tedious job in Windows). The simple copying of the files to the “14\TEMPLATE” folder is actually sufficient (followed by a recycling of the application pool/pools – including the central administration site application pool if you want to create sites from central administration) to get the generated site definitions available (though it is a bit cumbersome since it should be made on every machine in the farm).