Creating a Custom Meeting Workspace Site Definition

Heather Solomon posted an article recently regarding the difficulties of customizing the Meeting Workspace templates.  I agree with Heather that there is really only one reliable way to do this with any level of automation –a custom Site Definition.  Not too terribly difficult but if you’ve never done it the process can be a bit daunting.  So here’s a step-by-step guide on deploying a custom Meeting Workspace definition to get you going.

First, a few caveats:

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 ‘SampleMPS’ 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.  The example is fairly comprehsive; just follow it and you should be fine.

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

Ready?  Here we go!

    

Preparation

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

SampleMPS\Layouts\1033\Styles\SampleMPS
SampleMPS\Images\SampleMPS
SampleMPS\1033\XML
SampleMPS\Features\SampleMPSMasterPage
SampleMPS\SiteTemplates\SampleMPS

(NOTE: There are no fixed requirements for this file structure but it does mirror the folder structure in the \12\TEMPLATE\ directory on the SharePoint server)

 

Copy the Existing Site Definition

Locate the \12\TEMPLATE\SiteTemplates\MPS folder on the SharePoint server.  Copy the contents of this folder, including subfolders, into the SampleMPS\SiteTemplates\SampleMPS folder on your computer.

 

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 SampleMPS\1033\XML folder on your computer named “WEBTEMPSAMPLEMPS”.  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 WEBTEMPSAMPLEMPS.XML

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

<?xml version="1.0" encoding="utf-8"?> <!– _lcid="1033" _version="12.0.4518" _dal="1" –> <!– _LocalBinding –> <Templates xmlns:ows="Microsoft SharePoint">  <Template Name="SampleMPS" ID="20001">      <Configuration ID="0" Title="Sample Basic Meeting Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/mwsprev.png" Description="A site to plan, organize, and capture the results of a meeting. It provides lists for managing the agenda, meeting attendees, and documents." DisplayCategory="Samples" >    </Configuration>     <Configuration ID="1" Title="Sample Blank Meeting Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/blankmwsprev.png" Description="A blank meeting site for you to customize based on your requirements." DisplayCategory="Samples" >    </Configuration>     <Configuration ID="2" Title="Sample Decision Meeting Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/decisionmwsprev.png" Description="A site for meetings that track status or make decisions. It provides lists for creating tasks, storing documents, and recording decisions." DisplayCategory="Samples" >    </Configuration>     <Configuration ID="3" Title="Sample Social Meeting Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/socialmwsprev.png" Description="A site to plan social occasions. It provides lists for tracking attendees, providing directions, and storing pictures of the event." DisplayCategory="Samples" >    </Configuration>     <Configuration ID="4" Title="Sample Multipage Meeting Workspace" Hidden="FALSE" ImageUrl="/_layouts/images/multipagemwsprev.png" Description="A site to plan, organize, and capture the results of a meeting. It provides lists for managing the agenda and meeting attendees in addition to two blank pages for you to customize based on your requirements." DisplayCategory="Samples" >    </Configuration>  </Template> </Templates>

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 WEBTEMPSAMPLEMPS.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 MWSDEFAULT.MASTER file from \12\TEMPLATE\GLOBAL to SampleMPS\Features\SampleMPSMasterPage 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 SAMPLEMPS.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:

<link rel="stylesheet" type="text/css" href="{Stylesheet URL}/{Stylesheet Name}" / >

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

<link rel="stylesheet" type="text/css" href="/_layouts/1033/Styles/SampleMPS/samplemps.css" / >

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\SampleMPS 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/SampleMPS/logo.gif”. 

 

Edit Default Page

WSS sites, including Meeting Workspaces, 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 (more on that later) and this is the primary reason why the Meeting Workspace definition causes the difficulties that Heather describes.  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 SampleMPS\SiteTemplates\SampleMPS folder.

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

MasterPageFile="~masterurl/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 SampleMPS\Features\SampleMPSMasterPage directory and rename it Feature.xml.

2)  Paste the following text into the file:

<Feature Id=""   Title="Sample MPS Custom Master Page"   Scope="Web"   xmlns="http://schemas.microsoft.com/sharepoint/">       <ElementManifests>             <ElementManifest Location="ElementManifest.xml" />       </ElementManifests> </Feature>

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 SampleMPS\Features\SampleMPSMasterPage directory and rename it ElementManifest.xml.

