Rafelo
SharePoint, Enterprise Architecture, Design and Development Patterns
http://blog.rafelo.com

Introduction to Custom Site Definitions

I'll start out with a quote from an MSDN Article on site definitions:

"Changing a site definition after it has already been deployed can break existing sites and is not supported. If you find that you must modify a site definition after deployment, keep in mind that adding features can cause fewer problems than changing or deleting them. Changing features often results in loss of data, and deleting features often results in broken views."

The full article titled "Guidelines for Using Custom Site Definitions" can be found here.

Nevertheless there are plenty of scenarios that call for them, and they are not all that difficult to work with. The following are a set of exercises that walk you through most of the basic steps you'll need to know when creating custom site definitions. 

Part 1, "Creating Site Definitions", gives you step by step instruction on how to create a basic site definition based on the "STS" out-of-the-box definition.

Part 2, "Adding Content", gives you step by step instructions on how to add a WSS page to your site definition (not a publishing page.) It also walks you through creating a Picture Library and an Image as part of your site definition.

Part 3, "Adding Master Pages", gives you step by step instructions on how to include a master page in your site definition.

Part 1: Creating Site Definitions
In this exercise we will create our own site definition based on one of the existing ones. You will make the Site Definition available in SharePoint and use it to create your own site.
 
Exercise 1
 
1.  Make sure you’ve logged in to the SharePoint training Virtual PC as an Administrator
 
2. Open windows explorer and go to:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template\Site Templates\
This directory contains the SharePoint 2007 site definitions
 
3. Copy and paste the folder titled STS, re-naming the copy to NEWSTS
 
4. Open the ONET.xml file located in the “\NEWSTS\XML\” folder with Visual Studio. This document defines the Navigation Bars, Document Templates,  Configurations, Lists, Features, and Modules of the site definitions. We’ll cover these in more detail later.  Scroll down to the “Configurations” node and take note of the 4 configurations.  We’ll reference these later in this exercise.
 
image007
 
5. Go to:
 C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\1033\XML
Copy and paste the file titled WEBTEMP.xml renaming the copy to webtempnewsts.xml
 
6. Open the webtempnewsts.xml file with Visual Studio.
 
7. Remove all the Template Elements except the one named “STS”
 
image011
 
 
8. Change the Name attribute of the “STS” template to “NEWSTS” and its ID to “10001”. It is important to set the ID of the template to an integer value that has not already been taken and will not likely be taken by a template acquired from a third party, which is why it is recommend going with a value above the 10000 range.
 
image013
 
9. Notice the “Configuration” elements.  Each one of these refers to the configuration elements you made note of when reviewing the ONET.xml file. Including these in the WEBTEMP makes SharePoint aware of the configurations available for your Site Definition.
 
10. Change the Title of each of the configurations to include the word “New” as in “New Team Site” and “New Blank Site”
 
11. Change the value of the “Hidden” attribute of the New Document Workspace configuration to “TRUE” and the value of “DisplayCategory” to “CUSTOMDEFS”
 
12. Your file should look as follows:
 
image015
 
13. Save your changes and close the file.
 
14. Open the command prompt and execute an IISRESET
 
15. Open the SharePoint 3.0 Central Administration site and go to Application Management
 
16. Click on the “Create Site Collection” link
 
17. Select a Web Application other than the one used by your Central Administration or Shared Services Site
 
18. Set the title to “Site Definitions Exercise 1”
 
19. Enter “E1” for the URL
 
20. In the section title “Template Selection” click on the “CUSTOMDEFS” category; that is the Display Category we specified in the webtempnewsts.xml file.  Notice that the “New Document Workspace” configuration is not available, but the other 2 are; that is because we changed the “HIDDEN” attribute for that configuration to TRUE in the webtempnewsts.xml file.
 
21. Select the “New Team Site” template, specify the Primary Site Collection Administrator, and click OK.
 
22. SharePoint will create the new Site Collection based on the newly created Site Definition. When SharePoint has completed creating the site collection, click on the link to the site.
 
Note: The site may take a few minutes when loading for the first time.


Part 2: Adding Content to the Site Definitions
 
Exercise 1 - Adding a page to a WSS site
 
1. Copy and paste the default.aspx file located in the folder of the NEWSTS site definition renaming it to custom.aspx.
 
