Create The Structure

• You can also use the share point solution generator to create the site definition of your site and then add
  

• Start Visual Studio and choose a new WSPBuilder project.

• Create a folder structure for the solution that matches the folder structure for the SharePoint 12 hive (this is really important – WSPBuilder works on the premise that the Visual Studio solution matches the structure of the SharePoint 12 hive). For now we are just going to create the following folders:
  • Template – subfolder under 12 that holds the other subfolders
  • 1033 – holds the xml files that will tell SharePoint about our new site definitions
  • Features – holds the new features we are going to build (i.e.: lists, webparts, master pages, etc…)
  • Layouts – holds our reference files (i.e.: images, css, js, etc…)
  • Site Templates – holds our site definitions

Create a Site Definition

• Create a new site definition based off the team site definition in SharePoint.
• Copy the team site definition folder from the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sts

• • Paste the folder in the Visual Studio solutions SiteTemplates folder.
  • Rename the sts folder to something unique (DemoCompanySiteDef for this example)
  • Delete the defaultdws.aspx file because we aren’t going to use it for this example.

• • Open the default.aspx file and change the master page to a new master page. Call this custom.master (yes, I know that this is not the name of our master page. We are going to configure SharePoint to do a string replacement of custom.master with DemoCompany.master in later steps). We will create this master page in the next step.

<%@ Page language=”C#” MasterPageFile=”~masterurl/custom.master”

Modify the Onet.xml file of the Site Definition for initial preparation

• Open the Onet.xml file (located in the xml folder) and clean it up for our simple site definition.

The Onet.xml file is the file that tells SharePoint how to create the site definition. Whenever you create a new site in SharePoint it reads from the Onet.xml file to determine how to create the site. It is important to note that SharePoint is reading from the Onet.xml file when the site is being created. So, if you already have created a site, you can’t go back to the Onet.xml file, make changes, and expect it to show up on your already created sites.

• Scroll down to the Configurations XML nodes and remove 2 configurations:
  • ID=1 – Blank
  • ID-2 – DWS

Be very careful not to remove ID=0 – Default, because this is the configuration we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

• Scroll down to the Modules XML nodes and remove 2 modules:
  • DefaultBlank
  • DWS

Once again, be very careful not to remove the Default module because this is the module we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

Create the new master page feature

The master page will be created as a feature. The reason for this is that if the master page is in a feature the master page can be added to the master page gallery of SharePoint. This allows you to set out-of-the-box pages to the master page or your own custom site definitions. It also allows you to turn on or turn off the master page features on specific sites. Basically, having it in a feature (rather than directly in the site definition or in the layouts folder) gives you much more flexibility.

• Create a new folder under “FEATURES” and call it something unique for your master page. For this example we will call it DemoCompanyMasterPage.
• Create a folder under the DemoCompanyMasterPage called “MasterPages”.
  • Copy the general SharePoint master page from the 12 hive: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL\default.master
  • Paste the file under the “MasterPages” folder in the Visual Studio solution.
  • Rename the file to something unique (DemoCompany.master for this example).
• Create two xml files under the DemoCompanyMasterPage folder.
  • feature.xml – this will give a unique GUID to the feature (which we will reference later). This file also gives some important information about the Scope of the feature. Lastly, this file tells SharePoint where all the other files that make up this feature lives. This file must be called feature.xml (this is because SharePoint will read all files called feature.xml from the Features folder).

Please note that the Scope=”Site”. This is very important. This is telling SharePoint that this feature is for the site collection. If that Scope=”Web” then it would be telling SharePoint that this feature is for an individual site.

• elements.xml – this file is telling SharePoint to place the new master page into the master page gallery. This file does not have to be called elements.xml (unlike the feature file which has to be called feature.xml). It just has to match the name located in the “ElementManifest” of the feature.xml file.

Modify Onet.xml file of the Site Definition

We are modifying the Onet.xml file of the Site Definition in order to tell this Site Definition to activate our Master Page feature when the site is created and to use our custom master page with the dynamic url replacement technique.

Dynamic Token URL replacement

To learn more about Dynamic URL replacement please refer to the second article in this series: Examining the out of the box SharePoint Master Pages.

• Open the onet.xml file in Visual Studio (located at SiteTemplates/DemoCompanySiteDef/xml).
• Find the xml node that says Configuration ID=0 Name=”Default”.
• Add in a reference for the new master page:

Note: 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.

Activate the Feature

• Find the SiteFeatures XML node.
• Add a new Feature node in there that matches the GUID of the feature.xml file we created for our master page.

