Creating a Custom WSS Site Definition

1.     This example provides instructions to create the site definition without a coding tool like Visual Studio – the only necessity is a text editor of some sort (Notepad will work just fine).   I don’t recommend this method, especially if you live in a source-controlled environment, but I’m making the assumption that most of the audience will not be power developers.  If you are a VS guru, just create a blank solution called ‘SampleSTS’ and duplicate the sample file structure within the project – the final results will be the same.

2.     You must have direct access to the front-end SharePoint server(s) to complete this example.  You don’t need admin rights on the server, just the ability to write to the SharePoint 12 Hive and execute a few command-line utilities.

3.     Don’t panic – you don’t need to be a developer to make this work.  Just follow the example and you should be fine.

4.     I don’t show you how to create a custom master page.  Refer to Heather Solomon’s posts here and here and here to learn how to create your own Master Pages (but be sure to keep the WSS-specific settings intact).

Ready?  Here we go!

Preparation

Create a folder on your computer to store the Site Definition files called ‘SampleSTS’ (‘STS’ is the abbreviation SharePoint uses to refer to the Team Site template so I’m using it just to be consistent – name the folder anything you want).  Under this folder, create the following subfolders:

SampleSTS\Layouts\1033\Styles\SampleSTS
SampleSTS\Images\SampleSTS
SampleSTS\1033\XML
SampleSTS\Features\SampleSTSMasterPage
SampleSTS\SiteTemplates\SampleSTS

Create a Custom WEBTEMP File

In order to make a new Site Definition available for selection in the Site Creation dialog, the Definition must first be enabled within a custom WEBTEMP.XML file. 

1)  Create an empty text file in the SampleSTS\1033\XML folder on your computer named “WEBTEMPSAMPLESTS”.  Rename it with a “.xml” extension.

NOTE: Custom WEBTEMP files must always start with the string ‘WEBTEMP’.  Append unique names to the end of this string.

1)  Edit WEBTEMPSAMPLESTS.XML

a)  Copy the following text into the WEBTEMPSAMPLESTS.XML file.

Template Settings

Name – The name MUST match the name of the Site Definition folder in the \SiteTemplates directory (in this case, ‘SampleMPS’). 

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 Settings

Configuration ID – The zero-based identifier for the configuration.  The first configuration node always has an ID of ‘0’.

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.  Usually a wireframe representation of how the site will look.

Description – Descriptive text associated with the site definition.   Displayed immediately below the sample image on the site creation screen.

DisplayCategory – A category to display the new site definition in on the site creation screen.  An existing or custom value can be used.

b)  Save and close WEBTEMPSAMPLESTS.XML

Create Custom Master Page

Page layouts in SharePoint 2007 are defined by the site master page and the layout page(s).  Master pages are stored in 12\TEMPLATE\GLOBAL directory for WSS and MPS Site Definitions (default.master for WSS, mwsdefault.master for MPS) and layout pages (really a MOSS term but the concept applies to WSS as well) are the DEFAULT.ASPX files within the SiteTemplate directory.  Each site may reference either a default or custom master page; however, modifications to the default master pages are global changes that affect all sites derived from the associated Site Definition type.  To enable individual master pages on a site-by-site basis, custom master pages should be deployed as a Feature and provisioned in the ONET.XML file of the definition.

NOTE: Master pages may be edited in SharePoint designer or a text editor (including Visual Studio).  When edited on the file system the changes are global (all dependent Site Definitions are impacted by the change).  When modified in SharePoint Designer AFTER the site is provisioned the changes only apply to the site being edited.  This tutorial provides a method for creating a shared master page that WILL NOT be edited in Designer after the site has been provisioned (you can edit it post-provisioning but the changes would only apply to a single site).

1)  Copy the DEFAULT.MASTER file from \12\TEMPLATE\GLOBAL to SampleSTS\Features\SampleSTSMasterPage directory on your computer.