2. Open the custom.aspx file in Visual Studio
 
3. Locate the Content Placeholder titled “PlaceHolderMain”, it should be located around line 44, and enter “This page was created by the NEWSTS site definition.” right before the opening Table tag.
image025 
 
4. Save your changes and close the file.
 
5. Open the ONET.xml file located in:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template\Site Templates\NEWSTS\XML
 
6. Locate the “Modules” element following the “Configurations” element (it should be around line 164). DO NOT confuse it with the “Modules” element inside one of the Configurations.

7. Add the following XML to the Modules element:
 
<Module Name="CustomPage" Url="" Path="">  
         <File Url="custom.aspx" NavBarHome="False" />
</Module>
 
This module tells SharePoint to create the custom.aspx page in the root of the site. The “NavBarHome” attribute tells SharePoint that this is not the home page.
 
8. Your code should look as follows:
 
image027
 
9. Look for Configuration 0, the default configuration.
 
10. Find the Modules in the Configuration element and add the following XML
 
<Module Name="CustomPage" />
 
This tells SharePoint to call this module when creating a site from this configuration. The code should look like this:
 
11. Repeat Step 10 for each one of the configurations.
 
12. Scroll to the top of the document. Locate the Project XML node (this is the root node). 
 
13. Now Locate the NavBars node, and identify the NavBar element with an ID 1002. This should be the first NavBar in the NavBars node.  You’ll need to add a couple of XML nodes to it. Before doing so, you’ll need to open the element by  replacing “/>”  with “>” and adding the closing tag; “</Navbar>”
 
14. Add the following child XML node to the NavBar with the ID 1002.
 
<NavBarLink Name="My Custom Page" Url="custom.aspx"></NavBarLink>
 
This adds a Link to the custom page in the Top Navigation bar. Your XML should look as follows:
 
image031
 
15. Save your change and close the file.
 
16. Open the command prompt and execute an IISRESET
 
17. Open the SharePoint 3.0 Central Administration site and go to Application Management
 
18. Click on the “Create Site Collection” link
 
19. Select a Web Application other than the one used by your Central Administration or Shared Services Site
 
20. Set the title to “Part 2 Exercise 1”
 
21. Enter “P2E1” for the URL
 
22. In the section titled “Template Selection” click on the “CUSTOMDEFS” category.
 
23. Select the “New Team Site” template, specify the Primary Site Collection Administrator, and click OK.
 
24. SharePoint will create the new Site Collection based on the newly created Site Definition. When SharePoint has completed creating the site collection, click on the link to the site.
Note: The site may take a few minutes when loading for the first time.
 
25. The site will contain a link to the new page in the Top Navigation Bar.
Note: This link will not be available if the site is a sub-site and is inheriting navigation from the parent site.
 
26. Click on “My Custom Page”
 
Exercise 2 - Adding a Picture Library and Image
 
1. Copy the file titled “PREVIEW.JPG” from
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\IMAGES
and paste 2 copies in the NEWSTS site definition folder
 
2. Rename one copy to PREVIEW_JPG.JPG, you will need this file for the thumbnail.
 
3. Open the ONET.xml file located in:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template\Site Templates\NEWSTS\XML
 
4. Add a picture library to the default configuration. To do this, locate the “Lists” node under the default Configuration node (<Configuration ID="0" Name="Default">)  and add the following xml:
 
<List FeatureId="00BFEA71-52D4-45B3-B544-B1C71B620109" Url="SiteImages" Title="Site Images" Type="109" />
 
The FeatureID attribute references the Picture Library Feature, the URL attribute indicates what the URL of the library will be relative to the site, the Type attribute indicates the list type.

Your XML code should look as follows:
 
image037
 
Note:  Similarly you can include additional Document Libraries, Calendars, Contacts, etc.. Just copy one of the List elements located above or below the one you just entered and change its Title, URL, and QuickLaunchURL. You could also create your own Custom Library or List as a Feature and include it in the site definition the same way; but that (rightfully so) should be covered under a separate “Working with Features” subject (there are many factors and implications to consider).
 
5. Locate the “Modules” element following the “Configurations”. DO NOT confuse it with the “Modules” element inside one of the Configurations.

6. Add the following XML to the Modules element:
 
