This article is the second in a series of five articles which describe how to customize and brand a SharePoint site using several different methods. We will demonstrate how to customize a site template that hosts Bamboo’s Bamboo Knowledge Base, and in the process review the pros and cons of each different method.
In the first article of this series, we explained how to customize a SharePoint site template that hosts the Bamboo Knowledge Base Web Parts. In this article, we will explain how to deploy the customized site template using SharePoint Features.
The articles in this series cover:
In Part I, we explained how to customize a SharePoint site template that comes with Bamboo Knowledge Base. In that article, we used SharePoint Designer 2007 (SPD) to provide a quick, WYSIWYG way to customize our sample KB site. We also discussed the disadvantages of using SharePoint Designer. One of the main disadvantages is the fact that you are modifying an instance of the site template by directly editing the site’s master page and style sheet. Once that site is modified, it’s cumbersome to deploy across your SharePoint farm, especially in a more structured development environment.
In this article, we will provide step-by-step instructions for deploying a customized site template across your enterprise using SharePoint Feature management.
SharePoint Features Overview
As discussed in the first article in this series, when a SharePoint custom site (or Web Part for that matter) is deployed, there are multiple files, lists, style sheets and images that have to be deployed to your Web Front End (WFE) server. With previous versions of SharePoint, you pretty much have to perform these steps manually. With WSS 3.0, Microsoft addressed these issues through 2 new capabilities: Features and Solutions.
The new Features framework allows the SharePoint system administrator to combine a set of artifacts into a single entity, and then apply the feature entity to a scope within your server farm. The artifacts can be any components such as master pages, site definitions, web parts…etc. You can then activate a feature at against a certain scope such as Farm, Web Application, Site Collection, and Site.
In this use case, we will take the previously built master files (KBClient.master), style sheets (KBStyle.css), and images and package them into a Feature to deploy to a SharePoint site. To create a Feature for the above artifacts, follow these steps:
- Create the Feature folder and store your artifacts that are used in the site template.
- Create the Feature.xml file.
- Create the Element.xml manifest file.
- Copy style sheets and images to the correct folder.
- Run stsadm command file to deploy the feature.
Step 1 – Save the artifacts in the Features folder
SharePoint features reside in a folder on each web front end server at the default location [drive]:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\FEATURES. Inside this template folder is where we place our master page, CSS files and other images. The folders are mainly being used to:
- Features folder: contains our own feature for registering to web server.
- Control Templates folder: contains our custom control. This control will be used for selecting and applying our custom master page
- Layouts folder: contains images, styles, web pages
You can actually place artifacts in any folder, or you can place all of them under one folder such as the Bamboo Knowledge Base folder. The suggested placement of artifacts above are recommended best practices as used by SharePoint itself.
The first step is to create a new folder Bamboo.KBAccelerator under the FEATURES folder, and then copy the KBClient.master into this folder. Note that if you already installed Bamboo Knowledge Base using its default template, the Bamboo.KBAccelerator folder will be created automatically.
Step 2 – Create the feature.xml file
When you create new SharePoint site, only the default master page (default.master) and the default layout page (default.aspx) are copied to the site galleries. In order for a custom master page to be applied to new sites, our custom master page must be copied to the site along with the default pages. This task is accomplished by writing the feature.xml file.
Create a new text file name feature.xml in the \FEATURES directory; paste the following text into the file:
1: <?xml version="1.0" encoding="utf-8" ?>
3: <Feature Id="3EDB1BAC-D247-48ff-B215-74FE7A1B0403"
4: Title="Automatically Change Layouts Feature"
5: Description="Custom action on Site Settings"
10: <ElementManifest Location="Features\customElements.xml" />
The parameters for this XML feature file are defined as (see more details on MSDN here):
- ID: A Globally Unique Identifier (GUID) value that uniquely identifies this feature.
- Title: The name of the feature.
- Scope: Defines how the feature is applied. Available options are Farm, Site (site collection), and Web.
- ElementManifest: The artifact payload.
- Location: ElementManifest file location relative to the Feature file.
You can create a new GUID using an online tool such as GuidGenerator.com or the Visual Studio GUID generator (Tools >Create GUID). Copy the GUID value and paste it into the ID value of the Feature property in the Feature.xml file. Make sure to remove the curly braces as shown above.
Fill in the Title, Description and Version parameters. The Scope parameter will tell SharePoint how this feature can be activated at various scopes in the farm. In this use case, we will use Web, means it is activated per web site. The element manifest is identified as “customElements.xml” which resides in the same directory.
Step 3 – Create the (custom)Element.xml file
The next step is to create an element manifest file. This file contains the main instruction that SharePoint will use to copy the artifact files into the correct location in the destination site.
Create a new text file in the \FEATURES directory and rename it customElements.xml, and paste the following text into the file:
1: <?xml version="1.0" encoding="utf-8" ?>
2: <Elements xmlns="http://schemas.microsoft.com/sharepoint/">
3: <Module Name="Masterpages" List="116" Url="_catalogs/masterpage">
4: <File Url="KBClient.master" Type="GhostableInLibrary" />
The parameters for this module XML node are defined as (see more details on MSDN here):
- Name: The folder name of the file set.
- List: The ID of the list type, this sample uses a MasterPageGallery.
- Url: The post-provisioning, relative url of the list.
The attributes for this File node are defined as:
- Url: The local path of our custom master page.
- Type: Determines whether an actual list item is created for the file (GhostableInLibrary) or if it exists in a hidden state (Ghostable). Our sample master file will be set to Ghosted on the gallery.
Step 3 – Style and Image files
When you implement a customized site template, styles may be stored in a document library on a site and referenced by URL from within the master page headers. You can also store styles in the 12\TEMPLATE\Layouts\1033\Styles directory and thus they can be referenced globally using the virtual Layouts path (/_layouts/1033/styles/) in the master page header. It is recommended to place all custom styles in a subfolder of the 12\TEMPLATE\Layouts\1033\Styles directory to insure compatibility with future upgrades.
Next, copy the style sheet to \LAYOUTS\1033\STYLES\Bamboo.KBAccelerator folder and add the following line just above the closing </HEAD> tag in your custom master page:
1: <link rel="stylesheet" type="text/css" href="/_layouts/1033/styles/Bamboo.KBAccelerator/KBClient.css"/>
Images are stored similar to the style sheets. First, copy the images to \LAYOUTS\1033\ IMAGES \Bamboo.KBAccelerator folder and they can be referenced using path such as /_layouts/1033/images/Bamboo.KBAccelerator/icon_Admin.jpg
Step 4 – Deploy the feature files
Now that we have the entire necessary artifacts store in the file system, these files are ready to be copied to each front-end web server. This can be done from the command prompt on each SharePoint web front end server, using the “STSADM –o installfeature” command to start the deployment job. Alternatively, you can create a command.bat file and paste the following text:
"C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\STSADM.EXE" -o installfeature -filename [feature name]\feature.xml –force.
Use -force to install the feature even if it is already installed and activated somewhere in the farm. If you encounter an error and need to retry the operation, you must first uninstall it using the following command:
"C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\stsadm.exe" -o uninstallfeature -filename [feature name]\feature.xml
Step 4 – Activate the feature
Next, we need to activate the feature. Browse to Site Actions>Site Settings and from the Site Collection Administration menu, choose “Site Collection Features”. You should see the new feature listed (Note the title and description is as per our FEATURE.XML file).
Click “Activate” to activate the feature (you can also do this on the command line via STSADM -o activatefeature command).
This article demonstrates how we can use SharePoint features to deploy a customized site template to SharePoint site. In the next article, we will show you build and deploy the customized pages as a solutions using Visual Studio.
Some excellent resources on SharePoint branding are available here:
Sep 11 2008, 05:01 PM
Quyen is a Software Engineer and a member of the SharePoint Customization group. She works at Bamboo Solutions's Vietnam office in HCM City.