This article is the third in a series of five that 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 Knowledge Base Accelerator, and in the process review the pros and cons of each different customization method.
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 shows how you can directly modify a Site Template using SharePoint Designer. The second article demonstrates 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 using Features allows us to reduce the complexity of deploying a customized site.
In this third article, we will go one step further by demonstrating how we can build a Solutions package to deploy your customized sites across the entire SharePoint farm that fits with a more formal development methodology.
The articles in this series cover:
SharePoint Features and Solutions Overview
As you can see in previous article, when a SharePoint custom site (or a 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. In WSS 3.0, Microsoft addressed these issues with two major new capabilities: Features and Solutions.
The Solutions framework allows the developer to package all the files that are needed in a solution, along with an instructions file that tells SharePoint how to install each of the individual files. SharePoint will schedule a job to add the solution package to a central repository, and then deploy the solution to all the requested front end servers.
This Solutions framework sounds very familiar to the Features that we talked about in the last article. While they are very similar, the main reasons why you should consider using Solutions to deploy a customized site are:
- If your site template contains Web Parts, such as our sample KB Accelerator template, you cannot deploy an assembly to the GAC using Features.
- You cannot install a customized site template to all web front end servers in a single step.
- You cannot edit the web.config of a web application using Features
Although the differences are fairly small, there is potential for mistakes when you are deploying a feature to multiple sites and you can create unnecessarily risky work for rollback and updates.
Customize the KB using Solutions
Since the KB Accelerators sample has extensive modification to the site templates, our feature files contains these artifacts:
- Master page (kbmaster-001.master and kbmaster002.master)
- Style sheet (kbclient.css)
- Images (in images folder)
We will continue with our use case and use Visual Studio to package all the files into a WSS Solutions Package (.WSP) file, (which is really a CAB file in disguise), to be ready for upload into SharePoint.
To create a Solution Package deployment, you would follow these steps:
- Use Visual Studio and create the Solutions Project.
- Register Site Features
- Add Site Navigation to project
- Add the WebTemp.xml file
- Build the Solution
- Deploy and test the solution
Step 1: Creating Solution Project
While you can create a Solution package manually, it will be much easier to automate the whole process using Visual Studio. In this example, we will also be using WSPBuilder, which is one of the open source tools available on Codeplex to build the .wsp file. What we are basically doing is creating a project within Visual Studio 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. The screen shot below shows how Bamboo actually creates the folders for the KB Accelerator templates:
The important folders that you need are:
- Features: contains the features for the KB Accelerator (lists, web parts, master page). You can just copy the feature folder under this node (Bamboo.KBAccelerator). See article 2 for additional details.
- Layouts: contains the reference elements (images, css). This is where you can copy the style sheets and images. As mentioned in the previous article, you can also copy the images and css files into the Feature folder.
Step 2: Build the Solutions Package
At this point, if you were building the solution package by hand, you would have to manually create the manifest.xml and ddf files that define the solution. However, since we are using WSPBuilder, it will automatically build the file for us. Right click the project and click WSPBuilder > Build:
NOTE: You can also build the solution by hand by going to the WSPBuilder directory ([drive]:\program files\wspbuilder, and running the wspbuilder.exe program.
Once the solution package is built, you can verify that there are 3 files: wspbuilder.wsp, manifest.xml, and solutions.txt are created on your local project folder.
Step 3: Deploy the Solutions Package
If the build is successful, right click the project and click WSPBuilder > Deploy. This is the equivalent of running a ‘stsadm’ scripts to install your solution package. WSPBuilder can quickly facilitate the same process allowing the developer to quickly deploy the solution package to the current SharePoint farm. This command will deploy the WSP file on all the Web Applications in your local SharePoint farm.
Step 4: Test the Solutions Package
Open up SharePoint Central site and create a new Site Collection with the site definition we just created.
Update the Solutions Package
You can now update your site customization and use the same process to deploy and test your solutions. Several things to remember:
- WSPBuilder recycles the web site’s application pool each time you execute a deploy command.
- If the same solution is deployed more than once, WSPBuilder does an upgrade in the subsequent deployment. If you are making changes to the any code, you might have to do WSPBuilder > Uninstall and then WSPBuilder > Deploy to do a real install again.
This article demonstrates how we can use the SharePoint Solution package to deploy a customized site template into a SharePoint site. In the next article, we will show you how to deploy using site definition and allow users to select multiple templates at run time.
Here are some excellent additional resources on SharePoint branding:
Sep 16 2008, 04:05 PM
Duong is a Software Engineer and a member of the SharePoint Customization group. She is responsible for the design, development and customization of SharePoint sites. She works at Bamboo Solutions' Vietnam office in HCM City.