2)  Modify the file to suit your purposes in a text editor, not in SharePoint Designer, and save the changes as SAMPLESTS.MASTER.  This method does require that you edit HTML directly; if you’re unsure of how to do that, grab your nearest web designer and cajole, beg or bribe them to give you a quick lesson.

Styles

Just a quick note on Styles as they pertain to this particular method.  Styles may be applied on a per-site or global basis.  Per-site styles may be stored in any document library on a site and referenced by URL from within the master page headers.  Alternatively, styles may be stored in the 12\TEMPLATE\Layouts\1033\Styles directory and referenced globally using the virtual Layouts path (/_layouts/1033/styles/).  In order to avoid having to provision a style sheet to each site, and thus having to make future changes to multiple style sheets, we will instead deploy a global style sheet to the file system.  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.

The typical method for supplying new styles which take precedence over the default SharePoint styles is called ‘overriding’.  To override a given style, copy it intact from the CORE.CSS file (or wherever it lives – you may need to do some text searching through multiple CSS files in the 12\TEMPLATE\Layouts\1033\Styles directory to find what you are looking for) into your new style sheet then make the appropriate changes.  The key here is to make sure that your new style sheet is called AFTER the default style sheet(s).

To insure that styles specified in a custom master page overwrite the default SharePoint styles, reference the custom stylesheet using the following markup:

If you do create a custom style sheet, save it in the SampleSTS\Layouts\1033\Styles\SampleSTSfolder and add the following line just above the closing </HEAD> tag in your custom master page:

Images

Images, like Styles, may be also be referenced on a per-site or global basis.  Per-site images may be stored in any document library on a site and referenced by URL from within the master page.  Alternatively, may be stored in the 12\TEMPLATE\Images directory and referenced globally using the virtual Layouts path (/_layouts/images/).  Again, in order to avoid having to manage images scattered across multiple sites, it is best to place them in a central repository that all sites can reference, like the 12\TEMPLATE\Images\SampleSTS directory.  It is recommended to place all custom images in a subfolder of the 12\TEMPLATE\Images directory to insure compatibility with future upgrades.  Images stored in this location can be reference using a path such as “/_layouts/images/SampleSTS/logo.gif”. 

Edit Default Page

WSS sites may only reference either ‘default.master’ or ‘custom.master’ (these references are fixed; other master page references are not allowed and attempting to refer to any other file will result in an error).  During site provisioning, a configuration option in ONET.XML tells the site which actual file is used by either the DEFAULT or CUSTOM master page setting.  Custom master pages should be referenced by layout pages using the ‘custom.master’ setting in the page registration code.

1)  Open Default.aspx located in the SampleSTS\SiteTemplates\SampleSTSfolder.

2)  If it is not already set, change the master page setting in the page registration to reference custom.master.

3)  Save the Default.aspx file.

Create a Master Page Feature

When  a new WSS site is provisioned, only the default master page (default.master) and the default layout page (default.aspx) are copied to the site page galleries.  These ‘ghosted’ pages are then referred to by the parser when the site is rendered.  In order for a custom master page to be applied to new sites automatically (without post-provisioning modification) the new master page must be copied to the site along with the default pages.  This task is accomplished using the SharePoint Feature Framework.

Features define sets of functionality that can be used by sites and site collections either before or after site provisioning.  Features must be installed, activated, then associated with a Site Definition (automatic deployment) or selected from the web interface after a site is created (manual deployment).

1)  Create a new text file in the SampleSTS\Features\SampleSTSMasterPage directory and rename it Feature.xml.

2)  Paste the following text into the file:

Feature Settings

ID – A Globally Unique Identifier (GUID) value that uniquely identifies this particular feature.

Title – The name of the feature.  This is used in the Feature gallery of the site collection and should be something descriptive.

Scope – Defines how the feature is applied.  Available options are ‘Farm’ (entire server farm), ‘Site’ (individual site collection), and ‘Web’ (single web site).

ElementManifest – The payload of the Feature; this is where the actual work gets done.

