SharePoint Branding for the KB Accelerator – Part 4/4: Site Definitions

In the first article of this series, we explained how to customize a SharePoint site template that hosts the Knowledge Base Solution Accelerator Web Parts. That article demonstrates how you can directly modify a Site Template using SharePoint Designer. The second article showed how you can take the modified artifacts (master page, style sheets…etc), create a SharePoint Feature package, and deploy it to a site. We showed that the use of Features allows us to reduce the complexity of deployment within a customized site. In the third article, we showed how you can package and deploy the customization using SharePoint Solutions deployment.

In this fourth article, we will demonstrate how we can also customize a SharePoint site by building a Site Definition, and using Visual Studio to deploy a customized site.

The articles in this series cover:

• Part 1 - How to customize a SharePoint site using SPD.
• Part 2 - How to install a customized site using SharePoint solution and feature deployment.
• Part 3 - How to build a solution deployment package for a custom site.
• Part 4 - How to customize a site definition and deploy a solution package using Visual Studio.

SharePoint Site Definitions

So far, we know that we can customize a SharePoint site by editing the site master file, layout and style sheet. This modified site can be exported to a Site Template and can then be imported and used to create new sites. We talked about how we can package the customized file and deploy it using SharePoint Features. We then learned that we can package the customized files into a Solution package (.wsp) and deploy the solution to many sites at once. In conclusion, we will discuss how to deploy a customized site by creating a Site Definition and then deploying it as a Solution.

Why use a Site Definition? When you create a SharePoint site, the new site will be created based on one of the many out-of-the-box Site Definition files found in the [drive]:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE directory. Site Templates are much easier to use, but by creating a new Site Definition that contains lists, Web Parts, Features, etc., Site Definitions are more flexible and powerful. The key advantage of customizing using Site Definition over Site Templates are:

• There are sites that cannot be exported to Site Templates, such as a Publishing Site.
• You cannot declare and use Content Type in Site Template.
• You cannot export custom code to Site Template. One example that we will show in this article is a script that allows the user to select different a template skin at run time.

Customize the KB using Site Definition

A SharePoint Site Definition consists of a hierarchy tree of CAML elements (see more details on CAML here) that describe the makeup of the site. The top element of the site is the TEMPLATE element, which is declared in the WEBTEMP file, and which contains template Configuration elements (this is what the user will see as the site names when creating a new site in SharePoint) with references to an ONET.xml which contains the actual components that make up the site.

We will continue with our use case by creating a new Site Definition, and we will then use Visual Studio to package all the files into a WSS Solutions Package (.WSP) file (which is really a CAB file in disguise), which readies them for uploading into SharePoint.

To create a Solution Package deployment, follow these steps:

1. Using Visual Studio, create the Solutions Project
2. Register Site Features
3. Add Site Navigation to project
4. Add the WebTemp.xml file
5. Build the Solution
6. Deploy and test the Solution

Step 1: Creating Solution Project

While you can create a Solution package manually (as shown in the preceding article), it is much easier to automate the whole process using Visual Studio. In this example, we will also be using WSPBuilder, one of the open source tools on Codeplex, to build the .wsp file. What we are basically doing is creating a project within VS to mimic SharePoint 12 hives (for example: [Project]\12\Template\Features\KBFeature\), then putting our Feature files in the KBFeatures folder. We can then run the WSPBuilder from our project directory and it will automatically create the manifest.xml and pack it into a .wsp file with the content of the "\12" folder.

Start Visual Studio 2005/2008 and create a new project, using an Empty or C# class library template. When the project is ready, create a folder structure that matches the SharePoint 12 hive, as shown below:

The important folders are:

• 1033: Contains the .xml files that will tell SharePoint about your new site definitions
• Features: Contains the features for the KB Accelerator (lists, Web Parts, master page). See article 2 for additional details.
• Layouts: Contains the reference elements (images, css, etc.)
• Site Templates: Contains our Site Definitions. Note that our sample contains two different site templates: one for the KB client site, and one for the Admin KB site. We suggest that you create a sub-folder under this tree branch. In our example, we show two different templates, one for the KB client site and one for the KB admin site.
• Control Templates: Contains any custom controls that we use.

Step 2: Copy Files to Projects

Each site definition contains a set of files and folders. Under the XML folder is the file ONET.XML. This file contains elements that describe the actual content of the site such as navigation, lists, and document templates. In this example, we will edit the onet.xml file and add 3 sample Modules elements in the text block containing “Configuration” with ID =”1”, and adding 3 modules under Modules like this:

<Configurations>

    <Configuration ID="1" Name="Client" CustomMasterUrl="_catalogs/masterpage/KBClient-001.master" MasterUrl="_catalogs/masterpage/KBClient-001.master">

            <Lists>

…..

            </Lists>