<Module Name="PreviewImage" Url="SiteImages" Path="">
        <File Url="preview.jpg" Path="Preview.jpg" Type="GhostableInLibrary"/>
        <File Url="_t/preview_jpg.jpg" Path="Preview_jpg.jpg" />
        <File Url="_w/preview_jpg.jpg" Path="Preview_jpg.jpg" />
</Module>
 
The first File node loads the actual image, the second loads the thumbnail (which by default must go in the “_t” subfolder of the image library) this is the image that you see on the list view, the third loads the preview image (which by default must go in the “_w” subfolder of the image library) this is the image that you see on the properties view.
 
7. Locate the “Default” Module XML node and replace “/_layouts/images/homepage.gif”  with “SiteImages/Preview.jpg”
 
image039
 
8. Locate the “Modules” XML node in the default Configuration node (<Configuration ID="0" Name="Default">)  and add the following xml:
 
<Module Name="PreviewImage" />
 
Your code should look as follows:
 
9. Save your changes
 
10. Open the command prompt and execute an IISRESET
 
11. Open the SharePoint 3.0 Central Administration site and go to Application Management
 
12. Click on the “Create Site Collection” link
 
13. Select a Web Application other than the one used by your Central Administration or Shared Services Site (
 
14. Set the title to “Part 2 Exercise 2”
 
15. Enter “P2E2” for the URL
 
16. In the section title “Template Selection” click on the “CUSTOMDEFS” category.
 
17. Select the “New Team Site” template, specify the Primary Site Collection Administrator, and click OK.
 
18. SharePoint will create the new Site Collection based on the newly created Site Definition. When SharePoint has completed creating the site collection, click on the link to the site.
Note: The site may take a few minutes when loading for the first time.

19. Click on the “View All Site Content” link and notice the Picture Library with one item in it.
 

Part 3: Adding Master Pages to Site Definitions
 
Exercise 1
 
1. Go to
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\TEMPLATE\GLOBAL
 
2. Copy the default.master  file and paste it in the NEWSTS site definition folder,  renaming it to newsts.master.
 
3. Open the default.master page and find the ContentPlaceHolder with an ID of “PlaceHolderGlobalNavigation”. It should be located on line 27.
 
4. Change the visibility by giving it a visible attribute with a value of false (Visible="false").
 
image045
 
5. Save your changes and close the file.
 
6. Open the ONET.xml file located in:
C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\12\Template\Site Templates\NEWSTS\XML
 
7. Locate the default Configuration and add the following attributes:
 
CustomMasterUrl="_catalogs/masterpage/newsts.master" MasterUrl="_catalogs/masterpage/newsts.master"
 
The CustomMasterURL tells SharePoint where the “custom” master page will be located and the MasterURL tells SharePoint where the “default” master page will be. 
 
 image047

Note: SharePoint allows for 2 master pages usable per site at any given time, the “Default” and “Custom” master page. These are set at the page level in the MasterPageFile attribute of the @Page directive. The value must be set to either “~masterurl/default.master” or “~masterurl/custom.master”.  This is specific to WSS sites; there are other ways to work with master pages in publishing sites.
 
8. Locate the “Modules” element following the “Configurations”. DO NOT confuse it with the “Modules” element inside one of the Configurations.
 
9. Add the following Module:
 
<Module Name="AddMaster" Url="_catalogs/MasterPage" Path="">
   <File Url="newsts.master" Type="GhostableInLibrary"
   IgnoreIfAlreadyExists="True"/>
</Module>
 
10. Locate the Modules XML node in the default Configuration and add a reference to the newly created module.
 
image049 
 
11. Save your changes and close the file.
 
12. Open the command prompt and execute an IISRESET
 
13. Open the SharePoint 3.0 Central Administration site and go to Application Management
 
14. Click on the “Create Site Collection” link
 
15. Select a Web Application other than the one used by your Central Administration or Shared Services Site
 
16. Set the title to “Part 3 Exercise 1”
 
17. Enter “P3E1” for the URL
 
18. In the section title “Template Selection” click on the “CUSTOMDEFS” category.
 
19. Select the “New Team Site” template, specify the Primary Site Collection Administrator, and click OK.
 
20. SharePoint will create the new Site Collection based on the newly created Site Definition. When SharePoint has completed creating the site collection, click on the link to the site.
 
21. The global navigation will not be visible as specified in the new master page.