5)  Paste the following text into the file:

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">       <Module Name="SampleMPSMasterPage" List="116" Url="_catalogs/masterpage">             <File Url="samplemps.master" Type="GhostableInLibrary" />       </Module> </Elements>

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 SampleMPS Site Definition must be modified to a) deploy the SampleMPSMasterPage 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 SampleMPS\SiteTemplates\SampleMPS \XML folder.

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

<Configuration ID="0" Name="Basic" CustomMasterUrl="_catalogs/masterpage/MWSDefault.master">       <Lists>         <List Title="$Resources:xml_onet_mwsidmeetingDisp;" Type="200">         </List> …

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

<WebFeatures>     <Feature ID="00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5" />     <!– Sample MPS Master Page –>     <Feature ID="" /> </WebFeatures>

     

4)  Repeat for each configuration node in the file (there are five total, 0 – 4) using the same GUID.

5)  Save ONET.XML.

Change Master Page Settings

To use the new master page, it must be assigned to the CustomMasterUrl property of the base configuration using the post-provisioning URL :

1)  Within each <Configuration> node, replace CustomMasterUrl="_catalogs/masterpage/MWSDefault.master" with CustomMasterUrl="_catalogs/masterpage/SampleMPS.master".  The final markup should look similar to the following:

<Configuration ID="0" Name="Default" CustomMasterUrl="_catalogs/masterpage/SampleMPS.master">

NOTE:  The CustomMasterUrl property matches the URL setting from the ElementManifest.xml file used in the SampleMPSMasterPage feature.

2)  Save ONET.XML.

OPTIONAL: Remove References to MWSDEFAULT.MASTER

Although it is not required, you may wish to remove all references to MWSDEFAULT.MASTER if you never plan to use it again.  To do so, perform the following steps:

1)  Locate and remove the following markup in the <Configurations> node:

<Configuration ID="5" Hidden="TRUE" Name="EnsureMWSMaster">    <Modules>        <Module Name="EnsureMWSMasterPage" />    </Modules> </Configuration>

2) Locate the following markup in each remaining <Configuration> node.  Remove the text “<Module Name="MWSMasterPage" />”:

<Modules>     <Module Name="MultipageHome" />     <Module Name="Multipage" />     <Module Name="MWSMasterPage" /> </Modules>

3)  Locate and remove the following markup in the <Modules> node:

<Module Name="MWSMasterPage" Url="_catalogs/masterpage" SetupPath="global">       <File Url="MWSdefault.master" Type="GhostableInLibrary" IgnoreIfAlreadyExists="TRUE" />     </Module>

And also remove the following markup in the same <Modules> node:

<Module Name="EnsureMWSMasterPage" Url="_catalogs/masterpage" SetupPath="global" RootWebOnly="FALSE">       <File Url="MWSDefault.master" Type="GhostableInLibrary" IgnoreIfAlreadyExists="TRUE" />     </Module>

4)  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):

Source	Destination
SampleMPS\Layouts\1033\Styles\SampleMPS	\12\TEMPLATE\Layouts\1033\Styles\SampleMPS (new subdirectory, copy entire folder)
SampleMPS\Images\SampleMPS	\12\TEMPLATE\Images\SampleMPS (new subdirectory, copy entire folder)
SampleMPS\1033\XML\WEBTEMPSAMPLEMPS.XML	\12\TEMPLATE\1033\XML\WEBTEMPSAMPLEMPS.XML (individual file only)
SampleMPS\Features\SampleMPSMasterPage	\12\TEMPLATE\FEATURES\SampleMPSMasterPage (new subdirectory, copy entire folder)
SampleMPS\SiteTemplates\SampleMPS	\12\TEMPLATE\SiteTemplates\SampleMPS (new subdirectory, copy entire folder)

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 SampleMPSMasterPage\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 SampleMPSMasterPage\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 Meeting Workspace Site Definition” 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 Meeting Workspace 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 SampleMPS\Features\SampleMPSMasterPage\SampleMPS.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!

 

P.S. – This entire process applies equally to deploying custom Team Site-based site definitions.  The only real differences are: 1) the STS folder is used as the base of the new definition instead of MPS, 2) there are only two configurations in the ONET.XML file to apply the CustomMasterUrl property to (it’s not used by default in STS), and 3) there are no modules or configuration nodes to be deleted (in fact, the entire OPTIONAL section of the Edit ONET.XML step can be skipped).