<Modules>

   <Module Name="Default" />

            <Module Name="CustomMasterPage" />

            <Module Name="Client"/>

</Modules>

Where:

• Module “Default”: Defines default.aspx with Bamboo tree View Web Part
• Module “Client”: Ghost of all Web Part pages in Shared Documents library
• Module “CustomMasterPage”: Defines custom master pages used for KB Client Site and ghost of all in Master Pages Gallery
• See additional description here http://msdn.microsoft.com/en-us/library/ms474369.aspx.

We create a folder webpart page under KBClientTemplate. This folder holds all 6 Web Part pages that we used in this sample site. Our sample KB Client Site uses only the default Shared Documents Library, and two Web Part pages, AskQuestion.aspx and Search.aspx.

Step 2: Master page:

The KB Sample Site uses custom master for all Web Part pages. We create a KBClient.master file under the KBTemplate folder. Open file onet.xml, find Configurations xml node and add CustomMasterUrl attribute:

<Configuration ID="0" Name="Client" CustomMasterUrl="_catalogs/masterpage/KBClient.master" 

      MasterUrl="_catalogs/masterpage/KBClient.master">

Open all files webpart page (file .aspx) and edit attribute Masterurl. SharePoint will do a string replacement of any aspx page with ~masterurl/custom.master with the reference in CustomMasterUrl. And it will replace any aspx page with ~masterurl/default.master with the reference in MasterUrl.

MasterPageFile="~masterurl/custom.master"

Underneath Configuration ID=”0” and Module Masterpage:

<Module Name="CustomMasterPage" />

Find Modules node and define module Masterpage

<Module Name="CustomMasterPage" List="116" Url="_catalogs/masterpage" RootWebOnly="FALSE">

Module Url: The path where Master is copied to. Master will be copied to ="_catalogs/masterpage

Step 2: Register Site Features

Adding a custom list feature requires that you provide at least the following three files:

• Feature.xml: Including register title, feature ID, and scope for the Feature, as well as the location of an element file.
• Elements.xml: Identifies the list template and specifies information to display on the Create Page. Give it a Type value that is above 10000 and different from any other custom list definitions used in your deployment (maybe name is not the same, such as: KBCategories.xml, etc.).
• Schema.xml: Defines the list schema, which includes content type associations, field and view definitions, and form and toolbar references.

In the KB Admin Site Sample, we also use several SharePoint lists for configuration data. If you are using a list, each list must have FeatureID defined in each feature.xml. If feature has scope “Site,” we register feature to the Site Features node. After site creation, all lists registered exist on that site.

<SiteFeatures>

    <Feature ID="00BFEA71-1C5E-4A24-B310-BA51C3EB7A57" />

    <Feature ID="FDE5D850-671E-4143-950A-87B473922DC7" />

    <Feature ID="ABB49F6D-EB80-4668-A012-3FC9CED16CD2" />

        <!-- register KB List-->

    <Feature ID="A1036434-9F15-4132-9C1A-40F347E983F8"/>

    <Feature ID="C0292BA6-A243-4c7c-800A-0E8E2FDFA4E6"/>

    <Feature ID="CCB58B3A-E571-4bee-9777-A0A7059B747E"/>

    <Feature ID="18BDB285-C801-4495-8C72-BB5E78FD0856"/>

    <Feature ID="1D75DE56-7735-4fce-BB64-285F1F270C61"/>

    <Feature ID="63DAD0A9-828F-43eb-9774-8F34912D2C89"/>

</SiteFeatures>

Step 3: Add Site Navigation

In the sample site, we also use several global navigation links. These links will have to be defined in the onet.xml file as follows:

Open onet.xml and add the navigation bar link (NavBarLinks and NavBar snippet) as shown:

Step 4: Create the WebTemp.xml file

In order to make a new Site Definition available for selection in the Site Creation dialog, the custom site definition must be listed in the WEBTEMP.XML file.  Under the Template\1033 folder in your VS project, add a new folder under 1033 called XML. Create a new file WebTempKBA.xml (note that this file must start with WebTemp), and add the following text:

<Templates xmlns:ows="Microsoft SharePoint">

    <Template Name="Bamboo.KBClientTemplate" ID="10001">

         <Configuration ID="0" Title="KB Client Site " Hidden="FALSE" ImageUrl="/_layouts/images/BambooTinyLogo.gif" Description="A site for KB Client." DisplayCategory="KB Client Template" >    </Configuration>

      </Template>

      <Template Name="Bamboo.KBAdminTemplate" ID="10002">

       <Configuration ID="1" Title="KB  Admin Site" Hidden="FALSE" ImageUrl="/_layouts/images/BambooTinyLogo.gif" Description="A site for KB Admin ." DisplayCategory="KB Admin Template" >    </Configuration>

      </Template>

</Templates>

Where,