Location – Where the ElementManifest file is located relative to the Feature file.

3)  Create a new GUID using the a GUID creation 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.   Remove the curly braces at the beginning and end of the GUID string.

4)  Create a new text file in the SampleSTS\Features\SampleSTSMasterPage directory and rename it ElementManifest.xml.

5)  Paste the following text into the file:

ElementManifest Settings

Module – An element that contains some sort of action (such as <File> for file provisioning).

Name – The folder name of the Feature that it belongs to.

List – The ID of the list type (in this case, a MasterPageGallery).

Url – The post-provisioning, relative url of the list; not the actual list on the file system (what shows up in the hierarchy when you view the site in SharePoint Designer, for example).

File – The action element.

File Url – The local path of the file; in this case, our custom master page (I know, it should be ‘Path’ but it’s ‘Url’, which is confusing).

File Type – Determines whether an actual list item is created for the file (GhostableInLibrary) or if it exists in a hidden state (Ghostable).

6)  Save and close the ElementManifest.xml file.

Edit ONET.XML

Ok, this is where it gets a bit tricky.  As with previous versions of SharePoint, ONET.XML defines the structure, contents, and list elements of a site when it is first provisioned.  Changes to ONET.XML have no effect on sites that have already been created.  In order to make use of the new custom master page in this example, the ONET.XML file for the SampleSTS Site Definition must be modified to a) deploy the SampleSTSMasterPage page feature automatically, and b) change its custom.master property to refer to the new master page instead of MWSDEFAULT.MASTER.   

Deploy Custom Master Page Feature

In order to copy the custom master page to the site so that it exists within the Master Page Gallery upon provisioning, the accompanying feature must be referenced as part of the proper <Configuration> node:

1)  Open the ONET.XML file located in the SampleSTS\SiteTemplates\SampleSTS\XML folder.

2)  Locate the Configuration with ID=”0” in the <Configurations> node:

3)  Add the SampleSTSMasterPage feature to the <WebFeatures> node using the ID value (GUID) from the Feature.xml file (place the GUID between the empty quotation marks):

5)  Save ONET.XML.

Deploy Files and Features

You are now ready to deploy the new site definition.  All the necessary files in the SampleMPS project must be copied to each front-end web server.  The following table lists the location each file or directory in our sample project must be copied to each front-end web server (if you have multiple front ends, repeat the process for each server):

Install New Feature

Once created, the new Master Page Feature must now be installed to the server farm before it can be used by the custom site definition.  It does NOT need to be activated; it will be automatically activated during the site provisioning process.  To install the feature, execute the following from a command prompt on only one front-end server (must be performed from the SharePoint server itself):

"C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\stsadm.exe" -o installfeature -filename SampleSTSMasterPage\feature.xml

Followed by:

iisreset

If you encounter and error and need to fix then redeploy the feature, you must first uninstall it using the following command, then repeat the procedure:

"C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\BIN\stsadm.exe" -o uninstallfeature -filename SampleSTSMasterPage\feature.xml

Provision New Site Collection

Now that all the new Site Definition is in place and the Feature has been installed, create a new site using the custom Site Definition (NOTE: A Web Application must exist before this step can be completed):

1)  From SharePoint Central Administration, go to Application Management, select Create Site Collection.

2)  Enter a name for the site in the Title field.

3)  Enter a URL.

4)  Select “Sample Team Site” in the Samples tab of the Select Site Template field.

5)  Click ‘Create’.

You’re done!  From this point forward the custom master page will be used for all sites that derive from the Sample Team Site site definition.  Remember that in order modify the master page that is shared by all the sites deriving from this definition, you need only modify the SampleSTS\Features\SampleSTSMasterPage\SampleSTS.Master file and copy it to the feature folder on each front-end server (NOTE: if you modify this file in SharePoint Designer the changes will apply only to that site and not to the base site definition – new sites will continue to use the base master page file).

Good luck and Happy SharePointing!