This section of the onet.xml tells the site to activate this particular feature on this particular site when it is being created. The reason it goes into the SiteFeatures (instead of the WebFeatures) is because this particular feature was scoped for a Site Collection. If the feature was scoped for an individual site then it would go in the WebFeatures.

Create the WebTemp*.xml file

WebTemp*.xml files tell SharePoint about site definitions. When a new site is being created in SharePoint the “Select Templates” list box is populated by anything it can find in the WebTemp*.xml files. There can be multiple of these files in SharePoint as long as they are in the 12/Template/1033/XML folder. SharePoint will basically read this folder for any file that starts with the word WebTemp.

• Add a new folder under 12/Template/1033 in our Visual Studio solution called XML.
• Add a new file to the 12/Template/1033/XML folder in our Visual Studio solution. This file must start with WebTemp. We will call this file WebTempDemoCompany.xml.

• Add in the proper xml to tell SharePoint about our new site definition

A few things to note:

• The “Name” must match the site definition folder exactly. We used the name DemoCompanySiteDef. This matches our site definition name exactly.
• The Configuration ID must match the configuration ID in our onet.xml file of our Site Definition. We used configuration id 0.
• The display category will create a new tab on the new site screen in SharePoint.
• The ID has to be unique and SharePoint has already reserved certain IDs. To be safe use an ID over 10000 and make sure it is unique.

Use WSP Builder to build and deploy the solution

Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are files SharePoint needs to install the solution properly. However, since we are using WSPBuilder, it will do that for us.

• Right click the project and click WSPBuilder – Build

• Verify your Web Application is created on your local SharePoint environment. Note: the Site Collection should not be created at this point, just the Web Application. And, you only need to do this once.
• If the build is successful, right click the project and click WSPBuilder – Deploy.

This is needed because the build command in WSPBuilder just builds a wsp file. This file can be sent to other machines and you can use stsadm scripts to install it on other SharePoint farms. However, in development, we need a quick way to deploy it to the current SharePoint farm. The WSPBuilder – Deploy command will deploy the wsp file on all the Web Applications in the local SharePoint farm.

Use the Site Definition

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

Now you can go back and modify the master page or default.aspx page as you wish. Just be careful not to mess with the ContentPlaceHolders too much. SharePoint reserve these for certain actions on some of its internal pages. After every change you make you can rebuild by clicking WSPBuilder – Build and update the solution by clicking WSPBuilder – Deploy. Then you can just go to the website and see your changes. Just be aware that everytime you deploy WSPBuilder does an app pool recycle (to ensure the changes get pushed out through IIS), so you might have to wait a few seconds to see your changes (during that few seconds the site could say Service Unavailable).

It is also important to note that the first time you deploy with WSPBuilder it does a true SharePoint install. However, every subsequent time it does a SharePoint solution update. Solution updates work for most changes, however, there are some things it can’t do. So, if you run into errors it is sometimes good to do WSPBuilder – Uninstall and then WSPBuilder-Deploy to do a real install in certain situations when you are making changes.

If you are curious to what a SharePoint solution is doing, then just check out the files in the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12

You will notice that all the files we created in our Visual Studio solution have been “pushed” down to the folders in the 12 hive. The WSP knows to “push” these files there. The WSP also knows to tell SharePoint that these files exist. This is exactly how SharePoint develops it’s out of the box site definitions.

Side Notes:

1. Any file you place in the Layouts folder can be reference in the aspx pages as “/_layouts/{filename}”. I usually recommend placing another folder under Layouts in the Visual Studio solution (just because it makes it easy to find later – you can call this folder the name of your company or the name of your project or anything that is obvious that it contains your custom reference files). Then you can reference everything in there by “/_layouts/{folder}/{filename}”. An example of this is css files in the master page. This is possible because SharePoint sets an IIS path up to the Layouts folder in the 12 hive and calls it _layouts.

2. If you want to create a custom webpart with WSPBuilder just click Add – new item… WSPBuilder – WebPartFeature. This will create the feature folder, for your webpart, and the .cs class for your webpart. This way you can go directly into coding and not have to worry about the Feature creation. Once you are done coding the webpart just make sure it is in the appropriate scope of your onet.xml file (SiteFeatures or WebFeatures) and it will become available to you in your webpart gallery. Then all you have to do is worry about your dll being installed in the Bin or GAC. If you choose GAC I recommend post-build scripts to move it.

3. Do not remove Content Place Holders from your master page if you start doing customizations. The reason for this is if you assign other files in SharePoint (such as list pages) to use your master pages, they will assume certain Content Place Holders exist. If they are not there, your site will just break.