• Name: The name MUST match the name of the Site Definition folder in the \SiteTemplates directory. In our example, ‘Bamboo.KBClientTemplate’. 
• ID: Value must be unique and greater than 10,000 to avoid conflicts with built-in Site Definitions and to ensure compatibility with future upgrades. 
• Configuration ID: The zero-based identifier for the configuration.  The first configuration node always has an ID of ‘0’. This ID points to the blocks in the ONET.XML file that compose a Site Definition.
• Title: A descriptive title for the Site Definition.
• Hidden: Sets whether or not the Site Definition is displayed as an option on the Site Creation screen.
• ImageUrl: An image associated with the Site Definition.  This is typically a wireframe representation that will be displayed when user selects the site on the Site Creation form.
• Description: Descriptive text that is displayed below the sample image on the Site Creation form.
• DisplayCategory: A category will display the new Site Definition on the Site Creation screen.

Step 5: Adding the run-time template selection menu.

As a feature of using Site Definition, we can add custom control code to be used in our customized site. In this example, we will add code that can be used to switch to a different Master Page at run time. Under CONTROLTEMPLATES folder, create a new ApplyLayout.ascx. This control is used to apply the new theme on our customized KB site.

Add the code to handle event click button in Java script in the custom control ApplyLayout.ascx that is used in our AdvanceSetting.aspx module:

function Submit_Click()

{

    var queryString ="";

    if(document.getElementById("SiteMasterPageSelection").value!='')

        queryString = "HandleRequest.aspx?masterName=" + document.getElementById("SiteMasterPageSelection").value;

    else

        queryString = "HandleRequest.aspx?masterName=/_catalogs/masterpage/default.master";

if(queryString!="")

    window.location = queryString;

}

Next, create a HandleRequest.aspx file under KBClient Template folder

The HandleRequest.aspx page will process requests from Advance Setting page to change layout. When this code is executed, it will apply the new custom layout and the user will be redirected to default.aspx

<%

 if (this.Page.Request["masterName"] != null)

{

SPWeb myNewWeb = SPControl.GetContextWeb(Context);

myNewWeb.AllowUnsafeUpdates = true;

myNewWeb.CustomMasterUrl = myNewWeb.ServerRelativeUrl + this.Page.Request["masterName"].ToString() ;

myNewWeb.Update();

Response.Redirect(myNewWeb.Url);

}

%>

The last thing we need to do is to add a new link to the top navigation bar. This is done by opening the ONET.xml file, then adding new Navbar xml node under the NavBars xml node. We will name it Change Layout and edit URL attribute navigate to AdvanceSetting.aspx page

<NavBar Name="Change Layout" Prefix="&lt;table border=0 cellpadding=4 cellspacing=0&gt;" ..Url="AdvanceSetting.aspx"></NavBar>

Step 5: Build the Solutions Package

Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are files that SharePoint needs to install the solution properly. However, using the WSPBuilder template will allow us to automate the creation of those files through the build process. Right-click the project and click WSPBuilder, then select Build:

Verify your Web Application is created on your local SharePoint environment. Each time you build the solution, Visual Studio will create and copy the files in the Visual Studio project down to the 12 hive at [drive]:\Program Files\Common Files\Microsoft Shared\web server extensions\12. This is how SharePoint is able to create a new site based on your Site Definition.

If the build is successful, you can now deploy the site by right-clicking the project, clicking WSPBuilder, and selecting Deploy. The Deploy command will deploy the wsp file you just created on all of the Web Applications in the local SharePoint farm. The WSP file can also be used to install your site in other SharePoint farms via the stsadm command.

Step 6: Test the Solutions Package

Open up SharePoint Central Administration and create a new Site Collection with the Site Definition we just created.

Once the project is set up, you can modify the content of the solutions files such as the master page or default.aspx page, and rebuild and/or update the solution by clicking WSPBuilder, and selecting Build or Deploy. Note that an IISRESET or recycle of the app pool is needed each time you update the site.

You should now be able to see the solution deployed in your site, and you can click on the Change Layout menu to switch the template:

Summary

This series of articles describes how we use several different methods to create and deploy a customized SharePoint site. The sample templates and source code in these articles can be found here: http://community.bamboosolutions.com/media/p/4587.aspx.

References

Some excellent resources on SharePoint branding are available here:

• Working with Features
• Site Definitions and Configurations
• http://heathersolomon.com/blog/articles/sp2007.aspx
• Understanding Web Content Management and the Default Features
• Customizing the Look and Feel of Microsoft Office SharePoint Server (MOSS) 2007 - Custom Chrome / Branding
• How to: Create a Minimal Master Page
• Branding a SharePoint Portal Server 2003 Site: Part 1, Understanding the Use of a Corporate Brand. (Note: This article is for SPS 2003, but some concepts are still valid for SP 2007.)